AI导哈

MCP服务器模板

一个使用TypeScript和Node.js构建模型上下文协议（MCP）服务器的全面模板，支持本地和云端部署。

  • by chris-quintin
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 chris-quintin/mcp-server-template

使用说明

MCP服务器模板

使用TypeScript和Node.js构建模型上下文协议（MCP）服务器的综合模板。

特性

  • 🛠️ 完成MCP实施：工具、资源和提示
  • 🔄 双重运输支持：STDIO（本地）+HTTP（网络/云）模式
  • 📦 TypeScript：完全类型安全和现代JavaScript功能
  • 🔧 示例工具：示例实现，助您入门
  • 📚 资源管理：文件式数据暴露
  • 💬 提示模板：可重用的AI交互模板
  • 🚀 开发就绪：热重载、linting和构建脚本
  • ☁️ 云就绪：铁路、Docker和多平台部署
  • 📖 证据充分的：综合示例和评论

先决条件

  • Node.js v18.0.0或更高版本
  • npm或yarn包管理器

快速开始

  1. 克隆和设置

    git clone <your-repo-url> my-mcp-server
cd my-mcp-server
npm install

  2. 配置环境

    cp .env.example .env
# Edit .env with your configuration

  3. 发展模式

    npm run dev

  4. 为生产而建

    npm run build
npm start        # STDIO mode
npm start:http   # HTTP mode

🔄 运输方式

此模板支持 两种运输方式 具有相同的MCP功能：

📱 STDIO模式（本地MCP客户端）

非常适合本地MCP客户端，如Claude Desktop、Cursor或其他桌面应用程序。

# Development
npm run dev

# Production
npm run build
npm start

在以下情况下使用STDIO：

  • ✅ 与Claude Desktop集成
  • ✅ 在当地发展
  • ✅ 构建桌面MCP集成
  • ✅ 与基于流程的MCP客户端合作

客户端配置示例（Claude Desktop）：

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

🌐 HTTP模式（网络/云部署）

非常适合web应用程序、云部署和远程MCP访问。

# Development  
npm run dev:http

# Production
npm run build
npm start:http

在以下情况下使用HTTP：

  • ✅ 部署到Railway、Render或其他云平台
  • ✅ 构建基于web的MCP集成
  • ✅ 需要HTTP端点进行健康检查
  • ✅ 需要远程访问您的MCP服务器

终点：

  • 健康检查： GET /health
  • SSE连接： GET /sse
  • MCP消息： POST /message

📊 模式比较

功能 STDIO模式 HTTP模式
运输 stdin/stdout 基于HTTP的SSE
用例 本地客户端 Web/云部署
健康检查 ❌ ✅ /health 端点
远程访问 ❌ ✅ HTTPS支持
云部署 ❌ ✅ 铁路、渲染等。
桌面客户端 ✅ 克劳德桌面 ❌
相同的MCP功能 ✅ ✅

这两种模式都实现了 完全相同的MCP功能 -工具、资源和提示是相同的。根据您的部署需求进行选择！

项目结构

mcp-server-template/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .eslintrc.json        # ESLint configuration
├── .env.example          # Environment variables template
├── .gitignore           # Git ignore rules
└── README.md            # This file

核心概念

工具

工具是MCP客户端可以调用的函数。它们接受结构化输入并返回结构化输出。

// Example tool registration
{
  name: 'search_data',
  description: 'Search for data using a query string',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'The search query' }
    },
    required: ['query']
  }
}

资源

资源以类似文件的方式公开数据。它们有URI，可以被客户端读取。

// Example resource
{
  uri: 'config://server',
  mimeType: 'application/json',
  name: 'Server Configuration',
  description: 'Current server configuration and settings'
}

鼓励

提示是具有参数化支持的AI交互的可重用模板。

// Example prompt
{
  name: 'analyze_data',
  description: 'Analyze data and provide insights',
  arguments: [
    { name: 'data', description: 'The data to analyze', required: true }
  ]
}

定制

添加新工具

  1. 定义工具模式 在 ListToolsRequestSchema 处理程序：

    tools.push({
  name: 'my_tool',
  description: 'Description of what the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'First parameter' }
    },
    required: ['param1']
  }
});

  2. 执行工具逻辑 在 CallToolRequestSchema 处理程序：

    case 'my_tool': {
  const { param1 } = args as { param1: string };
  const result = await myService.doSomething(param1);
  return {
    content: [{ type: 'text', text: result }]
  };
}

添加新资源

  1. 注册资源 在 ListResourcesRequestSchema 处理器
  2. 执行读取逻辑 在 ReadResourceRequestSchema 处理器

添加新提示

  1. 注册提示 在 ListPromptsRequestSchema 处理器
  2. 执行提示逻辑 在 GetPromptRequestSchema 处理器

开发脚本

  • npm run dev -使用热重新加载启动开发服务器
  • npm run build -为生产而建
  • npm start -启动生产服务器
  • npm run watch -开发观看模式
  • npm run lint -运行ESLint
  • npm run lint:fix -自动修复ESLint问题
  • npm run clean -清理构建目录

环境变量

复制 .env.example 向 .env 并配置：

  • NODE_ENV -环境（开发/生产）
  • API_KEY -您的API密钥（如果使用外部服务）
  • DATABASE_URL -数据库连接字符串（如果需要）
  • LOG_LEVEL -日志记录级别（调试/信息/警告/错误）

错误处理

该模板包括全面的错误处理：

  • 工具错误：捕获并作为错误响应返回
  • 资源错误：缺少资源的正确错误消息
  • 服务器错误：已登录到stderr（从不stdout）
  • 优雅地关闭：处理SIGINT以实现干净关机

最佳实践

  1. 从不写入stdout -使用stderr进行日志记录
  2. 验证输入 -使用Zod模式进行输入验证
  3. 优雅地处理错误 -返回有意义的错误消息
  4. 使用TypeScript -始终利用类型安全
  5. 记录您的工具 -提供清晰的描述和示例
  6. 彻底测试 -测试所有工具、资源和提示

部署

地方发展

STDIO模式（适用于本地MCP客户端）:

npm run dev

HTTP模式（用于web/远程访问）:

npm run dev:http

生产建设

npm run build
npm start        # STDIO mode
npm start:http   # HTTP mode

铁路部署

Railway是部署具有自动HTTPS和扩展功能的MCP服务器的绝佳平台。

1.一键部署

2.手动部署

  1. 安装铁路CLI:

    npm install -g @railway/cli

  2. 登录并初始化:

    railway login
railway init

  3. 配置环境变量:

    railway variables set NODE_ENV=production
railway variables set API_KEY=your-api-key
railway variables set PORT=3000

  4. 部署:

    railway up

3.GitHub集成

  1. 将代码推送到GitHub
  2. 访问 铁路
  3. 点击“新建项目”→ “从GitHub仓库部署”
  4. 选择您的存储库
  5. 铁路将自动检测配置并部署

铁路配置文件:

  • railway.json -铁路部署设置
  • nixpacks.toml -构建配置
  • 通过铁路仪表板设置的环境变量

铁路特征:

  • ✅ 带有自定义域的自动HTTPS
  • ✅ 零停机部署
  • ✅ 基于流量的自动缩放
  • ✅ 内置监控和日志
  • ✅ 环境变量管理
  • ✅ GitHub/GitLab集成

4.访问已部署的服务器

部署后，铁路提供：

  • 公共URL: https://your-app.railway.app
  • 健康检查： https://your-app.railway.app/health
  • MCP端点： https://your-app.railway.app/message

Docker部署

创建一个 Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
EXPOSE 3000
CMD ["npm", "run", "start:http"]

构建并运行：

docker build -t mcp-server .
docker run -p 3000:3000 mcp-server

其他云平台

渲染

  1. 连接GitHub存储库
  2. 设置构建命令： npm run build
  3. 设置启动命令： npm run start:http
  4. 添加环境变量

Fly.io

fly launch
fly deploy

谷歌云运行

gcloud run deploy --source .

Vercel（无服务器）

添加 vercel.json:

{
  "builds": [{ "src": "dist/http-server.js", "use": "@vercel/node" }],
  "routes": [{ "src": "/(.*)", "dest": "/dist/http-server.js" }]
}

故障排除

常见问题

  1. 未找到模块错误

    • 确保安装了所有依赖项： npm install
    • 检查TypeScript编译： npm run build

  2. 服务器未响应

    • 检查服务器是否在stdio传输上运行
    • 验证没有stdout污染（使用stderr进行日志记录）

  3. 类型错误

    • 运行TypeScript编译器： npx tsc --noEmit
    • 检查tsconfig.json配置

调试模式

通过设置环境变量启用调试日志记录：

LOG_LEVEL=debug npm run dev

贡献

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature-name
  3. 进行更改
  4. 运行测试和梳理： npm run lint
  5. 构建项目： npm run build
  6. 提交您的更改： git commit -am 'Add feature'
  7. 推到分支： git push origin feature-name
  8. 创建拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

资源

支持

如果您遇到问题或需要帮助：

  1. 检查 MCP文件
  2. 查看中的示例实现 src/index.ts
  3. 在此存储库中打开问题
  4. 加入MCP社区讨论

相关 MCP