# nithiin7/remote-file-server-mcp architecture

> Architecture diagram of the GitHub repository nithiin7/remote-file-server-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nithiin7/remote-file-server-mcp
- Repository: https://github.com/nithiin7/remote-file-server-mcp

## Overview

1. **What this repo is**
   - This is a Python 3.11+ **MCP server** that sits between an MCP client (for example Claude Desktop) and an **SMB/CIFS file share**.
   - Its boundary is intentionally narrow: it provides **read-only file access** and never exposes write operations.

2. **Runtime entrypoint**
   - `server.py` is the main process entrypoint when run from source.
   - The server likely starts an MCP stdio transport, registers the available tools, and wires environment/config values into the SMB session layer.

3. **Public tool surface**
   - The `tools/` package contains the user-facing MCP tools:
     - `list_files.py`
     - `read_files.py`
     - `get_file_info.py`
     - `search_file.py`
   - These tools are the main application API and define the only operations an MCP client can invoke.

4. **Core data flow**
   - MCP client sends a tool call over stdio to the server.
   - The tool validates and sanitizes inputs.
   - The tool delegates to the SMB session layer to access the remote share.
   - Results are returned as structured text/JSON back to the client.
   - Audit logging happens alongside the request, but file contents are not written to logs.

5. **SMB access layer**
   - The `smb/` package contains the connection and share-access logic:
     - `session.py` is the central abstraction for connecting/authenticating to the SMB server and operating within the configured share root.
     - `helpers.py` likely contains share/path utilities used by multiple tools.
   - This layer is the boundary to the external SMB/CIFS network service on port 445.

6. **Security and path control**
   - `utils/validators.py` and `config.py` enforce the repo’s security model:
     - reject path traversal such as `..`
     - block sensitive filenames and extensions
     - enforce file size and depth limits
     - apply optional `ALLOWED_PATHS` subdirectory restrictions
   - Sanitization is important because the server handles untrusted model-generated paths.

7. **Document reading pipeline**
   - `utils/document_parsers.py` supports converting non-plain-text documents into text, especially Office and PDF files.
   - This means `read_file` is not just a raw SMB read; it may branch into parsing logic when the file type requires extraction.
   - That parsing is optional at install/runtime per the README’s `[docs]` extras.

8. **Operational logging**
   - `utils/logger.py` is responsible for audit-style logging.
   - The README indicates JSON logs capture operation, path, outcome, and tool metadata, but never file contents.
   - `AUDIT_LOG_PATH` controls whether logs go to a file or stderr.

9. **Configuration model**
   - `config.py` centralizes environment-driven settings such as:
     - SMB host/share/credentials
     - port, timeout, encryption flag
     - max file size and preview behavior
     - allowed paths and audit log destination
   - This makes the server deployable in multiple environments without code changes.

10. **Tests and quality boundaries**
   - `tests/` covers the public tool behavior and validation rules:
     - `test_tools.py`
     - `test_validators.py`
   - `tests/conftest.py` suggests shared fixtures for mocked SMB/session behavior, which is important because most behavior depends on an external file share.

11. **Packaging and delivery**
   - `pyproject.toml` and `requirements.txt` define the Python package, dependencies, and likely the console script entrypoint.
   - `Dockerfile` packages the same server into a container for deployment.
   - GitHub Actions in `.github/workflows/ci.yml` and `release-please.yml` handle CI and release automation.

12. **Architecture summary for a diagram**
   - Draw three main domains: **MCP client**, **this Python MCP server**, and **external SMB share**.
   - Inside the server, show a top layer of **MCP tools**, a middle layer of **validation/config/logging**, and a lower layer of **SMB session access** plus **document parsing** for file reads.
   - The key architectural rule is that all access flows through the tool layer, and every path is filtered before any SMB operation occurs.

Main entry points: [`tools/read_files.py`](https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/read_files.py) (Read files), [`server.py`](https://github.com/nithiin7/remote-file-server-mcp/blob/main/server.py) (Tool router), [`tools/list_files.py`](https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/list_files.py) (List files), [`tools/get_file_info.py`](https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/get_file_info.py) (File info)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External actors"]
  node_mcp_client(("MCP client"))
  node_smb_share[("SMB/CIFS share<br/>remote filesystem")]
end

subgraph group_server["Python MCP server"]
  node_stdio_transport["stdio transport<br/>[server.py]"]
  node_server_entrypoint["Server entry<br/>entrypoint<br/>[server.py]"]
  node_tool_router["Tool router<br/>mcp core<br/>[server.py]"]
  node_list_files_tool["List files<br/>tool<br/>[list_files.py]"]
  node_read_files_tool["Read files<br/>tool<br/>[read_files.py]"]
  node_get_file_info_tool["File info<br/>tool<br/>[get_file_info.py]"]
  node_search_file_tool["Search file<br/>tool<br/>[search_file.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_validators{{"Validators<br/>security<br/>[validators.py]"}}
  node_logger["Audit log<br/>logging<br/>[logger.py]"]
  node_smb_session[("SMB session<br/>smb access<br/>[session.py]")]
  node_smb_helpers["SMB helpers<br/>path utils<br/>[helpers.py]"]
  node_document_parsers["Doc parsers<br/>parsing"]
end

subgraph group_storage["Operational sinks"]
  node_audit_sink["Log sink"]
end

node_mcp_client -->|"tool call"| node_stdio_transport
node_stdio_transport -->|"start"| node_server_entrypoint
node_server_entrypoint -->|"register"| node_tool_router
node_tool_router -->|"expose"| node_list_files_tool
node_tool_router -->|"expose"| node_read_files_tool
node_tool_router -->|"expose"| node_get_file_info_tool
node_tool_router -->|"expose"| node_search_file_tool
node_list_files_tool -->|"sanitize"| node_validators
node_read_files_tool -->|"sanitize"| node_validators
node_get_file_info_tool -->|"sanitize"| node_validators
node_search_file_tool -->|"sanitize"| node_validators
node_validators -->|"policy"| node_config
node_list_files_tool -->|"browse"| node_smb_session
node_read_files_tool -->|"read"| node_smb_session
node_get_file_info_tool -->|"stat"| node_smb_session
node_search_file_tool -->|"scan"| node_smb_session
node_smb_session -->|"connect"| node_smb_share
node_read_files_tool -->|"extract"| node_document_parsers
node_read_files_tool -->|"audit"| node_logger
node_list_files_tool -->|"audit"| node_logger
node_get_file_info_tool -->|"audit"| node_logger
node_search_file_tool -->|"audit"| node_logger
node_logger -->|"emit"| node_audit_sink
node_read_files_tool -->|"path ops"| node_smb_helpers
node_list_files_tool -->|"path ops"| node_smb_helpers
node_get_file_info_tool -->|"path ops"| node_smb_helpers
node_search_file_tool -->|"path ops"| node_smb_helpers

click node_stdio_transport "https://github.com/nithiin7/remote-file-server-mcp/blob/main/server.py"
click node_server_entrypoint "https://github.com/nithiin7/remote-file-server-mcp/blob/main/server.py"
click node_tool_router "https://github.com/nithiin7/remote-file-server-mcp/blob/main/server.py"
click node_list_files_tool "https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/list_files.py"
click node_read_files_tool "https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/read_files.py"
click node_get_file_info_tool "https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/get_file_info.py"
click node_search_file_tool "https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/search_file.py"
click node_config "https://github.com/nithiin7/remote-file-server-mcp/blob/main/config.py"
click node_validators "https://github.com/nithiin7/remote-file-server-mcp/blob/main/utils/validators.py"
click node_logger "https://github.com/nithiin7/remote-file-server-mcp/blob/main/utils/logger.py"
click node_smb_session "https://github.com/nithiin7/remote-file-server-mcp/blob/main/smb/session.py"
click node_smb_helpers "https://github.com/nithiin7/remote-file-server-mcp/blob/main/smb/helpers.py"
click node_document_parsers "https://github.com/nithiin7/remote-file-server-mcp/blob/main/utils/document_parsers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_client,node_smb_share toneBlue
class node_stdio_transport,node_server_entrypoint,node_tool_router,node_list_files_tool,node_read_files_tool,node_get_file_info_tool,node_search_file_tool,node_config,node_validators,node_logger,node_smb_session,node_smb_helpers,node_document_parsers toneAmber
class node_audit_sink toneMint
```

## Components

### External actors

MCP client and remote SMB/CIFS services outside this server.

- **MCP client**: client · Claude Desktop or another MCP consumer sending tool calls over stdio.
- **SMB/CIFS share**: remote filesystem · External network file share accessed over SMB/CIFS on port 445.

### Python MCP server

Entrypoint, tool surface, validation, logging, and SMB access layers.

- [stdio transport](https://github.com/nithiin7/remote-file-server-mcp/blob/main/server.py): transport · MCP stdio channel between client and server process. · `server.py`
- [Server entry](https://github.com/nithiin7/remote-file-server-mcp/blob/main/server.py): entrypoint · Main process startup wiring transport, tools, and configuration. · `server.py`
- [Tool router](https://github.com/nithiin7/remote-file-server-mcp/blob/main/server.py): mcp core · Registers the public tool surface and dispatches tool calls. · `server.py`
- [List files](https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/list_files.py): tool · Enumerates share contents within allowed paths. · `tools/list_files.py`
- [Read files](https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/read_files.py): tool · Reads and may parse file contents for client output. · `tools/read_files.py`
- [File info](https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/get_file_info.py): tool · Returns metadata and attributes for a file or path. · `tools/get_file_info.py`
- [Search file](https://github.com/nithiin7/remote-file-server-mcp/blob/main/tools/search_file.py): tool · Searches file contents or names through the share boundary. · `tools/search_file.py`
- [Config](https://github.com/nithiin7/remote-file-server-mcp/blob/main/config.py): settings · Environment-driven SMB, limits, and path policy configuration. · `config.py`
- [Validators](https://github.com/nithiin7/remote-file-server-mcp/blob/main/utils/validators.py): security · Path and input sanitization enforcing read-only access constraints. · `utils/validators.py`
- [Audit log](https://github.com/nithiin7/remote-file-server-mcp/blob/main/utils/logger.py): logging · Structured audit logging without file contents. · `utils/logger.py`
- [SMB session](https://github.com/nithiin7/remote-file-server-mcp/blob/main/smb/session.py): smb access · Authenticated connection and share-root access abstraction. · `smb/session.py`
- [SMB helpers](https://github.com/nithiin7/remote-file-server-mcp/blob/main/smb/helpers.py): path utils · Shared SMB and path helper routines used by tools and session code. · `smb/helpers.py`
- [Doc parsers](https://github.com/nithiin7/remote-file-server-mcp/blob/main/utils/document_parsers.py): parsing · Optional extraction pipeline for Office and PDF documents. · `utils/document_parsers.py`

### Operational sinks

Audit log destination used by the server.

- **Log sink**: sink · File or stderr destination for audit events.

## Connections

- MCP client → stdio transport: tool call · Client sends MCP requests to the server over stdio.
- stdio transport → Server entry: start · Entrypoint initializes the MCP runtime.
- Server entry → Tool router: register · Server wires the public tools into the MCP runtime.
- Tool router → List files: expose · Registers list operations as an MCP tool.
- Tool router → Read files: expose · Registers read operations as an MCP tool.
- Tool router → File info: expose · Registers metadata lookup as an MCP tool.
- Tool router → Search file: expose · Registers search as an MCP tool.
- List files → Validators: sanitize · Validates requested paths before any SMB access.
- Read files → Validators: sanitize · Validates and constrains read targets.
- File info → Validators: sanitize · Validates metadata lookup targets.
- Search file → Validators: sanitize · Validates search scope and path inputs.
- Validators → Config: policy · Validation rules use configured limits and allowed paths.
- List files → SMB session: browse · Lists share contents through the SMB session layer.
- Read files → SMB session: read · Reads file bytes through the SMB session layer.
- File info → SMB session: stat · Fetches file metadata through the SMB session layer.
- Search file → SMB session: scan · Searches remote files through the SMB session layer.
- SMB session → SMB/CIFS share: connect · Session authenticates and operates against the remote share.
- Read files → Doc parsers: extract · Non-plain-text files may be converted into text for responses.
- Read files → Audit log: audit · Records the operation without logging file contents.
- List files → Audit log: audit · Records list activity and outcome.
- File info → Audit log: audit · Records metadata lookup activity and outcome.
- Search file → Audit log: audit · Records search activity and outcome.
- Audit log → Log sink: emit · Writes JSON audit events to file or stderr.
- Read files → SMB helpers: path ops · Uses shared SMB path and share-root utilities.
- List files → SMB helpers: path ops · Uses shared SMB path and share-root utilities.
- File info → SMB helpers: path ops · Uses shared SMB path and share-root utilities.
- Search file → SMB helpers: path ops · Uses shared SMB path and share-root utilities.