@findtime/mcp-server 3.25.18 → 3.25.20

package/README.md

@@ -49,9 +49,12 @@ Optional environment variables:
 - `FINDTIME_TIME_API_BASE_URL`
 - `TIME_API_BASE_URL`
 - `TIME_API_TIMEOUT_MS`
+- `FINDTIME_BINDING_TYPE` for optional install/workspace binding context. Supported values: `slack_team`, `workspace_id`, `install_id`.
+- `FINDTIME_BINDING_VALUE` for the install/workspace identifier that matches the selected binding type.
+- `FINDTIME_BINDING_HEADER` to override the header name directly for custom enterprise environments.
+- `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.
 - `FINDTIME_MCP_CLIENT_TYPE`
 - `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.
-- `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.
 - `FINDTIME_MCP_INSTRUMENTATION_ENABLED=false` to opt out of anonymous usage telemetry.
 - `FINDTIME_MCP_USAGE_TELEMETRY_URL` to override the default telemetry endpoint.
 
@@ -86,6 +89,9 @@ enabled = true
 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
@@ -99,13 +105,13 @@ FINDTIME_TIME_API_KEY = "YOUR_FINDTIME_SECRET_KEY"
     "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"
+        "env": {
+          "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
+          "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
+        }
       }
     }
   }
-}
 ```
 
 ### Claude CLI / Claude Code
@@ -138,6 +144,20 @@ If your Claude CLI uses JSON config instead, add:
 }
 ```
 
+For enterprise installs, the minimum credential is always the API key. If the install environment has a stable workspace or installation identifier, optionally add:
+
+```text
+FINDTIME_BINDING_TYPE=workspace_id
+FINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID
+```
+
+For Slack-specific installs:
+
+```text
+FINDTIME_BINDING_TYPE=slack_team
+FINDTIME_BINDING_VALUE=T01ABC123
+```
+
 ## Verify installation
 
 Use an explicit tool-call prompt first:

package/SKILL.md

@@ -70,6 +70,50 @@ When packaging instructions for another agent, include this `SKILL.md` file with
 
 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 installs, always try to provide a stable caller identifier.
+
+How to pass it:
+
+- if you control the MCP wrapper config, set `FINDTIME_MCP_INSTALL_ID` or `FINDTIME_MCP_CLIENT_ID`; the wrapper forwards that value to `time-api.findtime.io` as `X-Findtime-User-ID`
+- if you control direct HTTP calls to `time-api.findtime.io`, send the same value explicitly in the `X-Findtime-User-ID` header
+- if you also have a stable thread or conversation identifier, send it as `X-Findtime-Conversation-ID`
+
+Use this for enterprise usage attribution.
+
+Example MCP wrapper config:
+
+```text
+FINDTIME_TIME_API_KEY=your_enterprise_api_key
+FINDTIME_MCP_CLIENT_TYPE=enterprise-bot
+FINDTIME_MCP_INSTALL_ID=install_12345
+```
+
+With that config, the MCP wrapper calls `time-api.findtime.io` using:
+
+```text
+X-API-Key: your_enterprise_api_key
+X-Findtime-User-ID: install_12345
+```
+
+Direct HTTP example when you are not using the MCP wrapper:
+
+```text
+GET /api/time/current?query=Tokyo
+Authorization: Bearer <your_enterprise_api_key>
+X-Findtime-User-ID: install_12345
+X-Findtime-Conversation-ID: thread_abc
+```
+
+Use the most stable first-party identifier you have:
+
+- preferred: a true per-user ID from your platform or agent runtime
+- next best: a stable conversation or thread ID when the same user may appear across multiple sessions
+- next best: your platform's install ID or deployment ID
+- fallback: your platform's stable workspace or tenant ID
+- last resort: a stable agent client ID
+
+If no true per-user ID is available, it is acceptable for `X-Findtime-User-ID` to carry an install ID or other stable caller identity instead of a human end-user ID.
+
 For enterprise bots that should avoid model-level tool selection across the lower-level APIs, set:
 
 ```text
@@ -122,6 +166,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:

package/package.json

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

package/server.js

@@ -48,6 +48,18 @@ const DEFAULT_API_KEY = firstNonEmpty(
   process.env.FINDTIME_MCP_API_KEY,
   process.env.FINDTIME_TIME_API_KEY
 );
+const DEFAULT_BINDING_TYPE = firstNonEmpty(
+  process.env.FINDTIME_BINDING_TYPE,
+  process.env.FINDTIME_MCP_BINDING_TYPE
+) || '';
+const DEFAULT_BINDING_VALUE = firstNonEmpty(
+  process.env.FINDTIME_BINDING_VALUE,
+  process.env.FINDTIME_MCP_BINDING_VALUE
+) || '';
+const DEFAULT_BINDING_HEADER = firstNonEmpty(
+  process.env.FINDTIME_BINDING_HEADER,
+  process.env.FINDTIME_MCP_BINDING_HEADER
+) || '';
 const TIMEZONE_HELPERS_PATH = path.join(REPO_ROOT, 'slack-bot', 'timezone-helpers.js');
 const ANSWER_ONLY_TOOL_NAMES = new Set(['answer_time_question', 'get_findtime_help', 'get_api_diagnostics']);
 
@@ -1048,6 +1060,9 @@ function createFindtimeMcpServer(options = {}) {
   const apiBaseUrl = options.apiBaseUrl || DEFAULT_API_BASE_URL;
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
   const apiKey = options.apiKey === undefined ? DEFAULT_API_KEY : options.apiKey;
+  const bindingType = options.bindingType === undefined ? DEFAULT_BINDING_TYPE : options.bindingType;
+  const bindingValue = options.bindingValue === undefined ? DEFAULT_BINDING_VALUE : options.bindingValue;
+  const bindingHeader = options.bindingHeader === undefined ? DEFAULT_BINDING_HEADER : options.bindingHeader;
   const serverName = options.serverName || 'findtime';
   const serverTitle = options.serverTitle || 'findtime Time API MCP';
   const resolveLocationImpl = options.resolveLocationImpl === undefined
@@ -1079,6 +1094,13 @@ function createFindtimeMcpServer(options = {}) {
       headers.Authorization = `Bearer ${apiKey.trim()}`;
     }
 
+    const resolvedBindingHeader = typeof bindingHeader === 'string' && bindingHeader.trim()
+      ? bindingHeader.trim()
+      : normalizeBindingHeader(bindingType);
+    if (resolvedBindingHeader && typeof bindingValue === 'string' && bindingValue.trim()) {
+      headers[resolvedBindingHeader] = bindingValue.trim();
+    }
+
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
 
@@ -1403,6 +1425,14 @@ function createFindtimeMcpServer(options = {}) {
   };
 }
 
+function normalizeBindingHeader(bindingType) {
+  const normalized = String(bindingType || '').trim().toLowerCase();
+  if (normalized === 'slack_team') return 'X-Slack-Team-ID';
+  if (normalized === 'workspace_id') return 'X-Findtime-Workspace-ID';
+  if (normalized === 'install_id') return 'X-Findtime-Install-ID';
+  return '';
+}
+
 function tryParseJson(value) {
   if (typeof value !== 'string' || !value.trim()) {
     return undefined;