# Node/TypeScript MCP 服务端实现指南

## 概述

本文档提供了使用 MCP TypeScript SDK 实现 MCP 服务端时的 Node/TypeScript 特定最佳实践与示例。内容涵盖项目结构、服务端初始化、工具注册模式、基于 Zod 的输入验证、错误处理以及完整的可运行示例。

---

## 快速参考

### 关键导入
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import express from "express";
import { z } from "zod";
```

### 服务端初始化
```typescript
const server = new McpServer({
  name: "service-mcp-server",
  version: "1.0.0"
});
```

### 工具注册模式
```typescript
server.registerTool(
  "tool_name",
  {
    title: "Tool Display Name",
    description: "What the tool does",
    inputSchema: { param: z.string() },
    outputSchema: { result: z.string() }
  },
  async ({ param }) => {
    const output = { result: `Processed: ${param}` };
    return {
      content: [{ type: "text", text: JSON.stringify(output) }],
      structuredContent: output // 结构化数据的现代模式
    };
  }
);
```

---

## MCP TypeScript SDK

官方 MCP TypeScript SDK 提供：
- `McpServer` 类用于服务端初始化
- `registerTool` 方法用于工具注册
- Zod schema 集成实现运行时输入验证
- 类型安全的工具处理函数实现

**重要——仅使用现代 API：**
- **应该使用**：`server.registerTool()`、`server.registerResource()`、`server.registerPrompt()`
- **不要使用**：旧的已弃用 API，如 `server.tool()`、`server.setRequestHandler(ListToolsRequestSchema, ...)` 或手动注册处理函数
- `register*` 方法提供更好的类型安全性、自动 schema 处理，是推荐做法

详情请参阅参考资料中的 MCP SDK 文档。

## 服务端命名规范

Node/TypeScript MCP 服务端必须遵循以下命名模式：
- **格式**：`{service}-mcp-server`（小写，用连字符连接）
- **示例**：`github-mcp-server`、`jira-mcp-server`、`stripe-mcp-server`

名称应：
- 通用（不与特定功能绑定）
- 描述所集成的服务/API
- 易于从任务描述中推断
- 不包含版本号或日期

## 项目结构

为 Node/TypeScript MCP 服务端创建以下结构：

```
{service}-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts          # 主入口文件，包含 McpServer 初始化
│   ├── types.ts          # TypeScript 类型定义与接口
│   ├── tools/            # 工具实现（每个领域一个文件）
│   ├── services/         # API 客户端与共享工具函数
│   ├── schemas/          # Zod 验证 schema
│   └── constants.ts      # 共享常量（API_URL、CHARACTER_LIMIT 等）
└── dist/                 # 构建后的 JavaScript 文件（入口：dist/index.js）
```

## 工具实现

### 工具命名

工具名称使用蛇形命名法（snake_case），例如 "search_users"、"create_project"、"get_channel_info"，名称应清晰且面向操作。

**避免命名冲突**：包含服务上下文以防止重叠：
- 使用 "slack_send_message" 而非 "send_message"
- 使用 "github_create_issue" 而非 "create_issue"
- 使用 "asana_list_tasks" 而非 "list_tasks"

### 工具结构

工具通过 `registerTool` 方法注册，需满足以下要求：
- 使用 Zod schema 进行运行时输入验证和类型安全
- `description` 字段必须显式提供——JSDoc 注释不会被自动提取
- 显式提供 `title`、`description`、`inputSchema` 和 `annotations`
- `inputSchema` 必须是 Zod schema 对象（而非 JSON schema）
- 所有参数和返回值类型需显式声明

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "example-mcp",
  version: "1.0.0"
});

// 用于输入验证的 Zod schema
const UserSearchInputSchema = z.object({
  query: z.string()
    .min(2, "查询字符串至少需要 2 个字符")
    .max(200, "查询字符串不能超过 200 个字符")
    .describe("用于匹配姓名/邮箱的搜索字符串"),
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("返回的最大结果数"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("分页时跳过的结果数"),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("输出格式：'markdown' 用于人类可读，'json' 用于机器可读")
}).strict();

// 从 Zod schema 推导的类型定义
type UserSearchInput = z.infer<typeof UserSearchInputSchema>;

server.registerTool(
  "example_search_users",
  {
    title: "Search Example Users",
    description: `在 Example 系统中按姓名、邮箱或团队搜索用户。

该工具搜索 Example 平台中的所有用户资料，支持部分匹配和多种搜索筛选条件。不会创建或修改用户，仅搜索已有用户。

参数：
  - query (string)：用于匹配姓名/邮箱的搜索字符串
  - limit (number)：返回的最大结果数，范围 1-100（默认值：20）
  - offset (number)：分页时跳过的结果数（默认值：0）
  - response_format ('markdown' | 'json')：输出格式（默认值：'markdown'）

返回：
  JSON 格式：结构化数据，schema 如下：
  {
    "total": number,           // 找到的匹配总数
    "count": number,           // 本次响应中的结果数
    "offset": number,          // 当前分页偏移量
    "users": [
      {
        "id": string,          // 用户 ID（例如 "U123456789"）
        "name": string,        // 全名（例如 "张三"）
        "email": string,       // 邮箱地址
        "team": string,        // 团队名称（可选）
        "active": boolean      // 用户是否活跃
      }
    ],
    "has_more": boolean,       // 是否还有更多结果
    "next_offset": number      // 下一页的偏移量（若 has_more 为 true）
  }

示例：
  - 何时使用："查找所有营销团队成员" -> 参数为 query="team:marketing"
  - 何时使用："搜索张三的账号" -> 参数为 query="zhang"
  - 不要使用：需要创建用户时（应使用 example_create_user）

错误处理：
  - 请求过多时返回 "Error: Rate limit exceeded"（429 状态码）
  - 搜索结果为空时返回 "未找到与 '<query>' 匹配的用户"`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    try {
      // 输入验证由 Zod schema 处理
      // 使用验证后的参数发起 API 请求
      const data = await makeApiRequest<any>(
        "users/search",
        "GET",
        undefined,
        {
          q: params.query,
          limit: params.limit,
          offset: params.offset
        }
      );

      const users = data.users || [];
      const total = data.total || 0;

      if (!users.length) {
        return {
          content: [{
            type: "text",
            text: `未找到与 '${params.query}' 匹配的用户`
          }]
        };
      }

      // 准备结构化输出
      const output = {
        total,
        count: users.length,
        offset: params.offset,
        users: users.map((user: any) => ({
          id: user.id,
          name: user.name,
          email: user.email,
          ...(user.team ? { team: user.team } : {}),
          active: user.active ?? true
        })),
        has_more: total > params.offset + users.length,
        ...(total > params.offset + users.length ? {
          next_offset: params.offset + users.length
        } : {})
      };

      // 根据请求格式生成文本表示
      let textContent: string;
      if (params.response_format === ResponseFormat.MARKDOWN) {
        const lines = [`# 用户搜索结果：'${params.query}'`, "",
          `共找到 ${total} 个用户（显示 ${users.length} 个）`, ""];
        for (const user of users) {
          lines.push(`## ${user.name}（${user.id}）`);
          lines.push(`- **邮箱**：${user.email}`);
          if (user.team) lines.push(`- **团队**：${user.team}`);
          lines.push("");
        }
        textContent = lines.join("\n");
      } else {
        textContent = JSON.stringify(output, null, 2);
      }

      return {
        content: [{ type: "text", text: textContent }],
        structuredContent: output // 结构化数据的现代模式
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: handleApiError(error)
        }]
      };
    }
  }
);
```

## Zod Schema 用于输入验证

Zod 提供运行时类型验证：

```typescript
import { z } from "zod";

// 带验证的基本 schema
const CreateUserSchema = z.object({
  name: z.string()
    .min(1, "姓名为必填项")
    .max(100, "姓名不能超过 100 个字符"),
  email: z.string()
    .email("邮箱格式无效"),
  age: z.number()
    .int("年龄必须为整数")
    .min(0, "年龄不能为负数")
    .max(150, "年龄不能超过 150")
}).strict();  // 使用 .strict() 禁止额外字段

// 枚举
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

const SearchSchema = z.object({
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("输出格式")
});

// 带默认值的可选字段
const PaginationSchema = z.object({
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("返回的最大结果数"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("跳过的结果数")
});
```

## 响应格式选项

支持多种输出格式以提高灵活性：

```typescript
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

const inputSchema = z.object({
  query: z.string(),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("输出格式：'markdown' 用于人类可读，'json' 用于机器可读")
});
```

**Markdown 格式**：
- 使用标题、列表和格式化以提高可读性
- 将时间戳转换为人类可读格式
- 显示名称及括号中的 ID
- 省略冗长的元数据
- 按逻辑对相关信息分组

**JSON 格式**：
- 返回适合程序化处理的完整结构化数据
- 包含所有可用字段和元数据
- 使用一致的字段名和类型

## 分页实现

适用于列出资源的工具：

```typescript
const ListSchema = z.object({
  limit: z.number().int().min(1).max(100).default(20),
  offset: z.number().int().min(0).default(0)
});

async function listItems(params: z.infer<typeof ListSchema>) {
  const data = await apiRequest(params.limit, params.offset);

  const response = {
    total: data.total,
    count: data.items.length,
    offset: params.offset,
    items: data.items,
    has_more: data.total > params.offset + data.items.length,
    next_offset: data.total > params.offset + data.items.length
      ? params.offset + data.items.length
      : undefined
  };

  return JSON.stringify(response, null, 2);
}
```

## 字符限制与截断

添加 CHARACTER_LIMIT 常量以防止响应过长：

```typescript
// 在 constants.ts 模块级别
export const CHARACTER_LIMIT = 25000;  // 最大响应大小（字符数）

async function searchTool(params: SearchInput) {
  let result = generateResponse(data);

  // 检查字符限制，必要时截断
  if (result.length > CHARACTER_LIMIT) {
    const truncatedData = data.slice(0, Math.max(1, data.length / 2));
    response.data = truncatedData;
    response.truncated = true;
    response.truncation_message =
      `响应已从 ${data.length} 项截断至 ${truncatedData.length} 项。` +
      `请使用 'offset' 参数或添加筛选条件以查看更多结果。`;
    result = JSON.stringify(response, null, 2);
  }

  return result;
}
```

## 错误处理

提供清晰、可操作的错误信息：

```typescript
import axios, { AxiosError } from "axios";

function handleApiError(error: unknown): string {
  if (error instanceof AxiosError) {
    if (error.response) {
      switch (error.response.status) {
        case 404:
          return "错误：未找到资源。请检查 ID 是否正确。";
        case 403:
          return "错误：权限不足。您没有访问此资源的权限。";
        case 429:
          return "错误：请求频率超限。请稍后再发起更多请求。";
        default:
          return `错误：API 请求失败，状态码 ${error.response.status}`;
      }
    } else if (error.code === "ECONNABORTED") {
      return "错误：请求超时。请重试。";
    }
  }
  return `错误：发生意外错误：${error instanceof Error ? error.message : String(error)}`;
}
```

## 共享工具函数

将通用功能提取为可复用的函数：

```typescript
// 共享 API 请求函数
async function makeApiRequest<T>(
  endpoint: string,
  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
  data?: any,
  params?: any
): Promise<T> {
  try {
    const response = await axios({
      method,
      url: `${API_BASE_URL}/${endpoint}`,
      data,
      params,
      timeout: 30000,
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    });
    return response.data;
  } catch (error) {
    throw error;
  }
}
```

## Async/Await 最佳实践

网络请求和 I/O 操作始终使用 async/await：

```typescript
// 好的做法：异步网络请求
async function fetchData(resourceId: string): Promise<ResourceData> {
  const response = await axios.get(`${API_URL}/resource/${resourceId}`);
  return response.data;
}

// 不好的做法：Promise 链
function fetchData(resourceId: string): Promise<ResourceData> {
  return axios.get(`${API_URL}/resource/${resourceId}`)
    .then(response => response.data);  // 可读性和可维护性较差
}
```

## TypeScript 最佳实践

1. **使用严格 TypeScript**：在 tsconfig.json 中启用严格模式
2. **定义接口**：为所有数据结构创建清晰的接口定义
3. **避免使用 `any`**：使用正确类型或 `unknown` 替代 `any`
4. **使用 Zod 进行运行时验证**：使用 Zod schema 验证外部数据
5. **类型守卫**：为复杂类型检查创建类型守卫函数
6. **错误处理**：始终使用 try-catch 并配合正确的错误类型检查
7. **空值安全**：使用可选链（`?.`）和空值合并（`??`）

```typescript
// 好的做法：通过 Zod 和接口实现类型安全
interface UserResponse {
  id: string;
  name: string;
  email: string;
  team?: string;
  active: boolean;
}

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
  team: z.string().optional(),
  active: z.boolean()
});

type User = z.infer<typeof UserSchema>;

async function getUser(id: string): Promise<User> {
  const data = await apiCall(`/users/${id}`);
  return UserSchema.parse(data);  // 运行时验证
}

// 不好的做法：使用 any
async function getUser(id: string): Promise<any> {
  return await apiCall(`/users/${id}`);  // 没有类型安全
}
```

## 包配置

### package.json

```json
{
  "name": "{service}-mcp-server",
  "version": "1.0.0",
  "description": "用于 {Service} API 集成的 MCP 服务端",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "clean": "rm -rf dist"
  },
  "engines": {
    "node": ">=18"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.6.1",
    "axios": "^1.7.9",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2"
  }
}
```

### tsconfig.json

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

## 完整示例

```typescript
#!/usr/bin/env node
/**
 * Example 服务的 MCP 服务端。
 *
 * 本服务端提供与 Example API 交互的工具，包括用户搜索、
 * 项目管理和数据导出功能。
 */

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import axios, { AxiosError } from "axios";

// 常量
const API_BASE_URL = "https://api.example.com/v1";
const CHARACTER_LIMIT = 25000;

// 枚举
enum ResponseFormat {
  MARKDOWN = "markdown",
  JSON = "json"
}

// Zod schema
const UserSearchInputSchema = z.object({
  query: z.string()
    .min(2, "查询字符串至少需要 2 个字符")
    .max(200, "查询字符串不能超过 200 个字符")
    .describe("用于匹配姓名/邮箱的搜索字符串"),
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(20)
    .describe("返回的最大结果数"),
  offset: z.number()
    .int()
    .min(0)
    .default(0)
    .describe("分页时跳过的结果数"),
  response_format: z.nativeEnum(ResponseFormat)
    .default(ResponseFormat.MARKDOWN)
    .describe("输出格式：'markdown' 用于人类可读，'json' 用于机器可读")
}).strict();

type UserSearchInput = z.infer<typeof UserSearchInputSchema>;

// 共享工具函数
async function makeApiRequest<T>(
  endpoint: string,
  method: "GET" | "POST" | "PUT" | "DELETE" = "GET",
  data?: any,
  params?: any
): Promise<T> {
  try {
    const response = await axios({
      method,
      url: `${API_BASE_URL}/${endpoint}`,
      data,
      params,
      timeout: 30000,
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    });
    return response.data;
  } catch (error) {
    throw error;
  }
}

function handleApiError(error: unknown): string {
  if (error instanceof AxiosError) {
    if (error.response) {
      switch (error.response.status) {
        case 404:
          return "错误：未找到资源。请检查 ID 是否正确。";
        case 403:
          return "错误：权限不足。您没有访问此资源的权限。";
        case 429:
          return "错误：请求频率超限。请稍后再发起更多请求。";
        default:
          return `错误：API 请求失败，状态码 ${error.response.status}`;
      }
    } else if (error.code === "ECONNABORTED") {
      return "错误：请求超时。请重试。";
    }
  }
  return `错误：发生意外错误：${error instanceof Error ? error.message : String(error)}`;
}

// 创建 MCP 服务端实例
const server = new McpServer({
  name: "example-mcp",
  version: "1.0.0"
});

// 注册工具
server.registerTool(
  "example_search_users",
  {
    title: "Search Example Users",
    description: `[完整描述如上所示]`,
    inputSchema: UserSearchInputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  async (params: UserSearchInput) => {
    // 实现如上所示
  }
);

// 主函数
// 用于 stdio（本地）：
async function runStdio() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("错误：需要设置 EXAMPLE_API_KEY 环境变量");
    process.exit(1);
  }

  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP 服务端通过 stdio 运行");
}

// 用于流式 HTTP（远程）：
async function runHTTP() {
  if (!process.env.EXAMPLE_API_KEY) {
    console.error("错误：需要设置 EXAMPLE_API_KEY 环境变量");
    process.exit(1);
  }

  const app = express();
  app.use(express.json());

  app.post('/mcp', async (req, res) => {
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
      enableJsonResponse: true
    });
    res.on('close', () => transport.close());
    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  });

  const port = parseInt(process.env.PORT || '3000');
  app.listen(port, () => {
    console.error(`MCP 服务端运行在 http://localhost:${port}/mcp`);
  });
}

// 根据环境选择传输方式
const transport = process.env.TRANSPORT || 'stdio';
if (transport === 'http') {
  runHTTP().catch(error => {
    console.error("服务端错误：", error);
    process.exit(1);
  });
} else {
  runStdio().catch(error => {
    console.error("服务端错误：", error);
    process.exit(1);
  });
}
```

---

## 高级 MCP 功能

### 资源注册

将数据暴露为资源，实现基于 URI 的高效访问：

```typescript
import { ResourceTemplate } from "@modelcontextprotocol/sdk/types.js";

// 使用 URI 模板注册资源
server.registerResource(
  {
    uri: "file://documents/{name}",
    name: "Document Resource",
    description: "按名称访问文档",
    mimeType: "text/plain"
  },
  async (uri: string) => {
    // 从 URI 中提取参数
    const match = uri.match(/^file:\/\/documents\/(.+)$/);
    if (!match) {
      throw new Error("URI 格式无效");
    }

    const documentName = match[1];
    const content = await loadDocument(documentName);

    return {
      contents: [{
        uri,
        mimeType: "text/plain",
        text: content
      }]
    };
  }
);

// 动态列出可用资源
server.registerResourceList(async () => {
  const documents = await getAvailableDocuments();
  return {
    resources: documents.map(doc => ({
      uri: `file://documents/${doc.name}`,
      name: doc.name,
      mimeType: "text/plain",
      description: doc.description
    }))
  };
});
```

**何时使用资源 vs 工具：**
- **资源**：适用于基于简单 URI 参数的数据访问
- **工具**：适用于需要验证和业务逻辑的复杂操作
- **资源**：数据相对静态或基于模板时
- **工具**：操作有副作用或涉及复杂工作流时

### 传输选项

TypeScript SDK 支持两种主要传输机制：

#### 流式 HTTP（推荐用于远程服务端）

```typescript
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

const app = express();
app.use(express.json());

app.post('/mcp', async (req, res) => {
  // 为每个请求创建新的传输（无状态，防止请求 ID 冲突）
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
    enableJsonResponse: true
  });

  res.on('close', () => transport.close());

  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);
```

#### stdio（用于本地集成）

```typescript
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const transport = new StdioServerTransport();
await server.connect(transport);
```

**传输方式选择：**
- **流式 HTTP**：Web 服务、远程访问、多客户端
- **stdio**：命令行工具、本地开发、子进程集成

### 通知支持

在服务端状态变化时通知客户端：

```typescript
// 工具列表变更时通知
server.notification({
  method: "notifications/tools/list_changed"
});

// 资源变更时通知
server.notification({
  method: "notifications/resources/list_changed"
});
```

适度使用通知——仅当服务端能力确实发生变化时使用。

---

## 代码最佳实践

### 代码组合性与可复用性

你的实现必须优先考虑组合性和代码复用：

1. **提取通用功能**：
   - 为多个工具中使用的操作创建可复用的辅助函数
   - 构建共享的 API 客户端来处理 HTTP 请求，而非重复代码
   - 将错误处理逻辑集中到工具函数中
   - 将业务逻辑提取到可组合的专用函数中
   - 提取共享的 Markdown 或 JSON 字段选择与格式化功能

2. **避免重复**：
   - 切勿在不同工具之间复制粘贴相似代码
   - 如果发现自己两次编写相似逻辑，将其提取为函数
   - 分页、过滤、字段选择和格式化等常见操作应共享
   - 认证/授权逻辑应集中管理

## 构建与运行

始终先构建 TypeScript 代码再运行：

```bash
# 构建项目
npm run build

# 运行服务端
npm start

# 开发模式（自动重载）
npm run dev
```

始终确保 `npm run build` 成功完成后再认为实现完成。

## 质量检查清单

在最终确定 Node/TypeScript MCP 服务端实现之前，请确保：

### 战略设计
- [ ] 工具支持完整工作流，而不仅仅是 API 端点封装
- [ ] 工具名称反映自然的任务划分
- [ ] 响应格式针对智能体上下文效率进行优化
- [ ] 在适当的地方使用人类可读的标识符
- [ ] 错误信息引导智能体正确使用

### 实现质量
- [ ] 聚焦实现：实现最重要和最有价值的工具
- [ ] 所有工具使用 `registerTool` 注册，并带有完整配置
- [ ] 所有工具包含 `title`、`description`、`inputSchema` 和 `annotations`
- [ ] 注解正确设置（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）
- [ ] 所有工具使用 Zod schema 进行运行时输入验证，并启用 `.strict()` 约束
- [ ] 所有 Zod schema 具有适当的约束条件和描述性错误信息
- [ ] 所有工具具有全面的描述，包含显式的输入/输出类型
- [ ] 描述包含返回值示例和完整的 schema 文档
- [ ] 错误信息清晰、可操作且具有教育意义

### TypeScript 质量
- [ ] 为所有数据结构定义 TypeScript 接口
- [ ] 在 tsconfig.json 中启用严格 TypeScript 模式
- [ ] 不使用 `any` 类型——使用 `unknown` 或正确的类型替代
- [ ] 所有异步函数具有显式的 `Promise<T>` 返回类型
- [ ] 错误处理使用正确的类型守卫（例如 `axios.isAxiosError`、`z.ZodError`）

### 高级功能（如适用）
- [ ] 为适当的数据端点注册资源
- [ ] 配置了合适的传输方式（stdio 或流式 HTTP）
- [ ] 为动态服务端能力实现通知
- [ ] 通过 SDK 接口实现类型安全

### 项目配置
- [ ] Package.json 包含所有必要的依赖
- [ ] 构建脚本在 dist/ 目录中生成可运行的 JavaScript
- [ ] 主入口正确配置为 dist/index.js
- [ ] 服务端名称遵循格式：`{service}-mcp-server`
- [ ] tsconfig.json 正确配置，启用严格模式

### 代码质量
- [ ] 分页已正确实现（如适用）
- [ ] 大型响应检查 CHARACTER_LIMIT 常量并附带清晰信息截断
- [ ] 为可能较大的结果集提供过滤选项
- [ ] 所有网络操作优雅处理超时和连接错误
- [ ] 通用功能被提取为可复用的函数
- [ ] 相似操作的返回类型保持一致

### 测试与构建
- [ ] `npm run build` 成功完成且无错误
- [ ] dist/index.js 已创建且可执行
- [ ] 服务端可运行：`node dist/index.js --help`
- [ ] 所有导入正确解析
- [ ] 示例工具调用按预期工作