使用说明

什么是MCP？

模型上下文协议（MCP）是一个专门的框架，旨在简化使AI代理能够与各种工具交互的过程。此入门模板可帮助您使用TypeScript快速构建模型上下文协议（MCP）服务器。它提供了一个强大的基础，您可以轻松扩展以创建高级MCP工具，并将其与各种AI平台无缝集成。

核心组件

MCP服务器：这些服务器充当桥梁，将API、数据库和代码库暴露给外部AI主机。通过在TypeScript中实现MCP服务器，开发人员可以使用JSON-RPC 2.0以标准化的方式共享数据源或计算逻辑。
MCP客户端：这些是MCP面向消费者的一方，与服务器通信以查询数据或执行操作。MCP客户端使用TypeScript SDK，确保类型安全的交互和统一的工具使用方法。
MCP主机Claude、Cursor、Windsurf、Cline和其他基于TypeScript的平台等系统协调服务器和客户端之间的请求，确保无缝的数据流。因此，单个MCP服务器可以由多个AI主机访问，而无需自定义集成。

TypeScript实现

MCP TypeScript SDK为构建服务器提供了核心类：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "mcp-server-starter",
  version: "1.0.0",
  capabilities: {
    tools: {},      // Enable tools capability
    resources: {},  // Enable resource access
    prompts: {},    // Enable prompt handling
    streaming: true // Enable streaming responses
  }
});

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

通过使用MCP，开发人员不再需要复杂的自定义代码来集成新的工具或服务。相反，他们构建了一个MCP服务器，并将其提供给受支持的主机。

先决条件

Node.js（v18或更高版本）：Node.js的现代版本，利用了最新的JavaScript功能和性能改进。
npm（v7或更高版本）：确保安装和管理软件包的兼容性。
带有开发容器扩展的VS代码：允许您快速启动可复制的开发环境，使协作更容易、更高效。

项目结构

MCP服务器模板的典型文件布局可能如下：

mcp-server/
├── .devcontainer/        # Dev container configuration
│   └── devcontainer.json
├── src/
│   ├── index.ts         # MCP Server main entry point
│   └── examples/        # Example tool implementations
│       ├── calculator.ts # Calculator tool example
│       └── rest-api.ts  # REST API tool example
├── package.json         # Project configuration
└── tsconfig.json        # TypeScript configuration

这 .devcontainer 目录简化了基于容器的开发，而 src/ 文件夹中包含主服务器逻辑和自定义工具的示例。这种结构使您的项目组织有序，易于导航。

快速开始

通过Smithery安装

要为任何受支持的客户端安装MCP Server Starter，请执行以下操作：

# For Claude
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client claude

# For Cursor
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cursor

# For Windsurf
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client windsurf

# For Cline
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client cline

# For TypeScript
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client typescript

克隆此模板：从首选源检索存储库文件。
使用开发容器在VS代码中打开：如果安装了Dev Containers扩展，系统将提示您在容器中打开此项目。
安装依赖项:
```
npm install
```
此命令获取并安装MCP服务器所需的所有软件包。
构建项目:
```
npm run build
```
这将把你的TypeScript代码编译成JavaScript，为运行时做准备。

开发脚本

构建项目:
```
npm run build
```
编译TypeScript源代码并设置主入口点的文件权限。
观看模式:
```
npm run watch
```
每当进行更改时，都会自动重新编译TypeScript文件，非常适合主动开发。
与检查员一起运行:
```
npm run inspector
```
与调试工具一起启动服务器，使您能够跟踪问题、设置断点和实时检查变量。

工具响应格式

MCP工具必须以特定格式返回响应，以确保与AI主机的正确通信。结构如下：

interface ToolResponse {
  content: ContentItem[];
  isError?: boolean;
  metadata?: Record<string, unknown>;
}

interface ContentItem {
  type: string;
  text?: string;
  mimeType?: string;
  data?: unknown;
}

支持的内容类型包括：

text：纯文本内容
code：具有可选语言规范的代码段
image：MIME类型为Base64编码的图像
file：MIME类型的文件内容
error：错误消息（当 isError 是真的）

示例响应：

return {
  content: [
    {
      type: "text",
      text: "Operation completed successfully"
    },
    {
      type: "code",
      text: "console.log('Hello, World!')",
      mimeType: "application/javascript"
    }
  ]
};

安全最佳实践

在开发MCP工具时，请遵循以下安全指南：

输入验证:
- 始终使用Zod模式验证输入参数
- 实施严格的类型检查
- 在处理之前对用户输入进行消毒
- 使用 strict() 模式中用于防止额外属性的选项
错误处理:
- 切勿向客户端公开内部错误详细信息
- 实施适当的错误边界
- 安全地记录错误
- 返回用户友好的错误消息
资源管理:
- 实施适当的清理程序
- 处理进程终止信号
- 紧密联系和免费资源
- 为长时间运行的操作实现超时
API安全:
- 使用安全传输协议
- 实施速率限制
- 安全地存储敏感数据
- 使用环境变量进行配置

安全工具实施示例：

const SecureSchema = z.object({
  input: z.string()
    .min(1)
    .max(1000)
    .transform(str => str.trim())
    .pipe(z.string().regex(/^[a-zA-Z0-9\s]+$/))
});

server.tool(
  "secure_tool",
  SecureSchema.shape,
  async (params) => {
    try {
      // Implement rate limiting
      await rateLimiter.checkLimit();

      // Process validated input
      const result = await processSecurely(params.input);

      return {
        content: [{
          type: "text",
          text: result
        }]
      };
    } catch (error) {
      // Log error internally
      logger.error(error);

      // Return safe error message
      return {
        content: [{
          type: "text",
          text: "An error occurred processing your request"
        }],
        isError: true
      };
    }
  }
);

高级功能

流媒体响应

MCP支持对长时间运行的操作进行流式响应：

server.tool(
  "stream_data",
  StreamSchema.shape,
  async function* (params) {
    for (const chunk of dataStream) {
      yield {
        content: [{
          type: "text",
          text: chunk
        }]
      };
    }
  }
);

自定义内容类型

您可以为专门的数据定义自定义内容类型：

interface CustomContent extends ContentItem {
  type: "custom";
  data: {
    format: string;
    value: unknown;
  };
}

异步工具执行

实现正确的异步处理：

server.tool(
  "async_operation",
  AsyncSchema.shape,
  async (params) => {
    const operation = await startAsyncOperation();

    while (!operation.isComplete()) {
      await operation.wait();
    }

    return {
      content: [{
        type: "text",
        text: await operation.getResult()
      }]
    };
  }
);

测试与调试

单元测试

使用Jest测试您的工具：

describe('Calculator Tool', () => {
  let server: McpServer;

  beforeEach(() => {
    server = new McpServer({
      name: "test-server",
      version: "1.0.0"
    });
    registerCalculatorTool(server);
  });

  test('adds numbers correctly', async () => {
    const result = await server.executeTool('calculate', {
      a: 5,
      b: 3,
      operation: 'add'
    });

    expect(result.content[0].text).toBe('8');
  });
});

调试工具

MCP检查员:
```
npm run inspector
```
提供以下内容的实时检查：
- 工具注册
- 请求/响应流程
- 错误处理
- 性能指标

日志记录:

function logMessage(level: 'info' | 'warn' | 'error', message: string) {
  console.error(`[${level.toUpperCase()}] ${message}`);
}

错误跟踪:

process.on('uncaughtException', (error: Error) => {
  logMessage('error', `Uncaught error: ${error.message}`);
  // Implement error reporting
});

传输配置

MCP支持多种传输协议：

stdio运输

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

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

WebSocket传输

import { WebSocketServerTransport } from "@modelcontextprotocol/sdk/server/websocket.js";

const transport = new WebSocketServerTransport({
  port: 3000
});
await server.connect(transport);

海关运输

import { Transport } from "@modelcontextprotocol/sdk/server/transport.js";

class CustomTransport implements Transport {
  // Implement transport methods
}

服务器功能

配置服务器功能：

const server = new McpServer({
  name: "mcp-server",
  version: "1.0.0",
  capabilities: {
    tools: {}, // Enable tools capability
    streaming: true, // Enable streaming support
    customContent: ["myFormat"], // Define custom content types
    metadata: true // Enable metadata support
  }
});

与MCP主机集成

多客户端支持

此MCP服务器模板支持多种现成的AI平台：

克劳德桌面:
- 提供基于聊天的环境
- 支持所有MCP功能
- 非常适合对话式AI交互
光标:
- 人工智能驱动的开发环境
- 完整的工具集成支持
- 非常适合编码辅助
帆板运动:
- 现代人工智能开发平台
- 完整的MCP协议支持
- 简化的工作流程集成
克莱恩:
- 命令行AI界面
- 以工具为中心的互动
- 基于终端的高效使用
TypeScript:
- 原生TypeScript支持
- 类型安全工具开发
- 无缝SDK集成

每个客户端都可以使用适当的Smithery CLI命令进行配置：

npx -y @smithery/cli run @TheSethRose/mcp-server-starter --client [client-name]

替换 [client-name] 其中之一： claude, cursor, windsurf, cline，或 typescript.

Smithery集成

运行此MCP服务器的一种便捷方式是通过Smithery，这是一个用于发现和发布MCP服务器的集中式平台。Smithery简化了部署，并确保您的服务器可以集成到各种AI工作流程中。

快速运行

您可以通过Smithery CLI立即执行此服务器：

npx -y @smithery/cli@latest run mcp-server-template --config "{}"

Smithery会自动从最新版本获取、安装和运行服务器，只需要您进行最少的设置。

发布自己的版本

如果您开发了新工具或进行了本地修改并希望共享它们，请考虑发布您的自定义服务器：

在上创建帐户史密瑟里.
按照他们的部署说明捆绑并发布您的MCP服务器。
然后，其他用户可以通过Smithery引用您的唯一包名来运行您的服务器。

Smithery提供：

一个用于发现和共享MCP服务器的集中式注册表。
简化了部署，消除了重复的设置。
一种社区驱动的方法，开发人员贡献各种工具。
易于与流行的AI主机集成。

如需更多指导：

光标集成

Cursor是另一个支持MCP的AI开发环境。要将服务器合并到Cursor中，请执行以下操作：

构建您的服务器:
```
npm run build
```
确保可执行文件 index.js 生成于 build 目录。
在光标中，转到 Settings > Features > MCP: 添加新的MCP服务器。
注册您的服务器:
- 选择 stdio 作为运输类型。
- 提供描述性 Name.
- 设置命令，例如： node /path/to/your/mcp-server/build/index.js.
保存您的配置。

然后，Cursor会检测并列出您的工具。在人工智能辅助编码会话或基于提示的交互过程中，它将在相关时调用您的MCP工具。您还可以指示AI按名称使用特定工具。

Claude桌面集成

Claude Desktop提供了一个基于聊天的环境，您可以在其中利用MCP工具。要包含您的服务器，请执行以下操作：

构建您的服务器:
```
npm run build
```
确认没有发生错误，并且主脚本是在中生成的 build.

修改 claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-server/build/index.js"
      ]
    }
  }
}

提供编译后的主文件的路径以及任何其他参数。

重新启动克劳德桌面 加载新配置。

当您与Claude Desktop交互时，它现在可以调用您注册的MCP工具。如果用户的请求与您的工具的任何功能一致，Claude将提示使用该工具。

开发最佳实践

使用TypeScript 为了更好的类型检查、更清晰的代码组织和更容易的维护。
采用一致的模式 用于实施工具：
- 将每个工具保存在自己的文件中
- 使用带有适当文档的描述性模式
- 实施全面的错误处理
- 返回格式正确的内容
包括详尽的文件:
- 添加JSDoc注释以解释功能
- 文档参数和返回类型
- 包括有用的示例
利用检查员 用于调试：
```
npm run inspector
```
这有助于您：
- 测试工具功能
- 调试请求/响应流
- 验证架构验证
- 检查错误处理
全面测试 部署前：
- 验证输入验证
- 测试错误场景
- 检查响应格式
- 确保与主机正确集成
遵循MCP最佳实践:
- 使用适当的内容类型
- 实施适当的错误处理
- 验证所有输入和输出
- 安全地处理网络请求
- 一致地格式化响应

了解更多

有关MCP生态系统的更多信息，请参阅：

模型上下文协议文档：详细介绍MCP架构、设计原则和更高级的使用示例。
Smithery-MCP服务器注册表：向Smithery发布工具的指南及其注册表的最佳实践。
MCP TypeScript SDK文档：TypeScript SDK的全面文档。
MCP安全指南：详细的安全最佳做法和建议。

结论

通过遵循此模板和最佳实践，您可以快速构建一个强大的MCP服务器，将您的工具向各种AI主机开放。这种扩展的方法确保了在利用现代人工智能系统的功能时更容易维护、更好的类型安全性和流畅的用户体验。

鸣谢

Seth Rose创建的模板:

网站: https://www.sethrose.dev
120143143;: https://x.com/TheSethRose
🦋 （蓝天）: https://bsky.app/profile/sethrose.dev

最佳实践

类型安全:
- 利用TypeScript的类型系统实现健壮的工具定义
- 使用Zod模式进行运行时验证
- 为工具参数和响应定义清晰的界面
运输选择:
- 使用 StdioServerTransport 用于本地进程通信
- 实施 WebSocketServerTransport 基于网络的工具
- 考虑针对特定用例的自定义传输
能力管理:
- 在初始化过程中明确定义服务器功能
- 实施适当的能力谈判
- 优雅地处理特定功能的错误
安全考虑:
- 对敏感操作实施用户同意流程
- 使用TypeScript类型和Zod模式验证所有输入
- 安全地处理错误，而不会暴露内部细节