mcp-tools

MCP Tool Patterns

Tool Registration (Preferred: registerTool)

Use server.registerTool() (SDK v1.26.0+) with title, description, inputSchema, outputSchema, and annotations:

import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { configError, formatId, isCompact, toolError, toolResponse } from '../utils/compact.js';
import { logger } from '../utils/logger.js';

server.registerTool(
  'tool_name',
  {
    title: 'Tool Name',
    description: 'What this tool does',
    inputSchema: {
      query: z.string().min(1).max(10000).describe('Search query'),
      limit: z.number().min(1).max(50).default(10).describe('Max results'),
    },
    // For read-only tools: define outputSchema + return structuredContent
    outputSchema: {
      totalResults: z.number(),
      results: z.array(z.object({ id: z.string(), content: z.string() })),
    },
    annotations: {
      readOnlyHint: true,     // Does not modify data
      destructiveHint: false,  // Does not delete data
      idempotentHint: true,    // Safe to call multiple times
      openWorldHint: false,    // Does not make external API calls
    },
  },
  async ({ query, limit }) => {
    logger.info('tool_name called', { query, limit });

    if (!isSupabaseConfigured()) {
      return configError('Database', 'Set SUPABASE_URL and SUPABASE_SERVICE_KEY');
    }

    try {
      const results = await doQuery(query, limit);
      const structuredContent = { totalResults: results.length, results };

      return toolResponse({
        compact: { n: results.length, r: results.map(r => ({ id: formatId(r.id), c: r.content })) },
        verbose: structuredContent,
        structuredContent,  // Always verbose, canonical keys
      });
    } catch (error) {
      // Structured form — preferred. Logging happens inside toolError().
      return toolError('tool_name', error, { scope: 'query' });
    }
  }
);

logger.debug('Registered tool: tool_name');