SOLVE-IT MCP Server

Summary: This project is an MCP (Model Context Protocol) 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

• 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

Quick Start

1. Install dependencies

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:

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:

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

Related MCP server: MITRE ATT&CK Mapper MCP

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)

Lookup (3 tools)

Summary Listing (3 tools)

Objectives and Mappings (5 tools)

Relationships (6 tools)

Search (1 tool)

Citations (3 tools)

Extension Info (1 tool)

Status (1 tool — always available)

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.

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):

[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:

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

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

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:

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:

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

Claude Code

Add to your project's .mcp.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):

{
  "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:

pip install -e .

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