temporal-mcp-server

MCP-сервер с инструментами для времени, часовых поясов и длительностей.

Запускайте его локально через stdio (Claude Desktop, Claude Code, любой локальный MCP-клиент), локально через HTTP или используйте размещённый экземпляр — те же инструменты, тот же код, три способа запуска.

Публичный экземпляр работает на Cloudflare Workers по адресу https://time.somamcp.com/mcp:

claude mcp add --transport http temporal https://time.somamcp.com/mcp

Построен на somamcp, который предоставляет MCP-инфраструктуру, телеметрию и конечные точки здоровья/интроспекции для обеих сред выполнения. Логика времени чистая и функциональная, с использованием functype.

Инструменты

somamcp также регистрирует инструмент info и конечные точки /health, /health/detail, /info и /dashboard.

Поведение, о котором стоит знать

Арифметика месяцев ограничивает, а не переполняется. add_duration для 2026-01-31 с P1M возвращает 2026-02-28, а не 2026-03-03. Прибавление «одного месяца» к концу длинного месяца приводит к концу короткого.

Смещения определяются для каждого момента, а не для часового пояса. America/New_York сообщает -04:00 в августе и -05:00 в январе. Переход на летнее время берётся из базы данных tz среды выполнения, поэтому здесь нет таблицы смещений, которая могла бы устареть.

Ошибки содержат подсказку. Неизвестный часовой пояс возвращает неверное значение и ожидаемый формат, чтобы вызывающий агент мог исправиться, а не гадать снова.

Related MCP server: mcp-datetimeday

Запуск в качестве локального MCP-сервера

Stdio используется по умолчанию, и это режим, который ожидают локальные клиенты. Ничего не размещается на сервере, ничего не слушает порт — ваш клиент запускает процесс и общается с ним через stdin/stdout.

Claude Code

claude mcp add temporal -- npx -y temporal-mcp-server

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "temporal": {
      "command": "npx",
      "args": ["-y", "temporal-mcp-server"]
    }
  }
}

На macOS этот файл находится в ~/Library/Application Support/Claude/claude_desktop_config.json; на Windows — %APPDATA%\Claude\claude_desktop_config.json. Перезапустите Claude Desktop после редактирования.

Запуск из клона

Если вы предпочитаете не использовать npm:

pnpm install
pnpm build
pnpm start          # stdio

Затем укажите вашему клиенту на собранную точку входа:

claude mcp add temporal -- node /absolute/path/to/temporal-mcp-server/dist/node.js

{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": ["/absolute/path/to/temporal-mcp-server/dist/node.js"]
    }
  }
}

Пакет также устанавливает бинарник temporal-mcp-server, так что глобальная установка (npm i -g temporal-mcp-server) позволяет использовать это имя напрямую как команду.

Проверка работоспособности

Сервер говорит на JSON-RPC через stdout, так что вы можете управлять им вручную:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_time","arguments":{"timezone":"Asia/Tokyo"}}}' \
  | node dist/node.js

Только JSON-RPC выводится в stdout; логи идут в stderr, так что использование конвейеров безопасно.

Локальный запуск через HTTP

Для клиентов, которые говорят на streamable HTTP, а не на stdio:

pnpm start:http     # http://localhost:3333/mcp — override the port with PORT

Это тот же сервер и те же инструменты; отличается только транспорт.

Удалённый запуск на Cloudflare Workers

pnpm cf:dev         # local workerd runtime
pnpm cf:deploy      # build + edge-safety check + deploy

cf:deploy сначала запускает pnpm build, который включает check:worker — поэтому бандл, содержащий встроенный модуль Node, не пройдёт проверку до того, как что-либо достигнет Cloudflare.

Непрерывное развёртывание

Деплои выполняются через Cloudflare Workers Builds, а не GitHub Actions, поэтому токен Cloudflare API вообще не хранится в GitHub — Cloudflare подключается к репозиторию через собственное GitHub-приложение.

Настройте это один раз в панели управления (Workers & Pages → temporal-mcp-server → Settings → Build):

Указание команды деплоя на скрипт пакета сохраняет логику проверок в системе контроля версий; панель управления содержит одну стабильную строку. Имя Worker в панели управления должно совпадать с name в wrangler.jsonc (temporal-mcp-server), иначе сборка завершится ошибкой.

Образ сборки включает pnpm и учитывает .nvmrc (в нашем случае зафиксирован Node 24). Для непроизводственных веток по умолчанию используется npx wrangler versions upload, поэтому пуши в ветки создают предварительные версии, не затрагивая боевой деплой.

Конечная точка MCP находится по адресу /mcp. Чтобы требовать bearer-токен:

wrangler secret put MCP_AUTH_TOKEN

Если задан MCP_AUTH_TOKEN, неаутентифицированные вызовы к /mcp получают 401. Если его не задавать, конечная точка остаётся публичной — разумно для часов, но не для многого другого.

Необязательные vars: GIT_COMMIT и ENVIRONMENT отображаются инструментом info и /info.

Подключение клиента к развёрнутому Worker

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

claude mcp add --transport http temporal https://time.somamcp.com/mcp

Если задан токен, передавайте его как заголовок:

claude mcp add --transport http temporal https://time.somamcp.com/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Проверка здоровья: https://time.somamcp.com/health.

pnpm cf:dev обслуживает то же самое на http://localhost:8787/mcp, так что вы можете направить клиент на локальный экземпляр workerd перед деплоем.

Почему worker импортирует somamcp/edge

Корневой barrel-модуль somamcp реэкспортирует хелперы, которые импортируют node:fs. Импорт его из Worker тянет встроенные модули Node в бандл. Поэтому src/worker.ts импортирует somamcp/edge, и pnpm check:worker завершает сборку ошибкой, если node:-импорт, голый встроенный модуль Node или корневой спецификатор somamcp попадает в бандл worker.

Проверка проходит по фактическому графу импортов из dist/worker.js, а не сопоставляет имена файлов — бандлер поднимает код, общий с Node-входом, в чанк с сгенерированным именем, и glob по именам файлов пропустил бы именно тот файл, который с наибольшей вероятностью содержит утечку.

nodejs_compat намеренно не включён в wrangler.jsonc. Если встроенный модуль Node когда-либо появится, сборка должна громко упасть, а не быть тихо зашитой.

Блок alias в wrangler.jsonc

xsschema (транзитивно, через fastmcp) проверяет каждую поддерживаемую библиотеку схем — valibot, effect, sury — через динамический импорт. Мы используем только zod, поэтому эти ветки никогда не выполняются, но esbuild всё равно должен разрешать спецификаторы. Для них задаётся псевдоним на пустой модуль вместо установки трёх неиспользуемых библиотек.

Архитектура

src/
  clock.ts    pure time logic — Either<TemporalError, T>, no I/O, no globals
  tools.ts    MCP tool registration; takes a server, creates none
  index.ts    library surface (runtime-agnostic)
  node.ts     entry: somamcp      -> stdio + httpStream
  worker.ts   entry: somamcp/edge -> export default { fetch }

registerTemporalTools(server) принимает сервер, а не создаёт его, поэтому обе точки входа регистрируют одинаковые инструменты. Ничто в clock.ts, tools.ts или index.ts не касается process, файловой системы или любого встроенного модуля Node.

Сбои — это значения. Каждая подверженная ошибкам функция в clock.ts возвращает Either<TemporalError, T>; слой инструментов сводит Left к результату ошибки MCP. Ничто не зависит от разматывания стека, что позволяет одному и тому же коду работать без изменений в обеих средах выполнения.

Разработка

pnpm validate       # format + lint + typecheck + test + build
pnpm test           # 34 tests
pnpm check:worker   # verify the worker bundle is edge-safe

test/worker.spec.ts прогоняет реальные объекты Request через fetch-обработчик Worker по MCP-протоколу, поэтому нарушения интеграции всплывают в CI, а не после деплоя.

Лицензия

MIT