MCP 服务器

MCP TypeScript Server Starter

ralf-boltshauser

开发者工具

访问服务器

README

MCP TypeScript 服务端启动器

一个用于使用 TypeScript 构建模型上下文协议 (MCP) 服务端的启动项目。该项目提供了一个简单的回显服务端实现，演示了 MCP 的核心功能。

快速开始清单

📥 安装

[ ] 克隆仓库：

git clone https://github.com/ralf-boltshauser/mcp-typescript-server-starter.git
cd mcp-typescript-server-starter

[ ] 安装依赖：
```
pnpm install
```

🛠️ 本地开发

[ ] 启动开发服务器：
```
pnpm dev
```
[ ] 在 http://localhost:6274 访问检查器
[ ] 测试你的 MCP 服务端：
1. 在检查器中点击 "Connect"
2. 导航到 "Tools" 部分
3. 点击 "List Tools"
4. 选择 "echo" 工具
5. 编写测试消息
6. 点击 "Submit"
[ ] 打开 src/index.ts 添加你自己的：
- 工具 (你的 AI 可以调用的函数)
- 资源 (你的 AI 可以访问的数据)
- 提示词 (AI 交互的模板)
[ ] 使用你服务端的描述和文档更新 src/index.html

🚀 部署 (Coolify 示例)

[ ] 在 Coolify 上设置：
1. 连接你的仓库
2. 在高级设置中：
  - [ ] 禁用 GZIP 压缩 (SSE 需要)
3. 配置域名：
  - [ ] 添加你的域名为：https://subdomain.yourdomain.com:3001
    - :3001 至关重要 - 它告诉 traefik 绑定到你的内部端口
[ ] 验证部署：
1. 访问 subdomain.yourdomain.com 查看你的 index.html
2. 在 https://subdomain.yourdomain.com/sse 测试 SSE 连接

🔌 连接到你已部署的服务端

使用以下命令连接到你的服务端：

npx -y mcp-remote https://subdomain.yourdomain.com/sse

Cursor/Claude Desktop 的示例配置：

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://subdomain.yourdomain.com/sse"]
    },
  }
}

功能特性

简单的回显服务端实现
支持工具、资源和提示词
TypeScript 支持
带有热重载的开发服务器
用于测试和调试的内置检查器
支持 STDIO 和 SSE 两种通信模式

前置条件

Node.js (v16 或更高版本)
pnpm (推荐) 或 npm

使用模式

此服务器支持两种主要的通信模式：

STDIO 模式
- 适用于本地开发和基本测试
- 直接进程通信
- 默认情况下，大多数 MCP 客户端使用此模式
- 非常适合在本地运行服务器
- 设置和使用简单
SSE 模式
- 更适合生产环境部署
- HTTP/SSE 通信
- 可以使用 npm 包转换为 STDIO (稍后介绍)
- 允许远程访问你的服务器
- 更具可扩展性和生产就绪性

选择 STDIO 用于本地开发，并在需要部署服务器以进行远程访问时选择 SSE。

STDIO 模式 (直接进程通信)

此模式非常适合与 Cursor 或 Claude Desktop 等工具直接集成。

配置服务器
- 在 src/index.ts 中：
  - 注释掉 Express/SSE 代码 (在底部)
  - 取消注释 STDIO 代码 (在它上面)
构建和运行
```
pnpm build
node dist/index.cjs
```

或者

pnpm dev # 启动服务器和检查器

与 Claude Desktop 集成
```
pnpm add-claude
```
⚠️ 注意: 这将覆盖你现有的 Claude Desktop 配置。

这种配置 claude desktop 的方式是标准的。生成的 json 也可以在 cursor 等中使用！

手动集成 对于其他工具，使用以下命令：

node /path/to/your/project/dist/index.cjs

或者

pnpm cmd # 这会直接使用 pwd 给你 node .../dist/index.cjs 命令

SSE 模式 (HTTP/SSE 通信)

此模式非常适合基于 Web 的工具和远程部署。

配置服务器
- 在 src/index.ts 中：
  - 保持 Express/SSE 代码启用 (在底部)
  - 注释掉 STDIO 代码 (在它上面)
本地开发
```
pnpm dev
```
服务器将在以下位置可用：
- 主端点: http://127.0.0.1:3001
- SSE 端点: http://127.0.0.1:3001/sse
- 测试端点: http://127.0.0.1:3001/test
- 检查器: http://127.0.0.1:6274
本地 Docker 测试 需要 docker compose override 才能实际暴露端口。当部署到像 coolify 这样的东西时，你不需要它，因为 traefik 会处理它。
```
docker compose -f docker-compose.yaml -f docker-compose.local.yaml up
```
生产环境部署 (例如，Coolify)
- 让你的 IDE 更新 src/index.html 以匹配你的服务器描述。
- 将服务器部署到你喜欢的平台
- 重要: 在 Coolify 的高级设置中：
  - 禁用 GZIP 压缩 (这会终止 SSE 流)
  - 确保端口 3001 已正确暴露 -> 设置域名时，请执行以下操作：https://your-domain.com:3001，这告诉 traefik 绑定到端口 3001。
  - 配置服务器以侦听所有接口 (0.0.0.0) (已完成)
使用远程服务器 部署后，你可以使用以下命令连接到服务器：
```
npx -y mcp-remote https://your-domain.com/sse
```
你可以将此粘贴为命令，并将 "node .../dist/index.cjs" 替换为此命令。

项目结构

src/index.ts - 主要服务器实现
src/low-level-index.ts - 使用底层 API 的替代实现
dist/ - 编译后的输出目录

服务器功能

回显工具

一个简单的工具，用于回显输入消息：

server.tool("echo", { message: z.string() }, async ({ message }) => ({
  content: [{ type: "text", text: `Tool echo: ${message}` }],
}));

回显资源

可以通过 URI 访问的资源：

server.resource(
  "echo",
  new ResourceTemplate("echo://{message}", { list: undefined }),
  async (uri, { message }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Resource echo: ${message}`,
      },
    ],
  })
);

回显提示词

用于处理消息的提示词模板：

server.prompt("echo", { message: z.string() }, ({ message }) => ({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: `Please process this message: ${message}`,
      },
    },
  ],
}));

实现建议

调试消息

可以使用 server.server.sendLoggingMessage 方法发送调试消息，以提供服务器操作的可见性。

基本用法

server.server.sendLoggingMessage({
  level: "info",
  data: "Starting server...",
});

这允许你：

实时跟踪服务器操作
在开发期间调试问题
监控生产环境中的服务器状态

你可以在检查器的右下角看到它们！

环境变量

对于服务器端环境变量 (开发者提供，非用户特定)：

使用 Docker Compose

# docker-compose.yaml
services:
  mmcp-server:
    environment:
      - API_KEY=${API_KEY}
      - DATABASE_URL=${DATABASE_URL}

这允许你：

在你的 shell 中设置变量：export API_KEY=your-key
使用 Docker Compose 将自动加载的 .env 文件

在代码中访问

const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;

本地开发
- 在你的项目根目录中创建一个 .env 文件：
```
API_KEY=sk-123
```
- 将 .env 添加到 .gitignore 以确保密钥安全
- 使用环境变量运行开发服务器：
```
pnpm dev
```
生产环境部署
- 在你的部署平台 (例如，Coolify) 中设置环境变量
- 永远不要将敏感值提交到版本控制