@findtime/mcp-server

@findtime/mcp-server 是生产环境 findtime.io Time API（位于 https://time-api.findtime.io）之上的一个轻量级 stdio MCP 包装器。

该包有意代理生产 API，而不是在本地重新实现时间逻辑。当前时间、DST、转换、重叠、会议搜索和位置解析应与实时 API 保持一致。

已发布的入口：

• npm: @findtime/mcp-server

• GitHub: https://github.com/hkchao/findtime-mcp-server

• Official MCP Registry: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

• MCP Registry name: io.github.hkchao/findtime-mcp-server

工具接口

• answer_time_question

• get_findtime_help

• time_snapshot

• get_current_time

• get_dst_schedule

• convert_time

• get_overlap_hours

• find_meeting_time

• search_timezones

• get_location_by_id

对于杂乱的自然语言提示，如“3pm PST to London”、“what is the IANA timezone for San Francisco?”、“working hours overlap for SF, Berlin, and Tokyo”或“what does CST mean?”，请优先使用 answer_time_question。该工具通过 findtime.io 的领域逻辑对提示进行分类，分派到确定性的 Time API 行为，并在世界确实存在歧义时返回结构化的歧义或澄清信息。

Related MCP server: Time MCP Server

在 MCP 客户端中安装

通过 npx 使用已发布的包：

npx -y @findtime/mcp-server

对于 agent 作者，请在 MCP 配置旁边包含 SKILL.md。它为 Claude、Codex、Cursor、Cline、Windsurf、自定义公司机器人以及其他 LLM agent 提供了操作规则，说明何时优先使用 findtime.io MCP、调用哪些工具，以及如何处理歧义或回退。

所需运行时：

• Node 20+

• FINDTIME_TIME_API_KEY：来自 https://findtime.io/developers/keys/ 的有效 findtime.io 开发者密钥

可选环境变量：

• FINDTIME_TIME_API_BASE_URL

• TIME_API_BASE_URL

• TIME_API_TIMEOUT_MS

• FINDTIME_BINDING_TYPE：用于可选的安装/工作区绑定上下文。支持的值：slack_team、workspace_id、install_id。

• FINDTIME_BINDING_VALUE：用于与所选绑定类型匹配的安装/工作区标识符。

• FINDTIME_BINDING_HEADER：用于直接为自定义企业环境覆盖标头名称。

• FINDTIME_MCP_CLIENT_ID 或 FINDTIME_MCP_INSTALL_ID：用于提供稳定的客户端标识符。如果省略，服务器会在用户的状态目录下本地创建一个。如果存在，MCP 包装器会将其作为 X-Findtime-User-ID 转发给 time-api，用于企业使用归属。

• FINDTIME_MCP_CLIENT_TYPE

• FINDTIME_MCP_TOOL_MODE=answer-only：仅公开 answer_time_question、get_findtime_help 和 get_api_diagnostics，适用于应通过 answer API 路由每个自然语言请求的企业机器人。

• FINDTIME_MCP_INSTRUMENTATION_ENABLED=false：用于选择退出匿名使用遥测。

• FINDTIME_MCP_USAGE_TELEMETRY_URL：用于覆盖默认的遥测端点。

每次调用的最终用户归属

多用户 MCP 主机（如 Slack、Discord 和 Teams 机器人）可以运行一个长期存在的 @findtime/mcp-server 子进程，同时仍将每次 Time API 调用归属于触发该调用的最终用户。在 MCP 工具调用的 arguments 对象中添加一个可选的 _endUserId 字段。服务器会从工具参数中剥离 _endUserId，并仅将其作为上游的 X-Findtime-End-User-ID HTTP 标头转发。

await client.callTool({
  name: "get_current_time",
  arguments: {
    city: "Tokyo",
    _endUserId: "a3f2c1d4e5b6c7d8"
  }
});

该字段是可选的，并且向后兼容。如果 _endUserId 缺失、为 null 或空字符串，则省略该标头，归属将回退到安装级别的 FINDTIME_MCP_CLIENT_ID 或 FINDTIME_MCP_INSTALL_ID 行为。

隐私约定：_endUserId 必须是 MCP 主机提供的不透明令牌，通常是平台用户 ID 的 SHA-256 哈希，截断为 16-32 个十六进制字符。请勿发送原始电子邮件地址、姓名、Slack/Discord/Teams ID 或其他 PII。避免此字段中出现 PII 是主机应用程序的责任。

服务器会防御性地验证 _endUserId：它必须是字符串，最多 256 个字符，并且不得包含 CR、LF 或其他控制字符。服务器绝不会记录原始值。

Cursor

{
  "mcpServers": {
    "findtime": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_MCP_CLIENT_TYPE": "cursor",
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
      }
    }
  }
}

Codex

[mcp_servers.findtime]
command = "npx"
args = ["-y", "@findtime/mcp-server"]
enabled = true

[mcp_servers.findtime.env]
FINDTIME_MCP_CLIENT_TYPE = "codex"
FINDTIME_TIME_API_BASE_URL = "https://time-api.findtime.io"
FINDTIME_TIME_API_KEY = "YOUR_FINDTIME_SECRET_KEY"
# Optional enterprise install binding:
# FINDTIME_BINDING_TYPE = "workspace_id"
# FINDTIME_BINDING_VALUE = "YOUR_WORKSPACE_ID"

Claude Desktop

{
  "preferences": {
    "...": "keep your existing preferences here"
  },
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
        "env": {
          "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
          "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
        }
      }
    }
  }

Claude CLI / Claude Code

使用以下命令添加 findtime.io：

claude mcp add --transport stdio \
  --env FINDTIME_TIME_API_BASE_URL=https://time-api.findtime.io \
  --env FINDTIME_TIME_API_KEY=YOUR_FINDTIME_SECRET_KEY \
  --env FINDTIME_MCP_CLIENT_TYPE=claude-cli \
  findtime -- npx -y @findtime/mcp-server

如果您的 Claude CLI 改用 JSON 配置，请添加：

{
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY",
        "FINDTIME_MCP_CLIENT_TYPE": "claude-cli"
      }
    }
  }
}

对于企业安装，最低凭据始终是 API 密钥。如果安装环境具有稳定的工作区或安装标识符，可以选择添加：

FINDTIME_BINDING_TYPE=workspace_id
FINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID

对于特定于 Slack 的安装：

FINDTIME_BINDING_TYPE=slack_team
FINDTIME_BINDING_VALUE=T01ABC123

验证安装

首先使用显式的工具调用提示：

Use the findtime.io MCP tool get_api_diagnostics.

然后：

Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".

成功后，切换回正常的自然语言提示：

Best meeting time between New York, Sydney, and Mumbai?

本地开发

直接运行工作区版本：

npm run mcp:start

服务器会尝试从以下位置加载 .env.development.local、.env.development、.env.local 和 .env：

• 当前工作目录

• services/mcp-server

• 仓库根目录

测试

协议和传输测试：

npm run test:mcp-server

实时生产一致性冒烟测试：

npm run test:mcp-server:smoke

冒烟测试套件检查：

• search_timezones

• answer_time_question

• get_current_time

• get_dst_schedule

• convert_time

• get_overlap_hours

• find_meeting_time

• get_location_by_id

维护者发布流程

此包的规范公共源现在位于：

• GitHub: https://github.com/hkchao/findtime-mcp-server

• npm: @findtime/mcp-server

• Official MCP Registry: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

发布和版本更新应来自该公共仓库，而不是此私有应用仓库。

公共仓库中的标准发布流程：

npm test
npm pack --dry-run
npm publish --access public

此仓库中相应的本地验证检查是：

npm run test:mcp-server
npm run mcp:pack

请将此仓库视为最初生成 MCP 包的实现源，而不是规范的公共发布源。