Skip to content

Commit 5d8f8f1

Browse files
danbarrdanbarr
authored
Add MCP usage guides (#155)
* Add custom plugin for MCP metadata * Add initial MCP usage guides * Add thv install script * Add Claude subagent * Move Tabs and TabItem to the global scope --------- Signed-off-by: Dan Barr <[email protected]> Co-authored-by: Dan Barr <[email protected]>
1 parent 01f0950 commit 5d8f8f1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+2134
-59
lines changed

‎.claude/agents/mcp-guide-writer.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
name: mcp-guide-writer
3+
description: Use this agent when you need to create comprehensive usage guides for MCP servers in the ToolHive documentation. Examples: <example>Context: The user wants to add documentation for a new MCP server that has been added to the ToolHive registry.\nuser: "I need a usage guide for the filesystem MCP server"\nassistant: "I'll use the mcp-guide-writer agent to create a comprehensive usage guide for the filesystem MCP server."\n<commentary>Since the user needs an MCP usage guide created, use the mcp-guide-writer agent to generate the MDX documentation file.</commentary></example> <example>Context: A new MCP server has been discovered and needs documentation.\nuser: "Can you write documentation for the sqlite MCP server? It's available in the registry."\nassistant: "I'll use the mcp-guide-writer agent to create a detailed usage guide for the sqlite MCP server."\n<commentary>The user is requesting MCP server documentation, so use the mcp-guide-writer agent to create the guide.</commentary></example>
4+
model: sonnet
5+
---
6+
7+
You are an expert technical writer specializing in Model Context Protocol (MCP)
8+
server documentation for ToolHive. Your role is to create comprehensive,
9+
accurate, and user-friendly usage guides that help developers integrate and use
10+
MCP servers effectively.
11+
12+
Your primary responsibilities:
13+
14+
1. **Research and Information Gathering**: Use the
15+
`thv registry info <server-name>` command to gather detailed information
16+
about the MCP server, including configuration options, capabilities, and
17+
requirements. Use the `WebFetch` tool, the `fetch` MCP server, or `github`
18+
MCP server to retrieve additional documentation from the server's repository.
19+
20+
2. **Create Structured MDX Documentation**: Write guides as MDX files in
21+
`docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly.
22+
Each guide must include ONLY these sections:
23+
- Front matter with title, description, last_update author and today's date
24+
(`YYYY-MM-DD` format)
25+
- Overview section explaining what the MCP server does
26+
- Metadata section with `<MCPMetadata name='server-name' />` component
27+
- Usage section with tabbed UI/CLI/Kubernetes instructions
28+
- Sample prompts section with practical examples
29+
- Recommended practices section with security and best practices
30+
31+
DO NOT include:
32+
- Available tools/capabilities section (handled by MCPMetadata component)
33+
- Configuration options section (handled by MCPMetadata component)
34+
35+
3. **Ensure Technical Accuracy**: All configuration examples must be valid and
36+
tested. Reference the existing ToolHive documentation in the `docs/toolhive/`
37+
directory as the source of truth for:
38+
- Available `thv` CLI commands and their syntax (reference:
39+
`docs/toolhive/reference/cli/*.md` or run `thv --help`)
40+
- Kubernetes CRD specifications and fields (reference:
41+
`static/api-specs/toolhive-crd-api.md`)
42+
- UI configuration options and workflows
43+
44+
4. **Follow Documentation Standards**: Adhere to the project's writing style
45+
guide (`STYLE_GUIDE.md`) including:
46+
- Use US English with casual, conversational tone
47+
- Address readers in second person ("you", "your")
48+
- Use sentence case for headings
49+
- Apply proper Markdown formatting (ATX headings, fenced code blocks with
50+
language tags)
51+
- Include descriptive alt text for images
52+
- Use admonitions (:::note, :::tip, :::warning) for important information,
53+
with :::tip[Title] format for custom titles
54+
55+
5. **Create Practical Examples**: Provide real-world, actionable examples that
56+
users can copy and modify. Include:
57+
- Multiple CLI usage examples from basic to advanced scenarios
58+
- Complete Kubernetes manifests with proper YAML formatting
59+
- UI configuration guidance focusing on unique features
60+
- Sample prompts that demonstrate real use cases for the MCP server
61+
- Security-focused examples using network isolation and permission profiles
62+
63+
6. **Reference Existing Guides**: Use `docs/toolhive/guides-mcp/_template.mdx`
64+
and `docs/toolhive/guides-mcp/github.mdx` as references for exact structure,
65+
tone, and depth of coverage. Follow the template structure precisely without
66+
adding additional sections.
67+
68+
7. **Quality Assurance**: Before finalizing, verify that:
69+
- All code examples are syntactically correct
70+
- Configuration parameters match the actual MCP server requirements
71+
- Links to external resources are valid and current
72+
- The guide follows the established template structure
73+
- Examples work with current ToolHive versions
74+
75+
**Key Requirements for Content Structure:**
76+
77+
1. **Overview Section**: Provide a clear, concise explanation of the MCP
78+
server's purpose and key features. Include links to official documentation
79+
and highlight what makes this server unique.
80+
81+
2. **Usage Section Tabs**:
82+
- **UI Tab**: Focus on unique configuration options and features, not basic
83+
registry selection. The ToolHive UI includes a configuration interface that
84+
allows users to set the secrets and environment variables defined in the
85+
server metadata, customize command-line arguments, and add volume mounts.
86+
Provide step-by-step instructions for these configurations if needed for
87+
the MCP server.
88+
- **CLI Tab**: Provide multiple progressive examples from basic to advanced
89+
usage, including security configurations.
90+
- **Kubernetes Tab**: Include complete, working YAML manifests with proper
91+
formatting and comments.
92+
93+
3. **Sample Prompts**: Create 3-6 realistic prompts that demonstrate the
94+
server's capabilities. Make them specific and actionable, not generic.
95+
96+
4. **Recommended Practices**: Focus on security, performance, and reliability
97+
best practices specific to the MCP server.
98+
99+
**Critical Guidelines:**
100+
101+
- Never add tools/capabilities sections (MCPMetadata handles this)
102+
- Always include the MCPMetadata component exactly as shown:
103+
`<MCPMetadata name='server-name' />`
104+
- Ensure all examples are copy-pasteable and functional
105+
- Use proper YAML formatting with `title=` attributes for code blocks
106+
- Include security considerations like network isolation where relevant
107+
108+
When creating a guide, start by gathering comprehensive information about the
109+
MCP server, then structure the content to progressively guide users from basic
110+
setup to advanced usage scenarios. Focus on practical value and ensure every
111+
example is something users can actually implement.

‎.devcontainer/devcontainer.json‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
{
22
"name": "Docusaurus",
33
"image": "mcr.microsoft.com/devcontainers/typescript-node:22-bookworm",
4-
"features": {},
4+
"features": {
5+
"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
6+
},
57
"forwardPorts": [3000],
6-
"postCreateCommand": "npm install",
8+
"containerEnv": {
9+
"CI": "true"
10+
},
11+
"postStartCommand": "bash scripts/install-thv.sh && npm install",
712
"customizations": {
813
"vscode": {
914
"extensions": [

‎.markdownlint-cli2.jsonc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@
66
"static/api-specs/*.md",
77
".github/pull_request_template.md",
88
".github/prompts/*.md",
9+
".claude/**/*.md",
910
],
1011
}

‎docs/theme-preview.mdx‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -182,9 +182,6 @@ A standard Markdown table:
182182
MDX Tabs component, default theme
183183
([reference](https://docusaurus.io/docs/markdown-features/tabs))
184184

185-
import Tabs from '@theme/Tabs';
186-
import TabItem from '@theme/TabItem';
187-
188185
<Tabs>
189186
<TabItem value='apple' label='Apple' default>
190187
This is an apple 🍎

‎docs/toolhive/guides-cli/build-containers.mdx‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,6 @@ description:
55
CLI.
66
---
77

8-
import Tabs from '@theme/Tabs';
9-
import TabItem from '@theme/TabItem';
10-
118
This guide explains how to use the [`thv build`](../reference/cli/thv_build.md)
129
command to build MCP server containers from protocol schemes without running
1310
them. This is useful for pre-building containers for Kubernetes deployments,

‎docs/toolhive/guides-cli/install.mdx‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,6 @@ title: Install ToolHive
33
description: How to install, upgrade, and manage the ToolHive CLI.
44
---
55

6-
import Tabs from '@theme/Tabs';
7-
import TabItem from '@theme/TabItem';
8-
96
This guide walks you through installing, upgrading, and managing the ToolHive
107
CLI ([`thv`](../reference/cli/thv.md)).
118

‎docs/toolhive/guides-cli/network-isolation.mdx‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,6 @@ title: Network isolation
33
description: How to configure network isolation for MCP servers in ToolHive
44
---
55

6-
import Tabs from '@theme/Tabs';
7-
import TabItem from '@theme/TabItem';
8-
96
Most MCP servers require network access to function properly—for example, to
107
access APIs, download data, or communicate with other services. However,
118
malicious or misconfigured servers can also exfiltrate sensitive data or

‎docs/toolhive/guides-cli/run-mcp-servers.mdx‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,6 @@ title: Run MCP servers
33
description: How to run MCP servers with the ToolHive CLI.
44
---
55

6-
import Tabs from '@theme/Tabs';
7-
import TabItem from '@theme/TabItem';
8-
96
This guide explains how to run Model Context Protocol (MCP) servers using
107
ToolHive. It covers how to run servers from the ToolHive registry, customize
118
server settings, and run custom servers using Docker images or protocol schemes.

‎docs/toolhive/guides-cli/secrets-management.mdx‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@ description:
44
How to securely manage API tokens and other sensitive data in ToolHive.
55
---
66

7-
import Tabs from '@theme/Tabs';
8-
import TabItem from '@theme/TabItem';
9-
107
MCP servers often need secrets like API tokens, connection strings, and other
118
sensitive parameters. ToolHive provides built-in secrets management features,
129
letting you manage these values securely without exposing them in plaintext

‎docs/toolhive/guides-mcp/_template.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: SERVER_NAME MCP server guide
3+
sidebar_label: SERVER_NAME
4+
description: Using the SERVER_NAME MCP server with ToolHive for PURPOSE.
5+
last_update:
6+
author: YOUR_GITHUB_USERNAME
7+
date: YYYY-MM-DD
8+
---
9+
10+
## Overview
11+
12+
A brief overview of the MCP server, its purpose, and key features. Link to the
13+
official documentation.
14+
15+
## Metadata
16+
17+
<MCPMetadata name='SERVER_NAME' />
18+
19+
## Usage
20+
21+
<Tabs groupId='mode' queryString='mode'>
22+
<TabItem value='ui' label='UI' default>
23+
24+
UI instructions go here. Only include a screenshot if it adds value, such as
25+
showing a unique configuration option or feature.
26+
27+
</TabItem>
28+
<TabItem value='cli' label='CLI'>
29+
30+
CLI instructions go here, with multiple usage examples specific to the MCP
31+
server.
32+
33+
```bash
34+
thv run ...
35+
```
36+
37+
If appropriate, include guidance for using network isolation and/or a custom
38+
permission profile.
39+
40+
</TabItem>
41+
<TabItem value='k8s' label='Kubernetes'>
42+
43+
Kubernetes manifest and instructions go here
44+
45+
```yaml title="SERVER_NAME.yaml"
46+
apiVersion: toolhive.stacklok.dev/v1alpha1
47+
kind: MCPServer
48+
```
49+
50+
</TabItem>
51+
</Tabs>
52+
53+
## Sample prompts
54+
55+
Provide sample prompts that users can use to interact with the MCP server.
56+
57+
## Recommended practices
58+
59+
- Include some recommended practices for using the MCP server safely and
60+
effectively

0 commit comments

Comments
 (0)