EPICS-MCP: Instructions file for Claude Code

CLAUDE.md: EPICS MCP

Guidance for an AI assistant (Claude Code and similar) working in this repository. It applies to every session here, including a fresh one with no other skill or project folder loaded; this repo is meant to be self-sufficient.

Role of this file

This server is an autonomous knowledge carrier: its operational knowledge ships with the code, so a session that only has this repository can use and extend the server without re-deriving how the EPICS service landscape behaves. This file is the standing policy that keeps that true.

Orientation: where things live

• README.md is the landing page: what the server is, the planes, install, and an index of everything below. Keep it short; reference depth belongs in docs/.
• docs/ holds the reference pages the README indexes: tools.md, configuration.md, safety.md, mcp-clients.md, quick-start.md (three commands to a first answer, with no control system; it lived in the README until it was a quarter of the landing page), deployment.md (bringing the server up in a new facility, the first thing an outside adopter needs), write-gate-contract.md (the specification every in-server write gate must meet) and known-limits.md (what is deliberately not guarded, dated and measured, which the README indexes as well).
• ARCHITECTURE.md: the server → tools → services → clients layering and the plane model.
• CONTRIBUTING.md: dev setup, the gate chain, Definition of Done, commit style.
• SECURITY.md: reporting channel, security posture, and an explicit statement of what the write gates are not.
• CHANGELOG.md: release history for a USER, in English. A new, changed or removed tool; a breaking change; an error code or field that changed on the wire; a new EPICS_MCP_* var; a bug a user could hit. Not audit runs, test methodology, red-proof notes, tools/list byte budgets, work-item ids, or internal refactors with no user-visible effect: those go to the tiers below, and the work itself is narrated in the commit body. It drifted into a 763-line work journal once, because no rule claimed it. ⚠️ The kind decides the SECTION as well, and that half was missing. A change that moves a value on the wire is a breaking change wherever it is filed, so it belongs under ### Changed, marked BREAKING, and carrying an Are you affected? passage that names what a reader should search for. Filing it under ### Added because new fields arrived with it leaves the entries that DO carry that passage reading as the complete list of the release's breaks, and a reader who is affected concludes they are not. Measured TWICE, and the older case is the reason this is a rule and not an anecdote: [0.7.0] filed the has_display change that way, and [0.4.0] filed a plane status moving from ok to the new no_ingest that way. Only 0.7.0 sprang the trap in full, because only it has entries carrying the passage for a reader to mistake for the whole list; the filing error itself is older than the passage. ⚠️ The line through test vocabulary runs the same way, because "not test methodology" alone never said where it falls: what a USER can OBSERVE belongs in, such as has_display now answering about screens alone; how we convinced ourselves does not, such as a pin widened over a corpus. An entry that declares itself to have no user-visible effect fails the kind test outright and belongs in the commit body, whatever hardening it also does. ⚠️ That rule names a KIND, and a kind alone did not hold, so there is a SIZE as well: one entry under ## [Unreleased] is at most 1400 bytes. Held by tests/test_changelog_discipline.py, where the number is derived from the measured distribution rather than picked (it clears every entry standing today and would have stopped 13 of the 45 in [0.6.0]). It works forward only, by construction and not by exemption: the guard reads the [Unreleased] section and no other, so published history is out of scope rather than excused. An entry that needs more room is usually carrying the analysis as well as the change; that half belongs in the commit body, the guard's own docstring, or the operator guide. ⚠️ Those three are not interchangeable. The sdist ships src, docs and the top-level documents, never tests/ or scripts/, so a package consumer reaches the operator guide and docs/ and neither of the other two. For something a USER has to act on, the operator guide is the alternative that actually arrives. And the cap is about the length of one claim, never about whether the entry belongs: measured, the entries it would have stopped in [0.6.0] include a BREAKING change and four credential fixes.
• .env.example: the canonical, commented configuration template (every EPICS_MCP_* var).
• examples/ holds a sample .bob and an mcp.json: the path for someone with no facility at all. The test.db beside them is the ALTERNATIVE rather than the starting point, since running it needs EPICS Base, which this package does not install; epics-testpv is what needs nothing.
• src/epics_mcp/operator_guide.md: the operational cookbook (service planes, recipes, error signatures). Shipped as package data, served as the epics://guide MCP resource, mirrored for humans by OPERATING.md. One source file, three consumers: never copy it, link it.
• sandbox/: a LOCAL EPICS test stack (IOC + REST services) for the opt-in live tests. It is git-ignored, so it is absent from every clone; the live tests are pointed at it through EPICS_MCP_* env vars and skip when those are unset.