STARWARCLOUD STARWAR.AI
返回市场
MCP服务器启动器

MCP服务器启动器

作者：TheSethRose29 星标更新：2025-02-12
安装使用来源：spider==github.com

项目介绍

什么是MCP？

smithery徽章

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

核心组件

  • MCP服务器：这些服务器充当桥梁，向外部AI主机暴露API、数据库和代码库。通过在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: {},      // 启用工具功能
    resources: {},  // 启用资源访问
    prompts: {},    // 启用提示处理
    streaming: true // 启用流式响应
  }
});

// 连接传输
const transport = new StdioServerTransport();
await server.connect(transport);

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

前提条件

  • Node.js（v18或更高版本）：利用最新JavaScript特性和性能改进的现代Node.js版本。
  • npm（v7或更高版本）：确保兼容性，用于安装和管理包。
  • 带有Dev Containers扩展的VS Code：允许您快速启动可复制的开发环境，使协作更简单高效。

项目结构

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

mcp-server/
├── .devcontainer/        # 开发容器配置
│   └── devcontainer.json
├── src/
│   ├── index.ts         # MCP服务器主入口点
│   └── examples/        # 示例工具实现
│       ├── calculator.ts # 计算器工具示例
│       └── rest-api.ts  # REST API工具示例
├── package.json         # 项目配置
└── tsconfig.json        # TypeScript配置

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

快速开始

通过Smithery安装

要为任何支持的客户端安装MCP服务器启动器：

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

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

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

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

# 对于TypeScript
npx -y @smithery/cli install @TheSethRose/mcp-server-starter --client typescript
  1. 克隆此模板：从您首选的来源获取存储库文件。
  2. 在VS Code中使用Dev Containers打开：如果您已安装Dev Containers扩展，将提示您在容器内打开此项目。
  3. 安装依赖项： 
    npm install
    此命令获取并安装MCP服务器所需的所有包。
  4. 构建项目： 
    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为true时）

示例响应：

return {
  content: [
    {
      type: "text",
      text: "操作成功完成"
    },
    {
      type: "code",
      text: "console.log('Hello, World!')",
      mimeType: "application/javascript"
    }
  ]
};

安全最佳实践

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

  1. 输入验证：

    • 使用Zod模式始终验证输入参数
    • 实现严格的类型检查
    • 在处理之前清理用户输入
    • 在模式中使用strict()选项以防止额外属性

  2. 错误处理：

    • 永不向客户端暴露内部错误详情
    • 实现适当的错误边界
    • 安全地记录错误
    • 返回用户友好的错误消息

  3. 资源管理：

    • 实现适当的清理程序
    • 处理进程终止信号
    • 关闭连接并释放资源
    • 长时间运行的操作实施超时

  4. 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 {
      // 实现速率限制
      await rateLimiter.checkLimit();

      // 处理验证过的输入
      const result = await processSecurely(params.input);

      return {
        content: [{
          type: "text",
          text: result
        }]
      };
    } catch (error) {
      // 内部记录错误
      logger.error(error);

      // 返回安全的错误消息
      return {
        content: [{
          type: "text",
          text: "处理您的请求时出现错误"
        }],
        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('计算器工具', () => {
  let server: McpServer;

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

  test('正确地加法运算', async () => {
    const result = await server.executeTool('calculate', {
      a: 5,
      b: 3,
      operation: 'add'
    });

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

调试工具

  1. MCP Inspector：

    npm run inspector

    提供实时检查：

    • 工具注册
    • 请求/响应流程
    • 错误处理
    • 性能指标

  2. 日志记录：

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

  3. 错误跟踪：

    process.on('uncaughtException', (error: Error) => {
  logMessage('error', `未捕获的错误：${error.message}`);
  // 实现错误报告
});

传输配置

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 {
  // 实现传输方法
}

服务器能力

配置服务器能力：

const server = new McpServer({
  name: "mcp-server",
  version: "1.0.0",
  capabilities: {
    tools: {}, // 启用工具功能
    streaming: true, // 启用流式支持
    customContent: ["myFormat"], // 定义自定义内容类型
    metadata: true // 启用元数据支持
  }
});

与MCP主机集成

多客户端支持

此MCP服务器模板开箱即用地支持多个AI平台：

  1. Claude桌面版：

    • 提供基于聊天的环境
    • 支持所有MCP功能
    • 适用于对话式AI交互

  2. Cursor：

    • AI驱动的开发环境
    • 全面的工具集成支持
    • 适合编码辅助

  3. Windsurf：

    • 现代AI开发平台
    • 完整的MCP协议支持
    • 简化的流程集成

  4. Cline：

    • 命令行AI界面
    • 专注于工具交互
    • 高效的终端使用

  5. 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会自动获取、安装并运行服务器的最新版本，只需最少的设置即可。

发布您自己的版本

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

  1. 在Smithery上创建一个账户。
  2. 按照他们的部署说明打包并发布您的MCP服务器。
  3. 其他用户可以通过引用您的唯一包名在Smithery中运行您的服务器。

Smithery提供：

  • 中央注册表，用于发现和分享MCP服务器。
  • 简化部署，消除重复设置。
  • 社区驱动的方法，开发人员贡献多样化的工具。
  • 与流行AI主机的轻松集成。

更多指导：

Cursor集成

Cursor是另一个支持MCP的AI开发环境。要将您的服务器整合到Cursor中：

  1. 构建您的服务器：

    npm run build

    确保生成可执行的index.js文件在build目录中。

  2. 在Cursor中，转到 设置 > 功能 > MCP： 添加一个新的MCP服务器。

  3. 注册您的服务器：

    • 选择stdio作为传输类型。
    • 提供描述性的名称。
    • 设置命令，例如：node /path/to/your/mcp-server/build/index.js。

  4. 保存您的配置。

Cursor随后会检测并列出您的工具。在AI辅助编码会话或基于提示的交互期间，每当相关时，它都会调用您的MCP工具。您也可以指示AI按名称使用特定工具。

Claude桌面版集成

Claude桌面版提供了一个基于聊天的环境，您可以在其中利用MCP工具。要包含您的服务器：

  1. 构建您的服务器：

    npm run build

    确认没有错误并且主脚本生成在build中。

  2. 修改 claude_desktop_config.json：

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

    提供指向您的编译主文件的路径以及任何附加参数。

  3. 重启Claude桌面版以加载新配置。

当您与Claude桌面版互动时，现在它可以调用您注册的MCP工具。如果用户的请求与您的任何工具的功能相符，Claude将提示使用该工具。

开发最佳实践

  1. 使用TypeScript以获得更好的类型检查、更清晰的代码组织和长期更容易维护。
  2. 采用一致的模式来实现工具：
    • 将每个工具放在自己的文件中
    • 使用带有适当文档的描述性模式
    • 实现全面的错误处理
    • 返回正确格式的内容
  3. 包含详尽的文档：
    • 添加JSDoc注释以解释功能
    • 文档化参数和返回类型
    • 在有帮助的地方添加示例
  4. 利用inspector进行调试： 
    npm run inspector
    这有助于您：
    • 测试工具功能
    • 调试请求/响应流程
    • 验证模式验证
    • 检查错误处理
  5. 部署前进行全面测试：
    • 验证输入验证
    • 测试错误场景
    • 检查响应格式
    • 确保与主机的正确集成
  6. 遵循MCP最佳实践：
    • 使用正确的内容类型
    • 实现适当的错误处理
    • 验证所有输入和输出
    • 安全处理网络请求
    • 一致地格式化响应

更多信息

有关MCP生态系统进一步的信息，请参阅：

结论

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

致谢

模板由Seth Rose创建：

最佳实践

  1. 类型安全性：
    • 利用TypeScript的类型系统进行强大的工具定义