演示-mcp

Name: 演示-mcp
Author: sam-artuso

作者：sam-artuso8 星标更新：2025-10-22

安装使用来源：spider==github.com

项目介绍

时区 MCP 服务器

支持双接口的时区服务器，同时支持用于大语言模型发现的MCP（模型上下文协议）和用于直接HTTP访问的REST API。获取可用区域、城市以及任何时区的当前时间，并以ISO 8601格式的时间戳显示。

特性

🤖 MCP 协议支持 - 大语言模型可以通过JSON-RPC自动发现并使用时区工具
🌐 REST API - 具有Swagger/OpenAPI文档的传统HTTP端点
🔐 OAuth2 认证 - 使用用户白名单和客户端凭证的安全访问
⏰ 时区操作 - 获取区域、城市以及任何时区的当前时间
📅 ISO 8601 时间戳 - 带偏移量的本地日期时间、UTC日期时间和时区偏移量
🧪 100% 测试覆盖率 - 综合单元测试和端到端测试（Vitest）
🔧 NestJS & TypeScript - 现代且类型安全的开发环境
📚 双文档 - Swagger UI供人类阅读，MCP模式供大语言模型使用
🎨 代码质量 - ESLint、Prettier和自动化格式化

开始使用

预备条件

Node.js 22.20.0+（推荐长期支持版本）
pnpm 10.13.1（通过Corepack管理）

📦 包管理器： 本项目仅通过Corepack（内置在Node.js中）使用pnpm。确切的pnpm版本由package.json中的packageManager字段强制执行。安装Node.js后，运行corepack enable以激活pnpm支持。

🔧 版本管理： 本项目使用fnm（快速Node.js管理器）或nvm来管理Node.js版本。当您进入项目目录时（如果启用了fnm/nvm shell集成），.node-version文件会自动切换到正确的Node.js版本。

安装

pnpm install

认证设置

此服务器需要对所有端点进行OAuth2认证，除了/health。您需要在运行服务器之前配置认证。

步骤 1：配置环境变量

复制示例环境文件并编辑它：

cp example.env .env

编辑.env并配置：

JWT 设置（必需）：

JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRES_IN=3600

OAuth2 提供商（选择一个 - Google、GitHub或其他符合OAuth2标准的提供商）：

对于Google：

OAUTH2_AUTHORIZATION_URL=https://accounts.google.com/o/oauth2/v2/auth
OAUTH2_TOKEN_URL=https://oauth2.googleapis.com/token
OAUTH2_USER_INFO_URL=https://www.googleapis.com/oauth2/v2/userinfo
OAUTH2_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
OAUTH2_CLIENT_SECRET=your-google-client-secret
OAUTH2_CALLBACK_URL=http://localhost:3000/auth/callback
OAUTH2_SCOPE=openid email profile

对于GitHub：

OAUTH2_AUTHORIZATION_URL=https://github.com/login/oauth/authorize
OAUTH2_TOKEN_URL=https://github.com/login/oauth/access_token
OAUTH2_USER_INFO_URL=https://api.github.com/user
OAUTH2_CLIENT_ID=your-github-client-id
OAUTH2_CLIENT_SECRET=
OAUTH2_CALLBACK_URL=http://localhost:3000/auth/callback
OAUTH2_SCOPE=user:email

用户白名单（必需）：

ALLOWED_EMAILS=user1@example.com,user2@example.com,admin@company.com

步骤 2：设置 OAuth2 提供商

在您的提供商处创建OAuth2凭证：

Google：Google Cloud Console
GitHub：GitHub 开发者设置

设置授权重定向URI为：http://localhost:3000/auth/callback

步骤 3：认证流程

访问http://localhost:3000/auth/login
转向OAuth2提供商（Google/GitHub等）
登录并授权
返回带有屏幕显示的JWT令牌

复制令牌并在API请求中使用：

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/timezones/regions

运行服务器

本项目提供了可以独立运行的三个接口：

选项 1：通过 stdio 的 MCP 服务器（适用于本地大语言模型客户端）

# 开发模式，带热重载
pnpm mcp:dev

# 生产模式
pnpm build
pnpm mcp:start

使用stdio传输 - 作为子进程启动。非常适合Claude Desktop配置文件。

选项 2：通过 HTTP 的 MCP 服务器（适用于远程大语言模型客户端）

# 开发模式，带热重载
pnpm mcp:http:dev

# 生产模式
pnpm build
pnpm mcp:http

使用流式HTTP传输 - 在http://localhost:3001/mcp可访问

非常适合Claude Desktop的“添加自定义连接器”UI！🎯

选项 3：REST API 服务器（适用于HTTP客户端）

# 开发模式，带热重载
pnpm dev

# 生产模式
pnpm build
pnpm start:prod

# 在浏览器中打开 Swagger UI
pnpm swagger

REST API将在http://localhost:3000启动

交互式的Swagger/OpenAPI文档可在http://localhost:3000/api找到

可用端点

认证：

GET /auth/login - 启动OAuth2登录（重定向到提供商）
GET /auth/callback - OAuth2回调（返回JWT令牌）

健康检查：

GET /health - 健康检查端点（公开，无需认证）

{
  "status": "ok",
  "timestamp": "2025-10-17T18:30:45.123Z"
}

时区 API：（需要认证 - 包含Authorization: Bearer TOKEN头）

GET /timezones/regions - 获取所有可用的时区区域

{
  "regions": [
    "Africa",
    "America",
    "Antarctica",
    "Asia",
    "Atlantic",
    "Australia",
    "Europe",
    "Indian",
    "Pacific"
  ],
  "count": 15
}

GET /timezones/regions/:region/cities - 获取特定区域内的所有城市

{
  "region": "America",
  "cities": ["New_York", "Los_Angeles", "Chicago", "Denver", "Phoenix"],
  "count": 150
}

GET /timezones/:region/:city - 获取特定时区的当前时间

{
  "timezone": "America/New_York",
  "datetime_local": "2025-10-17T13:47:23-04:00",
  "datetime_utc": "2025-10-17T17:47:23.345Z",
  "timezone_offset": "-04:00",
  "timestamp": 1760723243345
}

MCP 协议集成

什么是 MCP？

模型上下文协议 (MCP) 是一种标准化协议，允许大语言模型自动发现和使用工具。不需要手动告诉大语言模型关于您的API端点，像Claude Desktop这样的MCP启用客户端可以：

自动发现可用工具通过tools/list
检查模式以理解输入参数
执行工具通过JSON-RPC tools/call请求

使用 MCP Inspector 测试（最快捷）

MCP Inspector是一个Web UI，无需Claude Desktop即可测试您的MCP服务器：

pnpm install
pnpm build
pnpm mcp:inspector

这将打开http://localhost:5173，在那里您可以：

查看列出的所有3个工具
检查工具模式和参数
执行工具并查看JSON响应
不需安装其他内容即可调试

使用 Claude Desktop 设置

方法 1：本地 stdio 连接（推荐）

构建项目：
```
pnpm install
pnpm build
```

编辑Claude Desktop配置（macOS上的~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "timezone": {
      "command": "node",
      "args": ["/absolute/path/to/demo-mcp/dist/main.js"]
    }
  }
}

重启Claude Desktop
Claude现在可以自动发现并使用时区工具！

可用的 MCP 工具

工具	参数	描述
`get_regions`	无	获取所有时区区域列表
`get_cities`	`region: string`	获取特定区域内的城市
`get_timezone_info`	`region: string`<br/>`city: string`	获取当前时间，采用ISO 8601格式

架构

┌───────────────────────────────────────────────────┐
│              时区 MCP 服务器                       │
├───────────────────────────────────────────────────┤
│                                                   │
│  REST API        MCP (HTTP/SSE)      MCP (stdio)  │
│  端口 3000       端口 3001           子进程       │
│      ↓                ↓                   ↓       │
│  ┌────────┐     ┌─────────┐         ┌─────────┐   │
│  │NestJS  │     │   MCP   │         │   MCP   │   │
│  │ HTTP   │     │  HTTP   │         │  stdio  │   │
│  └───┬────┘     └────┬────┘         └────┬────┘   │
│      │               │                   │        │
│      └───────────────┴───────────────────┘        │
│                      ↓                            │
│              时区服务                             │
│          （共享业务逻辑）                         │
└───────────────────────────────────────────────────┘

所有三个接口都使用相同的TimezoneService，确保REST API、远程MCP和本地MCP连接的一致行为。

测试

# 运行所有测试（包括MCP stdio端到端测试）
pnpm test

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

# 运行带有覆盖率报告的测试
pnpm test:cov

# 使用UI运行测试
pnpm test:ui

# 仅运行端到端测试
pnpm test:e2e

测试覆盖率：103/109测试通过（94.5%）。HTTP MCP传输已通过MCP Inspector进行了全面的手动测试，但由于SSE定时复杂性，自动端到端测试仍在等待中。

手动测试 HTTP MCP 服务器：

# 启动 HTTP MCP 服务器
pnpm mcp:http:dev

# 使用 MCP Inspector 测试
pnpm mcp:inspector

# 使用 Claude Desktop 测试
# 设置 > 连接器 > 添加自定义连接器
# URL: http://localhost:3001/mcp

代码质量

# 检查代码
pnpm lint

# 自动修复代码问题
pnpm lint:fix

# 格式化代码
pnpm format

# 检查代码是否正确格式化
pnpm format:check

文档

附加指南和文档位于docs/目录中：

本地测试指南 - 使用MCP Inspector进行测试的逐步说明
部署指南 - 部署到Google Cloud Run
部署成功指南 - 部署后的验证

脚本参考

服务器脚本

pnpm dev - 开发模式启动REST API服务器
pnpm start - 启动REST API服务器
pnpm start:prod - 生产模式启动REST API服务器
pnpm mcp:dev - 开发模式启动MCP服务器（stdio）
pnpm mcp:start - 生产模式启动MCP服务器（stdio）
pnpm mcp:http:dev - 开发模式启动MCP服务器（HTTP/SSE）
pnpm mcp:http - 生产模式启动MCP服务器（HTTP/SSE）
pnpm mcp:inspector - 启动MCP Inspector（在浏览器中调试/测试MCP工具）
pnpm swagger - 在默认浏览器中打开Swagger UI

构建与测试

pnpm build - 构建项目（编译TypeScript到dist/）
pnpm test - 运行所有测试（84个测试，包括MCP端到端）
pnpm test:watch - 监视模式下运行测试
pnpm test:cov - 运行带有覆盖率报告的测试（100%覆盖率）
pnpm test:ui - 使用Vitest UI运行测试
pnpm test:e2e - 仅运行端到端测试

代码质量

pnpm lint - 使用ESLint检查代码
pnpm lint:fix - 自动修复代码问题
pnpm format - 使用Prettier格式化代码
pnpm format:check - 检查代码是否正确格式化
deps:check - 检查依赖项是否可以升级（仅小版本/补丁版本）
deps:update - 升级依赖项（仅小版本/补丁版本）