temporal-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server exposing time, timezone, and duration tools. It ships two entry points from one codebase: a Node binary (stdio + httpStream) and a Cloudflare Worker.

Built on somamcp ^1.2.0, which provides the MCP backend abstraction, telemetry, and health/introspection surfaces for both runtimes.

Development Commands

pnpm validate        # format + lint + typecheck + test + build (run before commits)
pnpm test            # Vitest
pnpm check:worker    # verify the worker bundle contains no Node built-ins

pnpm start           # stdio server (dist/node.js)
pnpm start:http      # HTTP on :3333/mcp
pnpm cf:dev          # local workerd via wrangler
pnpm cf:deploy       # deploy to Cloudflare

Run a single test: pnpm test -- test/clock.spec.ts

Architecture

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

The rule that keeps both runtimes working

src/index.ts, src/clock.ts, and src/tools.ts must never import a Node built-in, directly or transitively. They are shared by both entry points; anything Node-only in them breaks the Worker.

• src/node.ts may use process and Node APIs.
• src/worker.ts must import from somamcp/edge, never somamcp. The root barrel re-exports createJsonFileTelemetry / imageContent / audioContent, which import node:fs.

pnpm check:worker enforces this by walking the import graph from dist/worker.js and failing on any node: specifier, bare Node built-in (fs, crypto, path…), or root somamcp import. It follows the graph rather than matching filenames because the bundler hoists shared code into a chunk with a generated name — a glob would miss it.