WORK-175
ID:WORK-175Status:draft

Site docs — MCP + plugin authoring update + CLAUDE.md pointer

Document the new @refrakt-md/mcp server (registration, tool reference, resource reference) at site/content/docs/mcp/, update the existing plugin authoring docs to cover the new cli-plugin schema fields (inputSchema, outputSchema, mcpHandler), and add a brief pointer in the root CLAUDE.md so AI agents know the MCP server exists when registered.

Priority:mediumComplexity:moderateMilestone:v0.11.0Source:SPEC-043
main View source

Criteria completion

Criteria completion: 0 of 5 (0%) checked; tracking started on May 1, no incremental history yet0%25%50%75%100%May 1May 11

Tracking started May 1 — check back for trends.

Relationships

Implements 1
Related 4
Branches 2
main current draft
claude/v0.11.0-config-foundation doneclaude/mcp-cli-wrapper-design-LsEXZ draft
History 2
  1. ce8fb3c
    Created (draft)by bjornolofandersson
  2. 2b1f874
    Content editedby Claude
    plan(v0.11.0): scaffold milestone and 17 work items

Acceptance Criteria

  • New site/content/docs/mcp/ directory with:
    • overview.md — what the MCP server is, when to use it, the auto-detection model
    • installation.md — registering with Claude Desktop, Claude Code, and other MCP clients
    • tools.md — full tool reference (core + plan), generated or hand-written
    • resources.md — full resource reference (refrakt://detect, refrakt://reference, refrakt://contracts, refrakt://rune/*, refrakt://plan/*)
    • errors.md — error envelope shape, error codes, how agents should react
  • site/content/docs/packages/authoring.md (or wherever package authoring lives) updated with a "Making your commands MCP-friendly" section covering inputSchema, outputSchema, mcpHandler
  • Root CLAUDE.md gets a short paragraph (≤5 lines) under a new ## MCP Server heading explaining that @refrakt-md/mcp exists, what it exposes, and how to know if it's available
  • Cross-references between MCP docs and the configuration docs (WORK-174) for --cwd and detection behavior
  • Docs site builds cleanly

Approach

  1. Mirror the structure of existing docs sections under site/content/docs/.

  2. Tool/resource references can be hand-written for v1; future work might generate them from the source if maintenance becomes a burden.

  3. The CLAUDE.md addition should be neutral — agents read it whether or not the MCP server is actually registered, so it should describe the server's existence and capability without assuming it's available.

Dependencies

  • WORK-169, WORK-170 — docs need real tools and resources to describe
  • WORK-167 — plan command schemas should be stable for the tool reference
  • WORK-174 — configuration docs that this section cross-references

References

  • SPEC-043 — Refrakt MCP Server (full surface)
  • CLAUDE.md — root-level instructions to extend
  • site/content/docs/packages/authoring.md — plugin authoring guide