Inception — inventory the Inspector factory, write docs/agent-guidance-inception.md #4859

Part of the agentic software factory tracker #4858. This is the first sub-issue, and has no dependencies.

Goal

Work out how much of the MCP Inspector's agentic software factory carries over to this repo unchanged, what needs adapting, and what is unique to this repo. Record the findings in docs/agent-guidance-inception.md, then use that doc to create the remaining sub-issues of #4858.

Sources

• inspector#2498: "MCP Inspector: Our AI Software Factory" (docs/ai-software-factory.md). This is the overall outline, covering:
  • the split between rules and skills
  • the issue lifecycle and PR flow, including how sessions start and /goal mode
  • automated dependency sweeps in place of Dependabot PRs
  • the human-gated security-advisory track
  • the quality gate
• The inspector's v2/main branch:
  • AGENTS.md
  • .claude/skills/*: board-ops, issue-create, issue-triage, local-dev, pr-flow, pre-push-gate, project-structure, release, security-advisory, test-servers, testing
  • CI workflows
  • the local:gate / validate / coverage scripts
  • the skills eval harness (skills:eval)
• This repo:
  • CLAUDE.md
  • .github/workflows/* (typescript, python, release with OIDC trusted publishing)
  • RELEASING docs
  • the PR template
  • the per-server package layout

What the doc must contain

1. Inventory: every element of the Inspector factory (each rule group in AGENTS.md, each skill, each script and gate, each CI and release workflow, each automated sweep, board conventions, labels and milestones). For each one, say what it does.
2. A verdict on each element:
   • Transfers directly: copy it with renames only.
   • Adapt: same intent, different mechanics. Name the adaptation, e.g. per-package gates, a Python equivalent, npm + PyPI publishing.
   • Not applicable: say why.
3. What only this repo needs:
   • A monorepo of 7 independently published servers in two languages:
     • gates that run per package and across the workspace
     • uv/pytest/pyright/ruff equivalents of every TypeScript gate
     • per-file coverage enforcement in Python (coverage.py's fail_under is global only)
   • Server-oriented testing: protocol-level client harnesses, and smoke tests with the Inspector and an LLM client, in both spec eras (see Tracker: 2026-07-28 Spec Refactor #4857).
   • Release and publish: v2/main → main milestone merges, npm and PyPI publishing, per-package versioning (calendar versioning today, vs changesets in New release pipeline, Phase 2: semver via changesets (TS), GitHub-Release-triggered publishing #4472).
   • Triage for high community inflow, including server-submission spam and "add my server to the README" PRs.
   • Security-advisory handling for servers with filesystem, git and network reach.
4. A reusable-templates list: the Inspector files that can be copied in as starting points, with the edits each one needs.
5. Proposed sub-issues: an ordered list grouped in waves, each with a scope and acceptance criteria. At a minimum:
   • AGENTS.md (absolute rules)
   • issue-create, pr-flow and board-ops skills
   • quality-gate skill(s) plus the matching CI enforcement
   • v2/main → main milestone release and publish flow
   • reconciling New release pipeline, Phase 2: semver via changesets (TS), GitHub-Release-triggered publishing #4472 and the coverage-gate work in Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854 / Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855

Retire CLAUDE.md: everything useful moves to AGENTS.md

Claude Code reads AGENTS.md directly, so this repo will not keep a CLAUDE.md, not even a one-line @./AGENTS.md pointer. The Inspector is making the same change.

• The inception doc must map every section of the current CLAUDE.md to where it goes: an AGENTS.md rule, a skill, or dropped as obsolete/derivable. Current sections:
  • project overview
  • monorepo structure (7 servers, package names, registries)
  • build and test commands for each language
  • code style for TypeScript and Python
  • contributing guidelines (accepted / selective / not accepted)
  • the CI/CD pipeline
  • the MCP protocol reference (.mcp.json docs server, schema repo)
  • key patterns (registerTools/registerResources/registerPrompts, tool annotations, transports, PR template checklist)
• The proposed AGENTS.md sub-issue must end with CLAUDE.md deleted. Verify that Claude Code still picks up the guidance without it.

Carried over from #4473, which this issue supersedes

#4473 planned the AGENTS.md content in detail. These decisions are inputs to the inception doc and the AGENTS.md / skills sub-issues it proposes. Where the rest of this tracker has since changed things, that is noted.

• Reference: the Inspector's AGENTS.md on v2/main. The main-branch version is a thin early draft.
• Tool-agnostic rules: Claude Code, Copilot, Cursor and other agents all read the same document, so nothing is maintained twice.
• Planned sections, adapted from the reference:
  • Project Structure: an annotated src/ tree with each server's package name and registry.
  • Development setup / build and test commands: npm workspaces for TypeScript (Node 22, vitest + coverage-v8), uv and hatchling for Python (pytest, pyright, ruff).
  • Repository & project board:

    • Repo: modelcontextprotocol/servers. Base branch is v2/main; Adopt AGENTS.md (with CLAUDE.md pointer) modeled on the inspector repo #4473 said main, which predates the v2/main flow.

    • Board: Servers V2 (Initial GitLab server version #43), the only board.

    • gh recipes with a table of stable IDs:

      Thing	ID
      Project node ID	PVT_kwDOCt2Azc4BcZgq
      Status field ID	PVTSSF_lADOCt2Azc4BcZgqzhXCpm0
      Status: Todo	f75ad846
      Status: In Progress	98236657
      Status: In Review	47fc9ee4
      Status: Done	25b87ca0

      This material probably belongs in the board-ops skill rather than AGENTS.md; the inception doc decides.

  • Issue-driven work style:
    • An issue isn't "created" until it is labelled v2, and is on board 43, and has a Status.
    • Only issues go on the board, never PRs.
    • No draft cards. Check for duplicates before creating. Assign the creator.
    • Status flow: Todo → In Progress (branch created) → In Review (PR open) → Done (merged).
    • The first line of a PR body is Closes #N. On v2/main, that doesn't auto-close, so close the issue and move the card by hand.
    • New work discovered along the way becomes new issues.
  • Maintenance rules: keep the READMEs, per-server READMEs, RELEASING.md and AGENTS.md itself in sync. Link to RELEASING.md rather than duplicating it.
  • Always test new or modified code: vitest and pytest. Adopt AGENTS.md (with CLAUDE.md pointer) modeled on the inspector repo #4473's "no 90% gate on day one" is superseded: the per-file 90% gate comes from Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854 / Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855.
  • Responding to code reviews: copy the reference's etiquette. Not every suggestion has to be implemented. Diverging or declining is fine with a reason. Reply to every review comment.
  • Lint-fixed, formatted code plus validate (decided in Adopt AGENTS.md (with CLAUDE.md pointer) modeled on the inspector repo #4473):
    • Root Prettier and ESLint (flat config), shared across the TypeScript workspaces.
    • A root npm run validate that runs format:check → lint → build → test across the workspaces.
    • The rule: always npm run format before committing, and npm run validate before pushing.
    • CI (typescript.yml) runs validate.
    • Python's equivalent is documented per server: uv run pyright && uv run ruff check . && uv run pytest.
  • TypeScript instructions:
    • The reference's rules: never any, never suppress compiler or linter errors through config, lean on inference, generics and type guards.
    • Server idioms:
      • ESM with .js import suffixes
      • Zod input schemas
      • naming conventions, with verb-first tool names
      • registerTools / registerResources / registerPrompts
      • tool annotations
      • transports
  • Python instructions: pyright-enforced type hints, ruff clean, async/await and pytest-asyncio, and the module layout of each server.
  • Contribution boundaries: accepted / selective / not accepted, no new server implementations (point to the registry instead), and the PR checklist.
  • Omitted: the Inspector's React/Mantine and web-auth-token sections have no equivalent here.

Tasks

• Write docs/agent-guidance-inception.md and open a PR against v2/main.
• After review, create the sub-issues it proposes under Tracker: Agentic software factory (AGENTS.md, skills, quality gates, v2/main release flow) #4858. Each one gets the v2 label and milestone, sits on the Servers V2 board, and states that it targets v2/main.
• Decide on New release pipeline, Phase 2: semver via changesets (TS), GitHub-Release-triggered publishing #4472: fold it in as a sub-issue, rescope it, or close it as superseded.
• Make sure every section of the current CLAUDE.md and every decision carried over from Adopt AGENTS.md (with CLAUDE.md pointer) modeled on the inspector repo #4473 is mapped to a proposed sub-issue.

Acceptance criteria

• The doc is merged on v2/main.
• Every Inspector factory element has a verdict.
• The follow-up sub-issues exist under Tracker: Agentic software factory (AGENTS.md, skills, quality gates, v2/main release flow) #4858 in wave order.