vestibule: 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

vestibule is a new Python 3.13 project using uv for package management. The project is in its initial scaffold stage.

Commands

# Run the application
uv run python main.py

# Add a dependency
uv add <package-name>

# Add a dev dependency
uv add --dev <package-name>

# Run a command in the project environment
uv run <command>

Architecture

• Entry point: main.py — currently a minimal scaffold printing a greeting
• Configuration: pyproject.toml — defines project metadata and dependencies (PEP 621)
• Python version: 3.13 (specified in .python-version)

Notes

• The project uses uv — prefer uv run, uv add over pip and python directly
• README.md is populated — keep it in sync as features are added

FastMCP integration notes

These are hard-won facts about the mcp library (FastMCP). Read the public API surface and source before touching library internals — do not reach into _private attributes.

• Version: mcp>=1.28.1 (see pyproject.toml). Re-validate these notes when bumping the dependency.
• Upstream docs: https://github.com/modelcontextprotocol/python-sdk

Public API surface (use these, not private attrs)

• list_tools() — returns registered tools (use for existence checks)
• call_tool(name, arguments) — invoke a tool
• add_tool() / remove_tool() / tool() — register/unregister
• list_prompts(), list_resources(), read_resource(), get_prompt()

Error-wrapping behavior (critical)

• FastMCP wraps all tool exceptions — pydantic argument-validation errors AND TypeError — into ToolError("Error executing tool {name}: ...").
• Consequence: argument-validation errors are not INVALID_PARAMS; they surface as ToolError. A TypeError branch in a handler is only reachable via a non-FastMCP fallback path (e.g. calling tool.handler(**args) directly).
• To distinguish protocol errors from business errors, pre-check tool existence (via list_tools()) and raise ToolError for unknown tools so the transport maps it to method_not_found.