atproto-mcp: Instructions file for Codex

AGENTS.md

MCP server exposing a semantic-search knowledge base over AT Protocol docs, lexicon schemas, Bluesky API docs, and cookbook examples. Python 3.12+, FastMCP-style MCPServer (mcp SDK >=2.0) + txtai hybrid (BM25 + dense) embeddings, stdio transport.

Commands

uv sync                                            # install (uv-managed, hatchling build)
uv run atproto-mcp                                 # run server over stdio
uv run mcp dev src/atproto_mcp/server.py           # MCP Inspector
uv run python -m unittest discover -s tests -p 'test*.py'  # test suite (what CI runs)
uv run python tests/smoke_test.py                  # manual end-to-end check (see gotcha below)

• No linter, formatter, or type-checker is configured. Match existing style by hand.
• CI (.github/workflows/tests.yml) installs with plain pip install . on Python 3.12 and runs the unittest discover command above.
• pyproject.toml requires Python >=3.12 (matches README's "Python 3.12+" prerequisite).

Architecture

Startup flow (server.py): app_lifespan → Config.from_env() → publish state.config → asyncio.create_task(_warmup(config)) → yield immediately. Nothing slow runs on the startup path: a cold start clones four repos and downloads a ~130MB model, far longer than a desktop host will wait during the stdio handshake.

_warmup() then, off the startup path:

1. KnowledgeBase.load() via asyncio.to_thread — before any network access, so a warm start serves in seconds even offline. On success it publishes with state.commit_kb(kb, generation, save=False) (already on disk, do not rewrite) and sets status ready.
2. fetch_all() to clone/refresh repos.
3. Cold start: parse_all() + kb.build(save=False) + commit_kb(). Warm start: if the loaded index's repo SHAs (kb.indexed_shas) or embedding pipeline (kb.indexed_pipeline) differ from the current config, the live index keeps serving while _rebuild_index() builds a fresh KnowledgeBase via asyncio.to_thread and commits it.