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 capability is available both as an MCP tool and as an equivalent CLI command. See the documentation index for the full map.

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-one MCP tools, each 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.

Projects and history

Finding and reading components

Structure and change analysis

Maintenance

CLI-only helpers round this out: doctor verifies the runtime, workers, protocol, and database; watch rescans on change; export-bundle and import-bundle move a graph between databases; serve starts the MCP server. Full input schemas are in the MCP tool reference and CLI reference.

Quick start

The recommended distribution is Docker: it pins PHP 8.4, Node 24, Python, 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.
• --allow-root is a security boundary, not a convenience flag. serve refuses to start without one.
• 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.