http_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

http-mcp is a lightweight Python library implementing the Model Context Protocol (MCP) over HTTP and STDIO. It exposes Python functions as tools and prompts via JSON-RPC, designed for use with Starlette/FastAPI applications. Published on PyPI as http-mcp.

Common Commands

# Install dependencies
uv sync

# Run all tests with coverage (90% minimum required)
pytest --cov-report term-missing --cov=src --cov-fail-under=90 tests/

# Run a single test file
pytest tests/test_tools.py

# Run a single test
pytest tests/test_tools.py::test_name -v

# Type checking (strict mode)
mypy .

# Lint (all ruff rules enabled)
ruff check

# Format
ruff format

# Format markdown files (never `mdformat .` — it rewrites the YAML
# frontmatter in .claude/ into a heading and breaks the agent definitions)
mdformat README.md docs/ --wrap 80 --exclude .claude/

# Full pre-push check (what CI runs)
ruff check && mypy . && pytest --cov-report term-missing --cov=src --cov-fail-under=90 tests/ && mdformat README.md docs/ --wrap 80 --exclude .claude/

Architecture

Source Layout

Source is in src/http_mcp/ and src/auth_mcp/ with hatchling as build backend. The package uses uv for dependency management. Both packages ship in the same wheel (http-mcp); auth_mcp is available via pip install http-mcp[auth].

Core Components

• server.py — MCPServer class: central entry point. Manages tools/prompts, handles JSON-RPC dispatch, supports both HTTP and STDIO transports. Integrates with Starlette's lifespan for state management.
• server_interface.py — Abstract base class (ServerInterface) that MCPServer implements.
• types/ — Public API types exported via http_mcp.types:
  • Tool — Wraps a function with Pydantic input/output schemas. Supports sync/async, optional Arguments[TInputs] parameter, error handling, and authorization scopes.
  • Prompt — Interactive templates returning tuple[PromptMessage, ...].
  • Arguments[T] — Generic container providing inputs, request, and get_state_key() for accessing lifespan state.
  • NoArguments — Empty Pydantic model for tools/prompts without parameters.
• exceptions.py — Exception hierarchy: BaseError → ProtocolError, ServerError (with ToolNotFoundError, ToolInvocationError, PromptNotFoundError, PromptInvocationError), ArgumentsError. Error codes live in _json_rcp_types/errors.py; -32002 was retired by the 2026-07-28 revision and must not be reintroduced.