MCP Project Context Router

Project Context Router

A local-first CLI and Model Context Protocol server that gives coding agents structured project memory, task contracts, compact context packs, backlog workflows, and verification evidence.

The router keeps durable knowledge in reviewable Markdown and YAML inside the consumer repository. A disposable SQLite index makes retrieval fast without turning an external service into the source of truth.

Status: active development. The current package is [email protected], requires Node.js 22.13 or newer, and is distributed from source or a versioned tarball. It is not currently published to an npm registry.

See the changelog and GitHub releases for versioned changes and installable tarballs.

Website and documentation

• English website · English documentation
• Сайт на русском · Документация на русском

Both languages cover installation, project stacks, agent workflow, tools and records, and upgrading/troubleshooting. The language switch keeps the current topic. Source pages are in site/content/en and site/content/ru; edit both translations when behavior changes. GitHub Actions builds and deploys site/dist to GitHub Pages after changes land on main. The website is excluded from the npm package.

To preview locally after npm ci:

npm run site:build
npm run site:check
npm run site:preview

Open http://127.0.0.1:4179/. Rebuild and refresh after editing Markdown or assets.

Why use it?

• Keep project memory versioned beside the code that it describes.
• Give agents a focused context pack instead of an unbounded repository dump.
• Validate and confirm a Task Contract before implementation begins.
• Search existing capabilities before adding duplicate code.
• Track backlog state, dependencies, decisions, and verification evidence.
• Expose the same workflow through a human-friendly CLI and MCP tools.
• Keep generated drafts and indexes out of version control and package artifacts.

Quick start

Install directly from GitHub in the repository that should own the project context:

npm install --save-dev --save-exact https://github.com/ukolov-dev/mcp-project-context-router/releases/download/v0.10.1/mcp-project-context-router-0.10.1.tgz
npx project-context init --name "Example Project" --module app:src
npx project-context index
npx project-context doctor --json
npx project-context hooks install

init is non-destructive: it does not overwrite an existing configuration. To install the bundled agent skills as well, add --with-skills:

npx project-context init --with-skills

This works for an already initialized project. It copies project-context-workflow and context-research into .agents/skills/<name>/SKILL.md for repository-scoped Codex discovery. Plain init installs no skills. Existing files are preserved and listed in skipped; review the output and commit the shared skills if your team wants them. Updating the npm package does not replace installed skill copies.

project-context-workflow guides task contracts, scoped context, reuse checks, verification and finalization. context-research guides idea exploration and backlog handoff. Skills provide instructions; connect the MCP server separately and select the tool profile needed by the task. See the workflow skill and Codex setup.

Review .project-context/project.yaml after generation and replace the example modules, source globs, playbooks, and verification commands with real project values.

hooks install creates a managed .githooks/pre-commit, configures the local clone's core.hooksPath, and records that wiring in project.yaml. The hook runs doctor --commit before every commit and blocks the commit when mappings are invalid or context records reference missing, non-file, or out-of-repository paths. Existing custom pre-commit hooks are never overwritten; merge the doctor command manually when one is already present.

Optional Codex lifecycle hooks

npx project-context init --with-hooks --with-skills

--with-hooks creates repository-local .codex/hooks.json with UserPromptSubmit, PostToolUse and Stop. Plain init installs no lifecycle hooks. Existing hook files and project configuration are preserved and reported in skipped; merge the bundled template manually if you already have hooks. Keep the package installed locally and use a Git checkout; commands resolve the repository root even when Codex works in a subdirectory. Standalone exports use their own hooks/ directory.

Review the commands, trust the project, and review/trust the exact hook definitions in Codex (/hooks in the CLI). Restart or reconnect the client as needed. Installation does not grant trust or prove hooks are active; see the official Codex hooks guide.

The prompt hook supplies workflow hints. The tool hook fingerprints staged, unstaged, untracked and deleted files. The Stop hook checks every confirmed task whose declared files overlap changes: save fresh record_verification_evidence, then call finalize_work. All required checks must pass, or the result must explicitly be partial/blocked with a reason for every unresolved check (checks[].reason in evidence or skippedChecks: [{command, reason}] in finalization). A bare finalization timestamp is insufficient. New source edits invalidate evidence; reading tools and generated task/evidence/index records do not. Repeated Stop events continue to block missing evidence.

Hooks validate reported evidence; they do not run tests, independently accept work, close tasks, or intercept every possible client operation. completion: "complete" still requires an independently accepted execution run. An explained partial result permits a final response without claiming completion. The Git pre-commit check remains a separate npx project-context hooks install command.

Hook state is disposable under ignored .project-context/indexes/hook-state/; inactive session files expire after seven days. For a storage/configuration error, repair the reported path and retry. Existing installed hook copies/configuration are never silently upgraded; compare them with the bundled template after package updates.

A typical agent workflow then looks like this:

npx project-context validate-task "Add CSV export" --mode feature
npx project-context pack "Add CSV export" --workflow standard --explain
npx project-context reuse-scan "CSV export"
npx project-context verify-task "CSV export"

Run npx project-context --help for the complete CLI surface.

Connect your coding agent

The package includes client-specific setup guides and copy-ready configuration templates:

Release 0.10.1 includes ZCode and official DeepSeek Harness support. Install the release package above and initialize explicitly:

npx project-context init --client zcode --with-skills
npx project-context init --client deepseek-harness --with-skills --with-hooks

Choose the command for your client. ZCode skills go to .zcode/skills; DSH uses .agents/skills. DSH loads its overlay with dsh web --patch "$PWD/.dsh/project-context.cordis.yml". ZCode ignores project hooks, so its --with-hooks request is rejected before writes; reviewed user-level hooks are documented in its guide. Existing client files are preserved and reported in skipped; merge templates manually when needed. Plain init keeps its previous behavior. Explicit --client codex additionally copies the existing Codex MCP template.

A complete Russian-language OpenCode guide is also available: Использование в OpenCode. The Russian workflow and artifact guide explains what is created at each task stage and what an agent receives before implementation.

These configurations start the same local stdio MCP server from the consumer repository. They contain no credentials or workstation-specific absolute paths. Codex uses .codex/config.toml; OpenCode uses opencode.json at the repository root. The two OpenCode schemas are intentionally separate because stable and V2 currently use different MCP nesting and enablement fields.

The server supports scoped tool profiles:

core is the default. The legacy PPM_CONTEXT_TOOL_PROFILE variable remains supported for compatibility.

Research preserves idea discussions, findings, status changes and conclusions separately from implementation tasks, then creates linked backlog drafts. See the research workflow and the portable Codex skill.

Local search and context packs also support an experimental, opt-in fts5 engine with a partial-identifier reserve. The existing current engine remains the default. FTS5 requires a runtime compiled with SQLite FTS5 (verified with Node.js 22.23.2); Node.js 22.13.0 supports the default mode and falls back with a pack warning. Use project-context pack "quick_valid" --search-engine fts5 --max-tokens 4000 or pass searchEngine: "fts5" to build_context_pack. See the SQLite search modes and evaluation.

Release 0.10.1 also routes exact task/backlog keys before module fallback and improves task ranking. See the release notes.

Configure your project stack

There is no language switch: discovery runs automatically for files selected by modules.*.source_globs in .project-context/project.yaml. Project memory, task contracts and context packs work independently of the application stack. The router itself requires Node.js 22.13+ and npm, even when the application uses another language.

For a repository without package.json, run npm init -y before the install command in Quick start. This adds the router's Node tooling beside your existing application build; keep the resulting package manifest and lockfile in the consumer repository.

To update an existing GitHub installation to the current main code:

npm install --save-dev --save-exact github:ukolov-dev/mcp-project-context-router#main

Review the changed lockfile and restart any running router MCP server so it loads the updated package. Versioned release tarballs contain the code from their tag; updating to main may include changes published after the latest release.

After installing the router, initialize from the consumer repository root:

npx project-context init --name "My Project" --module backend:src

Choose the initial module for the example layout you use:

init preserves existing configuration. Add or update the relevant blocks below in .project-context/project.yaml; keep other project settings and replace example paths and commands with your own. Explicit source_globs replace the module's defaults, so include every source path you need. Choose routing.default_modules for your project's default area.

C# / .NET

The default globs already include .cs. This example assumes solution projects under src/ and a solution at the repository root:

routing:
  default_modules: [backend]
modules:
  backend:
    path: src
    aliases: [backend, api, csharp, dotnet]
    source_globs:
      - "src/**/*.cs"
      - "!src/**/obj/**"
      - "!src/**/bin/**"
    playbooks: [AGENTS.md]
commands:
  backend_build:
    run: dotnet build
    required_for: [backend]
    context_pack: true
  backend_tests:
    run: dotnet test
    required_for: [backend]
    context_pack: true

Discovery recognizes common class, struct, record, interface and enum declarations, constructors, methods and properties, including multiline declarations. ASP.NET Core controller routes support literal Route, HttpGet, HttpPost, HttpPut, HttpPatch, HttpDelete, HttpHead and HttpOptions attributes, [controller] / [action] tokens, and absolute action routes. Computed templates and non-public, static or NonAction methods are skipped.

This is a text heuristic, not Roslyn. It does not resolve inheritance, conditional compilation, custom routing conventions, every C# declaration form, or Minimal API endpoints. Raw/interpolated route strings and complex attribute combinations are outside this basic coverage.

Java / Spring

Maven and Gradle use the same source module configuration. The examples below assume the application/build files are under backend/ and the selected wrapper is at the repository root; adjust both paths to match your layout.

Maven

routing:
  default_modules: [backend]
modules:
  backend:
    path: backend
    aliases: [backend, api, java, spring]
    source_globs:
      - "backend/src/**/*.java"
    playbooks: [AGENTS.md]
commands:
  backend_verify:
    run: ./mvnw -f backend/pom.xml verify
    required_for: [backend]
    context_pack: true

Gradle

Keep the Java module above and replace its commands block with:

commands:
  backend_verify:
    run: ./gradlew -p backend build
    required_for: [backend]
    context_pack: true

This also works with Kotlin DSL build.gradle.kts; the selected source files in this example remain Java. For a Gradle multi-project build rooted at the repository root, use its actual task path, for example ./gradlew :backend:build, instead of treating the subproject as a separate build. On Windows, use mvnw.cmd or gradlew.bat in place of the shell wrapper. See the official Gradle CLI and wrapper guide.

Discovery recognizes class, record, interface and enum declarations, plus simple Spring MVC RequestMapping and Get/Post/Put/Patch/DeleteMapping annotations with literal routes. It does not provide Java method discovery, compiler-level analysis, or complete Spring routing resolution.

Frontend / TypeScript / JavaScript

This example assumes a frontend package under frontend/ with build and test scripts. It includes src/ and root-level Next.js app/ or pages/ directories when present:

routing:
  default_modules: [frontend]
modules:
  frontend:
    path: frontend
    aliases: [frontend, web, react, next, ui]
    source_globs:
      - "frontend/src/**/*.{ts,tsx,js,jsx,mjs,cjs,mts,cts}"
      - "frontend/{app,pages}/**/*.{ts,tsx,js,jsx}"
    playbooks: [AGENTS.md]
commands:
  frontend_build:
    run: npm --prefix frontend run build
    required_for: [frontend]
    context_pack: true
  frontend_tests:
    run: npm --prefix frontend test
    required_for: [frontend]
    context_pack: true

Use your project's non-interactive test command and package manager. Discovery recognizes function, constant, type and interface declarations using text rules; it classifies common use* functions as hooks and capitalized functions as components. It does not resolve imports, infer framework routes, or fully parse JSX, Vue/Svelte components or TypeScript semantics.

Node.js backend / TypeScript / JavaScript

This example assumes a Node.js service in backend/ with sources in src/ and existing build and test npm scripts:

routing:
  default_modules: [backend]
modules:
  backend:
    path: backend
    aliases: [backend, api, node, nodejs, javascript, typescript]
    source_globs:
      - "backend/src/**/*.{ts,js,mjs,cjs,mts,cts}"
    playbooks: [AGENTS.md]
commands:
  backend_build:
    run: npm --prefix backend run build
    required_for: [backend]
    context_pack: true
  backend_tests:
    run: npm --prefix backend test
    required_for: [backend]
    context_pack: true

Node.js uses the same TS/JS discovery rules as the frontend example; Express, Fastify and other framework routes are not automatically resolved. For plain JavaScript without a build script, omit backend_build. If the service is at the repository root, use path: ., src/**/*.{ts,js,mjs,cjs,mts,cts} globs and commands without --prefix. Use the project's actual scripts and package manager.

Python

This example assumes sources in src/, tests in tests/, and pytest already installed in the active Python environment:

routing:
  default_modules: [app]
modules:
  app:
    path: .
    aliases: [app, backend, api, python]
    source_globs:
      - "src/**/*.py"
      - "tests/**/*.py"
    playbooks: [AGENTS.md]
commands:
  python_syntax:
    run: python -m compileall -q src tests
    required_for: [app]
    context_pack: true
  python_tests:
    run: python -m pytest tests
    required_for: [app]
    context_pack: true

Use the interpreter/environment and test runner already used by your project; replace python with python3 where appropriate. compileall checks syntax and writes bytecode caches, so keep __pycache__/ and *.pyc out of Git. It does not replace linting, type checks or tests. Command references: compileall and pytest.

Python discovery recognizes def / async def functions, class methods and classes, including decorated and multiline headers and generic type parameters. Explicit aliases declared with type Name = ... or Name: TypeAlias = ... are indexed as types. Leading underscores are treated as private by convention; __all__, decorator effects and inferred assignment aliases are not resolved.

Go

This example assumes go.mod at the repository root:

routing:
  default_modules: [app]
modules:
  app:
    path: .
    aliases: [app, backend, api, go, golang]
    source_globs:
      - "**/*.go"
      - "!vendor/**"
    playbooks: [AGENTS.md]
commands:
  go_build:
    run: go build ./...
    required_for: [app]
    context_pack: true
  go_tests:
    run: go test ./...
    required_for: [app]
    context_pack: true

For multiple Go modules, configure their actual source paths and run checks from each module directory. The commands above target the module rooted in the current directory. See the official Go command reference.

Go discovery recognizes named functions, methods with receivers, generic functions/types, struct/interface declarations, named types and aliases, including type (...) groups. Names beginning with an uppercase letter are marked exported. Interface member signatures and compiler/build-tag semantics are outside this basic declaration coverage.

Rust

This example assumes a Cargo package with Cargo.toml at the repository root:

routing:
  default_modules: [app]
modules:
  app:
    path: .
    aliases: [app, backend, rust, cargo]
    source_globs:
      - "**/*.rs"
      - "!target/**"
    playbooks: [AGENTS.md]
commands:
  rust_check:
    run: cargo check --all-targets
    required_for: [app]
    context_pack: true
  rust_tests:
    run: cargo test
    required_for: [app]
    context_pack: true

cargo check checks the package without producing the final executable. For a workspace, add --workspace to both commands when all members must be checked. See the official cargo check and cargo test references.

Rust discovery recognizes functions and methods in impl / trait blocks, structs, enums, traits, unions and type aliases. Common generics, lifetimes, raw identifiers and function qualifiers are accepted. Visibility reflects explicit pub and public trait items; restricted pub(crate) / pub(super) items are not marked externally exported. macro_rules! definitions and macro invocations are skipped.

All three languages have dedicated declaration extractors, selected automatically for .py, .go and .rs sources. Comments and string literals are masked before discovery; symbols feed the same SQLite index, reuse scans and context packs as other languages. Existing consumer indexes refresh after this extractor upgrade. These are bounded text parsers, not compiler frontends: they do not resolve imports, inheritance, generated symbols, macro expansion, conditional compilation, framework endpoints or the entire language grammar. A missing reuse-scan result does not prove that an implementation is absent; inspect the code and use reviewed context records or pack --file hints when needed.

For a monorepo, combine the relevant module/command blocks under one modules and one commands mapping. Use distinct module names and actual service paths when multiple examples would otherwise share app or backend. Add a separate module or globs for tests and documentation if they live outside the selected source paths. Use AGENTS.md in playbooks only when that file exists in the consumer repository; otherwise use your actual instruction files or playbooks: [].

Index and check the configuration

From the consumer repository root, after editing the configuration:

npx project-context index
npx project-context doctor --json
npx project-context reuse-scan "CustomerService" --modules backend
npx project-context pack "Update customer API" --modules backend

For frontend-only projects, use --modules frontend and a component or hook name. For Python, Go or Rust, use --modules app and your function/type names. An explicit source path can also be supplied, for example:

npx project-context pack "Update customer service" --modules app --file src/customer.py

Replace that path with an existing .py, .go or .rs file in your repository. Source edits and discovery-rule upgrades refresh the index automatically; index also lets you rebuild it explicitly. Configured build/test commands are verification guidance; indexing does not compile or execute the application.

How data is laid out

.project-context/
├── project.yaml       # routing, modules, commands, and project identity
├── active/            # reviewed, durable project records
├── drafts/            # reviewable generated proposals (ignored)
├── indexes/           # rebuildable SQLite/cache data (ignored)
└── templates/         # Task Contract and Verification Record templates

Project data belongs to the consumer repository, not to this package. The configuration routes queries to modules and playbooks; the index adds fast retrieval; the CLI and MCP server apply the same workflow and repository-boundary checks.

Supported memory records

The router supports 13 record types: task, bug, decision, backlog, research, verification-evidence, agent-run, acceptance-review, project, requirement, open_question, source, and source_chunk.

Task acceptance criteria stay inside the Task Contract. finalize_work saves last_result on that same task; it no longer creates a separate run summary. Requirement traces match exact task IDs or explicit task_key / task_keys metadata. Portal work preserves its source document, revision and task code.

Current source retires the unused integration/API/data-entity/meeting/acceptance and module/pattern/runbook/refactor/summary record types. Existing files remain readable and archivable. Module routing and playbooks are project configuration. See migration and removed commands before updating consumers.

Task execution

Confirmed tasks can have execution manifests, evidence-gated states, and a separate acceptance review. An optional project-context run TASK-ID --adapter execution-adapter.json command previews external implementation and review commands; --execute runs the workflow in the current checkout. See the execution guide for the adapter protocol, CLI/MCP tools, verification gates, and retry behavior.

Safety model

• Repository-boundary and symlink-escape checks reject paths outside the project.
• Secret-like values are redacted from generated excerpts.
• Credentials are read from environment variables or supported native credential stores and are never written into exported project context.
• Indexes, drafts, trash, build outputs, and local environment files are ignored.
• The npm package allowlist excludes source-project records, credentials, source TypeScript, tests, and generated SQLite databases.
• Network integrations such as Confluence and Context Hub are optional and require explicit project configuration and credentials.

See SECURITY.md for vulnerability reporting.

Develop locally

git clone https://github.com/ukolov-dev/mcp-project-context-router.git
cd mcp-project-context-router
npm ci
npm run build
npm test
npm run package:check
node bin/project-context doctor --json

To exercise the installable artifact locally:

mkdir -p artifacts
npm pack --pack-destination ./artifacts

The tarball contains compiled runtime code, launchers, hooks, credential helper scripts, installation guides, consumer templates, and this README. It excludes .project-context, .codex, tests, source TypeScript, generated indexes, and node_modules.

Contributing

Read CONTRIBUTING.md before opening a change. The required handoff checks are npm run build, npm test, npm run package:check, and node bin/project-context doctor --json.

License

No open-source license has been granted yet. The package is marked UNLICENSED; public availability of the source does not grant permission to copy, modify, or redistribute it.

Upgrading to 0.7

See the 0.7 migration guide for configured routing, lifecycle-aware retrieval, actionable diagnostics, required verification and scoped review. Existing records are preserved. The sanitized audit plan maps findings to regression coverage.