@findtime/mcp-server 3.25.14 → 3.25.16

package/README.md

@@ -14,6 +14,7 @@ Published surfaces:
 ## Tool surface
 
 - `answer_time_question`
+- `get_findtime_help`
 - `time_snapshot`
 - `get_current_time`
 - `get_dst_schedule`
@@ -49,7 +50,7 @@ Optional environment variables:
 - `TIME_API_BASE_URL`
 - `TIME_API_TIMEOUT_MS`
 - `FINDTIME_MCP_CLIENT_TYPE`
-- `FINDTIME_MCP_TOOL_MODE=answer-only` to expose only `answer_time_question` and `get_api_diagnostics` for enterprise bots that should route every natural-language request through the answer API.
+- `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.
@@ -123,15 +124,16 @@ Best meeting time between New York, Sydney, and Mumbai?
 
 ## Local development
 
-Run the server directly from the public repo root:
+Run the workspace version directly:
 
 ```bash
-npm start
+npm run mcp:start
 ```
 
 The server attempts to load `.env.development.local`, `.env.development`, `.env.local`, and `.env` from:
 
 - the current working directory
+- `services/mcp-server`
 - the repo root
 
 ## Tests
@@ -139,13 +141,13 @@ The server attempts to load `.env.development.local`, `.env.development`, `.env.
 Protocol and transport tests:
 
 ```bash
-npm test
+npm run test:mcp-server
 ```
 
 Live production-parity smoke tests:
 
 ```bash
-npm run test:smoke
+npm run test:mcp-server:smoke
 ```
 
 The smoke suite checks:
@@ -167,7 +169,7 @@ The canonical public source for this package now lives in:
 - npm: `@findtime/mcp-server`
 - Official MCP Registry: `https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server`
 
-Publish and version updates should happen from this public repo.
+Publish and version updates should happen from that public repo, not from this private app repo.
 
 Standard publish flow in the public repo:
 
@@ -177,4 +179,11 @@ npm pack --dry-run
 npm publish --access public
 ```
 
-Use the workflow in `.github/workflows/publish.yml` for repo-backed publishes.
+The equivalent local verification checks in this repo are:
+
+```bash
+npm run test:mcp-server
+npm run mcp:pack
+```
+
+Treat this repo as the implementation source that originally produced the MCP package, not as the canonical public release source.

package/SKILL.md

@@ -81,6 +81,7 @@ FINDTIME_MCP_TOOL_MODE=answer-only
 In answer-only mode, the MCP server exposes only:
 
 - `answer_time_question`
+- `get_findtime_help`
 - `get_api_diagnostics`
 
 Use this mode when the bot should route all natural-language time requests through the answer API first.
@@ -99,6 +100,7 @@ Examples:
 
 Use specific tools when the agent has already parsed the task into structured inputs:
 
+- `get_findtime_help`: examples of supported intents, answer API usage, ambiguity handling, and enterprise deployment guidance
 - `get_current_time`: current local time for a known city, country, timezone, or location
 - `convert_time`: convert a known date/time from one place or timezone to another
 - `get_dst_schedule`: DST status and transition dates

package/examples/claude-desktop-config.json

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

package/examples/cline-mcp.json

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

package/examples/codex-mcp.json

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

package/examples/cursor-mcp.json

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

package/examples/windsurf-mcp.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findtime/mcp-server",
-  "version": "3.25.14",
+  "version": "3.25.16",
   "mcpName": "io.github.hkchao/findtime-mcp-server",
   "description": "Production-parity MCP server for the findtime.io Time API",
   "bin": {
@@ -31,14 +31,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hkchao/findtime-mcp-server.git"
-  },
   "homepage": "https://findtime.io/developers/mcp/",
-  "bugs": {
-    "url": "https://github.com/hkchao/findtime-mcp-server/issues"
-  },
   "keywords": [
     "mcp",
     "model-context-protocol",

package/server.js

@@ -49,7 +49,7 @@ const DEFAULT_API_KEY = firstNonEmpty(
   process.env.FINDTIME_TIME_API_KEY
 );
 const TIMEZONE_HELPERS_PATH = path.join(REPO_ROOT, 'slack-bot', 'timezone-helpers.js');
-const ANSWER_ONLY_TOOL_NAMES = new Set(['answer_time_question', 'get_api_diagnostics']);
+const ANSWER_ONLY_TOOL_NAMES = new Set(['answer_time_question', 'get_findtime_help', 'get_api_diagnostics']);
 
 const TOOL_DEFINITIONS = [
   {
@@ -105,6 +105,18 @@ const TOOL_DEFINITIONS = [
       return { path: '/health', params: new URLSearchParams() };
     }
   },
+  {
+    name: 'get_findtime_help',
+    description: 'Return enterprise-friendly findtime.io MCP usage help, including supported time-intelligence intents, answer API examples, ambiguity handling examples, and recommended answer-only deployment guidance.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    buildRequest() {
+      return null;
+    }
+  },
   {
     name: 'time_snapshot',
     description: 'Return the production time snapshot payload for one location or a list of locations.',
@@ -405,6 +417,119 @@ function getVisibleToolDefinitions() {
   return TOOL_DEFINITIONS.filter((tool) => ANSWER_ONLY_TOOL_NAMES.has(tool.name));
 }
 
+function buildFindtimeHelpPayload() {
+  return {
+    ok: true,
+    tool: 'get_findtime_help',
+    recommendedTool: 'answer_time_question',
+    recommendedMode: 'FINDTIME_MCP_TOOL_MODE=answer-only',
+    summary: 'Use findtime.io MCP for accurate timezone, DST, conversion, overlap-hours, and cross-timezone meeting-time intelligence. In enterprise bots, route natural-language questions through answer_time_question.',
+    install: {
+      command: 'npx',
+      args: ['-y', '@findtime/mcp-server'],
+      requiredEnv: ['FINDTIME_TIME_API_KEY'],
+      recommendedEnterpriseEnv: {
+        FINDTIME_TIME_API_BASE_URL: 'https://time-api.findtime.io',
+        FINDTIME_MCP_CLIENT_TYPE: 'company-bot',
+        FINDTIME_MCP_TOOL_MODE: 'answer-only'
+      }
+    },
+    intents: [
+      {
+        intent: 'current_time',
+        example: 'What time is it now in Tokyo?',
+        notes: 'Returns local date/time, timezone, UTC offset, and DST context when relevant.'
+      },
+      {
+        intent: 'timezone_lookup',
+        example: 'What timezone is Auckland in?',
+        notes: 'Returns the canonical IANA timezone plus the current abbreviation.'
+      },
+      {
+        intent: 'timezone_abbreviation_lookup',
+        example: 'What timezone abbreviation is Auckland?',
+        notes: 'Returns the current abbreviation plus the canonical IANA timezone.'
+      },
+      {
+        intent: 'time_conversion',
+        example: 'If it is 3:30pm in London, what time is it in Sydney?',
+        notes: 'Include local dates because conversions often cross calendar days.'
+      },
+      {
+        intent: 'time_conversion',
+        example: 'What is 5pm San Francisco time in Tokyo?',
+        notes: 'Natural-language conversion works for common city and timezone phrasing.'
+      },
+      {
+        intent: 'dst_status',
+        example: 'Is Mexico City on DST?',
+        notes: 'Returns DST status and transition context when available.'
+      },
+      {
+        intent: 'overlap_hours',
+        example: 'What working hours overlap for San Francisco, Berlin, and Tokyo?',
+        notes: 'Useful for distributed-team availability and handoff planning.'
+      },
+      {
+        intent: 'meeting_time_search',
+        example: 'Find a good meeting time for San Francisco, Berlin, and Sydney.',
+        notes: 'Returns ranked meeting windows and tradeoffs across participants.'
+      },
+      {
+        intent: 'abbreviation_disambiguation',
+        example: 'What does CST mean for a customer in China versus a customer in Chicago?',
+        notes: 'Timezone abbreviations are aliases, not canonical identifiers.'
+      },
+      {
+        intent: 'location_disambiguation',
+        example: 'What time is it in Victoria?',
+        notes: 'Ambiguous place names should return clarification or country-aware choices instead of silent guessing.'
+      }
+    ],
+    ambiguityExamples: [
+      {
+        query: 'What time is it in Springfield?',
+        expectedBehavior: 'Ask for clarification or provide likely matches because many cities share this name.'
+      },
+      {
+        query: 'Convert 9am CST to London.',
+        expectedBehavior: 'Clarify whether CST means China Standard Time, Central Standard Time, Cuba Standard Time, or another regional meaning when context is insufficient.'
+      },
+      {
+        query: 'Schedule a meeting for Paris and Sydney next Friday.',
+        expectedBehavior: 'Resolve Paris, France unless context suggests otherwise; include date and local-time tradeoffs.'
+      }
+    ],
+    answerApiPattern: {
+      tool: 'answer_time_question',
+      arguments: {
+        query: 'Best meeting time for San Francisco, Berlin, and Sydney next week',
+        userTimezone: 'America/Los_Angeles',
+        locale: 'en-US'
+      }
+    },
+    failurePolicy: [
+      'If a findtime.io MCP call fails, say the MCP call failed and include the visible error.',
+      'Do not present fallback timezone or DST calculations as if they came from findtime.io MCP.',
+      'For high-stakes scheduling, retry or ask the user before using fallback reasoning.'
+    ]
+  };
+}
+
+function formatFindtimeHelpText(help) {
+  const lines = [
+    'findtime.io Time Help',
+    '',
+    'Try asking:',
+    ...help.intents.map((entry) => `- ${entry.example}`),
+    '',
+    'If a place or timezone is ambiguous, findtime.io will ask for clarification. For example:',
+    ...help.ambiguityExamples.map((entry) => `- ${entry.query} -> ${entry.expectedBehavior}`),
+  ];
+
+  return lines.join('\n');
+}
+
 function safeReadJson(filePath) {
   try {
     return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -1097,6 +1222,19 @@ function createFindtimeMcpServer(options = {}) {
       throw invalidParamsError(`Unknown tool: ${name}`);
     }
 
+    if (name === 'get_findtime_help') {
+      const help = buildFindtimeHelpPayload();
+      return {
+        content: [
+          {
+            type: 'text',
+            text: formatFindtimeHelpText(help)
+          }
+        ],
+        structuredContent: help
+      };
+    }
+
     if (name === 'get_api_diagnostics') {
       const request = tool.buildRequest(args || {});
       const [apiResponse, latestMcpVersionCheck] = await Promise.all([