Project Context MCP

project-context-mcp is an evidence-first local MCP server and CLI for navigating codebases. It performs deterministic status checks, exact and semantic search, bounded source reads, optional source-backed tracing adapters, and explicit handoff access.

It is designed to keep source evidence local: the tool talks only to the local or self-hosted services you configure. Search results include source paths and line ranges so an agent or developer can verify the underlying code.

Features

Capability	What it does
Exact search	Fast, deterministic rg search with configured source and exclusion rules.
Semantic search	Project-isolated embeddings in a persistent local vector store by default, validated against current file hashes.
Graph tracing	Optional language adapters return source-backed callers, callees, inheritance, and implementation relationships.
Bounded reads	Reads only configured project files and returns a limited source range.
Handoffs	Lists, reads, creates, and updates explicit Markdown handoff documents safely.

Quick start

Install the CLI globally:

npm install --global project-context-mcp
pctx --help

pctx is the short CLI alias. project-context-mcp remains available as the fully qualified command.

To enable C# tracing, install the optional C# adapter alongside the core:

npm install --global project-context-mcp-csharp

To enable TypeScript and JavaScript tracing, install the optional TypeScript adapter:

npm install --global project-context-mcp-typescript

Unity projects can add asset-graph tracing, and repositories with Git history can add change-impact analysis:

npm install --global project-context-mcp-unity
npm install --global project-context-mcp-git

Then add a .project-context.yml file to the project you want to inspect and run a status check:

pctx status /path/to/project
pctx index /path/to/project
pctx search /path/to/project "session restore" auto code 10
pctx update

On Windows, quote paths that contain spaces:

pctx status 'C:\work\my project'

Connect an MCP client

Add this standard MCP server entry to your client's configuration:

{
  "mcpServers": {
    "project-context-mcp": {
      "command": "project-context-mcp",
      "args": ["serve", "--mcp"]
    }
  }
}

The server exposes context_status, context_search, context_read, context_trace, context_impact, and the context_handoff_* tools. Start with context_status to confirm the selected project and local dependencies.

Requirements

• Node.js 20 or newer
• rg (ripgrep) for exact search
• An Ollama embedding model configured for semantic search

The core package runs status, exact search, and semantic search without .NET, TypeScript, or a language adapter. C# tracing additionally requires .NET 8 and the project-context-mcp-csharp adapter package. TypeScript and JavaScript tracing uses the TypeScript compiler bundled by the project-context-mcp-typescript adapter.

Semantic search requires an Ollama embedding model, but uses a persistent local vector store by default and does not require Milvus. Exact search, bounded reads, status checks, and handoff access do not require Ollama or Milvus. context_trace does not require either service.

Trace adapters

context_trace and project-context-mcp trace use an installed trace adapter. The core discovers the default C# and TypeScript candidates and any comma-separated package names in PROJECT_CONTEXT_TRACE_ADAPTERS. It selects the single adapter whose source extensions match the project, or requires language when several match. It never scans node_modules or installs packages automatically.

The TypeScript adapter is named project-context-mcp-typescript and handles TypeScript and JavaScript source files. Its canonical language is typescript, with javascript and js accepted as language aliases. JavaScript analysis enables allowJs for the requested JavaScript sources and respects the project's checkJs and JSDoc settings; dynamic runtime dispatch can produce partial results.

Without a compatible adapter, an explicit trace reports an installation hint. Automatic graph routing falls back to semantic search when tracing is unavailable or ambiguous. Pass an optional language after max-results to the CLI trace command, or the optional language field to context_trace.

The Unity adapter is named project-context-mcp-unity. Its YAML mode follows prefab, scene, ScriptableObject, .meta GUID, .asmdef, and .asmref links. Add Unity Assets paths to sources.code, then use unity as the trace language when another adapter also matches the project.

Project configuration

Configuration is optional. Create .project-context.yml in the target project root when you want to narrow the indexed sources or add project-specific exclusions. The example below contains only project-owned paths; it does not include a user home directory, account, token, or machine-specific setting.

version: 1
sources:
  code: [src]
  documents: [README.md, docs]
exclude:
  - node_modules/**
  - .git/**
  - "**/*.dll"
  - "**/*.keystore"

Semantic search services

Semantic search needs an Ollama embedding model that you operate and configure for the project. The vector store is local and persistent by default, so no Milvus service is needed.

services:
  ollama:
    embeddingModel: <installed-embedding-model>

Milvus opt-in

Use Milvus only when you explicitly select it. Configure the address for the Milvus service you operate:

services:
  vectorStore:
    backend: milvus
  milvus:
    address: <milvus-address>

For legacy compatibility, a configuration that contains services.milvus but does not set services.vectorStore.backend continues to select Milvus. When both are present, the explicit services.vectorStore.backend value wins.

Switching vector-store backends requires reindexing. Existing data in the old backend is not deleted or migrated automatically.

Optional handoff documents

Handoff documents are disabled by default because they live in user-level storage. Enable them only when you want this project to index its own handoff documents, and choose a project slug that is unique on your machine:

sources:
  handoff:
    enabled: true
    projectSlug: example-project

Add every credential-bearing, generated, or third-party path to exclude before indexing. The same policy is enforced by exact search, reads, indexing, semantic evidence, and C# tracing. The indexer never writes project source files.

PROJECT_CONTEXT_MILVUS_TOKEN enables authenticated Milvus access. PROJECT_CONTEXT_STATE_ROOT and PROJECT_CONTEXT_HANDOFF_ROOT redirect local state and handoff storage for tests or automation; typical installations do not need them.

Unity batch mode

YAML analysis requires no Unity installation. For importer-aware dependencies, configure a Unity Hub Editor version and batch mode:

adapters:
  unity:
    mode: batch
    editorVersion: 6000.0.32f1
    batchTimeoutSeconds: 180

The adapter resolves standard Unity Hub locations for the selected version. Set PROJECT_CONTEXT_UNITY_EDITOR to override the executable path for one machine. Batch mode requires the bundled com.project-context.asset-graph UPM bridge: install the bridge directory included in the Unity adapter package as a local Unity package. It calls AssetDatabase.GetDependencies and returns a temporary JSON result outside the project; Unity may still update its regular Library cache while it runs.

Git change impact

The Git adapter is an impact operation, not a symbol trace. It ranks files that changed in the same commits as a target file:

pctx impact . src/npm-updater.ts 20 git

Tune the bounded history window per project when needed:

adapters:
  git:
    historyLimit: 500

CLI reference

Command	Purpose
pctx status [project-root]	Check configuration, dependencies, and index freshness.
pctx index <project-root> [--rebuild]	Create or incrementally update the semantic index.
pctx watch <project-root> [interval-ms]	Keep an index current with filesystem events and safety scans.
pctx search <project-root> <query> [mode] [scope] [max-results]	Search in auto, exact, graph, or semantic mode.
pctx trace <project-root> <symbol> <direction> [max-results] [language]	Trace relationships with an installed language adapter.
pctx impact <project-root> <path> [max-results] [language]	Rank files that historically change with a project file.
pctx read <project-root> <path> [start-line] [end-line]	Read an allowed, bounded file range.
`pctx handoff save	update ...`
pctx update	Update the global core and any installed trace or impact adapters to their latest releases.
pctx serve --mcp	Start the stdio MCP server.

Development

git clone https://github.com/E-Hae/project-context.git
cd project-context
npm ci
npm run verify
npm --workspace adapters/csharp run verify
npm --workspace adapters/typescript run verify
npm pack --dry-run

npm run verify verifies the language-neutral core without .NET. The C# adapter builds and verifies its Roslyn worker separately. The core tarball includes JavaScript dependency notices but excludes workers and Microsoft binaries; the C# adapter tarball includes its worker and Microsoft third-party notices.

Migration to 2.0.0

The ask CLI command and services.ollama.answerModel setting were removed. Use an MCP client with context_search, context_read, and context_trace to compose answers, and remove answerModel from existing project configuration.

License

Project Context MCP is MIT licensed. Core JavaScript dependency notices are in THIRD_PARTY_NOTICES.md; the optional C# adapter carries the notices for its bundled Microsoft worker dependencies.