Create xmcp Tool

Step 1: Gather Information

1. Tool name (if not provided as argument): What should the tool be named? (Use kebab-case)
2. Handler type: Ask which handler type they need:
   • Standard - For data queries, calculations, API calls (returns string/JSON)
   • Template Literal (HTML) - For HTML widgets with external scripts
   • React Component - For interactive stateful widgets (.tsx file)
3. Schema fields: What parameters should the tool accept? Ask for:
   • Parameter name
   • Type (string, number, boolean, enum, array, object)
   • Description
   • Whether it's optional
   • Any validation rules
4. Annotations: Ask about behavior hints:
   • Is it read-only? (doesn't modify environment)
   • Is it destructive? (may delete or modify data)
   • Is it idempotent? (repeated calls have same effect)
   • Does it interact with external world? (openWorldHint)
5. Widget support (if Template Literal or React): Ask if they need:
   • OpenAI tool invocation messages (invoking/invoked status)
   • Widget accessibility (widgetAccessible)
   • Widget-to-tool communication

Step 2: Generate the Tool

src/tools/

• .ts

  for Standard and Template Literal handlers

• .tsx

  for React Component handlers

File Location

src/tools/{tool-name}.ts   # or .tsx for React

Tool Structure Reference

// 1. Schema (optional) - Define parameters with Zod
export const schema = { /* ... */ };

// 2. Metadata (optional) - Tool configuration
export const metadata: ToolMetadata = { /* ... */ };

// 3. Handler (required) - Default export function
export default function handler(params) { /* ... */ }

Quick Reference

Essential Imports

import { z } from "zod";
import { type InferSchema, type ToolMetadata } from "xmcp";

Handler Types Summary

.ts

.ts

.ts

.tsx

.ts

.ts

Annotations Quick Reference

readOnlyHint: true

destructiveHint: true

idempotentHint: true

openWorldHint: true

Detailed Templates

• Schema patterns (simple, validation, enum, optional, object)
• Metadata patterns (basic, annotations, OpenAI widgets, MCP Apps UI)
• All handler type templates (A through G)
• Return value patterns
• Type imports reference

references/templates.md

Checklist After Generation

1. File created in

   src/tools/{tool-name}.ts

   (or

   .tsx

   )
2. Schema uses

   .describe()

   for all parameters
3. If using metadata, ensure it has descriptive

   name

   and

   description

4. Appropriate annotations set based on tool behavior
5. Handler matches the chosen type
6. All imports are correct

pnpm build