itsoc_mcp — a read-only MCP server over the local analysis backend

mcp-name: io.github.Ankit512/itsoc-mcp

itsoc_mcp exposes this project's existing log-analysis capabilities as Model Context Protocol tools, so an MCP-capable agent (Claude Code / Claude Desktop) can drive them. It is an isolated sibling package: it imports nothing from anomaly_detector.py, changes no /api/* route, and adds no dependency to the core backend.

What it is (and is not)

• A client, not a brain. Every tool proxies the already-running local backend (http://127.0.0.1:8765 by default). This server computes no verdicts: severities, correlation, and rule verdicts are owned by the frozen deterministic detector on the backend. Tools relay; they never re-decide.
• Read-only. No tool writes, remediates, or acts. analyze_log starts an analysis (the one existing "write" the API offers) and explain_finding requests an advisory explanation via the existing endpoint — an explanation never changes, suppresses, or escalates a verdict.
• Honest by construction. Backend null / "0 lines parsed" / idle states are passed through verbatim — never a fabricated all-clear or an empty file.
• Redacted by default. Any field carrying raw log text is masked through the project's existing egress choke point (console/redact.py) before it leaves, unless you opt into a trusted local session (see below).

Every tool response carries a provenance block stating: verdicts are deterministic/rule-owned, explanations are advisory, MITRE tags are derived (not verdicts), plus the running detector's detector_sha256.

Tools

Install

The core backend stays stdlib-only — do not install anything to run it. Install the MCP SDK only if you want to run this server:

pip install -r itsoc_mcp/requirements-mcp.txt   # the `mcp` SDK, and nothing else

Run

1. Start the backend (from the repo root), stdlib-only, no extra installs:

   python3 console/serve.py           # serves http://127.0.0.1:8765
   

2. Launch the MCP server over stdio (from the repo root):

   python -m itsoc_mcp
   

Configuration (environment)

Register with an MCP client (stdio)

Paste into your MCP client config (e.g. Claude Desktop's claude_desktop_config.json, or .mcp.json for Claude Code). Replace /ABSOLUTE/PATH/TO/log-analyzer with the repo root:

{
  "mcpServers": {
    "itsoc": {
      "command": "python",
      "args": ["-m", "itsoc_mcp"],
      "cwd": "/ABSOLUTE/PATH/TO/log-analyzer",
      "env": {
        "ITSOC_BASE_URL": "http://127.0.0.1:8765"
      }
    }
  }
}

To allow raw evidence/export on a trusted local machine, add "ITSOC_MCP_TRUSTED_LOCAL": "1" (and optionally "ITSOC_STIX_BUNDLE": "...") to that env block. The backend (python3 console/serve.py) must be running.

Tests

Network-free, no SDK, no ATT&CK cache required — the client is faked and the offline mapper is stubbed:

python3 itsoc_mcp/test_mcp.py

It asserts each tool's shape, that get_evidence/get_findings/explain_finding are redacted by default and raw only with ITSOC_MCP_TRUSTED_LOCAL=1, and that idle/unrecognized/error states return honest errors, not empty payloads.

Standalone install (uvx / pipx)

pyproject.toml builds an itsoc-mcp distribution with an itsoc-mcp console script (itsoc_mcp.server:main) and pins mcp>=1.0,<2 — MCP clients speak the stable 1.x API; mcp 2.0 changed the server API. The package is self-contained: it runs with no repo checkout.

uvx itsoc-mcp        # or: pipx run itsoc-mcp   (the backend must still be running)

Two honesty points, stated plainly:

• The egress guard is never weakened standalone. Redaction has a single source of truth — console/redact.py — used whenever the repo is importable. In a bare install it falls back to a verbatim vendored mirror (_redact_vendored.py) that masks identically (redact-by-default; raw only with ITSOC_MCP_TRUSTED_LOCAL=1). A drift-guard test asserts the two never diverge, so the vendored copy can never silently mask less. redaction.redact_source() reports which is active. If neither could load, the module fails to import rather than pass text through — it fails closed, never open.
• threat_intel_lookup needs the repo. Its offline STIX→MITRE path reuses the repo's sibling threat_intel/ package, which a bare install does not ship. In a standalone install that one tool fails closed with an honest "offline threat-intel unavailable … NOT a clean verdict / not an all-clear" message — never a fabricated match or a fake all-clear. Run from the repo (python -m itsoc_mcp) to use offline threat-intel. Every other tool is a client of the backend API and works identically standalone or in-repo.

Standalone means no repo checkout is needed for the MCP package — the backend (python3 console/serve.py) still runs separately and must be reachable at ITSOC_BASE_URL.

License

MIT — see the repository's top-level LICENSE.

License

MIT — see the repository's top-level LICENSE.