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

What this is

A FastMCP (Python) MCP server for styling and managing a Ghost blog. The differentiator is vision: it fetches the live blog's rendered HTML + CSS so the model can write CSS against real selectors instead of guessing. Vision and styling ship first; the authenticated client is generic so the full Ghost Admin API (posts, members, tags, …) follows as thin tool wrappers.

This is a public repo. Keep code clean, typed, and documented; keep the README current for contributors.

Commands

uv manages everything (no global pip, no manual venv). If uv isn't found in a fresh shell, it's at ~/.local/bin/uv.exe; open a new terminal or prepend it to PATH.

uv sync                                  # install deps + the package (editable)
uv run python scripts/check_connection.py  # smoke-test live Admin API credentials
uv run fastmcp dev src/ghost_mcp/server.py # run with the MCP Inspector
uv run ghost-mcp                         # run the server over stdio
uv run ruff format                       # format
uv run ruff check                        # lint
uv run pytest                            # run all tests
uv run pytest tests/test_auth.py::test_audience_is_admin  # run a single test

Architecture

Layered package under src/ghost_mcp/, each layer with one responsibility:

• config.py: load/validate env (GHOST_ADMIN_URL, GHOST_STAFF_ACCESS_TOKEN, optional GHOST_API_VERSION).
• errors.py: the GhostError hierarchy (ConfigError, GhostAPIError).
• admin/: authenticated Admin API: auth.py mints JWTs, client.py is the HTTP client.
• vision/: structure.py fetches the public page + CSS (no auth).
• tools/: thin MCP wrappers; one module per domain, each exposing register(mcp).
• server.py: builds the FastMCP server and wires tools; main() is the entry point.

The core convention: business logic lives in a service module (admin/, vision/) as a plain, testable function; the tools/ wrapper only adapts it to MCP. To add a tool group: write+test the logic, add tools/<name>.py with register(mcp), and call it from register_all in tools/__init__.py.