Webmcp Add Tool

1---
2name: webmcp-add-tool
3description: Scaffolds a new WebMCP tool component using useMcpTool with Zod schema, handler, annotations, and wires it into the WebMCPProvider tree. Use when the user wants to expose functionality as an MCP tool, make something callable by AI, add a new tool, or create an AI-accessible action.
4---
5 
6# Add a WebMCP Tool
7 
8## Overview
9 
10Each tool is a React component that calls `useMcpTool`. It registers on mount, unregisters on unmount. Tools can be headless (return `null`) or render UI showing execution state.
11 
12## Workflow
13 
141. **Determine** the tool's name, description, input schema, and what the handler does
152. **Choose** headless vs UI tool
163. **Scaffold** using the appropriate template below
174. **Set annotations** based on tool behavior
185. **Wire** the component into the `<WebMCPProvider>` tree
19 
20## Template: Headless tool
21 
22For tools that do work without rendering anything visible:
23 
24```tsx
25import { useMcpTool } from "webmcp-react";
26import { z } from "zod";
27 
28export function MyTool() {
29  useMcpTool({
30    name: "my_tool",
31    description: "One-line description of what this tool does",
32    input: z.object({
33      // Define each input field with .describe() for AI context
34      query: z.string().describe("The search query"),
35    }),
36    handler: async ({ query }) => {
37      // Implement tool logic here
38      const result = await doSomething(query);
39      return {
40        content: [{ type: "text", text: JSON.stringify(result) }],
41      };
42    },
43  });
44  return null;
45}
46```
47 
48## Template: Tool with execution state UI
49 
50For tools that show loading, results, or errors:
51 
52```tsx
53import { useMcpTool } from "webmcp-react";
54import { z } from "zod";
55 
56export function MyTool() {
57  const { state, execute, reset } = useMcpTool({
58    name: "my_tool",
59    description: "One-line description of what this tool does",
60    input: z.object({
61      text: z.string().describe("Input text to process"),
62    }),
63    handler: async ({ text }) => {
64      const result = await process(text);
65      return { content: [{ type: "text", text: result }] };
66    },
67    onSuccess: (result) => {
68      // Optional: analytics, toast, etc.
69    },
70    onError: (error) => {
71      // Optional: error reporting
72    },
73  });
74 
75  return (
76    <div>
77      <button onClick={() => execute({ text: "hello" })} disabled={state.isExecuting}>
78        {state.isExecuting ? "Processing..." : "Run"}
79      </button>
80      {state.lastResult && <p>{state.lastResult.content[0].text}</p>}
81      {state.error && <p className="error">{state.error.message}</p>}
82      <span>Executions: {state.executionCount}</span>
83    </div>
84  );
85}
86```
87 
88## Annotations
89 
90Set annotations to hint AI agents about tool behavior. Only include annotations that apply:
91 
92```tsx
93useMcpTool({
94  // ...
95  annotations: {
96    title: "Human-friendly title",       // Display name for the tool
97    readOnlyHint: true,                  // Tool only reads data, no side effects
98    destructiveHint: true,               // Tool deletes or irreversibly modifies data
99    idempotentHint: true,                // Safe to call multiple times with same input
100    openWorldHint: true,                 // Tool interacts with external systems
101  },
102});
103```
104 
105**Guideline for choosing annotations:**
106 
107| Tool behavior | Annotations to set |
108|---|---|
109| Fetches/queries data | `readOnlyHint: true` |
110| Creates a record | `idempotentHint: false` (or omit, false is default) |
111| Deletes or overwrites data | `destructiveHint: true` |
112| Calls an external API | `openWorldHint: true` |
113| Can be retried safely | `idempotentHint: true` |
114 
115## Return format
116 
117Handlers must return `CallToolResult`:
118 
119```tsx
120// Text content (most common)
121return {
122  content: [{ type: "text", text: "result string" }],
123};
124 
125// Structured content (for machine-readable results alongside text)
126return {
127  content: [{ type: "text", text: "Human summary" }],
128  structuredContent: { key: "value", count: 42 },
129};
130 
131// Error result (caught by the framework, but you can also return errors explicitly)
132return {
133  content: [{ type: "text", text: "Something went wrong" }],
134  isError: true,
135};
136 
137// Image content
138return {
139  content: [{ type: "image", data: base64String, mimeType: "image/png" }],
140};
141```
142 
143## Dynamic tools
144 
145Tools register on mount and unregister on unmount. Use conditional rendering to dynamically control which tools are available:
146 
147```tsx
148function App({ user }) {
149  return (
150    <WebMCPProvider name="app" version="1.0">
151      <PublicTools />
152      {user.isAdmin && <AdminTools />}
153      {featureFlags.betaSearch && <BetaSearchTool />}
154    </WebMCPProvider>
155  );
156}
157```
158 
159## Wiring into the provider
160 
161Render the tool component anywhere inside `<WebMCPProvider>`. Common patterns:
162 
163**Dedicated tools file** (recommended for apps with many tools):
164 
165```tsx
166// components/mcp-tools.tsx
167export function McpTools() {
168  return (
169    <>
170      <SearchTool />
171      <TranslateTool />
172      <CheckoutTool />
173    </>
174  );
175}
176 
177// In app root:
178<WebMCPProvider name="app" version="1.0">
179  <McpTools />
180  <App />
181</WebMCPProvider>
182```
183 
184**Colocated with feature** (when the tool is tightly coupled to a specific component):
185 
186```tsx
187function ProductPage({ product }) {
188  return (
189    <div>
190      <ProductDetails product={product} />
191      <AddToCartTool productId={product.id} />
192    </div>
193  );
194}
195```
196 
197## Naming conventions
198 
199- Tool names: `snake_case` (e.g., `search_catalog`, `delete_user`, `get_order_status`)
200- Component names: PascalCase ending in `Tool` (e.g., `SearchCatalogTool`, `DeleteUserTool`)
201- Descriptions: start with a verb, be specific (e.g., "Search the product catalog by keyword" not "Search stuff")
202 
203## Checklist
204 
205Before finishing, verify:
206 
207- [ ] Tool name is unique across the app
208- [ ] Description clearly explains what the tool does (AI agents read this)
209- [ ] All input fields have `.describe()` for AI context
210- [ ] Handler returns `CallToolResult` with `content` array
211- [ ] Appropriate annotations are set
212- [ ] Component is rendered inside `<WebMCPProvider>`
213- [ ] For Next.js: file has `"use client"` directive
214