STARWARCLOUD STARWAR.AI
返回市场
模版服务器

模版服务器

作者：samwang07232 星标更新：2025-11-18
安装使用来源：spider==github.com

项目介绍

MCP服务器模板

这是一个用于创建具有HTTP传输的模型上下文协议（MCP）服务器的TypeScript生产就绪模板。此模板为构建可扩展、安全且易于维护的MCP服务器提供了坚实的基础。

🚀 特性

  • TypeScript：使用现代TypeScript模式实现完全类型安全
  • HTTP传输：基于Express.js服务器的RESTful API
  • 会话管理：具有适当会话处理的状态连接
  • 配置管理：基于环境的配置验证
  • 错误处理：全面的错误处理和日志记录
  • 健康检查：内置健康监控端点
  • Docker支持：生产就绪容器化
  • 开发工具：ESLint、Prettier和测试设置
  • 生产就绪：优化了可扩展性和安全性

📋 先决条件

  • Node.js 20+
  • npm 或 yarn
  • Docker（可选，用于容器化）

🛠️ 快速开始

方案1：使用项目生成器（推荐）

# 克隆模板
git clone <your-repo-url>
cd mcp-template

# 使用生成器创建新项目
./create-mcp-project your-project-name --description "Your project description" --author "Your Name"

# 或直接使用Node.js脚本
node setup-new-project.js your-project-name --description "Your project description" --author "Your Name"

生成器选项：

  • --description <desc>：项目描述
  • --author <name>：作者名称
  • --target-dir <dir>：目标目录（默认：mcp-<项目名称>）
  • --install-deps：自动安装npm依赖
  • --no-git：跳过git仓库初始化

方案2：手动设置

# 克隆模板
git clone <your-repo-url>
cd mcp-template

# 安装依赖
npm install

# 复制环境配置
cp .env.example .env  # 创建此文件并添加您的设置

2. 环境配置

在根目录下创建一个.env文件：

# 服务器配置
PORT=3000
LOG_LEVEL=info

# 添加您的自定义环境变量

3. 开发

# 启动带有热重载的开发服务器
npm run dev

# 构建生产版本
npm run build

# 启动生产服务器
npm start

# 运行测试
npm test

# 检查和格式化代码
npm run lint
npm run lint:fix

🏗️ 项目结构

mcp-template/
├── src/
│   ├── config/           # 配置管理
│   │   └── index.ts      # 主配置文件
│   ├── utils/            # 工具函数
│   └── index.ts          # 主服务器应用
├── create-mcp-project    # 项目生成的Bash脚本
├── setup-new-project.js  # Node.js项目生成器
├── Dockerfile            # Docker配置
├── package.json          # 依赖项和脚本
├── tsconfig.json         # TypeScript配置
└── README.md            # 此文件

🔧 项目生成器

此模板包括强大的项目生成工具，可以快速创建新的MCP服务器：

功能：

  • 自动名称转换：将kebab-case名称转换为所有所需格式（camelCase、PascalCase等）
  • 文件模板：更新所有文件以包含新项目名称和详细信息
  • Git集成：可选地初始化新的git仓库
  • 依赖管理：可以自动安装npm依赖
  • 智能复制逻辑：排除开发文件并防止无限递归

使用示例：

# 基本用法
./create-mcp-project weather-service

# 使用全部选项
./create-mcp-project task-manager \
  --description "AI驱动的任务管理MCP服务器" \
  --author "您的名字" \
  --install-deps

# 自定义目标目录
./create-mcp-project file-processor --target-dir ./my-custom-server

# 跳过git初始化
./create-mcp-project data-analyzer --no-git

🔧 架构

核心组件

  1. McpServerApp：协调MCP服务器的主要应用程序类
  2. 配置：具有类型安全性的基于环境的配置
  3. 会话管理：具有清理功能的基于HTTP的状态会话
  4. 传输层：用于MCP通信的StreamableHTTPServerTransport
  5. 错误处理：具有适当HTTP响应的全面错误处理

HTTP端点

  • GET /health - 健康检查端点
  • POST /mcp - 主MCP通信端点
  • GET /mcp - 通过SSE从服务器到客户端的通知
  • DELETE /mcp - 会话终止

🛠️ 自定义指南

添加新工具

要在src/index.ts中的createServer()方法中添加一个新的MCP工具：

// 注册您的自定义工具
server.tool(
  'your-tool-name',
  '您的工具描述',
  {
    // 使用Zod定义输入模式
    parameter1: z.string().describe('参数描述'),
    parameter2: z.number().optional().describe('可选参数'),
  },
  async ({ parameter1, parameter2 }) => {
    try {
      // 您的工具实现
      const result = await yourCustomLogic(parameter1, parameter2);

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2),
          } as TextContent,
        ],
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      throw new Error(`您的工具名称错误：${errorMessage}`);
    }
  }
);

配置管理

在src/config/index.ts中添加新的配置选项：

interface Config {
  logging: LoggingConfig;
  server: ServerConfig;
  // 添加您的自定义配置部分
  database: {
    url: string;
    timeout: number;
  };
  external: {
    apiKey: string;
    baseUrl: string;
  };
}

const config: Config = {
  // ... 现有配置
  database: {
    url: process.env.DATABASE_URL || 'sqlite://memory',
    timeout: parseInt(process.env.DB_TIMEOUT || '5000', 10),
  },
  external: {
    apiKey: process.env.EXTERNAL_API_KEY || '',
    baseUrl: process.env.EXTERNAL_BASE_URL || 'https://api.example.com',
  },
};

添加中间件

在run()方法中添加Express中间件：

async run() {
  const app = express();
  app.use(express.json());

  // 添加您的自定义中间件
  app.use(cors()); // CORS支持
  app.use(helmet()); // 安全头
  app.use(morgan('combined')); // 请求日志

  // ... 设置的其余部分
}

🐳 Docker部署

构建和运行

# 构建Docker镜像
docker build -t mcp-server .

# 运行容器
docker run -p 3000:3000 --env-file .env mcp-server

Docker Compose（推荐）

创建一个docker-compose.yml：

version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3

运行：

docker-compose up -d

🔒 安全最佳实践

此模板实现了多项安全措施：

  • 输入验证：所有工具参数的Zod模式验证
  • 错误处理：没有信息泄露的安全错误响应
  • 会话管理：适当的会话清理和验证
  • HTTP安全：准备安全头和CORS配置
  • 环境变量：安全配置管理

推荐额外的安全措施

// 添加安全中间件
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';

app.use(helmet());
app.use(
  cors({
    origin: process.env.ALLOWED_ORIGINS?.split(',') || false,
  })
);

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 每个IP每windowMs限制100次请求
});
app.use('/mcp', limiter);

📊 监控和日志

模板包括基本的日志设置。对于生产环境，考虑添加：

  • 结构化日志：Winston与JSON格式
  • 指标收集：Prometheus指标
  • 健康检查：全面的健康端点
  • APM集成：应用程序性能监控

🧪 测试

# 运行所有测试
npm test

# 在监视模式下运行测试
npm run test:watch

# 运行带覆盖率的测试
npm run test:coverage

编写测试

在src/**/*.test.ts中创建测试文件：

import { describe, test, expect } from '@jest/globals';
// 您的测试导入

describe('您的组件', () => {
  test('应处理有效输入', async () => {
    // 测试实现
  });
});

🚀 生产部署

环境变量

NODE_ENV=production
PORT=3000
LOG_LEVEL=warn

# 添加特定于生产的变量
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
API_KEYS=...

性能优化

  • 启用gzip压缩
  • 实现适当的缓存头
  • 对数据库使用连接池
  • 监控内存使用情况并实施限制
  • 设置日志轮换

扩展考虑

  • 在多个实例之间进行负载均衡
  • 数据库连接池
  • 会话存储外部化（Redis）
  • 在Kubernetes中设置水平pod自动缩放

📚 参考资料

🤝 贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 为新功能编写测试
  5. 运行测试套件
  6. 提交拉取请求

📝 许可证

本项目采用MIT许可证 - 查看LICENSE文件了解详情。

🆘 支持

对于问题和支持：

  • 查看MCP文档
  • 查看现有问题
  • 创建一个带有详细信息的新问题

祝编码愉快！🎉