# Project Context Router

[![CI](https://github.com/ukolov-dev/mcp-project-context-router/actions/workflows/ci.yml/badge.svg)](https://github.com/ukolov-dev/mcp-project-context-router/actions/workflows/ci.yml)
[![Node.js 22.13+](https://img.shields.io/badge/Node.js-22.13%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-5A67D8)](https://modelcontextprotocol.io/)

A local-first CLI and [Model Context Protocol](https://modelcontextprotocol.io/)
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
> `mcp-project-context-router@0.7.1`, 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](CHANGELOG.md) and [GitHub releases](https://github.com/ukolov-dev/mcp-project-context-router/releases)
for versioned changes and installable tarballs.

## 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:

```bash
npm install --save-dev --save-exact github:ukolov-dev/mcp-project-context-router
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.
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.

A typical agent workflow then looks like this:

```bash
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:

| Client | Setup guide | Configuration template |
| --- | --- | --- |
| Codex desktop, CLI, and IDE | [Install for Codex](docs/install/codex.md) | [`templates/client-configs/codex.toml`](templates/client-configs/codex.toml) |
| OpenCode stable | [Install for OpenCode](docs/install/opencode.md) | [`templates/client-configs/opencode.json`](templates/client-configs/opencode.json) |
| OpenCode V2 preview | [OpenCode V2 notes](docs/install/opencode.md#opencode-v2-preview) | [`templates/client-configs/opencode-v2.json`](templates/client-configs/opencode-v2.json) |

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

All three 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:

| Profile | Intended use |
| --- | --- |
| `core` | Task contracts, context packs, reuse scans, verification, refactor review, and finalization |
| `planning` | `core` plus research history, research-to-backlog handoff, and backlog lifecycle |
| `developer` | `core` plus assigned-work acceptance and implementation reports |
| `analyst` | `core` plus research, requirements, source traceability, analyst packs, and Confluence publishing |
| `admin` | `core` plus research, backlog lifecycle, promotion, retention, and decision management |
| `full` | The complete compatibility surface |

`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](docs/research.ru.md) and the portable
[Codex skill](templates/skills/context-research/SKILL.md).

## How data is laid out

```text
.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.

## 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](docs/execution.md) 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](SECURITY.md) for vulnerability reporting.

## Develop locally

```bash
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:

```bash
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](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](docs/upgrade-0.7.md) for configured routing, lifecycle-aware retrieval, actionable diagnostics, required verification and scoped review. Existing records are preserved. The [sanitized audit plan](docs/reliability-audit.md) maps findings to regression coverage.