{
  "markdown": "# @findtime/mcp-server\n\n`@findtime/mcp-server` is a thin stdio MCP wrapper over the production findtime.io Time API at `https://time-api.findtime.io`.\n\nThe package intentionally proxies the production API instead of re-implementing time logic locally. Current time, DST, conversion, overlap, meeting search, and location resolution should stay aligned with the live API.\n\nPublished surfaces:\n\n- npm: `@findtime/mcp-server`\n- GitHub: `https://github.com/hkchao/findtime-mcp-server`\n- Official MCP Registry: `https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server`\n- MCP Registry name: `io.github.hkchao/findtime-mcp-server`\n\n## Tool surface\n\n- `answer_time_question`\n- `get_findtime_help`\n- `time_snapshot`\n- `get_current_time`\n- `get_dst_schedule`\n- `convert_time`\n- `get_overlap_hours`\n- `find_meeting_time`\n- `search_timezones`\n- `get_location_by_id`\n\nPrefer `answer_time_question` for messy natural-language prompts such as \"3pm PST to London\", \"what is the IANA timezone for San Francisco?\", \"working hours overlap for SF, Berlin, and Tokyo\", or \"what does CST mean?\". The tool classifies the prompt through findtime.io's domain logic, dispatches to deterministic Time API behavior, and returns structured ambiguity or clarification when the world is genuinely ambiguous.\n\n## Install in MCP clients\n\nUse the published package through `npx`:\n\n```bash\nnpx -y @findtime/mcp-server\n```\n\nFor agent authors, include [`SKILL.md`](./SKILL.md) alongside the MCP config.\nIt gives Claude, Codex, Cursor, Cline, Windsurf, custom company bots, and other\nLLM agents the operating rules for when to prefer `findtime.io` MCP, which tools\nto call, and how to handle ambiguity or fallback.\n\nRequired runtime:\n\n- Node 20+\n- `FINDTIME_TIME_API_KEY`: a valid `findtime.io` developer key from `https://findtime.io/developers/keys/`\n\nOptional environment variables:\n\n- `FINDTIME_TIME_API_BASE_URL`\n- `TIME_API_BASE_URL`\n- `TIME_API_TIMEOUT_MS`\n- `FINDTIME_BINDING_TYPE` for optional install/workspace binding context. Supported values: `slack_team`, `workspace_id`, `install_id`.\n- `FINDTIME_BINDING_VALUE` for the install/workspace identifier that matches the selected binding type.\n- `FINDTIME_BINDING_HEADER` to override the header name directly for custom enterprise environments.\n- `FINDTIME_MCP_CLIENT_ID` or `FINDTIME_MCP_INSTALL_ID` to provide a stable client identifier. If omitted, the server creates one locally under the user's state directory. When present, the MCP wrapper forwards it to `time-api` as `X-Findtime-User-ID` for enterprise usage attribution.\n- `FINDTIME_MCP_CLIENT_TYPE`\n- `FINDTIME_MCP_TOOL_MODE=answer-only` to expose only `answer_time_question`, `get_findtime_help`, and `get_api_diagnostics` for enterprise bots that should route every natural-language request through the answer API.\n- `FINDTIME_MCP_INSTRUMENTATION_ENABLED=false` to opt out of anonymous usage telemetry.\n- `FINDTIME_MCP_USAGE_TELEMETRY_URL` to override the default telemetry endpoint.\n\n## Per-call end-user attribution\n\nMulti-user MCP hosts such as Slack, Discord, and Teams bots can run one long-lived `@findtime/mcp-server` subprocess while still attributing each Time API call to the end-user who triggered it. Add an optional `_endUserId` field inside the MCP tool call `arguments` object. The server strips `_endUserId` from the tool parameters and forwards it only as the upstream `X-Findtime-End-User-ID` HTTP header.\n\n```js\nawait client.callTool({\n  name: \"get_current_time\",\n  arguments: {\n    city: \"Tokyo\",\n    _endUserId: \"a3f2c1d4e5b6c7d8\"\n  }\n});\n```\n\nThe field is optional and backward-compatible. If `_endUserId` is missing, `null`, or an empty string, the header is omitted and attribution falls back to the install-level `FINDTIME_MCP_CLIENT_ID` or `FINDTIME_MCP_INSTALL_ID` behavior.\n\nPrivacy contract: `_endUserId` must be an opaque token supplied by the MCP host, typically a SHA-256 hash of the platform user ID truncated to 16-32 hex characters. Do not send raw email addresses, names, Slack/Discord/Teams IDs, or other PII. Avoiding PII in this field is the host application's responsibility.\n\nThe server validates `_endUserId` defensively: it must be a string, at most 256 characters, and must not contain CR, LF, or other control characters. The raw value is never logged by the server.\n\n### Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"findtime\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@findtime/mcp-server\"],\n      \"env\": {\n        \"FINDTIME_MCP_CLIENT_TYPE\": \"cursor\",\n        \"FINDTIME_TIME_API_BASE_URL\": \"https://time-api.findtime.io\",\n        \"FINDTIME_TIME_API_KEY\": \"YOUR_FINDTIME_SECRET_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Codex\n\n```toml\n[mcp_servers.findtime]\ncommand = \"npx\"\nargs = [\"-y\", \"@findtime/mcp-server\"]\nenabled = true\n\n[mcp_servers.findtime.env]\nFINDTIME_MCP_CLIENT_TYPE = \"codex\"\nFINDTIME_TIME_API_BASE_URL = \"https://time-api.findtime.io\"\nFINDTIME_TIME_API_KEY = \"YOUR_FINDTIME_SECRET_KEY\"\n# Optional enterprise install binding:\n# FINDTIME_BINDING_TYPE = \"workspace_id\"\n# FINDTIME_BINDING_VALUE = \"YOUR_WORKSPACE_ID\"\n```\n\n### Claude Desktop\n\n```json\n{\n  \"preferences\": {\n    \"...\": \"keep your existing preferences here\"\n  },\n  \"mcpServers\": {\n    \"findtime\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@findtime/mcp-server\"],\n        \"env\": {\n          \"FINDTIME_TIME_API_BASE_URL\": \"https://time-api.findtime.io\",\n          \"FINDTIME_TIME_API_KEY\": \"YOUR_FINDTIME_SECRET_KEY\"\n        }\n      }\n    }\n  }\n```\n\n### Claude CLI / Claude Code\n\nAdd `findtime.io` with:\n\n```bash\nclaude mcp add --transport stdio \\\n  --env FINDTIME_TIME_API_BASE_URL=https://time-api.findtime.io \\\n  --env FINDTIME_TIME_API_KEY=YOUR_FINDTIME_SECRET_KEY \\\n  --env FINDTIME_MCP_CLIENT_TYPE=claude-cli \\\n  findtime -- npx -y @findtime/mcp-server\n```\n\nIf your Claude CLI uses JSON config instead, add:\n\n```json\n{\n  \"mcpServers\": {\n    \"findtime\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@findtime/mcp-server\"],\n      \"env\": {\n        \"FINDTIME_TIME_API_BASE_URL\": \"https://time-api.findtime.io\",\n        \"FINDTIME_TIME_API_KEY\": \"YOUR_FINDTIME_SECRET_KEY\",\n        \"FINDTIME_MCP_CLIENT_TYPE\": \"claude-cli\"\n      }\n    }\n  }\n}\n```\n\nFor enterprise installs, the minimum credential is always the API key. If the install environment has a stable workspace or installation identifier, optionally add:\n\n```text\nFINDTIME_BINDING_TYPE=workspace_id\nFINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID\n```\n\nFor Slack-specific installs:\n\n```text\nFINDTIME_BINDING_TYPE=slack_team\nFINDTIME_BINDING_VALUE=T01ABC123\n```\n\n## Verify installation\n\nUse an explicit tool-call prompt first:\n\n```text\nUse the findtime.io MCP tool get_api_diagnostics.\n```\n\nThen:\n\n```text\nUse the findtime.io MCP tool get_current_time for city \"Tokyo\" with countryCode \"JP\".\n```\n\nAfter that succeeds, switch back to normal natural-language prompts:\n\n```text\nBest meeting time between New York, Sydney, and Mumbai?\n```\n\n## Local development\n\nRun the workspace version directly:\n\n```bash\nnpm run mcp:start\n```\n\nThe server attempts to load `.env.development.local`, `.env.development`, `.env.local`, and `.env` from:\n\n- the current working directory\n- `services/mcp-server`\n- the repo root\n\n## Tests\n\nProtocol and transport tests:\n\n```bash\nnpm run test:mcp-server\n```\n\nLive production-parity smoke tests:\n\n```bash\nnpm run test:mcp-server:smoke\n```\n\nThe smoke suite checks:\n\n- `search_timezones`\n- `answer_time_question`\n- `get_current_time`\n- `get_dst_schedule`\n- `convert_time`\n- `get_overlap_hours`\n- `find_meeting_time`\n- `get_location_by_id`\n\n## Maintainer release flow\n\nThe canonical public source for this package now lives in:\n\n- GitHub: `https://github.com/hkchao/findtime-mcp-server`\n- npm: `@findtime/mcp-server`\n- Official MCP Registry: `https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server`\n\nPublish and version updates should happen from that public repo, not from this private app repo.\n\nStandard publish flow in the public repo:\n\n```bash\nnpm test\nnpm pack --dry-run\nnpm publish --access public\n```\n\nThe equivalent local verification checks in this repo are:\n\n```bash\nnpm run test:mcp-server\nnpm run mcp:pack\n```\n\nTreat this repo as the implementation source that originally produced the MCP package, not as the canonical public release source.\n",
  "bytes": 8307,
  "sha": "fbc78440cff2804c68a05885ce17775860219a19709401784f063a3437b7715c",
  "repo_slug": "hkchao/findtime-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hkchao_findtime_mcp_server_6706007a/readme"
}