capsule-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Capsule CRM MCP (Model Context Protocol) server that exposes Capsule CRM API endpoints as AI tools. It's built using FastMCP framework with FastAPI backend and provides read-only access to Capsule CRM data.

The server can run in two modes:

• stdio mode: For direct integration with Claude Desktop and other MCP clients
• HTTP mode: For testing and development via REST endpoints

Development Commands

Testing

uv run pytest                       # Run all tests
uv run pytest tests/test_server.py::test_list_contacts  # Run specific test
uv run pytest -v                    # Verbose output

Development Server (HTTP mode)

uv run uvicorn capsule_mcp.server:app --reload  # Start dev server at http://localhost:8000/mcp/

MCP Server (stdio mode)

uv run python capsule_mcp/server.py # Run as MCP server via stdio

Installation

uv sync                             # Install dependencies and create virtual environment
uv sync --dev                       # Install with dev dependencies (black, isort, pytest, ruff)

Architecture

Core Components

• capsule_mcp/server.py: Main server implementation containing all MCP tools and FastAPI application
• capsule_request(): Centralized HTTP client for Capsule CRM API calls with auth and error handling
• FastMCP framework: Handles MCP protocol implementation and tool registration
• Tool functions: Each decorated with @mcp.tool to expose Capsule CRM endpoints

Key Patterns

1. Tool Structure: All tools follow the pattern of accepting pagination parameters (page, per_page) and optional filtering (since for date filtering)

2. API Client: The capsule_request() function handles:

   • Bearer token authentication via CAPSULE_API_TOKEN env var
   • Request/response processing and error handling
   • Test mode fallback (uses "test-token" when PYTEST_CURRENT_TEST is set)