safe-fetch-mcp-server: Skill for Claude Code

Writing MCP Server Tools (TypeScript)

Follow these when creating or editing any tool. They reflect the current MCP TypeScript SDK conventions — do not fall back to older patterns.

Use modern SDK APIs only

• Do use: server.registerTool(), server.registerResource(), server.registerPrompt().
• Do NOT use: server.tool(), or manual server.setRequestHandler(ListToolsRequestSchema, ...). The register* methods give type safety and automatic schema handling.

Initialize once:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
const server = new McpServer({
    name: 'safe-fetch-mcp-server',
    version: '0.1.0',
});

Tool naming

• snake_case, action-oriented, service-prefixed to avoid collisions with other servers.
• This repo's tool is fetch_url (and optionally fetch_raw). No version numbers in names.

Input schemas: Zod, strict, described

• Every input schema is a Zod object with .strict() (reject unknown keys).
• Every field has constraints and a .describe().
• Derive the TypeScript type from the schema with z.infer.

import { z } from 'zod';

export const FetchUrlInput = z
    .object({
        url: z.string().url().describe('Absolute http(s) URL to fetch.'),
        format: z
            .enum(['markdown', 'raw'])
            .default('markdown')
            .describe("Output format. 'markdown' (default) or 'raw' text."),
        max_bytes: z
            .number()
            .int()
            .positive()
            .optional()
            .describe('Override the max response size for this call.'),
        start_index: z
            .number()
            .int()
            .min(0)
            .default(0)
            .describe('Byte offset for chunked reading of long pages.'),
    })
    .strict();

export type FetchUrlInput = z.infer<typeof FetchUrlInput>;

Register with title, description, inputSchema, annotations

• The description is what the agent reads — make it precise and matched to actual behavior. Include args, return shape, and 1–2 usage examples. JSDoc is NOT auto-extracted.
• Annotations for a read-only fetch tool: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true.