Knossos-MCP
The labyrinth mapped once, so nobody has to wander it again.
Knossos (Κνωσός) is the Bronze Age palace at the heart of Minoan Crete, a complex so sprawling that Greek myth remembered it as the Labyrinth, the maze Daedalus built for the Minotaur, which no one could navigate without a thread to follow back out. Ariadne handed Theseus that thread.
What it does
Knossos-MCP 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; what static analysis cannot prove is labelled with its confidence instead of being guessed.
Scanning never installs dependencies, imports a module, or boots an application framework: workers run supervised, resource-capped, and their output only counts once it passes a schema and limit check. Thirty-three MCP tools cover orientation, projects and history, finding and reading components, structure and impact analysis, and maintenance; only server_info has no CLI equivalent. The four write tools preview by default and only apply once you pass execute explicitly.
Quick start
Knossos-MCP is not yet published to Packagist or any container registry, so build the image yourself from source. The recommended distribution is Docker: it pins PHP, Node, 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 --jsonExamples
Two calls, both run for real against Knossos-MCP's own source, abridged with '…'.
Scanning the repository:
$ knossos scan . --json
{"summary":"Scanned 394 files into 5446 nodes and 31972 relationships.",
"data":{"files":394,"nodes":5446,"edges":31972,"diagnostics":0,"mode":"full",
"scanner_metadata":{"knossos.php":{"files_scanned":372},
"knossos.typescript":{"files_scanned":17,"programs":1},
"knossos.python":{"files_scanned":5,"parser":"python.ast"}},
"metrics":{"elapsed_ms":7443.85, …}}}Orienting yourself in the resulting graph:
$ knossos architecture-summary project_1b4f41… --json
{"summary":"Knossos-MCP contains 5446 nodes and 31972 relationships.",
"data":{"node_kinds":[{"kind":"method","count":3814},{"kind":"class","count":415},
{"kind":"external_method","count":378},{"kind":"external_function","count":297},
{"kind":"property","count":205}, …],
"languages":[{"kind":"php","count":372},{"kind":"javascript","count":17},{"kind":"python","count":5}]}}Capabilities
| Category | Tools (selection) | What it answers |
|---|---|---|
| Orientation | server_info, diagnose_runtime | Which roots are readable, whether the runtimes are healthy |
| Projects and history | scan_project, list_snapshots, snapshot_diff, quality_gate | Build or refresh the graph, what changed between two scans, whether a change breaches architecture budgets |
| Finding and reading components | find_component, inspect_component, list_usages, architecture_summary | Ranked candidates from a partial name, a component's roles and relations, every usage with evidence |
| Structure and impact analysis | impact_analysis, explain_flow, dependency_cycles, change_impact, test_impact, review_diff | What depends on a symbol, how A reaches B, circular dependencies, the blast radius of a change, which tests it touches |
| Maintenance | annotate_component, remove_project, cleanup_stale_scans, maintain_database | Recording a durable annotation, cleaning up projects, checking database integrity |
| Language | Extraction | Framework enrichment |
|---|---|---|
| PHP 8.3+ | Declarations, inheritance, calls, construction, types, injection | Laravel, Symfony |
| TypeScript/JavaScript | Compiler symbol resolution, imports, calls, types | Next.js, React, Vue, stores, endpoints |
| Python 3.11+ | Standard-library AST, run in an isolated interpreter | FastAPI, Django, Celery |
Mixed repositories reconcile into one graph. impact_analysis and related tools label every conclusion with a confidence: certain, probable, or possible.
Configuration
Knossos-MCP reads knossos.json (or knossos.jsonc) from the scanned project's root. This is Knossos-MCP's own configuration:
{
"$schema": "./schemas/project-config-v1.schema.json",
"version": 1,
"ignores": ["tests/Fixtures"],
"boundaries": [
{ "name": "core", "path_prefix": "src" },
{ "name": "php-worker", "path_prefix": "workers/php" },
{ "name": "typescript-worker", "path_prefix": "workers/typescript" },
{ "name": "python-worker", "path_prefix": "workers/python" },
{ "name": "tooling", "path_prefix": "tools" },
{ "name": "tests", "path_prefix": "tests" }
],
"policies": [
{
"id": "workers-are-out-of-process",
"from_boundary": "php-worker",
"deny_targets": ["core"]
}
],
"quality_budgets": {
"new_cycles": 0,
"boundary_violations": 0,
"error_diagnostics": 0,
"warning_diagnostics": 0,
"hub_degree_growth": 25,
"unreferenced_candidates": 110
}
}boundaries divides the codebase into named regions; policies forbids specific relationships between them, and check_architecture checks every change against them. quality_budgets sets hard thresholds on regressions such as new circular dependencies or boundary violations, enforced by quality_gate.