mbta-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.

Architecture Overview

This is an MCP (Model Context Protocol) server that provides LLMs with access to Boston's MBTA V3 API. The architecture follows a layered approach:

Core Components:

• mbta_mcp/client.py: Base HTTP client using aiohttp with async session management
• mbta_mcp/extended_client.py: Extends base client with all 14 MBTA API endpoints
• mbta_mcp/server.py: MCP server implementation with tool registration and dispatch

MCP Integration Pattern: The server registers 14 tools that map to MBTA API endpoints. Each tool is defined with JSON schemas for input validation and calls the appropriate client method. The server uses async context managers for proper resource cleanup.

API Client Architecture:

• Uses aiohttp.ClientSession for HTTP requests with proper async lifecycle
• Base client handles authentication headers and error handling
• Extended client adds endpoint-specific methods with parameter validation
• Both clients require async with context for session management

Development Commands

Primary workflow using Task:

task verify          # Full verification (install, check, test)
task install-dev     # Install all dependencies including dev tools
task check           # Run format, lint, and typecheck
task test-server     # Test MCP server functionality
task run             # Start the MCP server

Individual quality checks:

task format          # Format code with ruff
task lint            # Lint with ruff (30+ rule categories)
task lint-fix        # Auto-fix linting issues
task typecheck       # Type check with strict mypy

Direct uv commands:

uv sync --dev        # Install dependencies
uv run mbta-mcp      # Run the server directly
uv run mypy mbta_mcp/
uv run ruff check mbta_mcp/
uv run ruff format mbta_mcp/

Configuration & Setup

Environment setup: