MCP TypeScript服务器启动器
一个用TypeScript构建模型上下文协议（MCP）服务器的启动项目。该项目提供了一个简单的echo服务器实现，演示了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. 点击检查器中的“连接” 1. 导航到“工具”部分 1. 点击“列出工具” 1. 选择“回声”工具 1. 编写测试消息 1. 点击“提交”
- \[\]打开
src/index.ts添加您自己的：
- 工具（AI可以调用的功能） - 资源（AI可以访问的数据） - 提示（AI交互模板）
- \[\]更新
src/index.html包含服务器的描述和文档
🚀 部署（Coolify示例）
- \[\]在Coolify上设置：
1. 连接您的存储库 1. 在高级设置中： - \[\]禁用GZIP压缩（SSE需要） 1. 配置域： - \[\]将您的域名添加为： https://subdomain.yourdomain.com:3001 - 这 :3001 是至关重要的-它告诉traefik绑定到您的内部端口
- \[\]验证部署：
1. 访问 subdomain.yourdomain.com 查看您的index.html 1. 在以下位置测试SSE连接 https://subdomain.yourdomain.com/sse
🔌 连接到已部署的服务器
使用此命令连接到您的服务器：
npx -y mcp-remote https://subdomain.yourdomain.com/sseCursor/Claude桌面的示例配置：
{
"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 # starts the server and the inspector- 与Claude Desktop集成
pnpm add-claude⚠️ 备注：这将覆盖您现有的Claude Desktop配置。
这种配置claude桌面的方式是标准的。生成的json也可以在游标等中使用！
- 手动积分
对于其他工具，请使用以下命令：
node /path/to/your/project/dist/index.cjs或
pnpm cmd # this gives you the node .../dist/index.cjs command directly with pwdSSE模式（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覆盖。当部署到像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”替换为this。
项目结构
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 - 使用 .env Docker Compose将自动加载的文件
- 在代码中访问
const apiKey = process.env.API_KEY;
const dbUrl = process.env.DATABASE_URL;- 地方发展
- 创建一个 .env 项目根目录中的文件：
API_KEY=sk-123- 添加 .env 向 .gitignore 保守秘密 - 使用环境变量运行开发服务器：
pnpm dev- 生产部署
- 在部署平台中设置环境变量（例如Coolify） - 切勿将敏感值提交到版本控制
最佳实践
- 错误处理
- 始终对环境变量实施正确的错误处理 - 为缺失的必需变量提供有意义的错误消息
- 类型安全
- 使用TypeScript定义环境变量类型 - 考虑使用类似的验证库 zod 用于运行时检查
- 安全
- 切勿将敏感的环境变量暴露给客户端 - 为开发和生产使用不同的变量集