mcp-scribe: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repository.

What this is

mcp-scribe turns an OpenAPI schema into a production-grade MCP server. It is a compiler with a runtime attached: it lowers an OpenAPI document into MCP tools, then executes those tools as real HTTP requests with auth, retries, rate limiting, and response shaping already handled.

Package lives in src/mcp_scribe/ (src layout, Poetry, packages = [{include = "mcp_scribe", from = "src"}]).

Commands

poetry install --all-extras --with lint,test

poetry run pytest -q                        # 201 tests, ~1s
poetry run pytest tests/test_toolset.py -q  # one file
poetry run pytest -m remote                 # network tests (opt-in marker)

poetry run ruff check src tests             # lint
poetry run black src tests examples         # format  <-- see below
poetry run mypy src/mcp_scribe              # types
poetry build

Formatting: black only. Do not run ruff format.

black at line-length = 70 is the formatter of record. [tool.black] and [tool.ruff] both pin 70 in pyproject.toml, and they must stay identical — when they drift, each tool rewrites what the other just wrote and every file shows up as modified.

At 70 columns black and ruff format genuinely disagree (tuple-unpacking RHS, assert x, msg parenthesization). They agreed at 100; they do not at 70. So:

• Format with black. Never run ruff format — it will fight black on ~2 files and reintroduce the churn loop.
• Lint with ruff check. That is ruff's only job here.
• E501 is in ruff's ignore list. At 70 the remaining long lines are URLs, OpenAPI keyword names, and string literals no formatter can split; enforcing it produces 400+ findings black cannot act on.

If a ruff check --fix result and black disagree, verify they reach a fixpoint (apply the fix, run black, confirm nothing changes) before committing.

README.md's Development section still lists ruff format --check src tests. That command now fails by design — it should be black --check.