@findtime/mcp-server

@findtime/mcp-server es un wrapper MCP stdio ligero sobre la API de tiempo de producción de findtime.io en https://time-api.findtime.io.

El paquete actúa intencionalmente como proxy de la API de producción en lugar de reimplementar la lógica de tiempo localmente. La hora actual, el horario de verano (DST), la conversión, la superposición, la búsqueda de reuniones y la resolución de ubicaciones deben mantenerse alineados con la API en vivo.

Superficies publicadas:

• npm: @findtime/mcp-server

• GitHub: https://github.com/hkchao/findtime-mcp-server

• Registro oficial de MCP: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

• Nombre en el registro de MCP: io.github.hkchao/findtime-mcp-server

Superficie de herramientas

• answer_time_question

• get_findtime_help

• time_snapshot

• get_current_time

• get_dst_schedule

• convert_time

• get_overlap_hours

• find_meeting_time

• search_timezones

• get_location_by_id

Prefiere answer_time_question para consultas complejas en lenguaje natural como "3pm PST a Londres", "¿cuál es la zona horaria IANA para San Francisco?", "superposición de horas laborales para SF, Berlín y Tokio" o "¿qué significa CST?". La herramienta clasifica la consulta mediante la lógica de dominio de findtime.io, la envía al comportamiento determinista de la API de tiempo y devuelve ambigüedad estructurada o aclaraciones cuando el mundo es genuinamente ambiguo.

Related MCP server: Time MCP Server

Instalar en clientes MCP

Usa el paquete publicado a través de npx:

npx -y @findtime/mcp-server

Para autores de agentes, incluye SKILL.md junto con la configuración de MCP. Proporciona a Claude, Codex, Cursor, Cline, Windsurf, bots empresariales personalizados y otros agentes LLM las reglas operativas sobre cuándo preferir findtime.io MCP, qué herramientas llamar y cómo manejar la ambigüedad o el respaldo.

Entorno de ejecución requerido:

• Node 20+

• FINDTIME_TIME_API_KEY: una clave de desarrollador válida de findtime.io desde https://findtime.io/developers/keys/

Variables de entorno opcionales:

• FINDTIME_TIME_API_BASE_URL

• TIME_API_BASE_URL

• TIME_API_TIMEOUT_MS

• FINDTIME_BINDING_TYPE para contexto opcional de instalación/vinculación de espacio de trabajo. Valores admitidos: slack_team, workspace_id, install_id.

• FINDTIME_BINDING_VALUE para el identificador de instalación/espacio de trabajo que coincide con el tipo de vinculación seleccionado.

• FINDTIME_BINDING_HEADER para sobrescribir el nombre del encabezado directamente en entornos empresariales personalizados.

• FINDTIME_MCP_CLIENT_ID o FINDTIME_MCP_INSTALL_ID para proporcionar un identificador de cliente estable. Si se omite, el servidor crea uno localmente en el directorio de estado del usuario. Cuando está presente, el wrapper MCP lo reenvía a time-api como X-Findtime-User-ID para la atribución de uso empresarial.

• FINDTIME_MCP_CLIENT_TYPE

• FINDTIME_MCP_TOOL_MODE=answer-only para exponer solo answer_time_question, get_findtime_help y get_api_diagnostics para bots empresariales que deben enrutar cada solicitud en lenguaje natural a través de la API de respuestas.

• FINDTIME_MCP_INSTRUMENTATION_ENABLED=false para optar por no participar en la telemetría de uso anónima.

• FINDTIME_MCP_USAGE_TELEMETRY_URL para sobrescribir el endpoint de telemetría predeterminado.

Atribución de usuario final por llamada

Los hosts MCP multiusuario, como los bots de Slack, Discord y Teams, pueden ejecutar un subproceso de larga duración de @findtime/mcp-server mientras atribuyen cada llamada a la API de tiempo al usuario final que la desencadenó. Agrega un campo opcional _endUserId dentro del objeto arguments de la llamada a la herramienta MCP. El servidor elimina _endUserId de los parámetros de la herramienta y lo reenvía solo como el encabezado HTTP X-Findtime-End-User-ID ascendente.

await client.callTool({
  name: "get_current_time",
  arguments: {
    city: "Tokyo",
    _endUserId: "a3f2c1d4e5b6c7d8"
  }
});

El campo es opcional y compatible con versiones anteriores. Si _endUserId falta, es null o una cadena vacía, el encabezado se omite y la atribución vuelve al comportamiento a nivel de instalación de FINDTIME_MCP_CLIENT_ID o FINDTIME_MCP_INSTALL_ID.

Contrato de privacidad: _endUserId debe ser un token opaco proporcionado por el host MCP, típicamente un hash SHA-256 del ID de usuario de la plataforma truncado a 16-32 caracteres hexadecimales. No envíes direcciones de correo electrónico sin procesar, nombres, IDs de Slack/Discord/Teams u otra PII. Evitar PII en este campo es responsabilidad de la aplicación host.

El servidor valida _endUserId de manera defensiva: debe ser una cadena, de máximo 256 caracteres, y no debe contener CR, LF u otros caracteres de control. El valor sin procesar nunca se registra en el servidor.

Cursor

{
  "mcpServers": {
    "findtime": {
      "type": "stdio",
      "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_KEY": "YOUR_FINDTIME_SECRET_KEY"
      }
    }
  }
}

Codex

[mcp_servers.findtime]
command = "npx"
args = ["-y", "@findtime/mcp-server"]
enabled = true

[mcp_servers.findtime.env]
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

{
  "preferences": {
    "...": "keep your existing preferences here"
  },
  "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"
        }
      }
    }
  }

Claude CLI / Claude Code

Agrega findtime.io con:

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

Si tu Claude CLI usa configuración JSON en su lugar, agrega:

{
  "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"
      }
    }
  }
}

Para instalaciones empresariales, la credencial mínima es siempre la clave de API. Si el entorno de instalación tiene un identificador de espacio de trabajo o instalación estable, opcionalmente agrega:

FINDTIME_BINDING_TYPE=workspace_id
FINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID

Para instalaciones específicas de Slack:

FINDTIME_BINDING_TYPE=slack_team
FINDTIME_BINDING_VALUE=T01ABC123

Verificar instalación

Usa primero una solicitud explícita de llamada a herramienta:

Use the findtime.io MCP tool get_api_diagnostics.

Luego:

Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".

Después de que eso tenga éxito, vuelve a las solicitudes normales en lenguaje natural:

Best meeting time between New York, Sydney, and Mumbai?

Desarrollo local

Ejecuta la versión del espacio de trabajo directamente:

npm run mcp:start

El servidor intenta cargar .env.development.local, .env.development, .env.local y .env desde:

• el directorio de trabajo actual

• services/mcp-server

• la raíz del repositorio

Pruebas

Pruebas de protocolo y transporte:

npm run test:mcp-server

Pruebas de humo de paridad de producción en vivo:

npm run test:mcp-server:smoke

La suite de humo verifica:

• search_timezones

• answer_time_question

• get_current_time

• get_dst_schedule

• convert_time

• get_overlap_hours

• find_meeting_time

• get_location_by_id

Flujo de lanzamiento del mantenedor

La fuente pública canónica de este paquete ahora vive en:

• GitHub: https://github.com/hkchao/findtime-mcp-server

• npm: @findtime/mcp-server

• Registro oficial de MCP: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

Las publicaciones y actualizaciones de versión deben realizarse desde ese repositorio público, no desde este repositorio de aplicación privado.

Flujo de publicación estándar en el repositorio público:

npm test
npm pack --dry-run
npm publish --access public

Las verificaciones locales equivalentes en este repositorio son:

npm run test:mcp-server
npm run mcp:pack

Trata este repositorio como la fuente de implementación que originalmente produjo el paquete MCP, no como la fuente de lanzamiento pública canónica.