MCP Server Boilerplate

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## New Context Management Tools This MCP server now includes powerful context-saving tools that implement the workflow patterns discussed in the Reddit post about advanced Claude usage. ### Context Saving Slash Commands #### `/save-context` - Save Conversation Context Use this to save important conversation context for future sessions: ``` @mcp-boilerplate save-context { "projectName": "my-game-project", "contextType": "planning", "content": "We discussed the core game mechanics: tower defense with resource management...", "summary": "Initial planning session for tower defense game", "nextSteps": ["Design UI mockups", "Research physics libraries", "Create player progression system"], "keyDecisions": ["Using React for frontend", "Node.js backend", "Real-time multiplayer"] } ``` **Context Types:** - `planning` - Project planning and design discussions - `progress` - Development progress and status updates - `technical-notes` - Technical decisions and implementation details - `decisions` - Important architectural or design decisions - `general` - General project context and notes #### `/list-context` - View Saved Context List all your saved context files: ``` @mcp-boilerplate list-context-files {"projectName": "my-game-project"} ``` ### Context Management Workflow 1. **During Development:** Use `save-context` to capture important decisions, progress, and technical findings 2. **Between Sessions:** Context files are automatically saved to `./context/` directory 3. **New Sessions:** Reference saved context files to maintain continuity 4. **Context Window Management:** Start fresh conversations while preserving project memory ### File Structure ``` context/ ├── my-game-project-planning-2024-01-15.md ├── my-game-project-technical-notes-2024-01-16.md ├── my-game-project-progress-2024-01-17.md └── my-game-project-decisions-2024-01-18.md ``` ### MCP Server Installation - `pnpm run install-mcp` - Install to .mcp.json only (local development) Installation scripts automatically: - Build the TypeScript project - Set executable permissions on dist/index.js - Update client configuration files - Parse and include .env.local environment variables ### Publishing and Release - `pnpm run release` - Build, commit, push, and publish to npm registry - `pnpm run build` - Compile TypeScript only ## Architecture - **Schema Validation**: Zod for parameter validation - **Transport**: StdioServerTransport for communication - **File System**: Node.js fs for context file management ### Project Structure ``` src/ ├── index.ts # Main MCP server implementation ├── tools.ts # Tool definitions and registration logic (including context tools) scripts/ ├── update-config.js # Multi-client configuration installer ├── build-and-publish.js # Automated release and npm publishing context/ # Generated context files (created automatically) dist/ # Compiled JavaScript output (generated) .env.local # Environment variables (optional) .env.example.local # Example environment configuration package.json # NPM package configuration tsconfig.json # TypeScript compiler configuration ``` ## Environment Variables Optional `.env.local` file for environment variables that get automatically included in MCP server configuration on installation. ### Tool Configuration - **ENABLED_TOOLS**: Comma-separated list of tool names to enable (e.g., `hello-world,save-context,list-context-files`) - If not specified or empty, all tools are enabled by default - Tools are defined in `src/tools.ts` for modular management - Example: `ENABLED_TOOLS=save-context,list-context-files` enables only the context management tools ## Development Workflow ### Local Development 1. Modify `src/tools.ts` to add/update tools 2. Run `pnpm run install-mcp` to compile and install locally 3. **IMPORTANT**: Ask the user to restart the CLI to test new changes to the MCP tools - You should explicitly ask: "Please restart your CLI to load the new MCP tool changes" - MCP servers are loaded at startup, so a restart is required for changes to take effect ### Context Management Best Practices 1. **Save Early and Often**: Use `save-context` whenever you make important decisions or complete significant work 2. **Use Descriptive Project Names**: Keep project names consistent across context files 3. **Choose Appropriate Context Types**: This helps organize and filter your saved contexts 4. **Include Next Steps**: Always capture what should be done next to maintain momentum 5. **Document Key Decisions**: Save architectural choices and reasoning for future reference ## Configuration Types - **Production Clients**: Use `npx -y @r-mcp/<package>@latest` (auto-updating) - **Local Development**: Use `node /absolute/path/to/dist/index.js` (for testing changes before publishing) ## Additional Resources For more detailed examples of MCP server implementations (including weather APIs, resources, and prompts), please read `@mcp-guide.md` which contains comprehensive Python and TypeScript examples. ## Additional Notes When the user asks you to test a tool, it means they want you to use the mcp corresponding to the tool you were working on. You should use the mcp**mcp-name**tool-name to execute the tool. If there is no change in output, it's likely because the CLI needs to be restarted. ### Context Slash Command Examples **Save planning context:** ``` /save-context game-planning planning "We discussed core mechanics and decided on tower defense with resource management. Player will collect resources, build towers, and defend against waves of enemies." ``` **Save technical decisions:** ``` /save-context game-tech technical-notes "Decided to use Three.js for 3D graphics, Socket.io for multiplayer, and React for UI. Will use TypeScript throughout." ``` **List project contexts:** ``` /list-context game-project ```