@findtime/mcp-server 3.25.8 → 3.25.10

package/README.md

@@ -41,7 +41,9 @@ Optional environment variables:
 - `TIME_API_BASE_URL`
 - `TIME_API_TIMEOUT_MS`
 - `FINDTIME_MCP_CLIENT_TYPE`
-- `FINDTIME_MCP_INSTRUMENTATION_ENABLED`
+- `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.
 
 ### Cursor
 
@@ -55,8 +57,7 @@ Optional environment variables:
       "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_MCP_INSTRUMENTATION_ENABLED": "false"
+        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
       }
     }
   }
@@ -75,7 +76,6 @@ 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"
-FINDTIME_MCP_INSTRUMENTATION_ENABLED = "false"
 ```
 
 ### Claude Desktop
@@ -91,8 +91,7 @@ FINDTIME_MCP_INSTRUMENTATION_ENABLED = "false"
       "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_INSTRUMENTATION_ENABLED": "false"
+        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
       }
     }
   }
@@ -115,15 +114,16 @@ Best meeting time between New York, Sydney, and Mumbai?
 
 ## Local development
 
-Run the server directly from the 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
@@ -131,13 +131,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:
@@ -152,17 +152,15 @@ The smoke suite checks:
 
 ## Maintainer release flow
 
-This repository is intended to be the canonical public source for `@findtime/mcp-server`.
+The canonical public source for this package now lives in:
 
-Recommended setup:
+- GitHub: `https://github.com/hkchao/findtime-mcp-server`
+- npm: `@findtime/mcp-server`
+- Official MCP Registry: `https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server`
 
-- keep `@findtime/mcp-server` as the npm package name
-- keep `io.github.hkchao/findtime-mcp-server` as the MCP Registry server name
-- add `repository` and `bugs` metadata after creating the GitHub repo
-- add an `NPM_TOKEN` secret to the GitHub repository
-- publish through GitHub Actions or a maintainer terminal from this repo root
+Publish and version updates should happen from that public repo, not from this private app repo.
 
-Standard local publish flow:
+Standard publish flow in the public repo:
 
 ```bash
 npm test
@@ -170,12 +168,11 @@ npm pack --dry-run
 npm publish --access public
 ```
 
-GitHub Actions release flow:
+The equivalent local verification checks in this repo are:
 
 ```bash
-npm test
-npm pack --dry-run
-npm publish --access public
+npm run test:mcp-server
+npm run mcp:pack
 ```
 
-Use the workflow in `.github/workflows/publish.yml` for repo-backed publishes.
+Treat this repo as the implementation source that originally produced the MCP package, not as the canonical public release source.

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@findtime/mcp-server",
-  "version": "3.25.8",
-  "mcpName": "io.github.hkchao/findtime-mcp-server",
+  "version": "3.25.10",
   "description": "Production-parity MCP server for the findtime.io Time API",
   "bin": {
     "findtime-mcp": "server.js"
@@ -29,14 +28,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

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 const fs = require('node:fs');
 const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
 
 const PACKAGE_ROOT = __dirname;
 const LOCAL_PACKAGE_PATH = path.join(PACKAGE_ROOT, 'package.json');
@@ -17,17 +19,29 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([
 
 loadEnvironmentFiles();
 
-const PACKAGE_METADATA = safeReadJson(LOCAL_PACKAGE_PATH) || safeReadJson(REPO_PACKAGE_PATH) || {};
+const LOCAL_PACKAGE_METADATA = safeReadJson(LOCAL_PACKAGE_PATH) || null;
+const REPO_PACKAGE_METADATA = safeReadJson(REPO_PACKAGE_PATH) || null;
+const PACKAGE_METADATA = LOCAL_PACKAGE_METADATA || REPO_PACKAGE_METADATA || {};
 const SERVER_VERSION = PACKAGE_METADATA.version || '0.0.0';
 const MCP_PACKAGE_NAME = PACKAGE_METADATA.name || '@findtime/mcp-server';
 const MCP_NPM_REGISTRY_LATEST_URL = `https://registry.npmjs.org/${encodeURIComponent(MCP_PACKAGE_NAME)}/latest`;
 const MCP_NPM_URL = `https://www.npmjs.com/package/${MCP_PACKAGE_NAME}`;
 const MCP_REGISTRY_URL = 'https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server';
+const MCP_INSTALL_MODE = determineInstallMode({
+  packageRoot: PACKAGE_ROOT,
+  localPackageMetadata: LOCAL_PACKAGE_METADATA,
+  repoPackageMetadata: REPO_PACKAGE_METADATA
+});
 const DEFAULT_API_BASE_URL = firstNonEmpty(
   process.env.TIME_API_BASE_URL,
   process.env.FINDTIME_TIME_API_BASE_URL
 ) || 'https://time-api.findtime.io';
 const DEFAULT_TIMEOUT_MS = parseInteger(process.env.TIME_API_TIMEOUT_MS, 15000);
+const MCP_USAGE_TELEMETRY_URL = firstNonEmpty(
+  process.env.FINDTIME_MCP_USAGE_TELEMETRY_URL,
+  process.env.FINDTIME_USAGE_TELEMETRY_URL
+) || 'https://slack.findtime.io/telemetry/usage';
+const MCP_USAGE_TELEMETRY_TIMEOUT_MS = parseInteger(process.env.FINDTIME_MCP_USAGE_TELEMETRY_TIMEOUT_MS, 1200);
 const DEFAULT_API_KEY = firstNonEmpty(
   process.env.FINDTIME_API_KEY,
   process.env.TIME_API_KEY,
@@ -328,6 +342,7 @@ const TOOL_DEFINITIONS = [
 
 const TOOL_DEFINITIONS_BY_NAME = new Map(TOOL_DEFINITIONS.map((tool) => [tool.name, tool]));
 let cachedResolveLocation;
+let cachedMcpClientId;
 
 function safeReadJson(filePath) {
   try {
@@ -392,6 +407,144 @@ function parseInteger(value, fallback) {
   return Number.isFinite(parsed) ? parsed : fallback;
 }
 
+function isMcpUsageTelemetryEnabled() {
+  const explicit = firstNonEmpty(
+    process.env.FINDTIME_MCP_USAGE_TELEMETRY_ENABLED,
+    process.env.FINDTIME_MCP_INSTRUMENTATION_ENABLED
+  );
+  const normalized = String(explicit || '').trim().toLowerCase();
+  return !['false', '0', 'off', 'no'].includes(normalized);
+}
+
+function getMcpClientType() {
+  return firstNonEmpty(
+    process.env.FINDTIME_MCP_CLIENT_TYPE,
+    process.env.TIME_API_CLIENT_TYPE
+  ) || 'stdio';
+}
+
+function getMcpClientIdPath() {
+  const explicitDir = firstNonEmpty(process.env.FINDTIME_MCP_STATE_DIR);
+  if (explicitDir) {
+    return path.join(explicitDir, 'mcp-client-id');
+  }
+
+  const xdgStateHome = firstNonEmpty(process.env.XDG_STATE_HOME);
+  const baseDir = xdgStateHome
+    ? path.join(xdgStateHome, 'findtime')
+    : path.join(os.homedir(), '.findtime');
+  return path.join(baseDir, 'mcp-client-id');
+}
+
+function getMcpClientId() {
+  const explicit = firstNonEmpty(
+    process.env.FINDTIME_MCP_CLIENT_ID,
+    process.env.FINDTIME_MCP_INSTALL_ID
+  );
+  if (explicit) return explicit.slice(0, 128);
+
+  if (cachedMcpClientId) return cachedMcpClientId;
+
+  const idPath = getMcpClientIdPath();
+  try {
+    const existing = fs.readFileSync(idPath, 'utf8').trim();
+    if (existing) {
+      cachedMcpClientId = existing.slice(0, 128);
+      return cachedMcpClientId;
+    }
+  } catch (_error) {
+    // First run or unreadable state file. Generate below.
+  }
+
+  cachedMcpClientId = `mcp-${crypto.randomUUID ? crypto.randomUUID() : crypto.randomBytes(16).toString('hex')}`;
+
+  try {
+    fs.mkdirSync(path.dirname(idPath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(idPath, `${cachedMcpClientId}\n`, { mode: 0o600 });
+  } catch (_error) {
+    // Telemetry remains best-effort; an unwritable home directory should not break MCP.
+  }
+
+  return cachedMcpClientId;
+}
+
+function getRuntimeLocale() {
+  return firstNonEmpty(
+    process.env.LC_ALL,
+    process.env.LC_MESSAGES,
+    process.env.LANG
+  );
+}
+
+function getRuntimeTimezone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function getMcpQueryText(args = {}) {
+  if (!args || typeof args !== 'object') return '';
+  return firstNonEmpty(
+    args.query,
+    args.city,
+    args.timezone,
+    args.from,
+    Array.isArray(args.locations) ? args.locations.join('|') : null
+  ) || '';
+}
+
+function buildMcpUsageTelemetryEvent({ toolName, args = {}, result = null, error = null, latencyMs = 0 } = {}) {
+  const queryText = getMcpQueryText(args);
+  const status = error
+    ? 'exception'
+    : result && result.isError
+      ? 'error'
+      : 'ok';
+
+  return {
+    platform: 'mcp-server',
+    route: String(toolName || 'unknown').slice(0, 80),
+    status,
+    source: getMcpClientType().slice(0, 80),
+    textLength: Math.min(2000, queryText.length),
+    userId: getMcpClientId(),
+    appVersion: SERVER_VERSION,
+    browser: 'mcp',
+    browserVersion: MCP_INSTALL_MODE,
+    os: `${os.platform()} ${os.release()}`.slice(0, 80),
+    locale: getRuntimeLocale(),
+    timezone: getRuntimeTimezone(),
+    latencyMs: Math.max(0, Math.round(Number(latencyMs || 0)))
+  };
+}
+
+function recordMcpUsageTelemetry(input) {
+  if (!isMcpUsageTelemetryEnabled() || !MCP_USAGE_TELEMETRY_URL || typeof fetch !== 'function') {
+    return;
+  }
+
+  const event = buildMcpUsageTelemetryEvent(input);
+  const controller = typeof AbortController === 'function' ? new AbortController() : null;
+  const timeout = controller
+    ? setTimeout(() => controller.abort(), MCP_USAGE_TELEMETRY_TIMEOUT_MS)
+    : null;
+
+  fetch(MCP_USAGE_TELEMETRY_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(event),
+    signal: controller ? controller.signal : undefined
+  }).catch((error) => {
+    if (String(process.env.FINDTIME_MCP_DEBUG || '').trim().toLowerCase() === '1') {
+      console.error('[findtime-mcp telemetry] failed:', error && error.message ? error.message : error);
+    }
+  }).finally(() => {
+    if (timeout) clearTimeout(timeout);
+  });
+}
+
 function stringOrStringArraySchema(description) {
   return {
     anyOf: [
@@ -903,6 +1056,8 @@ function createFindtimeMcpServer(options = {}) {
         mcpLatestVersionHint: latestVersion
           ? null
           : 'Could not verify the latest published MCP version automatically. Check the npm package page or Official MCP Registry listing directly.',
+        mcpInstallMode: MCP_INSTALL_MODE,
+        mcpExecutablePath: path.join(PACKAGE_ROOT, 'server.js'),
         mcpRegistryUrl: MCP_REGISTRY_URL,
         mcpNpmUrl: MCP_NPM_URL,
         apiBaseUrl,
@@ -1046,8 +1201,25 @@ function createFindtimeMcpServer(options = {}) {
       if (method === 'tools/call') {
         const toolName = message.params && message.params.name;
         const toolArgs = (message.params && message.params.arguments) || {};
-        const result = await callTool(toolName, toolArgs);
-        return createSuccessResponse(message.id, result);
+        const startedAt = Date.now();
+        try {
+          const result = await callTool(toolName, toolArgs);
+          recordMcpUsageTelemetry({
+            toolName,
+            args: toolArgs,
+            result,
+            latencyMs: Date.now() - startedAt
+          });
+          return createSuccessResponse(message.id, result);
+        } catch (toolError) {
+          recordMcpUsageTelemetry({
+            toolName,
+            args: toolArgs,
+            error: toolError,
+            latencyMs: Date.now() - startedAt
+          });
+          throw toolError;
+        }
       }
 
       throw methodNotFoundError(method);
@@ -1081,6 +1253,22 @@ function tryParseJson(value) {
   }
 }
 
+function determineInstallMode({ packageRoot, localPackageMetadata, repoPackageMetadata }) {
+  if (repoPackageMetadata && repoPackageMetadata.name === 'world-time-ai') {
+    return 'repo_checkout';
+  }
+
+  if (localPackageMetadata && localPackageMetadata.name === '@findtime/mcp-server') {
+    return 'npm_package';
+  }
+
+  if (typeof packageRoot === 'string' && packageRoot.includes(`${path.sep}world-time-ai${path.sep}services${path.sep}mcp-server`)) {
+    return 'repo_checkout';
+  }
+
+  return 'package_install';
+}
+
 function startStdioServer(options = {}) {
   const server = createFindtimeMcpServer(options);
   const messageBuffer = new ContentLengthMessageBuffer();