CurrentDT-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working in this repository. Everything here describes the code as it is; if a statement stops being true, fix the statement.

What this is

@strix-ai/currentdt-mcp is an MCP server exposing two tools over stdio: get_current_datetime (any IANA zone, structured output) and convert_timezone (DST-correct). Published to npm from CI via Trusted Publishing (OIDC) -- there is no npm token anywhere. Requires Node 18+.

Tool errors (bad format, failed provider) are thrown from the handler and become isError results; the SDK validates arguments against the zod inputSchema and structuredContent against outputSchema before anything reaches a client.

The v2 plan lives in docs/v2/ (ROADMAP.md, TOOL-SPEC.md, MIGRATION.md). Read ROADMAP.md before starting feature work; it says which phase is next and why the ordering matters. Nothing in those docs is marked complete until it is merged.

Commands

npm run build        # tsc -> dist/
npm test             # jest, all suites (unit + integration); must stay green in any TZ
npm run test:unit
npm run test:integration
npm run lint         # eslint "src/**/*.ts"  (keep the quotes -- bash globstar is off on CI)
npm run type-check   # tsc --noEmit
npm run dev          # tsx watch src/index.ts
node dist/index.js --test              # exercise the built package end to end
node dist/index.js --validate-format "YYYY-MM-DD"

Release: bump version in package.json (npm version patch --no-git-tag-version) and push to master. The workflow tests on Node 18/20/22, publishes to npm if the version is new, creates the tag and GitHub release, then publishes to the MCP Registry (OIDC, no secret; it syncs server.json's version from package.json). Do not create the release tag by hand. package.json mcpName must equal server.json name -- the registry reads it from the published npm tarball to prove ownership.

The workflow also builds currentdt-mcp.mcpb (npm run build:mcpb, manifest.json

• scripts/build-mcpb.js) and attaches it to the GitHub release: one-click install for Claude Desktop, and the artifact Smithery distributes for local servers. The build script launches the staged server before packing, so a bundle that cannot start is never published, and it derives the manifest's tool list and a separate server-card.json from the server's own tools/list.