project-context

project-context is a local MCP server for large JavaScript and TypeScript repositories. It exposes one tool, project_context(task), and returns a cited context pack from the repository's existing CodeGraph index, Markdown documentation, and Git commit messages.

It has no npm dependencies. Node supplies SQLite and FTS5. The codegraph CLI supplies structure and source context.

Requirements

• Node.js 22.13 or newer
• Git
• codegraph on PATH
• An existing .codegraph index in the repository

The tool still returns documentation and history if CodeGraph is missing. It reports the missing structure under Unknowns.

Setup

From this package directory:

npm install -g .

In each target repository, build CodeGraph's index once if the repository does not already have one:

codegraph init -i

Register the server with an MCP client and start it from the target repository. A typical stdio entry is:

{
  "mcpServers": {
    "project-context": {
      "command": "project-context"
    }
  }
}

The client can then call:

project_context({ "task": "Add tenant-aware caching to AccountService" })

The SQLite file is stored at .git/project-context/index.sqlite. It does not add files to the working tree.

Optional configuration

Without configuration, the index includes tracked and unignored .md and .mdx files. Add .project-context.yml only when the defaults retrieve the wrong prose:

docs:
  - docs/**/*.md
  - decisions/**/*.md
ignore:
  - docs/archive/**

docs replaces the default document globs. ignore adds exclusions. Those are the only accepted keys.

Check

Run the end-to-end check:

npm run check

The check creates a temporary TypeScript repository, commits its code and rationale, builds a CodeGraph index, starts the MCP server, calls the tool, and verifies the citations and local FTS5 database.

Limits

This package does not own a second graph, vector database, decision schema, parser system, service, or cross-repository index. The design spec records the boundary and the evidence needed to reconsider it.