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

Build and Test Commands

pip install -e ".[dev]"          # Install with dev dependencies
pytest                            # Run all tests
pytest tests/tools/test_channels.py  # Run a single test file
pytest tests/tools/test_channels.py::test_list_channels_returns_all_channels  # Single test
pytest -v                         # Verbose output

CI runs pytest on Python 3.11 and 3.12 via GitHub Actions.

Architecture

This is a Model Context Protocol (MCP) server for the Stoat chat platform (formerly Revolt). It lets AI assistants read channels, messages, users, and DMs from a Stoat server via structured tools.

Key Libraries

• FastMCP (fastmcp>=3.0) — MCP server framework. Tools are registered with @mcp.tool() decorators.
• stoat.py (stoat.py>=1.2) — Async client library for the Stoat API. All API calls are async.
• pydantic-settings — Config loaded from STOAT_ environment variables.

Module Dependency Flow

server.py (FastMCP instance + lifespan)
    ├── config.py (Config model, env vars)
    ├── client.py (stoat.Client factory)
    ├── safety.py (write guards, channel filters)
    ├── formatting.py (markdown helpers, timestamp, hydration)
    └── tools/*.py (each imports `mcp` from server.py)

server.py creates the mcp = FastMCP(...) instance and the lifespan context that yields {"config", "client", "server"}. Tool modules import mcp from server and register themselves via @mcp.tool(). Tools are registered by import side-effect — server.py has from .tools import channels, messages, ... after the mcp definition.

Lifespan context is how tools access runtime state. Every tool receives ctx: Context and reads from ctx.request_context.lifespan_context["config"], ["client"], or ["server"].

Safety Model

All write operations are disabled by default. Two layers of safety guards in safety.py: