@findtime/mcp-server

@findtime/mcp-server — это тонкая stdio-обёртка MCP поверх продакшн-API findtime.io Time API по адресу https://time-api.findtime.io.

Пакет намеренно проксирует продакшн-API вместо повторной реализации логики времени локально. Текущее время, переход на летнее время (DST), конвертация, пересечение, поиск встреч и определение местоположения должны оставаться согласованными с живым API.

Опубликованные поверхности:

• npm: @findtime/mcp-server

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

• Официальный реестр MCP: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

• Имя в реестре MCP: io.github.hkchao/findtime-mcp-server

Поверхность инструментов

• 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

Отдавайте предпочтение answer_time_question для запутанных естественно-языковых запросов, таких как «3pm PST to London», «what is the IANA timezone for San Francisco?», «working hours overlap for SF, Berlin, and Tokyo» или «what does CST mean?». Инструмент классифицирует запрос через доменную логику findtime.io, направляет его к детерминированному поведению Time API и возвращает структурированную неоднозначность или уточнение, когда мир действительно неоднозначен.

Related MCP server: Time MCP Server

Установка в MCP-клиентах

Используйте опубликованный пакет через npx:

npx -y @findtime/mcp-server

Авторам агентов: разместите SKILL.md рядом с конфигурацией MCP. Он даёт Claude, Codex, Cursor, Cline, Windsurf, кастомным корпоративным ботам и другим LLM-агентам правила работы: когда предпочитать MCP findtime.io, какие инструменты вызывать и как обрабатывать неоднозначность или откат.

Требуемое окружение выполнения:

• Node 20+

• FINDTIME_TIME_API_KEY: действующий ключ разработчика findtime.io с https://findtime.io/developers/keys/

Необязательные переменные окружения:

• FINDTIME_TIME_API_BASE_URL

• TIME_API_BASE_URL

• TIME_API_TIMEOUT_MS

• FINDTIME_BINDING_TYPE для необязательного контекста привязки установки/рабочего пространства. Поддерживаемые значения: slack_team, workspace_id, install_id.

• FINDTIME_BINDING_VALUE для идентификатора установки/рабочего пространства, соответствующего выбранному типу привязки.

• FINDTIME_BINDING_HEADER для прямого переопределения имени заголовка в кастомных корпоративных средах.

• FINDTIME_MCP_CLIENT_ID или FINDTIME_MCP_INSTALL_ID для предоставления стабильного идентификатора клиента. Если опущено, сервер создаёт его локально в каталоге состояния пользователя. При наличии обёртка MCP пересылает его в time-api как X-Findtime-User-ID для корпоративной атрибуции использования.

• FINDTIME_MCP_CLIENT_TYPE

• FINDTIME_MCP_TOOL_MODE=answer-only для раскрытия только answer_time_question, get_findtime_help и get_api_diagnostics для корпоративных ботов, которые должны направлять каждый естественно-языковой запрос через answer API.

• FINDTIME_MCP_INSTRUMENTATION_ENABLED=false для отказа от анонимной телеметрии использования.

• FINDTIME_MCP_USAGE_TELEMETRY_URL для переопределения конечной точки телеметрии по умолчанию.

Атрибуция конечного пользователя при каждом вызове

Многопользовательские MCP-хосты, такие как боты Slack, Discord и Teams, могут запускать один долгоживущий подпроцесс @findtime/mcp-server, при этом атрибутируя каждый вызов Time API конечному пользователю, который его инициировал. Добавьте необязательное поле _endUserId внутрь объекта arguments вызова инструмента MCP. Сервер удаляет _endUserId из параметров инструмента и пересылает его только как вышестоящий HTTP-заголовок X-Findtime-End-User-ID.

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

Поле необязательно и обратно совместимо. Если _endUserId отсутствует, равно null или пустой строке, заголовок опускается, и атрибуция возвращается к поведению на уровне установки через FINDTIME_MCP_CLIENT_ID или FINDTIME_MCP_INSTALL_ID.

Контракт конфиденциальности: _endUserId должен быть непрозрачным токеном, предоставленным хостом MCP, обычно SHA-256-хэшем идентификатора пользователя платформы, усечённым до 16–32 шестнадцатеричных символов. Не отправляйте сырые адреса электронной почты, имена, идентификаторы Slack/Discord/Teams или другие персональные данные (PII). Избегание PII в этом поле — ответственность хост-приложения.

Сервер защитно проверяет _endUserId: это должна быть строка длиной не более 256 символов, не содержащая CR, LF или других управляющих символов. Сырое значение никогда не логируется сервером.

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

Добавьте findtime.io с помощью:

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

Если ваш Claude CLI использует JSON-конфигурацию, добавьте:

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

Для корпоративных установок минимальным учётным данным всегда является ключ API. Если в среде установки есть стабильный идентификатор рабочего пространства или установки, опционально добавьте:

FINDTIME_BINDING_TYPE=workspace_id
FINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID

Для установок, специфичных для Slack:

FINDTIME_BINDING_TYPE=slack_team
FINDTIME_BINDING_VALUE=T01ABC123

Проверка установки

Сначала используйте явный запрос с вызовом инструмента:

Use the findtime.io MCP tool get_api_diagnostics.

Затем:

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

После успеха переключитесь обратно на обычные естественно-языковые запросы:

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

Локальная разработка

Запустите версию рабочего пространства напрямую:

npm run mcp:start

Сервер пытается загрузить .env.development.local, .env.development, .env.local и .env из:

• текущего рабочего каталога

• services/mcp-server

• корня репозитория

Тесты

Тесты протокола и транспорта:

npm run test:mcp-server

Живые смоук-тесты паритета с продакшном:

npm run test:mcp-server:smoke

Смоук-набор проверяет:

• search_timezones

• answer_time_question

• get_current_time

• get_dst_schedule

• convert_time

• get_overlap_hours

• find_meeting_time

• get_location_by_id

Процесс релиза мейнтейнера

Канонический публичный исходный код этого пакета теперь находится в:

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

• npm: @findtime/mcp-server

• Официальный реестр MCP: https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

Публикация и обновления версий должны происходить из этого публичного репозитория, а не из этого приватного репозитория приложения.

Стандартный процесс публикации в публичном репозитории:

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

Эквивалентные локальные проверки в этом репозитории:

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

Относитесь к этому репозиторию как к источнику реализации, который изначально создал пакет MCP, а не как к каноническому публичному источнику релизов.