My MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a Python MCP (Model Context Protocol) Server template built with FastMCP. It provides a foundation for creating custom MCP servers that expose tools via JSON-RPC over stdio, enabling secure context and tool invocation for language models. The project uses Python 3.13+ and follows modern Python development practices with comprehensive testing, linting, and code formatting. ## Common Development Commands ### Virtual Environment Setup ```bash # Create virtual environment task create-venv source .venv/bin/activate # Install runtime dependencies task install-requirements # Install dev dependencies (includes pytest, black, flake8, mypy) task install-dev ``` ### Running the Server ```bash # Run MCP server (after setup) task run # or python -m my_mcp_server ``` ### Development Workflow ```bash # Run all checks (format, lint, tests) task check # Individual commands: task format # Format code with Black task lint # Run flake8 and mypy task test # Run all tests # Run specific test suites task test-unit task test-integration task test-performance # Generate test coverage report task coverage ``` ### Build and Release ```bash # Build distribution packages task build # Clean build artifacts task clean ``` ## Architecture ### Core Components - **src/my_mcp_server/server.py**: FastMCP server with tool registrations - **src/my_mcp_server/__main__.py**: Entry point for running the server - **src/my_mcp_server/config/**: Configuration management modules - **src/my_mcp_server/context/**: Context providers for MCP - **src/my_mcp_server/models/**: Pydantic models and schemas - **src/my_mcp_server/tools/**: Custom tool implementations - **src/my_mcp_server/utils/**: Helper utilities ### Test Organization - **tests/unit/**: Unit tests for individual components - **tests/integration/**: Integration tests for tool interactions - **tests/performance/**: Performance and load tests - **tests/fixtures/**: Shared test data and fixtures ### Key Design Patterns - **FastMCP Framework**: Simplified MCP server creation with decorators - **Async/await**: Non-blocking I/O operations throughout - **Pydantic Models**: Type-safe configuration and data validation - **Dependency Injection**: Via FastAPI/Pydantic for configuration - **Test-Driven Development**: Following red-green-refactor cycle ## Development Guidelines ### Adding New Tools 1. Create tool function in `src/my_mcp_server/tools/` or directly in `server.py` 2. Use `@mcp_server.tool()` decorator to expose as MCP tool 3. Add comprehensive docstring describing parameters and behavior 4. Write unit tests in `tests/unit/test_[tool_name].py` 5. Add integration tests if tool interacts with external services ### Testing Requirements - **Coverage**: Minimum 80% code coverage required - **Test Structure**: Follow AAA pattern (Arrange-Act-Assert) - **Async Tests**: Use `pytest-asyncio` for async test functions - **Fixtures**: Place shared fixtures in `tests/conftest.py` - **Mocking**: Mock external dependencies, especially HTTP calls ### Code Quality Standards - **Black**: Code formatting with 88 character line length - **Flake8**: Linting with complexity limit of 18 - **Mypy**: Type checking for all source code - **Imports**: Use absolute imports from `my_mcp_server` package ### Task Automation The project uses Taskfile for automation. Key tasks include: - Environment management: `create-venv`, `clean-venv` - Development: `run`, `dev`, `check` - Testing: `test`, `test-unit`, `coverage` - Code quality: `format`, `lint`, `flake8`, `mypy` - Building: `build`, `clean` Run `task --list` to see all available tasks. ## Configuration ### Environment Variables Create a `.env` file in the project root for configuration: ```bash # API keys and sensitive data API_KEY=your-api-key-here # Additional configuration as needed ``` ### Pydantic Settings Configuration is managed via `pydantic-settings` which automatically loads from: 1. Environment variables 2. `.env` file (via python-dotenv) 3. Default values in configuration classes ## Project State This is a template/starter project. The current implementation includes: - Basic MCP server setup using FastMCP - Simple `echo` tool as an example - Comprehensive project structure for scalability - Full testing, linting, and build infrastructure To extend this template: 1. Add your custom tools to the server 2. Implement any required API clients or services 3. Update configuration as needed 4. Write tests following TDD practices 5. Update this documentation to reflect your changes