AgentSkillsCN

develop-mcp-server-ts

采用标准化的工作流程，以 TypeScript 构建 MCP（模型上下文协议）服务器。适用于使用官方 TypeScript SDK（工具、资源、提示）构建或扩展 MCP 服务器，为工具添加注解（如标题、只读提示等），选择 Stdio 还是可流式传输的 HTTP 传输方式，或借助 MCP Inspector 或 Claude Desktop 进行测试。

SKILL.md
--- frontmatter
name: develop-mcp-server-ts
description: Standardized workflow for building MCP (Model Context Protocol) servers in TypeScript. Use when building or extending an MCP server with the official TypeScript SDK (tools, resources, prompts), adding tool annotations (title, readOnlyHint, etc.), choosing Stdio vs Streamable HTTP transport, or testing with MCP Inspector or Claude Desktop.

Develop MCP Server (TypeScript)

Purpose

Provide a repeatable, documented workflow for building MCP servers with the official TypeScript SDK so that agents and developers can add tools, resources, and prompts without ad-hoc discovery. Follow this workflow to go from requirements to a testable server (Stdio or Streamable HTTP). The skill follows MCP specification 2025-11-25 for tools, resources, prompts, and server utilities (logging, completion, pagination).

Workflow Checklist

  • • Step 1: Requirements discovery
    • • Read references/mcp-specification.md for primitives (Tools, Resources, Prompts) and transports.
    • • Decide which primitives the server will expose (e.g. tools only, or tools + resources).
    • • Choose transport: Stdio (local, process-based) or Streamable HTTP (remote, web-based).
  • • Step 2: Project initialization
  • • Step 3: Implementation patterns
    • • Use references/typescript-sdk-cheatsheet.md for McpServer, transport, registerTool (with Zod inputSchema), and registerResource.
    • • Consider tool annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can present tools and users can approve them; see cheatsheet “Tool annotations” and MCP Tool annotations.
    • • For tools that delete or permanently change data, set destructiveHint: true; clients should prompt for confirmation before executing, and agent instructions should require asking the user before invoking destructive tools.
    • • For Stdio: Use only console.error (or stderr) for logging; never console.log (stdout corrupts JSON-RPC).
    • • Optionally copy from assets/templates/server-stdio.ts or assets/templates/server-http.ts.
  • • Step 4: Testing
    • • Test with MCP Inspector: e.g. npx @modelcontextprotocol/inspector and run your server (e.g. node build/index.js).
    • • Or test with Claude Desktop: Add the server to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) with command and args, then restart Claude Desktop.

Detailed Instructions

1. Requirements discovery

Read the MCP specification summary for:

  • •Primitives: Tools (callable by the LLM), Resources (read-only context), Prompts (reusable templates).
  • •Transports: Stdio (local, one client per process) vs Streamable HTTP (remote, many clients).
  • •Lifecycle: Initialize, negotiate capabilities, then list/call tools or read resources.

Decide which primitives your server needs and whether it will run locally (Stdio) or be hosted (Streamable HTTP).

2. Project initialization

  • •Create a package (e.g. pnpm init or npm init -y).
  • •Install: pnpm add @modelcontextprotocol/sdk zod (or npm install @modelcontextprotocol/sdk zod). The SDK requires Zod for tool inputSchema.
  • •Set "type": "module" in package.json if using ESM.
  • •Use a tsconfig with "module": "Node16", "moduleResolution": "Node16", "target": "ES2022", and "outDir": "./build" (or similar).

3. Implementation patterns

Use the TypeScript SDK cheatsheet for:

  • •Creating an McpServer and connecting a transport (StdioServerTransport or StreamableHTTPServerTransport).
  • •Registering tools with server.registerTool(name, { description, inputSchema }, handler). Use Zod for inputSchema (e.g. { id: z.string() }). Return { content: [{ type: "text", text: "..." }] }. Add tool annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) when they help clients present or approve tools. For destructive operations (e.g. delete), set destructiveHint: true; clients should prompt for user confirmation and agent instructions should require asking the user before calling such tools.
  • •Registering resources if needed (URI templates and read handler).
  • •Logging: For Stdio transport, never write to stdout; use console.error or a logger that writes to stderr.

4. Testing

  • •MCP Inspector: Run npx @modelcontextprotocol/inspector, then start your server (e.g. with the command you would use in Claude Desktop). Use the Inspector UI to list tools and call them.
  • •Claude Desktop: Edit the config file (see Connect to local MCP servers). Add an entry under mcpServers with command and args (e.g. node and ["/path/to/build/index.js"]). Restart Claude Desktop fully (quit the app, then reopen). Verify the server appears under Connectors.

Success Criteria

  • •The server lists and executes tools (and optionally resources/prompts) correctly.
  • •For Stdio: No use of console.log; logs go to stderr.
  • •Tool inputSchema uses Zod and matches the SDK expectations.
  • •Tool names follow spec 2025-11-25 (1–128 chars, allowed characters); errors use tool execution result (isError: true) or protocol errors as appropriate.
  • •Tool annotations (title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are used where they help clients present or approve tools.
  • •Official links (TypeScript SDK, MCP spec 2025-11-25) are used for version and API details.

References