# steipete/conduit-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/steipete/conduit-mcp
- Repository: https://github.com/steipete/conduit-mcp

## Overview

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: [`src/mcp-server.ts`](https://github.com/steipete/conduit-mcp/blob/main/src/mcp-server.ts) (Server), [`src/core/fileSystemOps.ts`](https://github.com/steipete/conduit-mcp/blob/main/src/core/fileSystemOps.ts) (Filesystem), [`src/operations/readOpsHandler.ts`](https://github.com/steipete/conduit-mcp/blob/main/src/operations/readOpsHandler.ts) (Read ops), [`src/operations/putOpsHandler.ts`](https://github.com/steipete/conduit-mcp/blob/main/src/operations/putOpsHandler.ts) (Write ops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["MCP boundary"]
  node_mcp_client(("MCP client<br/>external client"))
  node_mcp_server["Server<br/>mcp entrypoint<br/>[mcp-server.ts]"]
  node_find_tool["find<br/>tool adapter<br/>[findTool.ts]"]
  node_list_tool["list<br/>tool adapter<br/>[listTool.ts]"]
  node_read_tool["read<br/>tool adapter<br/>[readTool.ts]"]
  node_write_tool["write<br/>tool adapter<br/>[writeTool.ts]"]
  node_test_tool["test<br/>tool adapter<br/>[testTool.ts]"]
end

subgraph group_operations["Workflows"]
  node_find_ops["Search ops<br/>workflow<br/>[findOps.ts]"]
  node_list_ops["List ops<br/>workflow<br/>[listOps.ts]"]
  node_read_ops["Read ops<br/>workflow<br/>[readOpsHandler.ts]"]
  node_get_content_ops["Content fetch<br/>workflow<br/>[getContentOps.ts]"]
  node_metadata_ops["Metadata<br/>workflow<br/>[metadataOps.ts]"]
  node_diff_ops["Diffs<br/>workflow<br/>[diffOps.ts]"]
  node_write_ops["Write ops<br/>workflow<br/>[putOpsHandler.ts]"]
  node_put_content_ops["Put content<br/>workflow<br/>[putContentOps.ts]"]
  node_batch_write_ops["Batch write<br/>workflow<br/>[batchWriteOps.ts]"]
  node_archive_ops["Archive<br/>workflow<br/>[archiveOps.ts]"]
end

subgraph group_core["Core services"]
  node_path_validator["Path guard<br/>security service<br/>[pathValidator.ts]"]
  node_security_handler["Security<br/>access control<br/>[securityHandler.ts]"]
  node_fs_ops[("Filesystem<br/>storage service<br/>[fileSystemOps.ts]")]
  node_web_fetcher["Web fetcher<br/>http service<br/>[webFetcher.ts]"]
  node_image_processor["Image proc<br/>media service<br/>[imageProcessor.ts]"]
  node_mime_service["MIME<br/>type service<br/>[mimeService.ts]"]
  node_config_loader["Config<br/>[configLoader.ts]"]
  node_notice_service["Notices<br/>user notice<br/>[noticeService.ts]"]
end

subgraph group_external["External planes"]
  node_local_fs[("Local filesystem<br/>external data plane")]
  node_remote_web[("Remote web<br/>external data plane")]
end

node_mcp_client -->|"MCP request"| node_mcp_server
node_mcp_server -->|"routes"| node_find_tool
node_mcp_server -->|"routes"| node_list_tool
node_mcp_server -->|"routes"| node_read_tool
node_mcp_server -->|"routes"| node_write_tool
node_mcp_server -->|"routes"| node_test_tool
node_find_tool -->|"invokes"| node_find_ops
node_list_tool -->|"invokes"| node_list_ops
node_read_tool -->|"invokes"| node_read_ops
node_write_tool -->|"invokes"| node_write_ops
node_find_ops -->|"checks"| node_path_validator
node_list_ops -->|"checks"| node_path_validator
node_read_ops -->|"checks"| node_path_validator
node_write_ops -->|"checks"| node_path_validator
node_find_ops -->|"uses"| node_fs_ops
node_list_ops -->|"uses"| node_fs_ops
node_read_ops -->|"delegates"| node_get_content_ops
node_read_ops -->|"delegates"| node_metadata_ops
node_read_ops -->|"delegates"| node_diff_ops
node_get_content_ops -->|"uses"| node_fs_ops
node_get_content_ops -->|"fetches"| node_web_fetcher
node_get_content_ops -->|"processes"| node_image_processor
node_get_content_ops -->|"detects"| node_mime_service
node_write_ops -->|"delegates"| node_put_content_ops
node_write_ops -->|"delegates"| node_batch_write_ops
node_write_ops -->|"delegates"| node_archive_ops
node_put_content_ops -->|"writes"| node_fs_ops
node_batch_write_ops -->|"applies"| node_fs_ops
node_archive_ops -->|"packs"| node_fs_ops
node_fs_ops -->|"reads/writes"| node_local_fs
node_web_fetcher -->|"retrieves"| node_remote_web
node_mcp_server -->|"loads config"| node_config_loader
node_mcp_server -->|"enforces"| node_security_handler
node_read_ops -->|"emits"| node_notice_service
node_write_ops -->|"emits"| node_notice_service

click node_mcp_server "https://github.com/steipete/conduit-mcp/blob/main/src/mcp-server.ts"
click node_find_tool "https://github.com/steipete/conduit-mcp/blob/main/src/tools/findTool.ts"
click node_list_tool "https://github.com/steipete/conduit-mcp/blob/main/src/tools/listTool.ts"
click node_read_tool "https://github.com/steipete/conduit-mcp/blob/main/src/tools/readTool.ts"
click node_write_tool "https://github.com/steipete/conduit-mcp/blob/main/src/tools/writeTool.ts"
click node_test_tool "https://github.com/steipete/conduit-mcp/blob/main/src/tools/testTool.ts"
click node_find_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/findOps.ts"
click node_list_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/listOps.ts"
click node_read_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/readOpsHandler.ts"
click node_get_content_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/getContentOps.ts"
click node_metadata_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/metadataOps.ts"
click node_diff_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/diffOps.ts"
click node_write_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/putOpsHandler.ts"
click node_put_content_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/putContentOps.ts"
click node_batch_write_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/batchWriteOps.ts"
click node_archive_ops "https://github.com/steipete/conduit-mcp/blob/main/src/operations/archiveOps.ts"
click node_path_validator "https://github.com/steipete/conduit-mcp/blob/main/src/core/pathValidator.ts"
click node_security_handler "https://github.com/steipete/conduit-mcp/blob/main/src/core/securityHandler.ts"
click node_fs_ops "https://github.com/steipete/conduit-mcp/blob/main/src/core/fileSystemOps.ts"
click node_web_fetcher "https://github.com/steipete/conduit-mcp/blob/main/src/core/webFetcher.ts"
click node_image_processor "https://github.com/steipete/conduit-mcp/blob/main/src/core/imageProcessor.ts"
click node_mime_service "https://github.com/steipete/conduit-mcp/blob/main/src/core/mimeService.ts"
click node_config_loader "https://github.com/steipete/conduit-mcp/blob/main/src/core/configLoader.ts"
click node_notice_service "https://github.com/steipete/conduit-mcp/blob/main/src/core/noticeService.ts"

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_mcp_server,node_find_tool,node_list_tool,node_read_tool,node_write_tool,node_test_tool toneBlue
class node_find_ops,node_list_ops,node_read_ops,node_get_content_ops,node_metadata_ops,node_diff_ops,node_write_ops,node_put_content_ops,node_batch_write_ops,node_archive_ops toneAmber
class node_path_validator,node_security_handler,node_fs_ops,node_web_fetcher,node_image_processor,node_mime_service,node_config_loader,node_notice_service toneMint
class node_local_fs,node_remote_web toneRose
```

## Components

### MCP boundary

Protocol entrypoint and user-facing tool adapters.

- **MCP client**: external client · AI client that sends MCP tool requests.
- [Server](https://github.com/steipete/conduit-mcp/blob/main/src/mcp-server.ts): mcp entrypoint · Protocol boundary that receives MCP requests and routes tools. · `src/mcp-server.ts`
- [find](https://github.com/steipete/conduit-mcp/blob/main/src/tools/findTool.ts): tool adapter · MCP tool schema and dispatch for search requests. · `src/tools/findTool.ts`
- [list](https://github.com/steipete/conduit-mcp/blob/main/src/tools/listTool.ts): tool adapter · MCP tool schema and dispatch for directory and metadata listing. · `src/tools/listTool.ts`
- [read](https://github.com/steipete/conduit-mcp/blob/main/src/tools/readTool.ts): tool adapter · MCP tool schema and dispatch for content retrieval. · `src/tools/readTool.ts`
- [write](https://github.com/steipete/conduit-mcp/blob/main/src/tools/writeTool.ts): tool adapter · MCP tool schema and dispatch for file mutation and packaging. · `src/tools/writeTool.ts`
- [test](https://github.com/steipete/conduit-mcp/blob/main/src/tools/testTool.ts): tool adapter · MCP tool for exercising server behavior and scenarios. · `src/tools/testTool.ts`

### Workflows

Request orchestration for read, search, list, and write actions.

- [Search ops](https://github.com/steipete/conduit-mcp/blob/main/src/operations/findOps.ts): workflow · Filesystem search and filtering orchestration. · `src/operations/findOps.ts`
- [List ops](https://github.com/steipete/conduit-mcp/blob/main/src/operations/listOps.ts): workflow · Directory traversal and filesystem inspection orchestration. · `src/operations/listOps.ts`
- [Read ops](https://github.com/steipete/conduit-mcp/blob/main/src/operations/readOpsHandler.ts): workflow · Content read orchestration across files, URLs, metadata, and diffs. · `src/operations/readOpsHandler.ts`
- [Content fetch](https://github.com/steipete/conduit-mcp/blob/main/src/operations/getContentOps.ts): workflow · Fetches and normalizes file or web content for read workflows. · `src/operations/getContentOps.ts`
- [Metadata](https://github.com/steipete/conduit-mcp/blob/main/src/operations/metadataOps.ts): workflow · Produces file and content metadata for read workflows. · `src/operations/metadataOps.ts`
- [Diffs](https://github.com/steipete/conduit-mcp/blob/main/src/operations/diffOps.ts): workflow · Compares content and produces change summaries. · `src/operations/diffOps.ts`
- [Write ops](https://github.com/steipete/conduit-mcp/blob/main/src/operations/putOpsHandler.ts): workflow · Mutation orchestration for create, update, archive, and batch actions. · `src/operations/putOpsHandler.ts`
- [Put content](https://github.com/steipete/conduit-mcp/blob/main/src/operations/putContentOps.ts): workflow · Writes or replaces file content. · `src/operations/putContentOps.ts`
- [Batch write](https://github.com/steipete/conduit-mcp/blob/main/src/operations/batchWriteOps.ts): workflow · Coordinates multi-step file mutations in one request. · `src/operations/batchWriteOps.ts`
- [Archive](https://github.com/steipete/conduit-mcp/blob/main/src/operations/archiveOps.ts): workflow · Packages and extracts archive artifacts. · `src/operations/archiveOps.ts`

### Core services

Reusable infrastructure, security, and content services.

- [Path guard](https://github.com/steipete/conduit-mcp/blob/main/src/core/pathValidator.ts): security service · Confines access to allowed paths and handles symlink-aware validation. · `src/core/pathValidator.ts`
- [Security](https://github.com/steipete/conduit-mcp/blob/main/src/core/securityHandler.ts): access control · Enforces filesystem safety rules and resource limits. · `src/core/securityHandler.ts`
- [Filesystem](https://github.com/steipete/conduit-mcp/blob/main/src/core/fileSystemOps.ts): storage service · Primitive filesystem reads, writes, stats, traversal, copy, move, and delete. · `src/core/fileSystemOps.ts`
- [Web fetcher](https://github.com/steipete/conduit-mcp/blob/main/src/core/webFetcher.ts): http service · Retrieves remote HTTP/S content for read workflows. · `src/core/webFetcher.ts`
- [Image proc](https://github.com/steipete/conduit-mcp/blob/main/src/core/imageProcessor.ts): media service · Compresses or processes image content before return. · `src/core/imageProcessor.ts`
- [MIME](https://github.com/steipete/conduit-mcp/blob/main/src/core/mimeService.ts): type service · Detects MIME types and guides content handling. · `src/core/mimeService.ts`
- [Config](https://github.com/steipete/conduit-mcp/blob/main/src/core/configLoader.ts): config service · Loads environment-driven server configuration. · `src/core/configLoader.ts`
- [Notices](https://github.com/steipete/conduit-mcp/blob/main/src/core/noticeService.ts): user notice · Emits one-time or user-facing notices. · `src/core/noticeService.ts`

### External planes

Local and remote data sources accessed by the server.

- **Local filesystem**: external data plane · Allowed filesystem roots and their contents.
- **Remote web**: external data plane · HTTP/S resources fetched as read inputs.

## Connections

- 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.
