AI导哈

MCP服务器模板

一个功能完整的TypeScript MCP服务器模板，支持HTTP/SSE和stdio传输，用于与AI应用无缝集成。

  • by rully-saputra15
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 rully-saputra15/ts-mcp-starter-kit

使用说明

TypeScript MCP入门套件🚀

一个功能齐全的入门模板，用于使用TypeScript构建模型上下文协议（MCP）服务器，支持HTTP/SSE和stdio传输，与AI应用程序无缝集成。

✨ 特性

  • TypeScript就绪：完全支持TypeScript，具有严格的类型检查
  • 苏格兰和南方能源公司运输：使用服务器发送事件进行实时双向通信
  • Zod验证：运行时类型验证和架构解析
  • RESTful集成：使用REST国家/地区API的示例实现
  • 会话管理：用于多个并发连接的内置会话处理
  • CORS支持：配置了跨源资源共享
  • 热重载：开发服务器 tsx 用于即时反馈

🏗️ 建筑

src/
├── index.ts          # HTTP server & SSE transport setup
├── server.ts         # MCP server configuration & tool registration
├── types.ts          # TypeScript type definitions
├── api/              # External API integrations
│   └── fetchRestCountries.ts
├── parser/           # Zod schema validators
│   └── index.ts
└── resources/        # MCP resources configurations
│   └── index.ts
└── tools/            # MCP tool configurations
    └── index.ts

🚀 快速开始

  1. 克隆和安装依赖关系：

    pnpm install

  2. 启动开发服务器：

    pnpm start

  3. 服务器终结点：

    • SSE流： GET http://localhost:8000/mcp
    • 消息终结点： POST http://localhost:8000/mcp/messages?sessionId={id}

🔧 配置

环境变量

创建一个 .env 文件：

PORT=8000  # Optional, defaults to 8000

添加新工具

  1. 定义工具配置 在 src/tools/index.ts:
export const myNewToolConfig = (): TRegisterTool => ({
  title: "My New Tool",
  description: "Description of what it does",
  inputSchema: {
    param1: z.string().describe("Parameter description")
  },
  outputSchema: {
    result: z.any()
  }
});
  1. 注册该工具 在 src/server.ts:
server.registerTool(
  "my_new_tool",
  myNewToolConfig(),
  async ({ param1 }) => {
    // Tool implementation
    return {
      content: [{ type: "text", text: "Result" }],
      structuredContent: { result: "data" }
    };
  }
);

🛠️ 内置示例：国家数据工具

启动器包括一个获取国家信息的完整示例：

用途：

// The tool accepts a country name and returns detailed country data
{ "countryName": "Germany" }

🔍 关键组件

McpServer

核心MCP服务器设置，包括工具注册和功能配置。

SSEServerTransport

处理服务器发送事件传输层，用于客户端和服务器之间的实时通信。

StdioTransport

处理无法使用SSEServerTransport的客户端AI应用程序

SessionRecord

用于处理多个并发连接的类型安全会话管理。

fetchRestCountries

API与错误处理和响应格式的集成示例。

📊 传输层

此实现使用 SSE（服务器发送事件） 代替stdio传输：

  • ✅ 实时：即时双向通信
  • ✅ 网络兼容：与web客户端无缝协作
  • ✅ 基于会话：支持多个并发连接
  • ✅ 错误处理：强大的连接管理

🧪 发展

类型安全

所有模式都使用验证 萨德 与TypeScript集成：

import z from "zod";

export const mySchema = z.object({
  field: z.string().describe("Field description")
});

添加外部API

遵循中的模式 src/api/fetchRestCountries.ts:

const fetchMyAPI = async (param: string) => {
  try {
    const res = await fetch(`https://api.example.com/${param}`);
    return await res.json();
  } catch (err) {
    console.error(`API Error: ${err}`);
    return "Error message";
  }
};

📦 依赖项

🌐 使用AI客户端

此MCP服务器支持两种传输方式：

选项1:HTTP/SSE传输（通过ngrok用于ChatGPT）

  1. 启动HTTP服务器：

    pnpm start

  2. 使用ngrok暴露您的服务器：

    ngrok http 8000

  3. 配置ChatGPT：

    • 复制ngrok HTTPS URL（例如。， https://abc123.ngrok.io)
    • 在ChatGPT中，使用SSE端点添加MCP服务器：
      • SSE流： https://abc123.ngrok.io/mcp
      • 消息终结点： https://abc123.ngrok.io/mcp/messages

选项2：Stdio传输（适用于Claude桌面和本地AI应用程序）

  1. 配置Claude桌面 （或其他本地AI应用程序）：

    编辑您的 claude_desktop_config.json 文件：

    {
  "mcpServers": {
    "ts_mcp_starter": {
      "command": "C:\\Users\\YOUR_USERNAME\\Development\\mcp\\YOUR_MCP_FOLDER\\node_modules\\.bin\\tsx.cmd",
      "args": ["C:\\Users\\YOUR_USERNAME\\Development\\mcp\\YOUR_MCP_FOLDER\\src\\stdio.ts"],
      "cwd": "C:\\Users\\YOUR_USERNAME\\Development\\mcp\\YOUR_MCP_FOLDER"
    }
  }
}

    重要提示： 替换 YOUR_USERNAME 使用您的实际用户名，并根据需要调整路径。

    对于macOS/Linux：

    {
  "mcpServers": {
    "ts_mcp_starter": {
      "command": "node",
      "args": ["/absolute/path/to/YOUR_MCP_FOLDER/node_modules/.bin/tsx", "src/stdio.ts"],
      "cwd": "/absolute/path/to/YOUR_MCP_FOLDER"
    }
  }
}

  2. 重新启动克劳德桌面 加载MCP服务器

  3. 验证连接：

    • 检查Claude Desktop日志以确保连接成功
    • 服务器将向stderr输出：“MCP服务器在stdio上运行”

我应该使用哪种交通工具？

运输 用例 优点 缺点
HTTP/SSE ChatGPT、web客户端、远程访问 多个并发连接、web兼容、易于调试 需要ngrok进行ChatGPT和端口管理
工作室 Claude Desktop，本地AI应用程序 直接集成，无需网络设置，安全 单连接，仅限本地

🚀 生产部署

在生产环境中构建和运行：

# Build the project
npx tsc

# Run the built server
node build/index.js

对于容器化部署，服务器在配置的端口上运行，并接受MCP通信的HTTP连接。

准备好构建下一个MCP服务器了吗？ 这个入门套件提供了使用现代TypeScript工具创建健壮、类型安全的MCP应用程序所需的一切！ 🎉

相关 MCP