architecture

Ditto MCP – Architecture Guide

This repository implements an MCP (Model Context Protocol) server that executes Ditto DQL with safety guardrails.

• Entrypoint CLI: src/index.ts creates the server and connects a stdio transport.
• Server factory: src/mcpServer.ts registers tools/resources. It is the single place that adds tools to the MCP list.
• Config: src/config.ts parses environment variables and CLI overrides and returns a typed ServerConfig.
• Ditto HTTP client: src/ditto/client.ts contains the executeDql function.
• Guardrails: src/guards/dql.ts enforces single-statement, operation allow-list, and optional regex allow-list.
• Logging: src/utils/logger.ts handles leveled logging and redaction.

Responsibilities and Boundaries

• src/index.ts: CLI parsing, process error handling, transport lifecycle, graceful shutdown.
• src/mcpServer.ts: Tool and resource definitions only. No direct env access; uses values passed via ServerConfig.
• src/config.ts: Source of truth for allowed operations and timeouts. Only this module reads env variables.
• src/ditto/*: Pure HTTP logic. It returns typed results or a Ditto-style error envelope.
• src/guards/*: Stateless validation/guard code. Server must call before any network I/O.
• dist/*: Generated output. Never edit.

Transport

• Current transport is stdio. The CLI argument chooses transport string, but server connects stdio by default.
• HTTP transport can be added later as an orthogonal module; keep mcpServer.ts free of transport details.

Data Flow

• CLI + env → loadConfig() → ServerConfig → createServer() → tool handler → guard functions → Ditto HTTP client → typed response → MCP content.

Error Handling

• Process-level handlers in src/index.ts convert unknown errors to strings safely and exit on uncaughtException.
• Tool handlers return { isError: true, content: [...] } when validation or remote errors occur.
• HTTP client returns a Ditto-like envelope on failure to simplify tool logic.