add-new-tool

Add a New MCP Tool

The change touches four files. Do them in this order:

1. The tool file.
2. src/server.ts.
3. The server YAML.
4. README.md.

Step 1: create or extend a tool file in src/tools/

// src/tools/example.ts
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { registerTool, type ToolInput, type McpResult } from '../utils/mcp-types.js';
import type { WhatsAppClient } from '../whatsapp/client.js';
import type { MessageStore } from '../whatsapp/store.js';
import type { PermissionManager } from '../security/permissions.js';
import type { AuditLogger } from '../security/audit.js';

const schema = {
  param: z.string().describe('What this parameter is for')
};

export function registerExampleTools (
  server: McpServer,
  waClient: WhatsAppClient,
  store: MessageStore,
  permissions: PermissionManager,
  audit: AuditLogger
): void {
  registerTool(server, 'my_tool', {
    description: 'Clear description of what this tool does and when to use it.',
    inputSchema: schema,
    annotations: {
      readOnlyHint: true,      // true if the tool only reads data
      destructiveHint: false,  // true if the tool deletes or modifies irreversibly
      idempotentHint: true,
      openWorldHint: false
    }
  }, async (args: ToolInput<typeof schema>): Promise<McpResult> => {
    const rateCheck = permissions.checkRateLimit();
    if (!rateCheck.allowed) {
      return { content: [{ type: 'text', text: rateCheck.error ?? 'Rate limited' }], isError: true };
    }

    const result = /* implementation */;

    audit.log('my_tool', 'action', { param: args.param });

    return { content: [{ type: 'text', text: `Result: ${result}` }] };
  });
}

Key patterns:

• Call permissions.checkRateLimit() for outbound actions.
• Log every action with audit.log(toolName, action, details).
• Use Zod schemas for all parameters.
• Log to stderr, never stdout. stdout carries the MCP stdio transport.