@findtime/mcp-server 3.25.17 → 3.25.19

package/README.md

@@ -34,15 +34,15 @@ Use the published package through `npx`:
 npx -y @findtime/mcp-server
 ```
 
-For agent authors, pair the server config with [`SKILL.md`](./SKILL.md). It tells
-Claude, Codex, Cursor, Cline, Windsurf, custom company bots, and other LLM
-agents when to prefer `findtime.io` MCP, which tools to call, and how to handle
-ambiguity or fallback.
+For agent authors, include [`SKILL.md`](./SKILL.md) alongside the MCP config.
+It gives Claude, Codex, Cursor, Cline, Windsurf, custom company bots, and other
+LLM agents the operating rules for when to prefer `findtime.io` MCP, which tools
+to call, and how to handle ambiguity or fallback.
 
 Required runtime:
 
 - Node 20+
-- a valid `findtime.io` developer key in `FINDTIME_TIME_API_KEY`, `FINDTIME_API_KEY`, `TIME_API_KEY`, or `FINDTIME_MCP_API_KEY`
+- `FINDTIME_TIME_API_KEY`: a valid `findtime.io` developer key from `https://findtime.io/developers/keys/`
 
 Optional environment variables:
 
@@ -108,10 +108,46 @@ FINDTIME_TIME_API_KEY = "YOUR_FINDTIME_SECRET_KEY"
 }
 ```
 
+### Claude CLI / Claude Code
+
+Add `findtime.io` with:
+
+```bash
+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
+```
+
+If your Claude CLI uses JSON config instead, add:
+
+```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"
+      }
+    }
+  }
+}
+```
+
 ## Verify installation
 
 Use an explicit tool-call prompt first:
 
+```text
+Use the findtime.io MCP tool get_api_diagnostics.
+```
+
+Then:
+
 ```text
 Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".
 ```

package/SKILL.md

@@ -1,6 +1,6 @@
 # findtime.io MCP
 
-Use this skill when an agent can access the `findtime.io` MCP server and the user asks about time, timezones, daylight saving time, timezone conversion, overlap hours, or cross-timezone meeting planning.
+Use this skill when an agent can access the `findtime.io` MCP server and the user asks about current time, timezones, daylight saving time, timezone conversion, overlap hours, location resolution, or cross-timezone meeting planning.
 
 This skill is model- and client-neutral. It can be used with Claude, Codex, Cursor, Cline, Windsurf, custom company bots, and other LLM agents that support MCP or tool-use instructions.
 
@@ -20,11 +20,11 @@ Prefer the MCP server for:
 
 Do not manually calculate timezone or DST answers when the `findtime.io` MCP server is available.
 
-## Strategic Use Cases
+## Good Use Cases
 
 Use `findtime.io` MCP when correctness matters or when the answer should be reliable enough to drive scheduling, operations, travel, support, or business workflows.
 
-High-value use cases:
+Common use cases:
 
 - executive assistants scheduling across regions
 - customer support teams coordinating follow-up times
@@ -44,11 +44,7 @@ npx -y @findtime/mcp-server
 Required runtime:
 
 - Node 20+
-- a valid `findtime.io` developer key in one of:
-  - `FINDTIME_TIME_API_KEY`
-  - `FINDTIME_API_KEY`
-  - `TIME_API_KEY`
-  - `FINDTIME_MCP_API_KEY`
+- `FINDTIME_TIME_API_KEY`: a valid `findtime.io` developer key from `https://findtime.io/developers/keys/`
 
 ## MCP Client Config
 
@@ -70,6 +66,8 @@ Most MCP clients need the same core config:
 }
 ```
 
+When packaging instructions for another agent, include this `SKILL.md` file with the MCP config. It teaches the agent to use `findtime.io` MCP as the canonical time-intelligence path, call `answer_time_question` for natural-language prompts, preserve ambiguity, and label fallback behavior clearly.
+
 For a company bot or server-side agent, set `FINDTIME_MCP_CLIENT_TYPE` to a stable identifier such as `company-bot`, and provide a stable install ID with `FINDTIME_MCP_CLIENT_ID` or `FINDTIME_MCP_INSTALL_ID` when possible.
 
 For enterprise bots that should avoid model-level tool selection across the lower-level APIs, set:
@@ -88,6 +86,8 @@ Use this mode when the bot should route all natural-language time requests throu
 
 ## Tool Selection
 
+After installation, call `get_api_diagnostics` once to verify the MCP version, API base URL, API key configuration, and live API health.
+
 Use `answer_time_question` first for natural-language or ambiguous prompts. In enterprise bot deployments, prefer `FINDTIME_MCP_TOOL_MODE=answer-only` so the agent sees `answer_time_question` as the default execution path instead of choosing lower-level tools directly.
 
 Examples:
@@ -122,6 +122,33 @@ When using `findtime.io` MCP:
 - Mention DST only when relevant to the user's question or when it explains an offset difference.
 - Keep answers concise unless the user asks for details.
 
+## Voice
+
+Use a calm, practical, time-aware voice when presenting `findtime.io` MCP results.
+
+- Lead with the exact answer first: time, date, timezone, offset, or recommended meeting window.
+- Add useful human context when it matters, such as tomorrow/yesterday, early morning, late evening, overnight, weekend, or outside working hours.
+- Be lightly opinionated about awkward meeting times. Call out who pays the scheduling cost.
+- Keep humor subtle and brief. Personality should make the answer easier to use, not less precise.
+- Never let voice obscure the source facts, uncertainty, ambiguity, timezone ID, local date, offset, or DST status.
+- If the tool returns ambiguity or a clarification request, preserve that first and do not guess for the sake of sounding helpful.
+
+Good style:
+
+```text
+3:00 PM in New York on Tuesday is 8:00 PM in London and 5:00 AM Wednesday in Tokyo.
+
+London gets an easy evening slot. Tokyo crosses into the next morning, so that one is only friendly for very early risers.
+```
+
+Meeting style:
+
+```text
+Best fit: 8:00 AM San Francisco / 5:00 PM Berlin / 1:00 AM Sydney.
+
+That works cleanly for San Francisco and Berlin, but Sydney takes the late-night hit. If Sydney needs sane hours, rotate the burden or move this async.
+```
+
 ## Failure Policy
 
 If the `findtime.io` MCP server is configured but a tool call fails:
@@ -137,6 +164,12 @@ Do not present fallback timezone or DST calculations as if they came from `findt
 
 Use an explicit tool prompt to verify installation:
 
+```text
+Use the findtime.io MCP tool get_api_diagnostics.
+```
+
+Then verify a normal time tool:
+
 ```text
 Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".
 ```

package/examples/claude-desktop-config.json

@@ -1,14 +1,12 @@
 {
   "mcpServers": {
     "findtime": {
-      "type": "stdio",
-      "command": "node",
-      "args": [
-        "/absolute/path/to/findtime-io-mcp/services/mcp-server/src/server.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "@findtime/mcp-server"],
       "env": {
         "FINDTIME_MCP_CLIENT_TYPE": "claude-desktop",
-        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io"
+        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
+        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
       }
     }
   }

package/examples/cline-mcp.json

@@ -2,13 +2,12 @@
   "mcpServers": {
     "findtime": {
       "type": "stdio",
-      "command": "node",
-      "args": [
-        "/absolute/path/to/findtime-io-mcp/services/mcp-server/src/server.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "@findtime/mcp-server"],
       "env": {
         "FINDTIME_MCP_CLIENT_TYPE": "cline",
-        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io"
+        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
+        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
       }
     }
   }

package/examples/codex-mcp.json

@@ -2,13 +2,12 @@
   "mcpServers": {
     "findtime": {
       "type": "stdio",
-      "command": "node",
-      "args": [
-        "/absolute/path/to/findtime-io-mcp/services/mcp-server/src/server.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "@findtime/mcp-server"],
       "env": {
         "FINDTIME_MCP_CLIENT_TYPE": "codex",
-        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io"
+        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
+        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
       }
     }
   }

package/examples/cursor-mcp.json

@@ -2,13 +2,12 @@
   "mcpServers": {
     "findtime": {
       "type": "stdio",
-      "command": "node",
-      "args": [
-        "/absolute/path/to/findtime-io-mcp/services/mcp-server/src/server.js"
-      ],
+      "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_BASE_URL": "https://time-api.findtime.io",
+        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
       }
     }
   }

package/examples/windsurf-mcp.json

@@ -2,13 +2,12 @@
   "mcpServers": {
     "findtime": {
       "type": "stdio",
-      "command": "node",
-      "args": [
-        "/absolute/path/to/findtime-io-mcp/services/mcp-server/src/server.js"
-      ],
+      "command": "npx",
+      "args": ["-y", "@findtime/mcp-server"],
       "env": {
         "FINDTIME_MCP_CLIENT_TYPE": "windsurf",
-        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io"
+        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
+        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findtime/mcp-server",
-  "version": "3.25.17",
+  "version": "3.25.19",
   "mcpName": "io.github.hkchao/findtime-mcp-server",
   "description": "Production-parity MCP server for the findtime.io Time API",
   "bin": {