Project Context MCP

project-context-mcp

Give Claude Code instant access to your project's institutional knowledge.

An MCP server that makes your project documentation instantly accessible in Claude Code through @ mentions. Create a .context/ folder, add your docs, and watch Claude become an expert on your codebase.

---

The Problem

You're working with Claude Code on a complex project. Claude is smart, but it doesn't know:

• Your team's coding conventions
• Why you chose that weird architecture
• The gotchas in your database schema
• Your API design patterns
• That one thing that breaks if you don't do it just right

You end up copy-pasting the same context into every conversation. Or worse, Claude makes suggestions that violate your project's conventions.

The Solution

Create a .context/ folder in your project. Drop in your documentation. Now when you type @ in Claude Code, your context files appear right alongside your source files:

┌─────────────────────────────────────────────────────────────┐
│  > Help me add a new API endpoint @                         │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Suggestions:                                         │   │
│  │   📄 src/api/routes.py                              │   │
│  │   📄 src/models/user.py                             │   │
│  │   📘 architecture.md          <- Your context!      │   │
│  │   📘 api-patterns.md          <- Your context!      │   │
│  │   📘 conventions.md           <- Your context!      │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

One @api-patterns.md mention and Claude knows exactly how you structure endpoints.

---

Quick Start

1. Install the MCP server (one time)

claude mcp add project-context -s user -- uvx project-context-mcp

That's it. The server is now available in all your Claude Code sessions.

2. Create a .context/ folder in your project

my-project/
├── .context/               <- Create this folder
│   ├── architecture.md
│   ├── conventions.md
│   └── api-patterns.md
├── src/
├── tests/
└── ...

3. Use @ to include context

> Help me refactor this function @conventions.md
> Add a new database table @database-schema.md @naming-conventions.md
> Why is this test failing? @architecture.md @testing-patterns.md

---

What to Put in .context/

Your .context/ folder is for institutional knowledge — the stuff that isn't obvious from reading the code.

Recommended Files

Example: conventions.md

# Coding Conventions

## Naming
- Files: `snake_case.py`
- Classes: `PascalCase`
- Functions: `snake_case`
- Constants: `UPPER_SNAKE_CASE`

## Error Handling
- Use custom exceptions from `src/exceptions.py`
- Always log with context: `logger.error("Failed to process", extra={"user_id": id})`
- API endpoints return `{"error": {"code": "...", "message": "..."}}`

## Testing
- One test file per module: `test_<module_name>.py`
- Use fixtures from `conftest.py`, don't create new ones without discussion
- Mock external services, never hit real APIs in tests

Example: architecture.md

# Architecture Overview

## System Components

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Next.js   │────▶│   FastAPI   │────▶│  PostgreSQL │
│  Frontend   │     │   Backend   │     │   Database  │
└─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │    Redis    │
                    │    Cache    │
                    └─────────────┘

## Key Design Decisions

1. **Why FastAPI over Flask?**
   - Native async support for high-concurrency endpoints
   - Automatic OpenAPI documentation
   - Pydantic validation built-in

2. **Why Redis for caching?**
   - Session storage for horizontal scaling
   - Rate limiting with sliding windows
   - Pub/sub for real-time features

---

Supported File Types

The server exposes files with these extensions:

Automatically excluded: Hidden files (.foo), __pycache__, node_modules, .git, .DS_Store

---

Features

Smart Resource Names

The server extracts human-readable names from your files:

• Markdown files: Uses the first # Heading as the name
• Other files: Converts filename to title case (api-patterns.md → "Api Patterns")

Automatic Descriptions

First paragraph of each file becomes the description shown in autocomplete, helping you pick the right context quickly.

Nested Folders

Organize complex documentation with subfolders:

.context/
├── architecture.md
├── api/
│   ├── authentication.md
│   ├── pagination.md
│   └── error-codes.md
├── database/
│   ├── schema.md
│   └── migrations.md
└── frontend/
    ├── components.md
    └── state-management.md

All files are discovered recursively and accessible via @.

Zero Configuration

No config files. No setup. No environment variables. Just create .context/ and go.

---

How It Works

┌──────────────────┐         ┌─────────────────────┐
│   Claude Code    │◀───────▶│  project-context-mcp │
│                  │   MCP   │                     │
│  You type: @     │ Protocol│  1. Finds .context/ │
│                  │         │  2. Lists all files │
│  Server returns  │◀────────│  3. Returns as      │
│  your docs as    │         │     MCP resources   │
│  suggestions     │         │                     │
└──────────────────┘         └─────────────────────┘

1. On startup: MCP server checks current directory for .context/
2. On @ keystroke: Claude Code requests available resources
3. Server responds: List of files with names, descriptions, and URIs
4. On selection: File content is fetched and included in your prompt

URI Scheme

Resources use the context:// scheme:

• .context/architecture.md → context://architecture.md
• .context/api/patterns.md → context://api/patterns.md

---

Use Cases

Onboarding New Team Members

Share your .context/ folder in your repo. New developers get the same Claude experience as veterans — Claude knows the conventions from day one.

Enforcing Consistency

Instead of hoping everyone remembers the coding standards, put them in .context/conventions.md. Claude will suggest code that matches your patterns.

Complex Domains

Working in healthcare? Finance? Legal tech? Put your domain glossary and business rules in .context/. Claude won't confuse your specific terminology.

Legacy Codebases

Document the "why" behind legacy decisions. When Claude suggests a refactor, you can include @legacy-decisions.md to explain constraints.

Multi-Service Architecture

Keep architecture docs in context. Claude can help you make changes that respect service boundaries and communication patterns.

---

Comparison

This tool is ideal when you have multiple context documents and want to selectively include the relevant ones for each task.

---

Installation Options

Recommended: uvx (no install needed)

claude mcp add project-context -s user -- uvx project-context-mcp

Alternative: pip install

pip install project-context-mcp
claude mcp add project-context -s user -- project-context-mcp

Development: from source

git clone https://github.com/ericbrown/project-context-mcp.git
cd project-context-mcp
pip install -e .
claude mcp add project-context -s user -- python -m project_context_mcp.server

---

Troubleshooting

Context files not appearing?

1. Check the folder name: Must be exactly .context/ (with the dot)
2. Check file extensions: Only supported types are included
3. Restart Claude Code: MCP servers initialize on startup
4. Check server is registered: Run claude mcp list

Want to see what's discovered?

Run the server directly to see logs:

cd your-project
python -m project_context_mcp.server

You'll see:

INFO:project-context-mcp:Starting project-context-mcp server
INFO:project-context-mcp:Working directory: /path/to/your-project
INFO:project-context-mcp:Looking for context in: /path/to/your-project/.context
INFO:project-context-mcp:Found 5 context resources

---

Contributing

Contributions welcome! Ideas for improvements:

• [ ] File watching for hot reload
• [ ] context.yaml manifest for custom metadata
• [ ] Search tool to find content across context files
• [ ] Support for remote context (URLs, Notion, Confluence)
• [ ] Team sync via cloud storage

Development Setup

git clone https://github.com/ericbrown/project-context-mcp.git
cd project-context-mcp
pip install -e .

Running Tests

cd examples/sample-project
python -m project_context_mcp.server

---

License

MIT License — see LICENSE for details.

---

Related

• Model Context Protocol — The protocol this server implements
• Claude Code — Anthropic's CLI for Claude
• MCP Servers — Other MCP server implementations

---

Built for developers who are tired of repeating themselves.

Star this repo if it saves you time!