使用说明

时区MCP服务器

一个支持双接口的时区服务器，同时支持 MCP（模型上下文协议） 用于大型语言模型（LLM）的发现和 REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口） 用于直接HTTP访问。获取可用区域、城市以及任何时区的当前时间，时间戳采用ISO 8601格式。

特点/功能

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

入门指南

先决条件

Node.js 22.20.0+（建议使用LTS版本）
pnpm 10.13.1（通过 Corepack 管理）

📦 包管理器： 这个项目使用 pnpm（一种包管理器，全称为Performance Packaged Node Modules，高性能打包的Node模块） 仅通过 Corepack 翻译成中文是“核心包装”或“核心封包”，具体取决于上下文和使用场景。在一般情况下，如果是指产品或服务的核心部分进行包装或封装，可以翻译为“核心包装”；如果是指数据或信息的封装传输，可以翻译为“核心封包” （内置在 Node.js 中）。确切的 pnpm 版本由以下（因素/代码）强制执行 packageManager 在 package.json 文件中的字段。安装 Node.js 后，运行 corepack enable 启用 pnpm 支持。

🔧 版本管理： 这个项目使用 fnm（通常用于表示“文件名”或在特定上下文中作为缩写，具体含义需根据上下文确定） (Fast Node Manager) 或 不说了（或：算了） 来管理Node.js版本。该 .node-version 当您（进行操作时），文件将自动切换到正确的 Node.js 版本 cd 进入项目目录（如果你已启用 fnm/nvm 的 shell 集成）。

安装

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 标准的提供商）：

为了谷歌:

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=your-github-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 云控制台
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服务器（适用于本地LLM客户端）

# Development mode with hot reload
pnpm mcp:dev

# Production mode
pnpm build
pnpm mcp:start

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

选项2：通过HTTP访问MCP服务器（适用于远程LLM客户端）

# Development mode with hot reload
pnpm mcp:http:dev

# Production mode
pnpm build
pnpm mcp:http

用途 通过HTTP流式传输HTTP内容 - 可访问于 http://localhost:3001/mcp

非常适合Claude Desktop的“添加自定义连接器”用户界面！ 🎯

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

# Development mode with hot reload
pnpm dev

# Production mode
pnpm build
pnpm start:prod

# Open Swagger UI in browser
pnpm swagger

REST API 将于以下时间启动 http://localhost:3000 翻译为中文是：“本地主机的3000端口”。不过，通常在中文语境中，我们可能不会直接这样翻译网址，而是根据上下文来解释或描述这个网址的用途，比如“访问本地开发服务器的3000端口”或者“这是运行在本地计算机上的Web服务的地址”。但直接翻译网址本身，就是“本地主机的3000端口”

交互式 Swagger/OpenAPI 文档可访问地址为 http://localhost:3000/api 翻译为中文是：“本地主机：3000 端口的 API”。不过，通常在中文语境下，我们可能更简洁地表述为“本地 3000 端口的 API”或直接解释为“访问本地开发服务器的 API 端点（端口 3000）”，具体取决于上下文和表述习惯。但直接翻译网址的话，上述翻译是较为准确的

可用的终端节点

认证：

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）是一种标准化协议，允许大型语言模型（LLMs）自动发现和使用工具。无需手动告知大型语言模型您的API端点，启用MCP的客户端（如Claude Desktop）可以：

自动发现 通过可用的工具 tools/list
检查模式（或架构） 理解输入参数
执行工具 通过 JSON-RPC tools/call 请求：

使用MCP Inspector进行测试（最快）

MCP Inspector 是一个网页用户界面，用于测试您的 MCP 服务器，无需使用 Claude Desktop：

pnpm install
pnpm build
pnpm mcp:inspector

这打开了 http://localhost:5173 在那里你可以：

查看列出的所有3个工具
检查工具模式和参数
执行工具并查看JSON响应
无需安装其他任何东西即可进行调试

使用Claude桌面版进行设置

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

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

编辑Claude桌面配置（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

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

重启Claude桌面版
克劳德现在可以自动发现并使用时区工具了！

可用的MCP工具

工具	参数	描述
`get_regions`	无（None）	获取所有时区区域的列表
`get_cities`	`region: string`	获取特定区域的城市
`get_timezone_info`	`region: string` `city: string`	获取ISO 8601格式的当前时间

建筑学

┌───────────────────────────────────────────────────┐
│              Timezone MCP Server                  │
├───────────────────────────────────────────────────┤
│                                                   │
│  REST API        MCP (HTTP/SSE)      MCP (stdio)  │
│  Port 3000       Port 3001           subprocess   │
│      ↓                ↓                   ↓       │
│  ┌────────┐     ┌─────────┐         ┌─────────┐   │
│  │NestJS  │     │   MCP   │         │   MCP   │   │
│  │ HTTP   │     │  HTTP   │         │  stdio  │   │
│  └───┬────┘     └────┬────┘         └────┬────┘   │
│      │               │                   │        │
│      └───────────────┴───────────────────┘        │
│                      ↓                            │
│              TimezoneService                      │
│          (Shared Business Logic)                  │
└───────────────────────────────────────────────────┘

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

测试

# Run all tests (includes MCP stdio e2e tests)
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:cov

# Run tests with UI
pnpm test:ui

# Run e2e tests only
pnpm test:e2e

测试覆盖率103/109项测试通过（94.5%）。HTTP MCP传输已通过MCP Inspector进行了全面的手动测试，但由于SSE（服务器发送事件）时间复杂性，端到端自动化测试尚待进行。

手动测试HTTP MCP服务器：

# Start HTTP MCP server
pnpm mcp:http:dev

# Test with MCP Inspector
pnpm mcp:inspector

# Test with Claude Desktop
# Settings > Connectors > Add Custom Connector
# URL: http://localhost:3001/mcp

代码质量

# Lint code
pnpm lint

# Fix lint issues
pnpm lint:fix

# Format code
pnpm format

# Check formatting
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服务器（标准输入输出）
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 - 运行所有测试（包括MCP e2e在内的84个测试）
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 - 升级依赖项（仅限小版本/补丁版本）

使用说明

时区MCP服务器

特点/功能

入门指南

先决条件

安装

身份验证设置

步骤1：配置环境变量

步骤2：设置OAuth2提供者

步骤3：认证流程

运行服务器

选项1：通过stdio使用MCP服务器（适用于本地LLM客户端）

选项2：通过HTTP访问MCP服务器（适用于远程LLM客户端）

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

可用的终端节点

MCP协议集成

什么是MCP？

使用MCP Inspector进行测试（最快）

使用Claude桌面版进行设置

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

可用的MCP工具

建筑学

测试

代码质量

文档

脚本参考

服务器脚本

构建与测试

代码质量

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器