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

Option 1:

pip install "mcp>=1.6.0,<2.0" pydantic pybtex

Option 2: From within the root directory of this folder. ``bash pip install -e ".[dev]" ``

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

Lookup (3 tools)

| Tool | Description | |---|---| | solveit_get_technique | Retrieve full details for a single technique by ID | | solveit_get_weakness | Retrieve full details for a single weakness by ID | | solveit_get_mitigation | Retrieve full details for a single mitigation by 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 (2 tools)

| Tool | Description | |---|---| | solveit_list_objectives | List all forensic objectives defined in the active mapping | | solveit_get_techniques_for_objective | List techniques categorized under a given objective |

Relationships (5 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_techniques_for_weakness | List techniques affected by a given weakness | | solveit_get_weaknesses_for_mitigation | List weaknesses addressed by a given mitigation | | solveit_get_techniques_for_mitigation | List techniques related to a given mitigation |

Search (1 tool)

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

Extension Info (1 tool)

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

Citations (2 tools)

| Tool | Description | |---|---| | solveit_get_citation | Retrieve a citation by its DFCite ID | | solveit_list_citations | List all citation IDs in the knowledge base |

Status (1 tool)

| Tool | Description | |---|---| | solveit_status | Report data load status, item counts (including citations), and active configuration |

Full-Detail Listings

Note: These tools are disabled by default due to the large volume of data they return. They can be enabled 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 |

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

| 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

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                — Initializes the SOLVE-IT data loader on startup
    tools/
      solveit_tools.py             — All 21 SOLVE-IT tool registrations and handlers
  middleware/
    pipeline.py                    — Security middleware pipeline
  security/                        — Rate limiting, sanitization, validation, profiles
  transport/                       — Stdio transport (production)
config/
  default.toml                     — Server and application configuration
tests/
  unit/                            — Unit tests
  integration/                     — Integration tests (stdio subprocess)
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"]
    }
  }
}