wayne930242/merlin-my-pai

Overview

This skill documents how to develop and register MCP server tools for the mcp-tools collection. It emphasizes a clear service-to-tool pattern, error handling with ts-results, and Zod-based input schemas. It provides concrete conventions for naming, error formatting, and registration entry points.

How this skill works

Services return Result<T, Error> using ts-results. MCP tool handlers convert those Results into MCP content objects { content, isError } and use try/catch for legacy services. Tools are registered on the McpServer with a name, metadata (title, description, inputSchema), and an async handler that returns content blocks.

When to use it

• When creating a new MCP tool for the server
• When wrapping an existing service so it can be invoked by MCP
• When standardizing error handling and response shape across tools
• When adding or updating Zod input schemas for tool parameters
• When registering tool sets in the MCP server entry point

Best practices

• Return Result<T, Error> from service layer using ts-results (Ok / Err)
• Tool handler must check result.err and return isError: true for failures
• Define tool parameters with Zod and include .describe() text for each field
• Prefix error messages with the category name, e.g. "Google Calendar error: ..."
• Name tools as category_action and registration functions as registerXxxTools
• Register all tool modules from the MCP server creation entry point

Example use cases

• Add a new calendar listing tool: service returns Result<Events, Error>, tool registers as google_calendar_list
• Wrap a legacy API with try/catch and return MCP content on success or isError on failure
• Add search capability: memory_search tool that validates query via Zod then calls search service
• Create a utility tool set and import registerMyTools in the server index to enable them at startup
• Standardize error messages so UI can display category-prefixed failure reasons