TimeMCP

TimeMCP

一个提供时间和时区工具的 Model Context Protocol（MCP）服务。 它通过 stdio（默认）或可流式传输的 HTTP 运行，并基于 mark3labs/mcp-go 构建。

工具

get_current_time

返回指定时区或系统时区的当前时间。

参数	类型	必填	描述
timezone	字符串	否	IANA 时区；默认使用 TIME_DEFAULT_TIMEZONE，然后使用系统时区

示例响应：

Current time in Europe/Warsaw (CEST, UTC+02:00): Monday, 2025-04-09 15:30:45

convert_time

将一个时区的时间转换为另一个时区的时间。

参数	类型	必填	描述
source_timezone	字符串	否	源 IANA 时区；默认使用已配置的默认时区
time	字符串	否	HH:MM 格式的时间；默认使用当前时间
target_timezone	字符串	是	目标 IANA 时区

示例响应：

Time conversion: 2025-04-09 15:30 in Europe/Warsaw → 2025-04-09 09:30 in America/New_York

describe_time

解析灵活的日期／时间字符串，并说明其与当前时间的关系。 它会返回可供机器使用的 RFC 3339 时间戳，以及便于人理解的描述， 因此调用方无需自行计算日期。

支持的输入包括绝对日期（July 4th, 1776、22:08、 Thursday, July 20 2026）和相对表达（now、today、tomorrow、 yesterday、next/last/this <weekday>、单独的 <weekday>、 in N minutes/hours/days/weeks/months/years、N ... ago、 next/last week/month/year），还可以选择附加 at <time>。

对于有歧义的输入，会返回带标签的候选项，而不是进行猜测： 与日期不匹配的星期、mm/dd 与 dd/mm 的区别， 以及距今超过 30 天的无年份日期。

参数	类型	必填	描述
date	字符串	是	要解析的日期／时间表达
timezone	字符串	否	用于确定“现在”的时区；默认值同上

示例响应：

input:       "tomorrow at 5pm"
machine:     2026-10-24T17:00:00-04:00
human:       tomorrow at 5:00 PM
tense:       future
perspective: tomorrow evening

构建和运行

Taskfile.yml 封装了常用命令；也可以直接使用 go。

task build                       # go build -o bin/mcp-time .
task run                         # stdio transport
task run:http                    # HTTP transport on :8080
task run:http:auth               # HTTP transport with JWT auth
task test                        # unit tests
task test-client                 # stdio smoke test via examples/test_client.go
task check                       # fmt:check, vet, lint, test

使用 --hash-password 读取密码并输出其 PBKDF2 哈希，或使用 --generate-token 生成静态 Bearer 令牌。 这些凭据标志会在加载服务配置前退出，且不能同时使用。

客户端配置

Claude Desktop（stdio 传输）：

{
  "mcpServers": {
    "time": {
      "command": "/Path/To/Your/Bin/mcp-time"
    }
  }
}

任何兼容 MCP 的客户端都可以发现这些工具、调用它们并读取格式化后的响应。

HTTP 传输

使用 --transport=http 启动服务（可选添加 --auth-enabled）。 MCP 端点为 POST {TIME_HTTP_PATH}（默认为 /mcp）。 健康检查位于 GET /health；没有单独的 capabilities 端点 （工具发现通过 MCP tools/list 进行）。

CORS

默认禁用 CORS。 启用后，除非明确列入清单，否则不允许任何来源。

TIME_HTTP_CORS_ORIGINS 接受以逗号分隔的允许列表：

• 主机名：example.com
• 主机和端口：localhost:3000、127.0.0.1:8080
• 完整 URL：https://app.example.com（会规范化为其主机）
• 通配符子域：*.example.com（匹配 example.com 及其所有子域）
• *（仅在禁用身份验证时适用）

当 TIME_AUTH_ENABLED=true 时，启动会拒绝 * 条目。 仅针对允许的来源发送预检和响应标头。

JWT 身份验证

生成令牌（密钥必须至少包含 32 个字符）：

export TIME_AUTH_SECRET_KEY="your-256-bit-secret-key-here"
go run . --generate-token \
  --token-user-id="user123" --token-username="john" --token-role="admin"

每次 HTTP 请求都随附此令牌：

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/mcp

OAuth 2.1（claude.ai 自定义连接器）

设置 TIME_OAUTH_ENABLED=true，即可为 claude.ai、Claude Desktop、 移动端自定义连接器或 Claude Code /mcp 登录启用 OAuth。 OAuth 默认不启用；现有 stdio 和静态 JWT 配置仍可正常使用。

设置以下环境变量：

• TIME_OAUTH_ENABLED：默认为 false。
• TIME_OAUTH_ISSUER：必填的公开基础 URL，包含任何 nginx 前缀， 例如 https://karma.example/time。
• TIME_OAUTH_RESOURCE：必填的公开 MCP URL，例如 https://karma.example/time/mcp。 这是公开 URL；TIME_HTTP_PATH 是本地端点路径。
• TIME_OAUTH_LOGIN_USER：必填的登录用户名，由运维人员提供。
• TIME_OAUTH_LOGIN_PASSWORD_HASH：必填的 PBKDF2 哈希，由 mcp-time -hash-password 生成。
• TIME_OAUTH_ACCESS_TTL：默认为 1h。
• TIME_OAUTH_REFRESH_TTL：默认为 720h；必须大于访问令牌的有效期。

无需将密码放入命令参数即可生成密码哈希：

bin/mcp-time -hash-password

启用 OAuth 后，即使 TIME_AUTH_ENABLED=false，也会强制启用身份验证。 TIME_AUTH_SECRET_KEY 必须至少有 32 字节；此密钥用于签署 OAuth 访问令牌。 OAuth 设置无效时，服务将无法启动。 OAuth 布尔值和 TTL 为空时会使用默认值。 启用 CORS 时，TIME_HTTP_CORS_ORIGINS 中不允许使用 *。

OAuth 会在服务根路径挂载以下路由：

• /.well-known/oauth-protected-resource[/<resource path>]
• /.well-known/oauth-authorization-server[/<issuer path>]
• /authorize、/login、/token 和 /register

.well-known 路由会同时提供不带路径后缀和带路径后缀的发现文档。 /register 支持动态客户端注册；授权使用 PKCE S256。 启用 OAuth 后，缺失或无效的令牌会返回 HTTP 401，并附带 WWW-Authenticate: Bearer ... resource_metadata="..."。 此质询会让 claude.ai 启动 OAuth 流程。 有效的 OAuth 令牌若权限范围不正确，则会收到 HTTP 403 insufficient_scope。 关闭 OAuth 时，未经身份验证的工具调用仍会像以前一样返回 MCP 工具错误。 /health 仍无需身份验证。

使用公开 MCP URL 创建自定义连接器：

https://karma.example/time/mcp

已部署的实例使用 https://karma.rrj.pl/time/mcp。 Client ID 和 Client Secret 留空。 使用运维人员提供的用户名和密码登录。

对于 Claude Code，将以下内容添加到项目的 .mcp.json，不要添加请求头，然后运行 /mcp 完成 OAuth 登录：

{
  "mcpServers": {
    "time": {
      "type": "http",
      "url": "https://karma.example/time/mcp"
    }
  }
}

也可以使用 --generate-token 生成静态 bearer 令牌（参见 JWT 身份验证），并将其配置为请求头：

{
  "mcpServers": {
    "time": {
      "type": "http",
      "url": "https://karma.example/time/mcp",
      "headers": {
        "Authorization": "Bearer <operator-issued-token>"
      }
    }
  }
}

服务会将 OAuth 状态（已注册客户端、授权码和刷新令牌） 存储在内存中，因此服务重启后，连接器需要重新登录。 只要签名密钥、发行者和受众保持不变，静态 TIME_AUTH bearer 令牌在重启后仍可使用。

如果 nginx 会剥离 /time，还需将 /time/authorize、/time/login、/time/token 和 /time/register 代理到对应的服务根路径路由。 此外，还需转发主机根路径下的 /.well-known/* 请求，并保留派生路径， 例如 /.well-known/oauth-protected-resource/time/mcp。 服务根路径授权路由会以发行者前缀发布。

配置

变量	默认值	说明
TIME_DEFAULT_TIMEZONE	system timezone	所有工具的默认 IANA 时区
TIME_HTTP_ADDRESS	:8080	HTTP 监听地址
TIME_HTTP_PATH	/mcp	MCP 端点路径
TIME_HTTP_STATELESS	false	运行无会话的流式 HTTP 传输
TIME_HTTP_HEARTBEAT	30s	SSE 心跳间隔
TIME_HTTP_TIMEOUT	30s	读取、写入和关闭超时时间
TIME_HTTP_SESSION_IDLE_TTL	5m	空闲会话清理时间
TIME_HTTP_DISABLE_LOCALHOST_PROTECTION	true	禁用 DNS 重绑定检查（TimeMCP 运行在反向代理之后）
TIME_HTTP_CORS_ENABLED	false	启用 CORS 包装器
TIME_HTTP_CORS_ORIGINS	empty	以逗号分隔的来源允许列表
TIME_AUTH_ENABLED	false	要求 HTTP 工具调用携带 JWT
TIME_AUTH_SECRET_KEY	empty	HMAC 密钥，启用身份验证时必填
TIME_AUTH_ISSUER	TimeMCP	预期的 JWT 签发者
TIME_AUTH_AUDIENCE	TimeMCP-user	预期的 JWT 受众
TIME_OAUTH_ENABLED	false	启用 OAuth 连接器登录
TIME_OAUTH_ISSUER	empty	公共基础 URL，包括任何 nginx 前缀
TIME_OAUTH_RESOURCE	empty	公共 MCP URL
TIME_OAUTH_LOGIN_USER	empty	操作员提供的登录用户名
TIME_OAUTH_LOGIN_PASSWORD_HASH	empty	由 --hash-password 生成的哈希
TIME_OAUTH_ACCESS_TTL	1h	访问令牌有效期
TIME_OAUTH_REFRESH_TTL	720h	刷新令牌有效期；必须长于访问令牌有效期

开发

• 单元测试与代码放在一起（*_test.go）；使用 task test 或 go test -race ./... 运行。
• examples/test_client.go 检查旧版 2025-11-25 初始化握手，并仅通过 stdio 测试 MCP 2026-07-28（server/discover、tools/list、tools/call）及 _meta。 它会调用每个工具，并在发生协议或工具错误时失败。
• docs/ARCHITECTURE.md 说明各部分如何协同工作，docs/STATUS.md 记录 当前工具链和健康状况，docs/OPEN_ITEMS.md 列出已知待处理事项。
• 已被取代的文档和旧报告应放在 docs/retired/（受版本控制）。 新报告应放在 docs/reports/（被 git 忽略）。

支持的时区

任何 IANA 时区标识符均可使用，例如 Europe/Warsaw、 America/New_York、Asia/Tokyo、Australia/Sydney 或 Africa/Cairo。