How steipete/conduit-mcp works
1. What this repo is
- conduit-mcp is a TypeScript Model Context Protocol (MCP) server.
- Its role is to expose file-system, web-fetching, search, and archive capabilities to an AI client over MCP, rather than serving a browser UI or traditional REST API.
2. Top-level request flow
- MCP requests enter through src/mcp-server.ts.
- That server routes tool invocations into the tool layer in src/tools/, which then delegates to operation handlers in src/operations/.
- Most business logic is not in the MCP layer itself; the server is mainly the protocol boundary.
3. Tool layer = MCP-facing contract
- The concrete MCP tools are find, list, read, write, and test.
- Each tool module in src/tools/ defines the user-visible operation schema and converts a tool request into one of the internal operation workflows.
- This is the main boundary between protocol semantics and application logic.
4. Operation layer = domain orchestration
- src/operations/ contains the actual workflows:
- findOps.ts for search
- listOps.ts for directory/system inspection
- readOpsHandler.ts / getContentOps.ts / metadataOps.ts / diffOps.ts for content inspection
- putOpsHandler.ts / putContentOps.ts / batchWriteOps.ts / mkdirOps.ts / archiveOps.ts for file mutation and packaging
- These modules orchestrate lower-level core services and implement batch handling, validation, and response shaping.
5. Core layer = reusable infrastructure services
- src/core/ holds the foundational services used by all operations:
- fileSystemOps.ts for filesystem reads/writes/stats/listing/copy/move/delete
- pathValidator.ts and securityHandler.ts for path confinement and symlink-aware access control
- configLoader.ts for env-driven configuration
- webFetcher.ts for HTTP/URL retrieval
- imageProcessor.ts for image compression/processing
- mimeService.ts for MIME detection and content-type decisions
- noticeService.ts for one-time or user-facing notices
- This is the primary internal dependency center.
6. Data sources and external boundaries
- The server works across two main data domains:
- Local filesystem within allowed paths
- Remote web content fetched over HTTP/S
- Web reads can be converted into cleaner text/Markdown, while binary/image content can be returned as base64 or processed through the image pipeline.
- Archive operations also form a distinct boundary because they transform filesystem trees into packaged artifacts and back.
7. Security and tenancy boundary
- The most important architectural constraint is the allowed-path sandbox driven by CONDUIT_ALLOWED_PATHS.
- pathValidator.ts and securityHandler.ts enforce this boundary and are central to safe operation.
- The README explicitly notes symlink-aware validation and resource limits, so access control is not just string-prefix checking; it is part of the core design.
8. Content-processing pipeline
- File and URL reads are not treated identically.
- For URLs, webFetcher.ts retrieves content and the stack can extract readable content/Markdown from HTML.
- For images, imageProcessor.ts can compress large files before returning them.
- For file comparisons and checksums, the utilities in src/utils/ support deterministic byte-level processing.
9. Search and listing behavior
- find and list are specialized traversal workloads over the filesystem.
- find supports recursive filtering by name pattern, content pattern, MIME type, timestamps, size, and entry type.
- list supports recursive directory enumeration, recursive size calculation, and system/filesystem metadata.
- These are read-heavy operations, so they likely depend heavily on fileSystemOps.ts, path validation, and size/time limits.
10. Write and archive behavior
- write is the mutation surface: put, mkdir, copy, move, delete, touch, archive, and unarchive.
- Batch operations are first-class, meaning the architecture is designed to process multiple file actions in one request.
- Archive creation/extraction is a separate concern inside operations, but still ultimately constrained by the same filesystem security model.
11. Shared types and utilities
- src/types/ defines the shared contracts for config, MCP messages, tool inputs/outputs, and common primitives.
- src/utils/ provides cross-cutting helpers such as logging, checksum calculation, date/time formatting, and error normalization.
- This keeps protocol shapes and operational logic aligned without scattering ad hoc types across the codebase.
12. Testing strategy
- There is strong separation between unit/integration tests under tests/ and end-to-end MCP scenario tests under e2e/.
- Core modules have focused tests for filesystem primitives, security, web fetching, MIME handling, and image processing.
- Tool and operation tests use mocks, especially for filesystem access, while e2e/ validates real MCP behavior against scenario JSON files.
- That indicates the repo is organized around a stable internal core with protocol-level verification at the edge.
13. Runtime and tooling
- The repo is TypeScript/Node-based and expects a modern Node runtime; the README calls out Node.js 24+.
- Build/test quality is handled with TypeScript, Vitest, and formatting/linting tooling.
- start.sh and the npm scripts support running the MCP server as a CLI-style service, which fits the protocol-server architecture.
14. Architecture summary for a diagram
- A good diagram would show:
- MCP client on the outside
- MCP server entrypoint
- Tool adapters
- Operation orchestrators
- Core services
- Two external data planes: local filesystem and remote HTTP content
- The dominant control flow is request-driven and synchronous from MCP request to tool handler to operation to core service, with security validation wrapping every filesystem and URL access path.
Main entry points: mcp-server.ts Server · fileSystemOps.ts Filesystem · readOpsHandler.ts Read ops · putOpsHandler.ts Write ops
Components 27
MCP boundary
Protocol entrypoint and user-facing tool adapters.
- MCP client · AI client that sends MCP tool requests.
- Server · Protocol boundary that receives MCP requests and routes tools.
src/mcp-server.ts - find · MCP tool schema and dispatch for search requests.
src/tools/findTool.ts - list · MCP tool schema and dispatch for directory and metadata listing.
src/tools/listTool.ts - read · MCP tool schema and dispatch for content retrieval.
src/tools/readTool.ts - write · MCP tool schema and dispatch for file mutation and packaging.
src/tools/writeTool.ts - test · MCP tool for exercising server behavior and scenarios.
src/tools/testTool.ts
Workflows
Request orchestration for read, search, list, and write actions.
- Search ops · Filesystem search and filtering orchestration.
src/operations/findOps.ts - List ops · Directory traversal and filesystem inspection orchestration.
src/operations/listOps.ts - Read ops · Content read orchestration across files, URLs, metadata, and diffs.
src/operations/readOpsHandler.ts - Content fetch · Fetches and normalizes file or web content for read workflows.
src/operations/getContentOps.ts - Metadata · Produces file and content metadata for read workflows.
src/operations/metadataOps.ts - Diffs · Compares content and produces change summaries.
src/operations/diffOps.ts - Write ops · Mutation orchestration for create, update, archive, and batch actions.
src/operations/putOpsHandler.ts - Put content · Writes or replaces file content.
src/operations/putContentOps.ts - Batch write · Coordinates multi-step file mutations in one request.
src/operations/batchWriteOps.ts - Archive · Packages and extracts archive artifacts.
src/operations/archiveOps.ts
Core services
Reusable infrastructure, security, and content services.
- Path guard · Confines access to allowed paths and handles symlink-aware validation.
src/core/pathValidator.ts - Security · Enforces filesystem safety rules and resource limits.
src/core/securityHandler.ts - Filesystem · Primitive filesystem reads, writes, stats, traversal, copy, move, and delete.
src/core/fileSystemOps.ts - Web fetcher · Retrieves remote HTTP/S content for read workflows.
src/core/webFetcher.ts - Image proc · Compresses or processes image content before return.
src/core/imageProcessor.ts - MIME · Detects MIME types and guides content handling.
src/core/mimeService.ts - Config · Loads environment-driven server configuration.
src/core/configLoader.ts - Notices · Emits one-time or user-facing notices.
src/core/noticeService.ts
External planes
Local and remote data sources accessed by the server.
- Local filesystem · Allowed filesystem roots and their contents.
- Remote web · HTTP/S resources fetched as read inputs.
Connections 35
- MCP client → Server: MCP request · Client sends tool invocations to the server.
- Server → find: routes · Server dispatches search requests to the find tool.
- Server → list: routes · Server dispatches listing requests to the list tool.
- Server → read: routes · Server dispatches content requests to the read tool.
- Server → write: routes · Server dispatches mutation requests to the write tool.
- Server → test: routes · Server dispatches test requests to the test tool.
- find → Search ops: invokes · Tool adapter converts request into search workflow.
- list → List ops: invokes · Tool adapter converts request into list workflow.
- read → Read ops: invokes · Tool adapter converts request into read workflow.
- write → Write ops: invokes · Tool adapter converts request into write workflow.
- Search ops → Path guard: checks · Search is constrained by allowed-path validation.
- List ops → Path guard: checks · Listing is constrained by allowed-path validation.
- Read ops → Path guard: checks · Read workflows validate access before resolving targets.
- Write ops → Path guard: checks · Mutations validate access before changing the filesystem.
- Search ops → Filesystem: uses · Search traverses the filesystem primitives.
- List ops → Filesystem: uses · Listing depends on filesystem traversal and stats.
- Read ops → Content fetch: delegates · Read handler delegates content retrieval.
- Read ops → Metadata: delegates · Read handler delegates metadata shaping.
- Read ops → Diffs: delegates · Read handler delegates comparison logic.
- Content fetch → Filesystem: uses · File content retrieval uses filesystem primitives.
- Content fetch → Web fetcher: fetches · URL reads go through the web fetcher.
- Content fetch → Image proc: processes · Image content can be transformed before return.
- Content fetch → MIME: detects · Content handling depends on MIME classification.
- Write ops → Put content: delegates · Write handler delegates content writes.
- Write ops → Batch write: delegates · Write handler delegates batch mutation orchestration.
- Write ops → Archive: delegates · Write handler delegates archive packaging and extraction.
- Put content → Filesystem: writes · Content writes go through filesystem primitives.
- Batch write → Filesystem: applies · Batch mutations execute through filesystem primitives.
- Archive → Filesystem: packs · Archive creation and extraction operate on filesystem trees.
- Filesystem → Local filesystem: reads/writes · Filesystem service operates on allowed local data.
- Web fetcher → Remote web: retrieves · Web fetcher accesses remote HTTP/S resources.
- Server → Config: loads config · Server startup depends on environment configuration.
- Server → Security: enforces · Server-level behavior is constrained by security rules.
- Read ops → Notices: emits · Read workflows may produce user-facing notices.
- Write ops → Notices: emits · Write workflows may produce user-facing notices.