Knossos MCP

Local-first architecture intelligence over MCP — scans a repository once and answers architecture questions from an evidence-backed graph.

Pre-release / in active development. Knossos is not yet published to Packagist or any container registry. The source is public on GitHub — build from source (see Quick start). Image names such as knossos-mcp:dev in this README are built locally by you; there is no docker pull to fetch them yet.

Knossos is a local-first MCP server that scans a repository once and answers architecture questions from an evidence-backed graph, so an agent stops re-reading the whole source tree to work out what depends on what.

Every fact points back to a file and a source location. Facts that static analysis cannot prove are labelled with their confidence and origin instead of being guessed. Nothing in the scan pipeline installs dependencies, imports a module, or boots an application framework.

What you can ask after one scan

• What are the major modules, entry points, and boundaries?

• What depends, directly or transitively, on UserRepository?

• What are the exact call sites of ScannerClient::scan?

• How can a checkout request reach invoice generation?

• Which relationships cross a declared boundary policy?

• Which test files exercise the blast radius of this diff?

• What does this working tree risk, reviewed architecturally in one call?

• Where would a refunds feature fit the existing structure?

Every query and analysis capability is available both as an MCP tool and as an equivalent CLI command; watch, serve, and the graph-bundle commands remain CLI-only. See the documentation index for the full map.

Related MCP server: code-context-mcp

Worked example

Scanning this repository takes about ten seconds and yields a graph you can interrogate. Output below is real, abridged with ….

$ knossos scan . --json
{"summary":"Scanned 402 files into 4965 nodes and 23126 relationships.",
 "data":{"files":402,"nodes":4965,"edges":23126,"diagnostics":20,"mode":"full",
 "scanner_metadata":{"knossos.php":{"files_scanned":353},
   "knossos.typescript":{"files_scanned":34,"programs":9},
   "knossos.python":{"files_scanned":15,"parser":"python.ast"}},
 "metrics":{"elapsed_ms":10541.0, …}}}

Orient yourself in a codebase you have never opened:

$ knossos architecture-summary project_1b4f41… --json
{"summary":"Knossos-MCP contains 4965 nodes and 23126 relationships.",
 "data":{"node_kinds":[{"kind":"method","count":3243},{"kind":"class","count":426},
   {"kind":"function","count":138},{"kind":"interface","count":15},
   {"kind":"route","count":12}, …]}}

Ask what breaks if you change an interface. Each dependant carries the edge that justifies it and the exact source line, so the answer is checkable:

$ knossos impact-analysis project_1b4f41… 'Knossos\Scanner\ScannerClient' --json
{"summary":"Found 37 potential static dependants within depth 4.",
 "data":{"target":{"kind":"interface","canonical_name":"Knossos\\Scanner\\ScannerClient", …},
   "dependants":[{"node":{"canonical_name":"Knossos\\Scanner\\Worker\\ProcessScannerClient", …},
     "distance":1,"path_confidence":"certain",
     "via":{"kind":"implements","origin":"ast",
       "explanation":"ProcessScannerClient depends through --implements (certain, ast)--> ScannerClient",
       "evidence":{"path":"src/Scanner/Worker/ProcessScannerClient.php","start_line":10}}}, …],
   "counts":{"by_distance":{"1":1,"2":8,"3":2,"4":26},
     "by_confidence":{"certain":12,"probable":25,"possible":0}}, …}}

dependants is a flat, BFS-ordered list rather than grouped by distance; sort or filter on the distance and path_confidence fields directly. MCP tool calls default to a compact verbosity that agents should prefer over --json: it hoists each repeated node (and target) object into a one-time component_legend keyed by canonical name, leaving a plain name string behind wherever the node appeared, and shortens each via object down to just its edge kind (e.g. "via":"implements").

Find refactor targets without shelling out to wc and find:

$ knossos file-metrics project_1b4f41… --limit=3 --json
{"summary":"3 of 402 files by line_count desc.",
 "data":{"files":[{"path":"tests/phpunit/Reconciliation/GraphReconcilerTest.php","language":"php","line_count":1666},
   {"path":"src/Mcp/ToolService.php","language":"php","line_count":1426},
   {"path":"tests/phpunit/Cli/CommandsTest.php","language":"php","line_count":1354}]}}

Answers that rest on inference say so. impact-analysis returns the warning "Impact is a conservative static blast radius; it does not guarantee that a dependant will break", and dead-code candidates report absence of evidence rather than proven absence.

Tools

Thirty-three MCP tools, all but server_info with an equivalent CLI command. Read tools are annotated read-only and idempotent. The four write tools — annotate_component, remove_project, cleanup_stale_scans, and maintain_database — preview by default and only apply once called with execute set; remove_project and cleanup_stale_scans are additionally annotated destructive. The server also exposes per-project MCP resources (summary, boundaries, brief) and prompts (orient, review_diff); these are MCP-protocol surfaces with no CLI equivalent. Agent annotations (intended_boundary, confirmed_dead, false_positive, note) record a durable judgment on a component that survives rescans; a false_positive annotation removes that component from future dead-code candidates.

Orientation

Projects and history

Finding and reading components

Structure and change analysis

Maintenance

Three helpers remain CLI-only: watch rescans on change, export-bundle and import-bundle move a graph between databases, and serve starts the server itself. doctor is also available over MCP as diagnose_runtime. Full input schemas are in the MCP tool reference and CLI reference.

Quick start

The recommended distribution is Docker: it pins PHP 8.5, Node 26, Python 3.13, Composer, SQLite, the PHP parser, and the TypeScript compiler, so the scanned project needs none of them.

docker build -t knossos-mcp:dev .
docker run --rm knossos-mcp:dev doctor --json

Scan a project with networking disabled and the source mounted read-only:

docker run --rm --network none \
  --mount type=bind,source=/absolute/project,target=/workspace,readonly \
  --mount type=volume,source=knossos-data,target=/data \
  knossos-mcp:dev scan /workspace --json

Recover persisted project IDs later without exposing absolute roots:

docker run --rm \
  --mount type=volume,source=knossos-data,target=/data \
  knossos-mcp:dev list-projects --json

Register the server with an MCP client, and grant the narrowest readable tree:

{
    "mcpServers": {
        "knossos": {
            "command": "php",
            "args": ["bin/knossos", "serve", "--allow-root=."]
        }
    }
}

Docker, native, and client-specific variants are in installation.

Supported languages

Mixed repositories reconcile into one graph. Third-party scanners plug in as isolated worker processes through the scanner SDK.

Safety model

• Scanning never installs dependencies, executes project code, or boots a framework; workers are supervised, resource-capped, and their output is untrusted until it passes schema and limit validation.

• The allow-list is a security boundary, not a convenience. serve refuses to start with no root from --allow-root, KNOSSOS_ALLOWED_ROOTS, or the roots file. That file is re-read per request so one installation can serve every project; Knossos only ever reads it, so widening the boundary stays a deliberate act recorded on disk.

• The SQLite database is derived and rebuildable; source mounts stay read-only. The one exception is architecture_context's opt-in include_source, which reads a bounded query-time excerpt (≤40 lines, files ≤2MB) through the same root-guard as scanning and degrades to unavailable rather than failing, so it does not require write access.

• MCP stdio is the default and recommended transport. The constrained loopback-only Streamable HTTP profile and its deployment limits are documented in the HTTP threat model.

• Failed work is never activated: the last complete scan remains the queryable graph. See the fault recovery matrix.

Documentation

docs/README.md is the index. The most-used entries:

• Installation and MCP configuration

• Checked-in project configuration

• Running in Docker

• CLI reference and MCP tool reference

• Troubleshooting and migrations

Development

One versioned quality profile runs locally, in Git hooks, and in CI:

tools/quality-container fast
tools/quality-container full

fast covers linting, static analysis, formatting, hygiene, and the whole test suite; full adds security audits, coverage floors, performance budgets, mutation score, and supply-chain assurance. Details are in quality gates.

See CONTRIBUTING.md for the contribution workflow, the Conventional Commit prefixes that drive releases, and how to add a language scanner.

License

MIT.