# cke-proto/mcp_solve-it architecture

> Architecture diagram of the GitHub repository cke-proto/mcp_solve-it, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cke-proto/mcp_solve-it
- Repository: https://github.com/cke-proto/mcp_solve-it

## Overview

#### Purpose and Runtime Entry Points
This is a Python MCP (Model Context Protocol) server exposing the external SOLVE-IT digital-forensics knowledge base to LLM clients as query, navigation, search, citation, relationship, and status tools. It is primarily a stdio subprocess server, not a web application.

- Launchers: `run.py`, `src/mcp_chassis/__main__.py`
- Central runtime orchestration: `src/mcp_chassis/server.py`
- Primary production transport: `src/mcp_chassis/transport/stdio.py`

#### Startup, Configuration, and Initialization
Startup loads TOML configuration, applies environment overrides, configures logging/security, builds the server, and initializes the external SOLVE-IT dataset. `solveit_data_path` identifies a separately cloned SOLVE-IT repository; it is the core external data dependency.

- Configuration model/loading: `src/mcp_chassis/config.py`
- Default deployment configuration: `config/default.toml`
- SOLVE-IT bootstrap and degraded-mode behavior: `src/mcp_chassis/extensions/solveit_init.py`

When `init_required` is true, failed KB loading terminates startup. Otherwise, the server remains available in degraded mode with status reporting.

#### Chassis Server and Request Dispatch
`ChassisServer` is the application boundary between MCP protocol events, registered extensions/tools, middleware, and a chosen transport. Tool registration is conditional: full-detail list tools and search parameters are exposed only when enabled by app configuration.

- Orchestrator: `src/mcp_chassis/server.py`
- Extension registration namespace: `src/mcp_chassis/extensions/__init__.py`
- Tool handlers/registration: `src/mcp_chassis/extensions/tools/solveit_tools.py`

The MCP client invokes a tool; the server applies middleware before handing sanitized, validated inputs to a SOLVE-IT handler, which queries loaded in-memory/library-backed knowledge-base data and returns MCP-compatible results.

#### SOLVE-IT Knowledge-Base Adapter
The domain extension wraps SOLVE-IT’s own library and datasets rather than owning the forensic taxonomy. It exposes techniques, weaknesses, mitigations, objectives, mappings, citations, cross-entity relationships, full-text search, extension state, and load status.

- Data initialization and loader integration: `src/mcp_chassis/extensions/solveit_init.py`
- Domain tool API: `src/mcp_chassis/extensions/tools/solveit_tools.py`
- Batch-related extension support: `src/mcp_chassis/extensions/batch.py`

Optional SOLVE-IT-X extension datasets are loaded according to application configuration. Objective mappings are selected from the external repository’s `data/` directory.

#### Security Middleware Boundary
All tool requests cross an ordered defensive pipeline: I/O limits, authentication, rate limiting, sanitization, then validation. This is the main trust boundary between MCP client input and domain handlers.

- Pipeline composition/order: `src/mcp_chassis/middleware/pipeline.py`
- Auth and rate enforcement: `src/mcp_chassis/security/auth.py`, `src/mcp_chassis/security/rate_limiter.py`
- Input/output bounds and sanitization: `src/mcp_chassis/security/io_limits.py`, `src/mcp_chassis/security/sanitization.py`
- Profiles and schema validation: `src/mcp_chassis/security/profiles.py`, `src/mcp_chassis/security/validation.py`

Security profiles define baseline limits and behavior; TOML/environment values can override them.

#### Transport and Operational Interfaces
The transport abstraction separates protocol serving from server logic. Stdio is the implemented production interface for MCP-hosted subprocesses; an HTTP implementation is explicitly a stub.

- Transport contract: `src/mcp_chassis/transport/base.py`
- Stdio implementation: `src/mcp_chassis/transport/stdio.py`
- HTTP placeholder: `src/mcp_chassis/transport/http_stub.py`

Health/diagnostics, structured logging, request context, and normalized error handling support operation without changing tool semantics.

- Health reporting: `src/mcp_chassis/diagnostics/health.py`
- Logging/context/errors: `src/mcp_chassis/logging_config.py`, `src/mcp_chassis/context.py`, `src/mcp_chassis/errors.py`

#### Material Dependencies and Infrastructure
Runtime is Python with MCP (`mcp>=1.6,<2` per README), Pydantic, and Pybtex. Deployment can run directly through Python or containerize via `Dockerfile`. No database, HTTP service, or cloud dependency is indicated; persistence and authoritative content remain in the externally supplied SOLVE-IT filesystem checkout.

Main entry points: [`src/mcp_chassis/server.py`](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/server.py) (ChassisServer), [`src/mcp_chassis/config.py`](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/config.py) (Configuration), [`src/mcp_chassis/middleware/pipeline.py`](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/middleware/pipeline.py) (Defensive pipeline), [`src/mcp_chassis/extensions/solveit_init.py`](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/extensions/solveit_init.py) (SOLVE-IT bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup"]
  node_launcher["Launchers<br/>Python entry points<br/>[run.py]"]
  node_config["Configuration<br/>TOML + environment loader<br/>[config.py]"]
  node_default_config["Default configuration<br/>TOML<br/>[default.toml]"]
end

subgraph group_runtime["MCP Runtime"]
  node_server["ChassisServer<br/>MCP orchestrator<br/>[server.py]"]
  node_stdio["Stdio transport<br/>production transport<br/>[stdio.py]"]
  node_transport_contract["Transport contract<br/>abstraction<br/>[base.py]"]
  node_http_stub["HTTP placeholder<br/>transport stub<br/>[http_stub.py]"]
end

subgraph group_security["Trust Boundary"]
  node_middleware["Defensive pipeline<br/>ordered middleware<br/>[pipeline.py]"]
  node_security_controls["Security controls<br/>auth, limits, validation<br/>[auth.py]"]
end

subgraph group_domain["SOLVE-IT Adapter"]
  node_tool_api["SOLVE-IT tools<br/>MCP tool handlers<br/>[solveit_tools.py]"]
  node_extension_registry["Extension registry<br/>registration namespace<br/>[__init__.py]"]
  node_solveit_init["SOLVE-IT bootstrap<br/>dataset loader<br/>[solveit_init.py]"]
  node_solveit_checkout[("SOLVE-IT checkout<br/>external knowledge base")]
end

subgraph group_operations["Operations"]
  node_health["Health reporting<br/>diagnostics<br/>[health.py]"]
  node_runtime_support["Runtime support<br/>logging, context, errors<br/>[logging_config.py]"]
end

node_launcher -->|"loads"| node_config
node_default_config -->|"defaults"| node_config
node_config -->|"builds"| node_server
node_config -->|"configures loading"| node_solveit_init
node_solveit_init -->|"loads"| node_solveit_checkout
node_solveit_init -->|"initializes extension"| node_server
node_server -->|"uses"| node_transport_contract
node_stdio -->|"implements"| node_transport_contract
node_http_stub -.->|"placeholder for"| node_transport_contract
node_server -->|"routes tool requests through"| node_middleware
node_middleware -->|"enforces via"| node_security_controls
node_middleware -->|"validated requests"| node_tool_api
node_extension_registry -->|"registers"| node_tool_api
node_server -->|"loads extensions"| node_extension_registry
node_tool_api -->|"queries"| node_solveit_checkout
node_server -->|"exposes status"| node_health
node_server -->|"uses"| node_runtime_support

click node_launcher "https://github.com/cke-proto/mcp_solve-it/blob/main/run.py"
click node_config "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/config.py"
click node_default_config "https://github.com/cke-proto/mcp_solve-it/blob/main/config/default.toml"
click node_server "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/server.py"
click node_stdio "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/transport/stdio.py"
click node_transport_contract "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/transport/base.py"
click node_http_stub "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/transport/http_stub.py"
click node_middleware "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/middleware/pipeline.py"
click node_security_controls "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/security/auth.py"
click node_tool_api "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/extensions/tools/solveit_tools.py"
click node_extension_registry "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/extensions/__init__.py"
click node_solveit_init "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/extensions/solveit_init.py"
click node_health "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/diagnostics/health.py"
click node_runtime_support "https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/logging_config.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_launcher,node_config,node_default_config toneBlue
class node_server,node_stdio,node_transport_contract,node_http_stub toneAmber
class node_middleware,node_security_controls toneMint
class node_tool_api,node_extension_registry,node_solveit_init,node_solveit_checkout toneRose
class node_health,node_runtime_support toneIndigo
```

## Components

### Startup

- [Launchers](https://github.com/cke-proto/mcp_solve-it/blob/main/run.py): Python entry points · `run.py`
- [Configuration](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/config.py): TOML + environment loader · `src/mcp_chassis/config.py`
- [Default configuration](https://github.com/cke-proto/mcp_solve-it/blob/main/config/default.toml): TOML · `config/default.toml`

### MCP Runtime

- [ChassisServer](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/server.py): MCP orchestrator · Connects protocol events, middleware, extensions, and transport. · `src/mcp_chassis/server.py`
- [Stdio transport](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/transport/stdio.py): production transport · Serves MCP as a subprocess over standard I/O. · `src/mcp_chassis/transport/stdio.py`
- [Transport contract](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/transport/base.py): abstraction · `src/mcp_chassis/transport/base.py`
- [HTTP placeholder](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/transport/http_stub.py): transport stub · `src/mcp_chassis/transport/http_stub.py`

### Trust Boundary

- [Defensive pipeline](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/middleware/pipeline.py): ordered middleware · Applies I/O limits, auth, rate limiting, sanitization, and validation. · `src/mcp_chassis/middleware/pipeline.py`
- [Security controls](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/security/auth.py): auth, limits, validation · Profiles and configuration determine enforcement behavior. · `src/mcp_chassis/security/auth.py`

### SOLVE-IT Adapter

- [SOLVE-IT tools](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/extensions/tools/solveit_tools.py): MCP tool handlers · Registers configurable query, navigation, search, citation, and status tools. · `src/mcp_chassis/extensions/tools/solveit_tools.py`
- [Extension registry](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/extensions/__init__.py): registration namespace · `src/mcp_chassis/extensions/__init__.py`
- [SOLVE-IT bootstrap](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/extensions/solveit_init.py): dataset loader · Loads the external checkout and selects degraded or fail-fast startup behavior. · `src/mcp_chassis/extensions/solveit_init.py`
- **SOLVE-IT checkout**: external knowledge base · Authoritative datasets and library remain in a separately cloned filesystem repository.

### Operations

- [Health reporting](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/diagnostics/health.py): diagnostics · Reports extension state and dataset load status. · `src/mcp_chassis/diagnostics/health.py`
- [Runtime support](https://github.com/cke-proto/mcp_solve-it/blob/main/src/mcp_chassis/logging_config.py): logging, context, errors · Provides structured logging, request context, and normalized errors. · `src/mcp_chassis/logging_config.py`

## Connections

- Launchers → Configuration: loads
- Default configuration → Configuration: defaults
- Configuration → ChassisServer: builds
- Configuration → SOLVE-IT bootstrap: configures loading
- SOLVE-IT bootstrap → SOLVE-IT checkout: loads
- SOLVE-IT bootstrap → ChassisServer: initializes extension
- ChassisServer → Transport contract: uses
- Stdio transport → Transport contract: implements
- HTTP placeholder → Transport contract: placeholder for
- ChassisServer → Defensive pipeline: routes tool requests through
- Defensive pipeline → Security controls: enforces via
- Defensive pipeline → SOLVE-IT tools: validated requests
- Extension registry → SOLVE-IT tools: registers
- ChassisServer → Extension registry: loads extensions
- SOLVE-IT tools → SOLVE-IT checkout: queries
- ChassisServer → Health reporting: exposes status
- ChassisServer → Runtime support: uses