# SOLVE-IT MCP Server

**Summary**: This project is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that wraps the  digital forensics knowledge base and its built-in library in order to provision LLMs with programmatic access to SOLVE-IT content. Related repositories include:

- **SOLVE-IT**: Provides a structured taxonomy of digital forensic techniques, the weaknesses that affect evidence reliability, and the mitigations that address those weaknesses. This server exposes tools for querying, navigating, and searching that knowledge base. It can be found here: [SOLVE-IT](https://github.com/SOLVE-IT-DF/solve-it)

- **MCP Server Chassis**: This MCP server was built on the MCP Server Chassis project, which provides an extensible, generic MCP server designed to be easily forked and used for various purposes. It can be found here: [MCP Server Chassis](https://github.com/CKE-Proto/mcp_server-chassis/)

## Quick Start

### 1. Install dependencies

```bash
pip install -e ".[dev]"
```

The required dependencies (`mcp`, `jcs`) are declared in `pyproject.toml`. HTTP transport and optional features (auth, OTel) can be installed via extras:

```bash
pip install -e ".[http]"    # HTTP/SSE transport
pip install -e ".[auth]"    # OAuth 2.0 / API key auth
pip install -e ".[otel]"    # OpenTelemetry
```

### 2. Download this repo.

### 3. Download the main SOLVE-IT repo. 

**Ref**: https://github.com/SOLVE-IT-DF/solve-it

### 4. Configure config/default.toml 

The default.toml file from this repository must point to your downloaded instance of the main SOLVE-IT repository. 

**Example:**
```
solveit_data_path = "<full path to your>/solve-it-main"
```

### 5. Run the MCP server

**Note**: You will not need to run the server manually if your MCP client runs the server when connecting to it, such as with the example in step 6 below.

**Example 1:**
```
python3 run.py --config config/default.toml
```

**Example 2:**
```
python -m mcp_chassis
```

### 6. Configure your MCP client

Configure your MCP client to connect to the MCP server. In some cases (e.g. Claude Desktop), the client will also start the MCP server.

**Example Claude Desktop Config:**

**Example File:** `claude_desktop_config.json` \
**Example Path (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`):

**Example Config**:
```json
{
  "mcpServers": {
    "solveit": {
      "command": "python3",
      "args": ["/path/to/mcp_server/run.py", "--config", "/path/to/mcp_server/config/default.toml"]
    }
  }
}
```


## Available MCP Tools

24 tools are always registered when the KB loads successfully, plus 3 config-gated full-detail tools and 1 status tool that is always available.

### Orientation (1 tool)

| Tool | Description |
|---|---|
| `solveit_get_database_description` | Call this first — returns the DB structure, entity types, available mappings, and item counts |

### Lookup (3 tools)

| Tool | Description |
|---|---|
| `solveit_get_technique` | Retrieve full details for a technique by DFT-XXXX ID |
| `solveit_get_weakness` | Retrieve full details for a weakness by DFW-XXXX ID |
| `solveit_get_mitigation` | Retrieve full details for a mitigation by DFM-XXXX ID |

### Summary Listing (3 tools)

| Tool | Description |
|---|---|
| `solveit_list_techniques` | List all techniques with ID and name |
| `solveit_list_weaknesses` | List all weaknesses with ID and name |
| `solveit_list_mitigations` | List all mitigations with ID and name |

### Objectives and Mappings (5 tools)

| Tool | Description |
|---|---|
| `solveit_list_objectives` | List all forensic objectives defined in the active mapping |
| `solveit_get_techniques_for_objective` | List techniques under a given objective |
| `solveit_get_objectives_for_technique` | Find which objectives a technique belongs to (reverse lookup) |
| `solveit_list_available_mappings` | List available framework mapping files (solve-it, carrier, dfrws) |
| `solveit_load_objective_mapping` | Switch to a different investigation framework |

### Relationships (6 tools)

| Tool | Description |
|---|---|
| `solveit_get_weaknesses_for_technique` | List weaknesses that affect a given technique |
| `solveit_get_mitigations_for_weakness` | List mitigations that address a given weakness |
| `solveit_get_mitigations_for_technique` | List mitigations for a technique in one call (shortcut) |
| `solveit_get_techniques_for_weakness` | List techniques affected by a given weakness (reverse) |
| `solveit_get_weaknesses_for_mitigation` | List weaknesses addressed by a given mitigation (reverse) |
| `solveit_get_techniques_for_mitigation` | List techniques linked to a given mitigation (reverse) |

### Search (1 tool)

| Tool | Description |
|---|---|
| `solveit_search` | Full-text search across techniques, weaknesses, and mitigations |

### Citations (3 tools)

| Tool | Description |
|---|---|
| `solveit_get_citation` | Resolve a DFCite-XXXX ID to its full bibliographic text |
| `solveit_list_citations` | List all citation IDs in the knowledge base |
| `solveit_resolve_inline_citations` | Replace [DFCite-XXXX] markers in text with Harvard-style citations |

### Extension Info (1 tool)

| Tool | Description |
|---|---|
| `solveit_list_loaded_extensions` | List any SOLVE-IT-X extension datasets currently loaded |

### Status (1 tool — always available)

| Tool | Description |
|---|---|
| `solveit_status` | Report data load status, item counts, and active configuration |

### Full-Detail Listings (disabled by default)

**Note:** These tools return the complete dataset for an entire item type and may consume ~25,000–32,000 LLM context tokens. Enable in **config/default.toml**.

| Tool | Description |
|---|---|
| `solveit_list_techniques_full_detail` | List all techniques with complete field data |
| `solveit_list_weaknesses_full_detail` | List all weaknesses with complete field data |
| `solveit_list_mitigations_full_detail` | List all mitigations with complete field data |

## Configuration

The `[app]` section in `config/default.toml` controls SOLVE-IT-specific settings. Top-level `[app]` keys can also be overridden by environment variables with the `MCP_APP_` prefix (env vars take precedence over TOML values):

| Environment Variable | Config Key | Type |
|---|---|---|
| `MCP_APP_SOLVEIT_DATA_PATH` | `solveit_data_path` | string |
| `MCP_APP_OBJECTIVE_MAPPING` | `objective_mapping` | string |
| `MCP_APP_ENABLE_EXTENSIONS` | `enable_extensions` | bool (`true`/`false`/`1`/`0`/`yes`/`no`) |
| `MCP_APP_INIT_REQUIRED` | `init_required` | bool |
| `MCP_APP_ENABLE_FULL_DETAIL_TOOLS` | `enable_full_detail_tools` | bool |

```toml
[app]
# Path to the SOLVE-IT repository root (absolute or relative to CWD).
solveit_data_path = "/<path>/<to>/<your>/solve-it-main"

# Objective mapping file (must exist in the SOLVE-IT data/ directory).
# Default: "solve-it.json" (the standard SOLVE-IT categorization).
# Custom mapping files can be placed in the data/ directory to provide
# alternative categorizations of techniques into objectives.
# See: https://custom-viewer.solveit-df.org
objective_mapping = "solve-it.json"

# Whether to load SOLVE-IT-X extension data.
enable_extensions = true

# If true (default), the server exits immediately when the KB fails to load.
# If false, the server starts in degraded mode with only solveit_status available.
init_required = true

# Enable full-detail listing tools (large payloads, disabled by default).
# WARNING: These tools return the entire dataset for a given type and may
# consume significant LLM context. You may also need to increase
# [security.io_limits] max_response_size when enabling this.
enable_full_detail_tools = false

[app.search]
# Each flag controls whether the corresponding parameter is exposed
# in the solveit_search tool's schema. When disabled, the default
# value is used: item_types=all, substring_match=false, search_logic="AND"
enable_item_types_filter = true
enable_substring_match = true
enable_search_logic = true
```

**`solveit_data_path`** — Path to the cloned SOLVE-IT repository. Accepts an absolute path or a path relative to the working directory when the server is started.

**`objective_mapping`** — Filename of the JSON mapping that categorizes techniques into forensic objectives. Must exist inside the SOLVE-IT `data/` directory. The default `solve-it.json` reflects the official categorization.

**`enable_extensions`** — When `true`, the server loads any SOLVE-IT-X extension datasets found in the repository.

**`init_required`** — When `true` (the default), the server exits with a clear error if the knowledge base fails to load. When `false`, the server starts in degraded mode with only `solveit_status` available, which reports the load failure. Set to `false` during development if you need to test server behavior without valid KB data.

**`enable_full_detail_tools`** — Controls whether the three full-detail listing tools are registered. See the section below before enabling.

**Search parameter flags** — The three `[app.search]` flags each control whether the corresponding parameter appears in the `solveit_search` tool schema. When a flag is `false`, the parameter is hidden and its default value is applied silently: `item_types` defaults to all types, `substring_match` defaults to `false` (word-boundary matching), and `search_logic` defaults to `"AND"`.

## Enabling Full-Detail Tools

Set `enable_full_detail_tools = true` in `config/default.toml` to register the three full-detail listing tools.

**Warning:** These tools return the complete dataset for an entire item type in a single response. Depending on the size of the SOLVE-IT data and any loaded extensions, responses can be very large and may consume a significant portion of an LLM's context window. If you enable these tools you will likely also need to raise the response size limit:

```toml
[security.io_limits]
max_response_size = 20971520   # 20 MB; default is 5 MB
```

## Security

Security behavior is inherited from the MCP server chassis on which this MCP server was built. Every tool request passes through the middleware pipeline in this order:

```
I/O limits → Auth → Rate limit → Sanitize → Validate
```

Through this pipeline, sanitization attempts can be applied to inputs before they reach tool handlers. The default security profile is `moderate`. 

**IMPORTANT**: These protections are a basic attempt to provide some security by default. If you decide to use this server in a production setting, we recommend you still perform security testing and modify the code of this project to implement security mitigations as appropriate for your threat environment and risk tolerance.

| Profile | Rate Limit | I/O Limits | Sanitization | Error Detail |
|---|---|---|---|---|
| `strict` | 60 rpm global, 30 rpm/tool | 1 MB req, 5 MB resp | Full (path traversal, shell metachars, control chars) | Generic |
| `moderate` | 120 rpm global, 60 rpm/tool | 5 MB req, 20 MB resp | Path traversal + control chars | Detailed |
| `permissive` | Disabled | 50 MB req/resp | Null bytes only | Detailed |

The active profile is set via `[security] profile` in `config/default.toml`, where the individual settings can be used to override elements of the specified profile. Furthermore, the profile set in default.toml can be overridden with the `MCP_SECURITY_PROFILE` environment variable.

## Testing

```bash
python -m pytest tests/              # All tests
python -m pytest tests/unit/         # Unit tests only
python -m pytest tests/integration/  # Integration tests only
```

## Project Structure

```
src/mcp_chassis/
  server.py                        — ChassisServer: central orchestrator
  config.py                        — Configuration dataclasses and TOML loading
  __main__.py                      — CLI entry point
  extensions/
    solveit_init.py                — Init hook: loads KB, computes KB version CAI
    tools/
      solveit_tools.py             — All 24 SOLVE-IT tool registrations and handlers
  middleware/
    pipeline.py                    — Security middleware pipeline (+ replay prevention)
  security/                        — Auth (none/apikey/oauth), rate limiting, sanitization
  transport/
    stdio.py                       — Stdio transport (default)
    http.py                        — HTTP/SSE transport (optional, requires [http] extra)
  utils/
    fss_context.py                 — FSS per-request context variables
    integrity.py                   — CAI computation, Ed25519 signing (FSS-0005)
    provenance.py                  — _provenance record builder (FSS-0004)
    telemetry.py                   — Optional OpenTelemetry integration
    metrics.py                     — Per-dispatch OTel metrics
config/
  default.toml                     — Server and application configuration
scripts/
  generate_signing_key.py          — Generate Ed25519 keypair for FSS signing
  verify_provenance.py             — Verify _provenance records (FSS-0005 §8)
  validate_dataset.py              — Check KB structural integrity (FSS-0006 §4.4)
tests/
  unit/                            — Unit tests
  integration/                     — Integration tests
  stress/                          — Locust load tests
docs/
  ARCHITECTURE.md                  — Component design and data flow
  TROUBLESHOOTING.md               — Common issues and fixes
```

## Using with MCP Clients

The project includes a `run.py` launcher that handles Python path setup automatically. Use absolute paths for both `run.py` and `--config` so the server works regardless of the client's working directory.

**Prerequisites:** Python dependencies must be installed on the machine running the server:

```bash
cd /path/to/mcp_server
pip install "mcp>=1.2.0,<2.0" pydantic pybtex   # minimum dependencies
```

Before configuring a client, set `solveit_data_path` in `config/default.toml` to an absolute path:

```toml
[app]
solveit_data_path = "/absolute/path/to/solve-it/solve-it-main"
```

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "solveit": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/mcp_server/run.py", "--config", "/path/to/mcp_server/config/default.toml"]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "solveit": {
      "command": "python3",
      "args": ["/path/to/mcp_server/run.py", "--config", "/path/to/mcp_server/config/default.toml"]
    }
  }
}
```

### Alternative: Using `pip install`

If you prefer not to use `run.py`, install the package and use `-m` directly:

```bash
pip install -e .
```

```json
{
  "mcpServers": {
    "solveit": {
      "command": "python3",
      "args": ["-m", "mcp_chassis", "--config", "/path/to/mcp_server/config/default.toml"]
    }
  }
}
```