euclidMCPPaper CLAUDE.md

CLAUDE.md — Euclid-MCP project conventions

Binding guidelines for any agent working in this repo. Read alongside SPEC.md.

Golden rules

1. Spec is the source of truth. Implement what SPEC.md + specs/*.md describe. If reality forces a deviation, note it in the PR and update the spec in the same change — never let code and spec drift.
2. Milestone discipline. Build M0→M6 in order. A milestone is not "done" until ruff, mypy --strict, and that milestone's tests are green. Don't scaffold ahead.
3. The IR boundary is sacred. Nothing above lowering/ may mention Prolog. ir/, tools/, and the MCP surface stay engine-agnostic so a second backend can be added later.
4. Determinism over cleverness. Normalize ordering, avoid nondeterministic dict iteration in outputs, seed nothing random. Same input ⇒ same bytes.

Language & style (Python)

• Python ≥ 3.11, src layout (src/euclid_mcp/).
• Type hints everywhere; mypy runs in --strict. No Any unless justified with a comment.
• Pydantic v2 for every tool I/O model and the IR AST. Use model_config = ConfigDict(extra="forbid", str_strip_whitespace=True). Use field_validator (not validator), model_dump() (not dict()).
• Ruff for lint + format (line length 100). Rule sets: E,F,I,UP,B,SIM,RUF.
• Module-level constants in UPPER_CASE (MAX_INPUT_BYTES = 500_000, DEFAULT_TIMEOUT_S = 30, DEFAULT_MAX_SOLUTIONS = 5, DEFAULT_MAX_DEPTH = 30).
• Group imports: stdlib / third-party / local. Prefer specific exceptions over bare Exception.
• DRY: shared parse→lower→run pipeline lives in one place; the four tools call it, they do not each re-implement it.
• Docstrings on every public function; for tools, the docstring is the MCP description — make it precise and include the return schema.

MCP conventions (from MCP best practices)

• Server name: euclid_mcp ({service}_mcp, lowercase, no versions/dates).
• Tool names: exactly reason, diagnose, what_if, check_kb (snake_case, paper-defined — do not rename or prefix).
• Every @mcp.tool sets name and annotations. All four tools are read-only:

  annotations={
      "title": "...",
      "readOnlyHint": True,
      "destructiveHint": False,
      "idempotentHint": True,
      "openWorldHint": False,
  }
  

• Tool inputs are a single Pydantic model argument with Field(...) descriptions and constraints. Let Pydantic validate; don't hand-roll validation.
• Errors are feedback, not exceptions across the boundary. Backend/parse errors are returned as readable text in the result payload so the LLM can self-correct — never leak a stack trace or crash the tool call. Messages must be actionable ("Undefined predicate mortal/1; add a fact or rule with head mortal(...)").
• Prefer structured returns (Pydantic models) so FastMCP emits an output schema; also include a rendered human-readable field where the paper shows one (conclusion, proof-tree text).