How nithiin7/remote-file-server-mcp works
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: read_files.py Read files · server.py Tool router · list_files.py List files · get_file_info.py File info
Components 16
External actors
MCP client and remote SMB/CIFS services outside this server.
- MCP client · Claude Desktop or another MCP consumer sending tool calls over stdio.
- SMB/CIFS share · 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 · MCP stdio channel between client and server process.
server.py - Server entry · Main process startup wiring transport, tools, and configuration.
server.py - Tool router · Registers the public tool surface and dispatches tool calls.
server.py - List files · Enumerates share contents within allowed paths.
tools/list_files.py - Read files · Reads and may parse file contents for client output.
tools/read_files.py - File info · Returns metadata and attributes for a file or path.
tools/get_file_info.py - Search file · Searches file contents or names through the share boundary.
tools/search_file.py - Config · Environment-driven SMB, limits, and path policy configuration.
config.py - Validators · Path and input sanitization enforcing read-only access constraints.
utils/validators.py - Audit log · Structured audit logging without file contents.
utils/logger.py - SMB session · Authenticated connection and share-root access abstraction.
smb/session.py - SMB helpers · Shared SMB and path helper routines used by tools and session code.
smb/helpers.py - Doc parsers · Optional extraction pipeline for Office and PDF documents.
utils/document_parsers.py
Operational sinks
Audit log destination used by the server.
- Log sink · File or stderr destination for audit events.
Connections 27
- 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.