claude-code-mcp

# Claude Code with MCP Servers ## Project Overview This project enables Claude to use Model Context Protocol (MCP) servers for enhanced capabilities, including web search, GitHub integration, file operations, database access, and communication tools. ## Key Concepts - **MCP (Model Context Protocol)**: A standardized way for LLMs to interact with external tools and services - **Reference MCP Servers**: Located at `$HOME/dev/mcp-servers-repo` (a clone of [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)) - **Local MCP Servers**: Our own implementations located at `$HOME/dev/claude-code/mcp-servers/` The reference servers should be treated as read-only. Our local servers will be our own implementations, some based on reference servers but with extensions and improvements. ## Directory Structure - `docs/` - Reference documentation - `mcp-servers/` - Our local MCP server implementations - `archive/` - Storage for deprecated code components - `data/` - Storage for server data (SQLite DB, memory files, etc.) - `scripts/` - Utility scripts for setup and testing - `src/` - Python modules and utilities ## MCP Server Configuration Configuration is handled by the `claude-mcp` script at the project root. This script: 1. Sets up environment variables for server paths 2. Registers servers with Claude using the `claude mcp add` command 3. Uses both package-based servers (from npm/pypi) and local implementations ```bash # Script path /Users/williambrown/dev/claude-code/claude-mcp # List all registered servers claude mcp list ``` ## Available MCP Servers | Server | Purpose | Source | |--------|---------|--------| | brave-search | Web search capabilities | npm package | | github | GitHub repository operations | npm package | | filesystem | Local file system operations | npm package | | fetch | Web page fetching | PyPI package | | memory | Knowledge graph for persistent memory | npm package | | sqlite | Database operations | Local implementation | | slack | Slack communication | npm package | | linear | Linear issue tracking | npm package | | e2b | Code execution sandbox | npm package | ## Required Environment Variables - `BRAVE_API_KEY` - For brave-search server - `GITHUB_TOKEN` - For GitHub operations - `LINEAR_API_KEY` - For Linear issue tracking - `SLACK_BOT_TOKEN` and `SLACK_TEAM_ID` - For Slack communication - `E2B_API_KEY` - For code execution sandbox - `ALLOWED_PATHS` - For filesystem access control (defaults to project root) ## Development Approach We're taking a two-pronged approach to MCP servers: 1. **Using Existing Servers**: Leveraging established MCP servers via npm/PyPI packages for standard functionality 2. **Building Custom Servers**: Developing our own implementations for extended functionality and experimentation All legacy or unmaintained code is moved to the `archive/` directory to keep the main codebase clean and focused. ## Development Guidelines ### Package Management - Use `uv` for Python package management (NEVER pip) - Installation: `uv add package` - Running tools: `uv run tool` - TypeScript: Use npm for package management ### Code Quality - Type hints required for all Python and TypeScript code - Public APIs must have docstrings - Functions must be focused and small - Line length: 88 chars maximum - Follow PEP standards for Python - Follow existing patterns for TypeScript ### Testing - Framework: `uv run pytest` - Async testing: use anyio, not asyncio - Coverage: test edge cases and errors - New features require tests - Bug fixes require regression tests ### Coding Principles - Use clean, modular abstractions - Avoid code duplication - Ensure backward compatibility - Document all extensions and differences from reference implementations - Strive for minimal clean code that's easily maintained ### Git Workflow - Develop in separate branches, merge to main quickly - For user-reported fixes: `git commit --trailer "Reported-by:<user>"` - For GitHub issues: `git commit --trailer "Github-Issue:#<number>"` - NEVER mention co-authored-by or tools used to create commits/PRs ## MCP Server Development Guidelines When developing our own local MCP servers: 1. **Reference Implementation First**: - Study the original server in `MCP_REPO_PATH` - Understand its API, behavior, and implementation details - Document the key functions and features 2. **Implementation Strategy**: - Start by mimicking the reference server exactly - Once basic functionality is working, add extensions - Ensure backward compatibility 3. **Code Quality**: - Use proper typing (TypeScript/Python type hints) - Add comprehensive documentation - Implement proper error handling - Follow consistent naming conventions - Write tests for all functionality For detailed information about project standards, code style, and specific server implementations, refer to `CLAUDE.md`.