@findtime/mcp-server 3.25.13 → 3.25.15

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,6 +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`, `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.

package/SKILL.md

@@ -72,9 +72,23 @@ Most MCP clients need the same core config:
 
 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:
+
+```text
+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.
+
 ## Tool Selection
 
-Use `answer_time_question` first for natural-language or ambiguous prompts.
+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:
 
@@ -86,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/package.json

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

package/server.js

@@ -49,6 +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_findtime_help', 'get_api_diagnostics']);
 
 const TOOL_DEFINITIONS = [
   {
@@ -104,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.',
@@ -385,6 +398,114 @@ const TOOL_DEFINITIONS_BY_NAME = new Map(TOOL_DEFINITIONS.map((tool) => [tool.na
 let cachedResolveLocation;
 let cachedMcpClientId;
 
+function getMcpToolMode() {
+  const mode = String(firstNonEmpty(
+    process.env.FINDTIME_MCP_TOOL_MODE,
+    process.env.FINDTIME_MCP_TOOLS
+  ) || 'full').trim().toLowerCase();
+
+  return ['answer-only', 'answer_only', 'answer'].includes(mode)
+    ? 'answer-only'
+    : 'full';
+}
+
+function getVisibleToolDefinitions() {
+  if (getMcpToolMode() !== 'answer-only') {
+    return TOOL_DEFINITIONS;
+  }
+
+  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 is the IANA timezone for San Francisco?',
+        notes: 'Use IANA timezone IDs as canonical identifiers.'
+      },
+      {
+        intent: 'time_conversion',
+        example: 'Convert 3pm next Tuesday in New York to London, Berlin, and Singapore.',
+        notes: 'Include local dates because conversions often cross calendar days.'
+      },
+      {
+        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 45-minute meeting time next week 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 safeReadJson(filePath) {
   try {
     return JSON.parse(fs.readFileSync(filePath, 'utf8'));
@@ -1073,10 +1194,22 @@ function createFindtimeMcpServer(options = {}) {
 
   async function callTool(name, args = {}) {
     const tool = TOOL_DEFINITIONS_BY_NAME.get(name);
-    if (!tool) {
+    if (!tool || (getMcpToolMode() === 'answer-only' && !ANSWER_ONLY_TOOL_NAMES.has(name))) {
       throw invalidParamsError(`Unknown tool: ${name}`);
     }
 
+    if (name === 'get_findtime_help') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `get_findtime_help response\n${JSON.stringify(buildFindtimeHelpPayload(), null, 2)}`
+          }
+        ],
+        structuredContent: buildFindtimeHelpPayload()
+      };
+    }
+
     if (name === 'get_api_diagnostics') {
       const request = tool.buildRequest(args || {});
       const [apiResponse, latestMcpVersionCheck] = await Promise.all([
@@ -1231,7 +1364,7 @@ function createFindtimeMcpServer(options = {}) {
 
       if (method === 'tools/list') {
         return createSuccessResponse(message.id, {
-          tools: TOOL_DEFINITIONS.map(({ name, description, inputSchema }) => ({
+          tools: getVisibleToolDefinitions().map(({ name, description, inputSchema }) => ({
             name,
             description,
             inputSchema