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

File	What to Include
`architecture.md`	System overview, component relationships, data flow diagrams
`conventions.md`	Coding standards, naming conventions, file organization
`api-patterns.md`	Endpoint structure, authentication, error handling patterns
`database-schema.md`	Table relationships, naming conventions, migration patterns
`testing-patterns.md`	Test organization, mocking strategies, fixture patterns
`deployment.md`	Environment setup, deployment procedures, rollback steps
`gotchas.md`	Known issues, workarounds, "don't do this" warnings
`glossary.md`	Domain-specific terms, abbreviations, business logic

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:

Category	Extensions
Documentation	`.md`, `.txt`, `.rst`, `.asciidoc`, `.adoc`
Data/Config	`.yaml`, `.yml`, `.json`, `.toml`, `.xml`, `.csv`, `.ini`, `.cfg`, `.conf`
Code Examples	`.py`, `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`, `.sql`, `.sh`

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     │         │                     │
└──────────────────┘         └─────────────────────┘

On startup: MCP server checks current directory for .context/
On @ keystroke: Claude Code requests available resources
Server responds: List of files with names, descriptions, and URIs
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

Approach	Pros	Cons
Copy-paste context	No setup	Tedious, inconsistent, clutters prompt
CLAUDE.md file	Auto-included	Single file, always included even when not relevant
`.context/` folder	Organized, selective, discoverable	Requires explicit `@` mention

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?

Check the folder name: Must be exactly .context/ (with the dot)
Check file extensions: Only supported types are included
Restart Claude Code: MCP servers initialize on startup
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.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
examples/sample-project		examples/sample-project
scripts		scripts
src/project_context_mcp		src/project_context_mcp
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

project-context-mcp

The Problem

The Solution

Quick Start

1. Install the MCP server (one time)

2. Create a .context/ folder in your project

3. Use @ to include context

What to Put in .context/

Recommended Files

Example: conventions.md

Example: architecture.md

Supported File Types

Features

Smart Resource Names

Automatic Descriptions

Nested Folders

Zero Configuration

How It Works

URI Scheme

Use Cases

Onboarding New Team Members

Enforcing Consistency

Complex Domains

Legacy Codebases

Multi-Service Architecture

Comparison

Installation Options

Recommended: uvx (no install needed)

Alternative: pip install

Development: from source

Troubleshooting

Context files not appearing?

Want to see what's discovered?

Contributing

Development Setup

Running Tests

License

Related

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

2. Create a `.context/` folder in your project

3. Use `@` to include context

What to Put in `.context/`

Example: `conventions.md`

Example: `architecture.md`

Packages