project-context-mcp

Purpose

project-context-mcp aims to solve the problem of lacking project background knowledge when using Claude Code. It lets developers put "tacit knowledge" such as the team's coding standards, architectural decisions, database schema pitfalls, and API design patterns into the project's .context/ folder, and Claude Code can then directly access these documents through @ mentions, making Claude more aware of your codebase and project conventions.

Main Capabilities

• Reference documents in the .context/ folder in Claude Code through @ mentions.
• Automatically discover and recursively include supporting files in subfolders.
• Smart resource names: Markdown files use the first # heading as the name; other files convert the filename to title case (e.g., api-patterns.md → "Api Patterns").
• Automatic descriptions: the first paragraph of each file becomes the description shown in autocomplete, helping you choose quickly.
• Resources use the context:// protocol, for example .context/architecture.md → context://architecture.md, .context/api/patterns.md → context://api/patterns.md.
• Zero configuration: no configuration files, environment variables, or additional setup are needed; just create a .context/ folder.
• Automatically exclude hidden files (such as .foo), pycache, node_modules, .git, .DS_Store.

How to Use

1. Install the MCP server (one-time):
   • uvx is recommended (no installation required): the specific command is not provided in the materials.
   • Alternative: pip install, the specific command is not provided in the materials.
   • Development mode: install from source, the specific steps are not provided in the materials. After installation, the server will be available in all Claude Code sessions.
2. Create a .context/ folder in the project.
3. Type @ in Claude Code, and you will see context files appear alongside source files; select one to include the file contents in the prompt.

Workflow

• On startup: the MCP server checks whether .context/ exists in the current directory.
• When @ is typed: Claude Code requests available resources.
• Server response: returns a list of files including filenames, descriptions, and URIs.
• On selection: retrieves the file contents and includes them in the prompt.

Applicable Scenarios

• New member onboarding: include the .context/ folder in the repository, and new developers can get the same Claude experience as senior members from day one.
• Enforce consistency: put coding standards into .context/conventions.md, and Claude will suggest code that conforms to the patterns.
• Complex domain knowledge: such as healthcare, finance, and legal tech; put domain vocabulary and business rules into .context/ to prevent Claude from confusing terminology.
• Legacy codebases: document the "why" behind legacy decisions, and when refactoring you can reference @legacy-decisions.md to explain constraints.
• Multi-service architecture: put architecture documents into context to help Claude respect service boundaries and communication patterns when making changes.

Supported File Types

The server exposes files with specific extensions (the complete list of specific extensions is not provided in the materials).

Limitations and Notes

• The folder name must be exactly .context/ (with a dot).
• Only supported file types are included.
• After modifying .context/, you may need to restart Claude Code because the MCP server initializes at startup.
• You can run claude mcp list to check whether the server is registered; running the server directly lets you view logs.
• Current features include: file watching hot reload, context.yaml manifest custom metadata, cross-context file search, remote context support (URL, Notion, Confluence), cloud storage team sync, etc. are still under consideration; the materials do not state that they have been implemented.
• License: MIT License.
• This project implements the Model Context Protocol and provides services for Claude Code.