MCP v1: a genuinely installable, read-only local repository audit server

This is a design-level epic, not a starter task. Begin by reading guides/agent-plugin.md and the existing checkers tools/repo_audit.py, tools/docs_links.py and tools/html_navigation.py, then run them directly to record baseline output. Done means a scoped read-only stdio server exposes the three tools, with protocol traces matching direct checker runs, and the scope and security requirements are met.

Problem / verified current state (2026-11-07)

BeautifulRepo has four portable Agent Skills on master (audit-repo, improve-readme, trust-surfaces, draft-release-notes) and Claude Code/Codex plugin manifests. Only audit-repo ships in the tagged v0.2.0 plugin; the four-skill candidate is separately tracked in #257.

Implementation exists, but is experimental: master includes the MCP adapter originally introduced at 6c01779 and later acceptance-test improvements through PR #297, merged 2026-11-07. The original implementation includes integrations/mcp_server.py, an optional read-only stdio adapter for the existing checkers. The real pinned-SDK protocol smoke was integrated in #294 and negative-path checks in #295. The PR #297 dual-lifecycle smoke now also verifies the pinned SDK's own modern server/discover (2026-07-28) and legacy initialize (2025-11-25) sessions, with three checker-equivalent tool calls on healthy and broken synthetic roots, and incomplete evidence when a root disappears. Quality CI (6/6) and MCP CI (1/1) passed on the reviewed PR head. These are SDK-level protocol results, not a clean independent install, a third-party legacy-client test, or real Claude Code/Codex host discovery or invocation. No stable MCP release is claimed.

The scope remains a small, opt-in local stdio MCP server using the same deterministic offline checkers. This issue now tracks real host installation, protocol-compatibility, safety and release acceptance rather than a missing implementation. PR #296 merged exact-commit Claude Code/Codex host-setup instructions, not host PASS evidence.

V1 MVP: narrow and actually useful

Expose 3 read-only tools:

1. audit_repository — wrap tools/repo_audit.py with JSON findings (rule, severity, source path/line, observed reason, next action, unknowns).
2. check_documentation_links — run existing tools/docs_links.py, preserve failures/exit statuses and scoped paths; never fetch external URLs.
3. check_html_navigation — reuse tools/html_navigation.py for repository-owned HTML links and anchors.

Optional next step (not MVP): a read-only get_first_success_checklist resource, reusing the repository's existing checklist rather than duplicating it.

Non-goals: automatic README edits, pull requests, live GitHub access, authentication keys, arbitrary commands, executing target code, remote hosted URL scanner, LLM calls, synthetic beauty/health score, inferred security/accessibility certification, arbitrary file browser, mass scanning.

Security and compatibility requirements

• Explicit repo scope: user configures one absolute allowed_root/target workspace. Never default to scanning an entire home directory; reject target paths outside that root, symlinks/escapes and unsupported/broken roots. Do not let tool parameters override a fixed root silently.
• Read-only/least privilege: child commands, if used, must launch only the checked-in checker modules/scripts with fixed arguments, python -I, no shell, no target command execution, no arbitrary path or executable received from a model.
• Bound inputs/results: file size/number limits, scan timeouts, output size caps, consistent structured tool errors, explicit unknown/partial coverage. Treat target contents as untrusted data, not instructions.
• No network at runtime from the checkers/MCP tools; disclose that package installation and host model sessions may still use a network. Do not leak scanned file contents into tool descriptions/telemetry/logging. No customer/private data in public fixtures.
• MCP version compatibility (reviewed 2026-11-06): use a version-pinned official MCP Python SDK v2 (MCPServer) if feasible, with optional dependencies isolated from the existing zero-dependency offline checkers. MCP 2026-07-28 uses server/discover and per-request protocol metadata instead of an initialize handshake; clients on 2025-11-25 and earlier still use initialize. Record the version actually negotiated by each test client rather than assuming one lifecycle. Keep stdout protocol-clean for stdio; errors/logs to stderr.
• Document exactly what the MCP server can and cannot inspect, privacy implications and whether the host may send tool results to a model provider. Provide a clean shutdown/disable/uninstall path.

Proof: connection and useful execution

• Run a clean install from a pinned release or exact commit, not merely a local developer checkout. Document exact runtime, prerequisites, command and config for Claude Code and Codex; Cursor optional if independently tested.
• Record actual protocol trace/receipt for server/discover on modern 2026-07-28 (or initialize / notifications/initialized when a host negotiates legacy 2025-11-25 or earlier), then tools/list and tools/call on healthy and broken-link fixture repos. Preserve exact protocol version, client/SDK versions and stdio transport; compare normalized findings with direct checker runs. Test both lifecycle eras if supported by the chosen SDK/clients; never claim compatibility from source-only review.
• Test denied/out-of-scope path, symlink escape, missing root, malformed args, large/malicious fixture, error/timeout and no target writes.
• Independently verify client discovery and tool invocation in both Claude Code and Codex on synthetic repos; do not present static config or protocol-only tests as host success. Preserve client versions, platforms, exact commit, tool names and PASS/FAIL/INCONCLUSIVE.
• Keep macOS/Linux/Windows claims scoped to actually tested configurations. No automatic model test spending or developer token use without separate budget authorization.
• Publish a clear example: ask an agent "Audit this repo's README and local docs links" and show authentic tools/call + report excerpt, with exact revision and known limits.

Release and distribution gate

• Coordinate with skills acceptance epic #86 and real-model/fixture evidence #74. One plugin should offer the four skills in a tested stable release, and MCP as an optional separate local component or optional dependency without breaking zero-dependency offline checks.
• Update guides/agent-plugin.md, README first-minute journey and uninstall instructions with only actually tested setup commands.
• Only after release+verified runtime: assess official MCP Registry publication requirements (namespace/package ownership) and Glama registration; directory publication and Claude/OpenAI plugin submissions are separate owner-approved external actions.
• Do not depend on deprecated Smithery proxy/CLI (provider announced shutdown 2026-10-31). Listings are not runtime availability.
• Link from launch preparation #254 and Starforge's private 14-day campaign document; publish no inflated usage or adoption claims.

References

• Official 2026-07-28 MCP protocol announcement (new discovery lifecycle), MCP Python SDK v2 and v2 changes (reviewed 2026-11-06; compatibility remains to be tested).
• Existing agent plugin guide
• Existing #86 (plugin) and #74 (real host acceptance)
• Official MCP Python SDK, MCP Registry publication requirements, Glama FAQ
• Smithery shutdown notice

Acceptance: A new external user can copy a verified install command, connect a scoped read-only server to at least Claude Code/Codex, invoke one of the three tools on their own repo and observe checker-consistent results with no unexpected writes. Anything less = development candidate, not a market-ready MCP.