calculator mcp server changelog

• + calculator-guide

version

0.5.3 → 0.6.0

https://raw.githubusercontent.com/cyanheads/calculator-mcp-server/HEAD/AGENTS.md

− **Version:** 0.5.1− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`− **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0− **Zod:** 4.6.5− Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant f− | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |− `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was − The `release-and-publish` skill drives all three — don't run the commands manually unless the skill halts.+ **Version:** 0.5.3+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0+ **Zod:** 4.6.7+ Two skill trees live at the project root, written for different readers:+ | Tree | For | Written by |+ |:-----|:----|:-----------|+ | `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |+ | `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |+ Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, the published `skills/` tree (run by devcheck) |+ `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`: exclude each development-only root path with an anchored pattern (`/docs/`, never `docs/`, which also strips dependency paths). Root `skills/` ships when present. `scripts/clean-mcpb.ts` prunes dev dependencies, dependency-shipped agent docs, platform-specific native bindings, node-gyp build output, and build-only package files such as the framework's c+      --build-arg APP_VERSION=<version> \+ 4. **MCP Registry** — `bun run publish-mcp` publishes `server.json` under `io.github.cyanheads/calculator-mcp-server`.+ The `release-and-publish` skill drives all four — don't run the commands manually unless the skill halts.+ - [ ] Root `plugin.json` + `mcp.json` follow Agent Plugins 1.0.0: unscoped display name, metadata from `package.json`, one stdio server using `npx -y <full package name>`, and fixed env values matching `.codex-plugin/mcp.json`. Keep the Codex overlay's `mcpServers` pointer so its `env_vars` reach the root server.+ - [ ] New root development paths have root-anchored exclusions in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass+ - [ ] If publishing root `skills/`, packaging validation and live verification of every gate and identifier claim pass

version

0.5.2 → 0.5.3

version

0.5.1 → 0.5.2

https://raw.githubusercontent.com/cyanheads/calculator-mcp-server/HEAD/AGENTS.md

− **Version:** 0.5.0− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`− **MCP SDK:** `@modelcontextprotocol/server` 2.0.0− When the user asks what to do next, what's left, or needs direction, suggest relevant options based on the current project state:− 3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills− 8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps (injection, blast radius, input sinks, tenant isolation)− | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino and `notifications/message` to the client, so treat it as client-visible. |− | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |− | `ctx.inputs` | Reader over a retried request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped`. Empty on the first round. |− | `ctx.enrich` | Success-path agent context — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches both response surfaces only when the definition declares an `enrichment` block. |− | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)`. Prepended to `content[]`; never enters `structuredContent`. |− | `ctx.requestId` | Unique request ID. |− | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |− **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. `recovery` is required (≥ 5 words) and is the single source of truth for the agent's next move. Pass `ctx.recoveryFor('reason')` as the throw's data to put it on the−   if (!item) throw ctx.fail('no_match', `No item ${input.id}`, ctx.recoveryFor('no_match'));− **Declare contracts inline on each tool, even when similar across tools.** The contract is part of the tool's documented public surface — reading one tool definition file should give the full picture (input, output, errors, handler, format). Don't extract a shared `errors[]` constant or contract module to deduplicate; per-tool repetition is the intended cost of locality, and dynamic `recovery` hints often need tool-specific context anyway.− **Fallback (no contract entry fits, prototype tools, service-layer code):** throw via factories or plain `Error`.− // Error factories — explicit code, concise− import { notFound, validationError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';− throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });− Available factories: `invalidParams`, `invalidRequest`, `notFound`, `forbidden`, `unauthorized`, `validationError`, `conflict`, `rateLimited`, `timeout`, `serviceUnavailable`, `configurationError`, `internalError`, `serializationError`, `databaseError`. For HTTP responses from upstream APIs, use `httpErrorFromResponse(response, { service, data })` from `/utils`.− See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table and contract reference.− Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the registry. Keep development skills out of the plugin-host auto-loaded root `skills/` directory.− | `code-simplifier` | Post-session code review and cleanup against `git diff` — modernize syntax, consolidate duplication, align with codebase |− | `git-wrapup` | Land working-tree changes as a commit stack — version bump, changelog, verify, commit by concern. No tag or push to main. |− | `techniques` | Reusable response/data-shaping patterns (outline-on-overflow, capped-list disclosure) |− | `release-pr-review` | Review an open release PR; applies only to projects declaring release PR mode. |− | `release-and-publish` | Tag + push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |− | `api-context` | Context interface, logger, state, input requests, enrichment |− | `api-mirror` | MirrorService: persistent SQLite-backed local mirror of bulk upstream datasets — Tier 3 opt-in, Node/Bun only |− | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |− | `bun run audit:fix` | Upgrade vulnerable packages within existing ranges via `bun audit fix`; first response to a transitive advisory. |− | `bun run audit:refresh` | Delete `bun.lock`, reinstall, and audit. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe`; re-resolves every ranged dependency. |− | `bun run list-skills` | Print skill index from `framework-skills/` frontmatter |− | `bun run lint:mcp` | Validate MCP definitions |− | `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` |− | `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |− | `bun run test` | Run tests |− | `bun run start:stdio` | Production mode (stdio) |− | `bun run start:http` | Production mode (HTTP) |+ **Version:** 0.5.1+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0+ When the user asks what's next or needs direction, suggest options based on the current project state. Common next steps:+ 3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills+ 8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation+ - **Cut noise.** Add only what earns its place: no speculative generality, no guards for states the framework already prevents (Zod-validated params, classified errors), no abstraction until a third caller proves it, no option nothing sets.+ `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`CALC_MAX_RESULT_LENGTH`) not the path (`maxResultLength`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.+ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.+ ### Server identity and instructions+ `createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):+ ```ts+ await createApp({+   name: 'my-mcp-server',+   title: 'My Server',                         // human-readable display name+   websiteUrl: 'https://github.com/owner/repo', // canonical homepage URL+   description: 'One-line description.',        // wins over MCP_SERVER_DESCRIPTION+   icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],+   instructions: 'Use shortcut alpha for the most common case.', // session-level context+ });+ ```+ `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.+ ### Session posture and shutdown+ Two more `createApp()` options shape how the server runs rather than how it presents itself:+ ```ts+ await createApp({+   sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }+   setup(core) { startMyWatcher(core.config); },+   async teardown() { await stopMyWatcher(); },+ });+ ```+ `sessionMode` declares the HTTP session posture in `src/` instead of leaving it to a deployment's `MCP_SESSION_MODE`, which still wins whenever it carries a meaningful value (an empty string and an unsubstituted `${…}` placeholder read as unset and fall through to the option). Add `require: 'stateful'` when a tool asks the caller for input mid-handler via `ctx.requestInput`: startup then fails with a `ConfigurationError` rather than serving a mode in which a 2025-era client can never answer the + `teardown(core)` is the `setup()` counterpart — release a watcher, socket, or non-`unref()`'d timer there. It runs after the transport stops and before the logger closes, on every shutdown path, and a signal-triggered shutdown then exits the process explicitly (0, or 1 if a step never settles within the framework's 10 s ceiling).+ | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. Dual-sink: Pino **and** `notifications/message` to the client, so treat it as client-visible. |+ | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.getMany(keys)`, `.list(prefix, { cursor, limit })`. Accepts any JSON-serializable value; reads return its JSON form (a `Date` comes back as an ISO string). |+ | `ctx.inputs` | The request's responses — `.accepted(key, schema)`, `.view(key)`, `.state()`, `.dropped` — limited to what the client declared (`elicitation` and its form/url modes, `sampling`, `roots`). Client-supplied: a consent gate trusts only a `ctx.state` record it stored when it asked, bound to the operation, caller, and target (see the `api-context` skill). |+ | `ctx.clientCapabilities` | What the client declared for this request, `undefined` when no view exists. Decides whether to ask for optional context (e.g. roots); never a reason to skip a consent prompt. |+ | `ctx.enrich` | Success-path agent context (empty-result notices, query echo, pagination totals) — `ctx.enrich(...)` or `.notice()` / `.total()` / `.echo()` / `.truncated()`. Reaches `structuredContent` and `content[]`; lands only when the definition declares an `enrichment` block (no-op otherwise). |+ | `ctx.content` | Non-text content blocks — `.image(data, mimeType)`, `.audio(data, mimeType)`, or `ctx.content(block)` for a raw block. Prepended to `content[]` after `format()`; never enters `structuredContent`. |+ | `ctx.requestId` | Request ID — the one every log record of the call carries and its error envelope returns as `data.requestId`. |

Showing the first 40 of each.

version

0.5.0 → 0.5.1