findtime.io MCP Server

@findtime/mcp-server

@findtime/mcp-server 是一个精简的 stdio MCP 封装，调用生产环境中的 findtime.io Time API，地址为 https://time-api.findtime.io。

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

发布渠道：

• npm：@findtime/mcp-server
• GitHub：https://github.com/hkchao/findtime-mcp-server
• 官方 MCP Registry：https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server
• MCP Registry 名称：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 行为，并在问题确实存在歧义时返回结构化的歧义说明或澄清请求。

在 MCP 客户端中安装

通过 npx 使用已发布的软件包：

npx -y @findtime/mcp-server

对于 Agent 作者，请将 SKILL.md 与 MCP 配置放在一起。 它为 Claude、Codex、Cursor、Cline、Windsurf、自定义企业机器人和其他 大模型 Agent 提供操作规则，说明何时优先使用 findtime.io MCP、应调用哪些工具， 以及如何处理歧义或回退。

运行时要求：

• Node 20+
• FINDTIME_TIME_API_KEY：有效的 findtime.io 开发者密钥，获取地址为 https://findtime.io/developers/keys/

可选环境变量：

• 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：覆盖默认遥测端点。

每次调用的最终用户归属

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

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 或其他个人身份信息。避免在此字段中包含个人身份信息是宿主应用的责任。

服务会以防御性方式验证 _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 软件包的实现源，而不是规范的公开发布源。

发布者与工具安全

npm 软件包 @findtime/mcp-server 和 GitHub 仓库 hkchao/findtime-mcp-server 是 findtime.io 的 MCP 分发渠道。 产品文档：https://findtime.io/developers/mcp/

所有工具都会查询时间信息、推荐会议时间，或返回帮助和诊断信息；它们不会预订会议或修改日历。它们声明了 readOnlyHint: true、destructiveHint: false、idempotentHint: true 和 openWorldHint: true。只读描述的是面向用户的操作，并不代表没有网络流量：API 请求、诊断信息和可选的使用情况遥测会联系外部服务。重复查询当前时间可能会返回新的时间；幂等表示不会产生额外的领域数据变更。

API 密钥环境变量是同一个密钥的不同配置名称，并非四个独立凭据。

隐私、身份验证和服务限制

隐私政策：https://findtime.io/privacy/

stdio 进程在本地运行。时间工具会将查询参数发送到配置的 Time API（默认为 https://time-api.findtime.io）。所选 API 密钥会通过 Authorization: Bearer 标头发送到该 API，而不会发送到 npm 或遥测服务。仅配置你信任的 API 主机。四个 API 密钥环境变量名称互为别名，按以下顺序使用第一个非空值：FINDTIME_API_KEY、TIME_API_KEY、FINDTIME_MCP_API_KEY、FINDTIME_TIME_API_KEY。

托管的 Time API 负责验证 API 密钥、配置每个密钥的速率限制和配额。此包装器会将上游故障（包括 HTTP 429）作为 MCP 工具错误转发。它不会开放公共 HTTP 监听器，也不会另行实现本地速率限制。帮助信息在本地提供；诊断功能也会读取 npm 版本元数据。

可选的使用情况遥测默认发送到 https://slack.findtime.io/telemetry/usage。此包装器会发送工具名称、结果、查询文本长度、持久化的安装/客户端标识符、版本、操作系统、区域设置、时区和延迟。此遥测事件不包含原始查询文本、API 密钥或每次调用的 _endUserId。设置 FINDTIME_MCP_INSTRUMENTATION_ENABLED=false 可将其禁用。生成的安装标识符存储在用户的状态目录中。主机提供的归属标识符会按上述说明发送到 Time API；请使用不透明且不含个人身份信息的值。

许可证

本仓库中的 MCP 包装器和文档采用 MIT License 授权。

此许可证仅适用于本仓库。它不授予使用托管的 findtime.io Time API、其后端实现或数据，以及更广泛的 findtime.io 应用程序的权利。使用托管服务仍须遵守其适用条款和 API 访问要求。