mcp-guide-writer

# MCP server usage guide writer Create accurate, user-friendly usage guides that help developers run an MCP server with ToolHive. **Guide scope**: the guide's job is to get the server working with ToolHive: install, configure, connect a client, and try it out. It is not a tutorial for the upstream server itself. Keep upstream-server caveats and behavior details to a sentence with a link to the server's own documentation. ## Research and information gathering - Use the `thv registry info <server-name> --format json` command to gather detailed information about the MCP server, including configuration options, capabilities, and requirements. - Use the `WebFetch` tool, the `fetch` MCP server, or `github` MCP server to retrieve additional documentation from the server's repository. ## Structure Write guides as MDX files in `docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly. Each guide must include ONLY these sections: - Front matter with title, description, last_update author and today's date (`YYYY-MM-DD` format) - Overview section explaining what the MCP server does - Metadata section with `<MCPMetadata name='server-name' />` component - Usage section with tabbed UI/CLI/Kubernetes instructions - Sample prompts section with practical examples - Recommended practices section with security and best practices DO NOT include: - Available tools/capabilities section (handled by MCPMetadata component) - Configuration options section (handled by MCPMetadata component) ## Technical accuracy All configuration examples must be valid and tested. Reference the existing ToolHive documentation in the `docs/toolhive/` directory as the source of truth for: - Available `thv` CLI commands and their syntax (reference: `docs/toolhive/reference/cli/*.md` or run `thv --help`) - Kubernetes CRD specifications and fields (reference: `static/api-specs/toolhive-crds/*.schema.json`) - UI configuration options and workflows (reference: `docs/toolhive/guides-ui/*`) ## Documentation standards Before drafting, read the tech-writer skill's how-to reference and anti-patterns list (`.claude/skills/tech-writer/references/how-to-guides.md` and `.claude/skills/tech-writer/references/anti-patterns.md`); usage guides are how-to guides and follow that mode's discipline. Adhere to the project's writing style guide (`STYLE-GUIDE.md`) including: - Use US English with casual, conversational tone - Address readers in second person ("you", "your") - Use sentence case for headings - Apply proper Markdown formatting (ATX headings, fenced code blocks with language tags) - Include descriptive alt text for images - Use admonitions (`:::note`, `:::tip`, `:::warning`) for important information, using `:::tip[Title]` format for custom titles ## Practical examples Provide real-world, actionable examples that users can copy and modify. Include: - CLI usage examples covering the common configurations for this server, including security configurations - Complete Kubernetes manifests with proper YAML formatting - UI configuration guidance focusing on unique features - Sample prompts that demonstrate real use cases for the MCP server - Security-focused examples using network isolation and permission profiles ## Reference existing guides - Use `docs/toolhive/guides-mcp/_template.mdx` as the reference for exact structure. - Use existing guides as reference for tone and depth of coverage. A good example is `docs/toolhive/guides-mcp/github.mdx`. ## Quality assurance Before finalizing, verify that: - All code examples are syntactically correct - Configuration parameters match the actual MCP server requirements - Links to external resources are valid and current - The guide follows the established template structure - Examples work with current ToolHive versions ## Content structure requirements 1. **Overview section**: Provide a clear, concise explanation of the MCP server's purpose and key features. Include links to official documentation and highlight what makes this server unique. 2. **Usage section tabs**: Using the MCP server's documentation as reference, use its unique features and use cases to create detailed instructions for each tab: - **UI tab**: Focus on unique configuration options and features, not basic registry selection. The ToolHive UI includes a configuration interface that allows users to set the secrets and environment variables defined in the server metadata, customize command-line arguments, and add volume mounts. Provide step-by-step instructions for these configurations if needed for the MCP server. - **CLI tab**: Provide examples covering the common configurations, including security configurations. - **Kubernetes tab**: Include complete, working YAML manifests with proper formatting and comments. 3. **Sample prompts**: Create 3-6 realistic prompts that demonstrate the server's capabilities. Make them specific and actionable, not generic. 4. **Recommended practices**: Focus on security, performance, and reliability best practices specific to the MCP server.