MCP Project Context Server

# MCP Project Context Server A Model Context Protocol (MCP) server that provides persistent project context and planning state between Claude Code sessions. This eliminates the need to re-explain project details, current status, and development context every time you start a new coding session. ## What It Does The MCP Project Context Server acts as a persistent memory layer for your development projects, maintaining: - **Project Information**: Name, description, current phase, and status - **Technology Stack**: Frontend, backend, database, infrastructure, and tooling choices - **Task Management**: Development tasks with priorities, status tracking, and dependencies - **Decision History**: Architectural and technical decisions with reasoning - **Session Continuity**: Goals, achievements, and blockers from previous sessions - **Development Notes**: Important observations and insights ## How It Works The server implements the Model Context Protocol to provide Claude Code with tools for managing project context: 1. **Project Creation**: Initialize new projects with tech stack and current phase 2. **Context Retrieval**: Get comprehensive project state and history 3. **Task Management**: Create, update, and track development tasks 4. **Decision Recording**: Document important technical and architectural decisions 5. **Session Tracking**: Maintain continuity between development sessions 6. **Note Taking**: Capture important insights and observations Data is stored as JSON files in a local `data` directory, making it easy to backup, version control, or inspect manually. ## Key Features - **Persistent Context**: Project state survives between Claude Code sessions - **Technology Stack Awareness**: Tracks your preferred technologies and tools - **Task Prioritization**: Organize work with priority levels and status tracking - **Decision Documentation**: Maintain architectural decision records (ADRs) - **Session Goals**: Track what you planned vs what you achieved - **File-Based Storage**: Simple JSON storage that's easy to understand and backup ## Prerequisites - Node.js 18 or higher - pnpm package manager - Claude Code CLI tool ## Installation 1. **Clone and setup the project:** ```bash git clone <repository-url> cd mcp-project-context pnpm install ``` 2. **Build the server:** ```bash pnpm run build ``` 3. **Make the server executable:** ```bash chmod +x dist/index.js ``` ## Configuration ### Claude Code Setup 1. **Create or edit the Claude Code MCP configuration file:** ```bash mkdir -p ~/.claude ``` 2. **Add your server configuration to `~/.claude.json:** ```json { "mcpServers": { "mcp-project-context": { "type": "stdio", "command": "/path/to/mcp-project-context/dist/index.js", "args": [], "env": {} } } } ``` Replace `/absolute/path/to/your/mcp-project-context` with the actual path to your project directory. 3. **Verify the configuration:** ```bash cat ~/.claude/mcp.json ``` ## Usage Once configured, Claude Code will automatically start and connect to your MCP server. You can then use natural language to interact with your project context: ### Example Commands **Create a new project:** ``` "Create a new project called 'E-commerce Platform' for building a modern online store using Next.js, Node.js, PostgreSQL, and Docker" ``` **Get current project status:** ``` "What's the current status of my project? Where did we leave off?" ``` **Add development tasks:** ``` "Add a high-priority task to implement user authentication with OAuth" ``` **Record architectural decisions:** ``` "Record that we decided to use Prisma as our ORM because it provides better TypeScript support and easier migrations" ``` **Update task status:** ``` "Mark the authentication task as completed" ``` **Add project notes:** ``` "Add a note that the API rate limiting is causing issues in development" ``` ## Available Tools The server provides these tools to Claude Code: - `create_project` - Initialize a new project with tech stack and description - `get_project_context` - Retrieve comprehensive project state and history - `list_projects` - Show all projects ordered by last access - `add_task` - Create new development tasks with priorities - `update_task` - Modify task status, priority, or details - `add_note` - Capture important observations and insights - `record_decision` - Document architectural and technical decisions - `start_session` - Begin a development session with specific goals ## Data Storage Project data is stored in the `data` directory: ``` data/ ├── projects/ │ ├── project-uuid-1.json │ ├── project-uuid-2.json │ └── project-uuid-3.json └── sessions/ ├── session-uuid-1.json ├── session-uuid-2.json └── session-uuid-3.json ``` Each file contains structured JSON data that you can inspect or backup as needed. ## Development ### Project Structure ``` mcp-project-context/ ├── src/ │ ├── index.ts # Entry point │ ├── server.ts # MCP server implementation │ ├── storage/ │ │ ├── project-store.ts # File-based storage layer │ │ └── context-manager.ts # Context management logic │ └── types/ │ └── project-types.ts # TypeScript type definitions ├── data/ # Project data storage ├── package.json ├── tsconfig.json └── README.md ``` ### Available Scripts - `pnpm run build` - Compile TypeScript to JavaScript - `pnpm run start` - Run the compiled server - `pnpm run dev` - Run in development mode with auto-reload ### Testing the Server You can test the server manually: ```bash # Start the server directly node dist/index.js # The server will wait for MCP protocol messages via stdin ``` For interactive testing, use the MCP Inspector: ```bash npx @modelcontextprotocol/inspector node dist/index.js ``` ## Troubleshooting ### Server Connection Issues 1. **Verify the server builds successfully:** ```bash pnpm run build ``` 2. **Check that the executable bit is set:** ```bash ls -la dist/index.js chmod +x dist/index.js ``` 3. **Test the server manually:** ```bash node dist/index.js ``` 4. **Verify Claude Code configuration:** ```bash cat ~/.claude/mcp.json ``` ### Data Directory Issues If you encounter permission errors, ensure the data directory exists and is writable: ```bash mkdir -p data/projects data/sessions chmod -R 755 data/ ``` ### Claude Code Logs Check Claude Code logs for connection issues: ```bash # The server logs errors to stderr, which Claude Code captures # Check your terminal output when starting Claude Code ``` ## Privacy and Data - All project data is stored locally on your machine - No data is transmitted to external services - JSON files can be easily backed up or version controlled - Each developer/machine maintains separate project contexts ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License MIT License - see LICENSE file for details ## Support For issues related to: - **MCP Protocol**: See [Model Context Protocol documentation](https://modelcontextprotocol.io/) - **Claude Code**: See [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) - **READ THE DOCS**: See [official TS SDK for MCP](https://github.com/modelcontextprotocol/typescript-sdk) - **This Server**: Open an issue in this repository