fastmcp-docs: 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

FastMCP Docs is a Python library that generates Swagger-style documentation for FastMCP servers. It automatically extracts tool information from FastMCP instances and provides a web-based UI similar to Swagger/OpenAPI documentation interfaces.

Key Commands

Development Setup

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install package in development mode
pip install -e ".[dev]"

Testing

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_extractor.py

Code Formatting

# Format all code
black fastmcp_docs/

Type Checking

# Type check with mypy
mypy fastmcp_docs/

Building and Distribution

# Clean previous builds
rm -rf dist/ fastmcp_docs.egg-info/

# Build package
uv run python -m build

# Check distribution
uv run python -m twine check dist/*

# Upload to PyPI
uv run python -m twine upload dist/*

# Install from local build
pip install -e .

Version Bump Process:

1. Update version in pyproject.toml
2. Run full build and distribution process above
3. Commit and tag the release:

   git add -A
   git commit -m "Release v1.0.0: Add FastMCP v3 support"
   git tag -a v1.0.0 -m "Version 1.0.0"
   git push && git push --tags
   

Running Examples

# Run basic usage example
python examples/basic_usage.py

Architecture

Core Components

The library consists of five main modules:

1. __init__.py - Main entry point exposing the FastMCPDocs class

   • Provides the public API for library users
   • Coordinates between extractor, routes, and config modules
   • Setup is async because it needs to call async methods on FastMCP server

2. config.py - Configuration dataclasses

   • FastMCPDocsConfig: Main configuration with route paths, OpenAPI settings, UI customization
   • DocsLink: Simple dataclass for documentation links
   • Configuration supports dict-to-DocsLink conversion in __post_init__