Project Context Map MCP

Give your coding agent a map before it starts wandering

Turn a repository into structured project memory for MCP clients like Claude Code, so they can query context, inspect only relevant files, and understand topology before touching code.

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

| Part | Purpose | | --- | --- | | .project.md | Main readable project memory for humans and agents | | .project-map.json | Structured index used by tools | | .project-map.md | Lightweight markdown summary | | read_project_context | Returns .project.md | | query_topology | Finds relevant files from natural-language queries | | read_files_sparse | Reads only indexed files | | write_and_log | Writes changes and appends to .project.md Change Log |

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

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

| Command | What it does | | --- | --- | | serve | Starts the MCP server over stdio | | refresh | Regenerates .project.md, .project-map.json, and .project-map.md | | install-hooks | Installs git hooks to keep the map refreshed | | configure-claude | Creates repo-local Claude Code skill and .mcp.json | | print-mcp-config | Prints the MCP config JSON without writing files | | help | Shows command help |

MCP Tools

These are the main tools exposed by the server.

Core workflow tools

| Tool | Purpose | | --- | --- | | read_project_context | Returns .project.md content | | query_topology | Takes a natural-language query and returns matched file paths from the query index | | read_files_sparse | Reads file content only for indexed paths | | write_and_log | Writes file changes and appends an entry to .project.md Change Log |

Additional tools

| Tool | Purpose | | --- | --- | | get_project_summary | Returns summary, stack, modules, hotspots | | refresh_project_map | Regenerates the project memory artifacts | | get_module_context | Returns a focused view of one module | | find_relevant_files | Legacy ranking-oriented file query | | get_recent_git_changes | Summarizes recent git activity | | explain_file_role | Explains a file’s role and recent changes |

read_project_context

Returns:

• .project.md path
• full markdown content

query_topology

Returns:

• matched file paths
• confidence score
• match reasons
• per-file dependencies
• per-file usedBy relationships

read_files_sparse

Returns:

• file content for indexed files
• safe errors for files outside the repo or outside the known topology

write_and_log

Returns:

• path written
• bytes written
• appended change log entry

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

1. Go to your repo root.
2. Run project-context-map-mcp refresh --project-root .
3. Run project-context-map-mcp configure-claude --project-root .
4. Open the repo in Claude Code.
5. Approve the MCP server from .mcp.json.
6. Ask the agent to use read_project_context and query_topology first.

Use:

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

Then copy the JSON into your own MCP config file and adjust:

• server name
• command path
• working project root

Install locally:

npm install project-context-map-mcp

Then run through npx:

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

You should see:

• .project.md
• .project-map.json
• .project-map.md
• .mcp.json after Claude setup

You can also run:

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

Example Prompts For Your MCP Client

• Read the project context first, then find the files involved in session refresh logic.
• Use query_topology to locate the API and UI files for export CSV.
• Check .project.md before making changes.
• Refresh the project map after this feature is complete.
• Find the files that control authentication and read only those files first.

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