Docs MCP server: typed results, instructions and a section option #577

Summary

Make the docs MCP server easier for a client and a model to use: typed results, a short statement of how to use it, and a way to fetch one section of a long page.

Context

At docs commit aeb5162, probed on https://docs.marfa.so/mcp:

• docs_search and docs_list_topics return JSON written into a text block. There is no structuredContent and no outputSchema.
• The server sends no instructions and exposes no resources or prompts.
• docs_fetch returns the whole page. The changelog is 11,854 words.

The MCP tools specification (revision 2026-07-28, https://modelcontextprotocol.io/specification/latest/server/tools) says a tool that returns structured content SHOULD also return the serialized JSON in a text block, and that a server that declares an outputSchema MUST return results that conform to it.

Acceptance criteria

• docs_search and docs_list_topics declare an outputSchema and return structuredContent that conforms to it, plus the same JSON as a text block.
• The server sends instructions that say: search, then fetch; the server reads the docs only and cannot reach an instance.
• docs_fetch takes an optional heading. With it, the result is that section only. An unknown heading is a tool error (isError: true) that lists the page's headings.
• Cases for each change are in src/lib/mcp/server.test.ts before the change, per src/AGENTS.md.
• The tool names, inputs and text results that clients use today keep working.

Out of scope

• Resources, prompts and any tool that writes an answer.
• Changing the search itself.

Notes

marfa docs reads the .md copies and can cut a section out of the Markdown on its own, so it needs no change to the JSON addresses.