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. You're working with Claude Code on a complex project. Claude is smart, but it doesn't know: - Your team's coding convention
Add this skill
npx mdskills install ericbrown/project-context-mcpWell-documented MCP server enabling selective project documentation access through `.context/` folder integration
1# project-context-mcp23[](https://badge.fury.io/py/project-context-mcp)4[](https://opensource.org/licenses/MIT)5[](https://www.python.org/downloads/)67**Give Claude Code instant access to your project's institutional knowledge.**89An 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.1011---1213## The Problem1415You're working with Claude Code on a complex project. Claude is smart, but it doesn't know:1617- Your team's coding conventions18- Why you chose that weird architecture19- The gotchas in your database schema20- Your API design patterns21- That one thing that breaks if you don't do it *just right*2223You end up copy-pasting the same context into every conversation. Or worse, Claude makes suggestions that violate your project's conventions.2425## The Solution2627Create 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:2829```30┌─────────────────────────────────────────────────────────────┐31│ > Help me add a new API endpoint @ │32│ │33│ ┌─────────────────────────────────────────────────────┐ │34│ │ Suggestions: │ │35│ │ 📄 src/api/routes.py │ │36│ │ 📄 src/models/user.py │ │37│ │ 📘 architecture.md <- Your context! │ │38│ │ 📘 api-patterns.md <- Your context! │ │39│ │ 📘 conventions.md <- Your context! │ │40│ └─────────────────────────────────────────────────────┘ │41└─────────────────────────────────────────────────────────────┘42```4344One `@api-patterns.md` mention and Claude knows exactly how you structure endpoints.4546---4748## Quick Start4950### 1. Install the MCP server (one time)5152```bash53claude mcp add project-context -s user -- uvx project-context-mcp54```5556That's it. The server is now available in all your Claude Code sessions.5758### 2. Create a `.context/` folder in your project5960```61my-project/62├── .context/ <- Create this folder63│ ├── architecture.md64│ ├── conventions.md65│ └── api-patterns.md66├── src/67├── tests/68└── ...69```7071### 3. Use `@` to include context7273```74> Help me refactor this function @conventions.md75> Add a new database table @database-schema.md @naming-conventions.md76> Why is this test failing? @architecture.md @testing-patterns.md77```7879---8081## What to Put in `.context/`8283Your `.context/` folder is for **institutional knowledge** — the stuff that isn't obvious from reading the code.8485### Recommended Files8687| File | What to Include |88|------|-----------------|89| `architecture.md` | System overview, component relationships, data flow diagrams |90| `conventions.md` | Coding standards, naming conventions, file organization |91| `api-patterns.md` | Endpoint structure, authentication, error handling patterns |92| `database-schema.md` | Table relationships, naming conventions, migration patterns |93| `testing-patterns.md` | Test organization, mocking strategies, fixture patterns |94| `deployment.md` | Environment setup, deployment procedures, rollback steps |95| `gotchas.md` | Known issues, workarounds, "don't do this" warnings |96| `glossary.md` | Domain-specific terms, abbreviations, business logic |9798### Example: `conventions.md`99100```markdown101# Coding Conventions102103## Naming104- Files: `snake_case.py`105- Classes: `PascalCase`106- Functions: `snake_case`107- Constants: `UPPER_SNAKE_CASE`108109## Error Handling110- Use custom exceptions from `src/exceptions.py`111- Always log with context: `logger.error("Failed to process", extra={"user_id": id})`112- API endpoints return `{"error": {"code": "...", "message": "..."}}`113114## Testing115- One test file per module: `test_<module_name>.py`116- Use fixtures from `conftest.py`, don't create new ones without discussion117- Mock external services, never hit real APIs in tests118```119120### Example: `architecture.md`121122```markdown123# Architecture Overview124125## System Components126127┌─────────────┐ ┌─────────────┐ ┌─────────────┐128│ Next.js │────▶│ FastAPI │────▶│ PostgreSQL │129│ Frontend │ │ Backend │ │ Database │130└─────────────┘ └─────────────┘ └─────────────┘131 │132 ▼133 ┌─────────────┐134 │ Redis │135 │ Cache │136 └─────────────┘137138## Key Design Decisions1391401. **Why FastAPI over Flask?**141 - Native async support for high-concurrency endpoints142 - Automatic OpenAPI documentation143 - Pydantic validation built-in1441452. **Why Redis for caching?**146 - Session storage for horizontal scaling147 - Rate limiting with sliding windows148 - Pub/sub for real-time features149```150151---152153## Supported File Types154155The server exposes files with these extensions:156157| Category | Extensions |158|----------|------------|159| **Documentation** | `.md`, `.txt`, `.rst`, `.asciidoc`, `.adoc` |160| **Data/Config** | `.yaml`, `.yml`, `.json`, `.toml`, `.xml`, `.csv`, `.ini`, `.cfg`, `.conf` |161| **Code Examples** | `.py`, `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`, `.sql`, `.sh` |162163**Automatically excluded:** Hidden files (`.foo`), `__pycache__`, `node_modules`, `.git`, `.DS_Store`164165---166167## Features168169### Smart Resource Names170171The server extracts human-readable names from your files:172173- Markdown files: Uses the first `# Heading` as the name174- Other files: Converts filename to title case (`api-patterns.md` → "Api Patterns")175176### Automatic Descriptions177178First paragraph of each file becomes the description shown in autocomplete, helping you pick the right context quickly.179180### Nested Folders181182Organize complex documentation with subfolders:183184```185.context/186├── architecture.md187├── api/188│ ├── authentication.md189│ ├── pagination.md190│ └── error-codes.md191├── database/192│ ├── schema.md193│ └── migrations.md194└── frontend/195 ├── components.md196 └── state-management.md197```198199All files are discovered recursively and accessible via `@`.200201### Zero Configuration202203No config files. No setup. No environment variables. Just create `.context/` and go.204205---206207## How It Works208209```210┌──────────────────┐ ┌─────────────────────┐211│ Claude Code │◀───────▶│ project-context-mcp │212│ │ MCP │ │213│ You type: @ │ Protocol│ 1. Finds .context/ │214│ │ │ 2. Lists all files │215│ Server returns │◀────────│ 3. Returns as │216│ your docs as │ │ MCP resources │217│ suggestions │ │ │218└──────────────────┘ └─────────────────────┘219```2202211. **On startup**: MCP server checks current directory for `.context/`2222. **On `@` keystroke**: Claude Code requests available resources2233. **Server responds**: List of files with names, descriptions, and URIs2244. **On selection**: File content is fetched and included in your prompt225226### URI Scheme227228Resources use the `context://` scheme:229- `.context/architecture.md` → `context://architecture.md`230- `.context/api/patterns.md` → `context://api/patterns.md`231232---233234## Use Cases235236### Onboarding New Team Members237238Share your `.context/` folder in your repo. New developers get the same Claude experience as veterans — Claude knows the conventions from day one.239240### Enforcing Consistency241242Instead of hoping everyone remembers the coding standards, put them in `.context/conventions.md`. Claude will suggest code that matches your patterns.243244### Complex Domains245246Working in healthcare? Finance? Legal tech? Put your domain glossary and business rules in `.context/`. Claude won't confuse your specific terminology.247248### Legacy Codebases249250Document the "why" behind legacy decisions. When Claude suggests a refactor, you can include `@legacy-decisions.md` to explain constraints.251252### Multi-Service Architecture253254Keep architecture docs in context. Claude can help you make changes that respect service boundaries and communication patterns.255256---257258## Comparison259260| Approach | Pros | Cons |261|----------|------|------|262| **Copy-paste context** | No setup | Tedious, inconsistent, clutters prompt |263| **CLAUDE.md file** | Auto-included | Single file, always included even when not relevant |264| **`.context/` folder** | Organized, selective, discoverable | Requires explicit `@` mention |265266This tool is ideal when you have **multiple context documents** and want to **selectively include** the relevant ones for each task.267268---269270## Installation Options271272### Recommended: uvx (no install needed)273274```bash275claude mcp add project-context -s user -- uvx project-context-mcp276```277278### Alternative: pip install279280```bash281pip install project-context-mcp282claude mcp add project-context -s user -- project-context-mcp283```284285### Development: from source286287```bash288git clone https://github.com/ericbrown/project-context-mcp.git289cd project-context-mcp290pip install -e .291claude mcp add project-context -s user -- python -m project_context_mcp.server292```293294---295296## Troubleshooting297298### Context files not appearing?2993001. **Check the folder name**: Must be exactly `.context/` (with the dot)3012. **Check file extensions**: Only [supported types](#supported-file-types) are included3023. **Restart Claude Code**: MCP servers initialize on startup3034. **Check server is registered**: Run `claude mcp list`304305### Want to see what's discovered?306307Run the server directly to see logs:308309```bash310cd your-project311python -m project_context_mcp.server312```313314You'll see:315```316INFO:project-context-mcp:Starting project-context-mcp server317INFO:project-context-mcp:Working directory: /path/to/your-project318INFO:project-context-mcp:Looking for context in: /path/to/your-project/.context319INFO:project-context-mcp:Found 5 context resources320```321322---323324## Contributing325326Contributions welcome! Ideas for improvements:327328- [ ] File watching for hot reload329- [ ] `context.yaml` manifest for custom metadata330- [ ] Search tool to find content across context files331- [ ] Support for remote context (URLs, Notion, Confluence)332- [ ] Team sync via cloud storage333334### Development Setup335336```bash337git clone https://github.com/ericbrown/project-context-mcp.git338cd project-context-mcp339pip install -e .340```341342### Running Tests343344```bash345cd examples/sample-project346python -m project_context_mcp.server347```348349---350351## License352353MIT License — see [LICENSE](LICENSE) for details.354355---356357## Related358359- [Model Context Protocol](https://modelcontextprotocol.io/) — The protocol this server implements360- [Claude Code](https://claude.ai/code) — Anthropic's CLI for Claude361- [MCP Servers](https://github.com/modelcontextprotocol/servers) — Other MCP server implementations362363---364365**Built for developers who are tired of repeating themselves.**366367*Star this repo if it saves you time!*368
Full transparency — inspect the skill content before installing.