Project Context Map

Why This Exists

AI coding tools often begin the same way in a medium or large repo:

• they read too many files
• they spend tokens on unrelated areas
• they rebuild context from scratch every time
• they miss the real dependency chain behind a feature or bug

project-context-map-mcp fixes that by generating a lightweight project memory and exposing it through MCP tools.

Instead of:

scan everything -> guess -> open random files

you get:

index first -> query topology -> read sparse files -> edit with context

What This Project Does

This package gives you:

• an MCP server for project-aware queries
• a CLI to generate and refresh repository memory
• a readable .project.md with topology highlights and change log
• a machine-readable .project-map.json
• a human-readable .project-map.md
• import/dependency relationships between files
• sparse file access limited to indexed paths
• MCP-assisted writes with automatic logging
• Claude Code setup helpers and skill generation

At A Glance

Installation

Option 1: Global install

Best if you want to use it across many repositories.

npm install -g project-context-map-mcp

Option 2: Local install

Best if you want it only inside one project.

npm install project-context-map-mcp

Requirements

• Node.js 20 or newer
• an MCP-compatible client such as Claude Code

Quick Start

1. Generate the project memory

Run this from the root of the repo you want to index:

project-context-map-mcp refresh --project-root .

This creates:

• .project.md
• .project-map.json
• .project-map.md

2. Configure Claude Code for that repo

project-context-map-mcp configure-claude --project-root .

This creates or updates:

• .mcp.json
• .claude/skills/project-context-map/SKILL.md

3. Start the MCP server

If your client starts the server from .mcp.json, you usually do not need to run it manually.

If you want to run it yourself:

project-context-map-mcp serve --project-root .

4. Use it from your MCP client

Typical flow:

1. read the project context
2. query topology with a natural-language task
3. read only the matched files
4. make changes
5. refresh the map

Prompt examples:

• See PROMPTS.md for tested starter prompts for Claude Code, Cursor, and VS Code Copilot Chat.
• For best results, use prompts that name the feature area, module, or source files you want the agent to inspect.

MCP Config

If you want to wire the server manually, add this to your MCP config:

{
  "mcpServers": {
    "project-context-map": {
      "command": "project-context-map-mcp",
      "args": ["serve", "--project-root", "."],
      "env": {}
    }
  }
}

Generate it automatically

project-context-map-mcp print-mcp-config --project-root .

Write it into the repo

project-context-map-mcp configure-claude --project-root .

CLI Commands

project-context-map-mcp serve --project-root .
project-context-map-mcp refresh --project-root .
project-context-map-mcp install-hooks --project-root .
project-context-map-mcp configure-claude --project-root .
project-context-map-mcp print-mcp-config --project-root .
project-context-map-mcp help

MCP Tools

These are the main tools exposed by the server.

Core workflow tools

Additional tools

Recommended Workflow

flowchart LR
  A[Refresh project map] --> B[Read .project.md]
  B --> C[Query topology]
  C --> D[Read sparse files]
  D --> E[Implement change]
  E --> F[Write and log]
  F --> G[Refresh project map]

Example task flow

User asks:

Fix the login bug where session expires after refresh

Recommended agent behavior:

1. call read_project_context
2. call query_topology with the task
3. call read_files_sparse with the matched file paths
4. inspect only those files first
5. edit code
6. call write_and_log if using MCP-managed writes
7. call refresh_project_map

Topology & Visual Graph

The project map is not only a file list. It also extracts internal relationships such as:

• JavaScript and TypeScript imports
• CommonJS require(...) usage
• basic Python import detection
• reverse usage information with used_by

That data is written into:

• .project-map.json
• .project.md

.project.md includes a Mermaid graph so markdown viewers that support Mermaid can render a visual dependency map.

What It Generates

.project.md

The main working document. It includes:

• project summary
• key modules
• query index preview
• topology highlights
• Mermaid dependency graph
• running change log

.project-map.json

The structured source of truth. It includes fields such as:

• project_summary
• tech_stack
• modules
• files
• topology
• entrypoints
• dependencies
• recent_changes
• hotspots

.project-map.md

A shorter human-readable summary.

Claude Code Setup

After running:

project-context-map-mcp configure-claude --project-root .

your repo will contain:

.mcp.json
.claude/skills/project-context-map/SKILL.md

The generated skill tells Claude Code to:

• consult project memory first
• avoid broad repo scans
• query relevant files before opening source
• refresh the project map after edits

Git Hooks

If you want the map to stay fresh automatically:

project-context-map-mcp install-hooks --project-root .

This installs:

• post-commit
• post-merge
• post-push

Each hook refreshes the project memory after repository activity.

Interactive Setup Guide

project-context-map-mcp print-mcp-config --project-root .

npm install project-context-map-mcp

npx project-context-map-mcp refresh --project-root .
npx project-context-map-mcp configure-claude --project-root .

project-context-map-mcp help
project-context-map-mcp refresh --project-root .

Example Prompts For Your MCP Client

Tested prompt templates now live in PROMPTS.md.

Quick examples:

• Use the project context map first, then find the files involved in session refresh logic.
• Use query_topology to locate the files related to npm publishing, package configuration, and release safety checks.
• Use get_module_context for src and explain how the CLI and MCP server fit together.
• Find the files that control authentication and prefer source files over docs.

Best Fit Repositories

• Node.js applications
• React apps
• Next.js projects
• mixed frontend/backend repos
• Python services
• large internal tools where AI agents are used often

Local Development

npm install
npm run check
node src/cli.js refresh --project-root .
node src/cli.js serve --project-root .

Current Limitations

• topology detection is strongest for JS, TS, and simple Python import patterns
• visual graph output is Mermaid markdown, not a full interactive web app
• natural-language ranking quality depends on file names, summaries, tags, and recent changes

License

MIT