@cyanheads/workflows-mcp-server 0.2.0 → 0.3.1

package/AGENTS.md

@@ -0,0 +1,364 @@
+# Agent Protocol
+
+**Server:** @cyanheads/workflows-mcp-server
+**Version:** 0.3.1
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.5`
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
+**Zod:** ^4.5.4
+
+> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
+
+---
+
+## What's Next?
+
+When the user asks what's next or needs direction, suggest options based on the current project state. Common next steps:
+
+1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
+2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
+4. **Add services** — scaffold domain service integrations using the `add-service` skill
+5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
+6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
+7. **Run `devcheck`** — lint, format, typecheck, and security audit
+8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
+9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
+10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
+
+Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
+
+---
+
+## Core Rules
+
+- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
+- **Use `ctx.log`** for request-scoped logging. No `console` calls.
+- **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
+- **Need caller input?** Return `ctx.requestInput(...)`; the handler is re-entered with answers in `ctx.inputs`. Never await input mid-handler.
+- **Secrets in env vars only** — never hardcoded.
+- **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
+
+---
+
+## Patterns
+
+### Tool
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getWorkflowIndexService } from '@/services/workflow-index/workflow-index-service.js';
+
+export const workflowList = tool('workflow_list', {
+  description: 'List all permanent workflows in the index. Supports optional filtering by category and tags (AND match).',
+  annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  input: z.object({
+    category: z.string().optional().describe('Filter by category (case-insensitive substring).'),
+    tags: z.array(z.string()).optional().describe('Filter to workflows that have ALL of these tags.'),
+    includeTools: z.boolean().optional().describe('When true, include unique server/tool pairs per workflow.'),
+  }),
+  output: z.object({
+    workflows: z.array(z.object({ name: z.string().describe('Workflow name.'), /* ... */ })).describe('Matching workflows.'),
+    totalCount: z.number().describe('Total number of matching workflows.'),
+  }),
+  errors: [
+    { reason: 'index_unavailable', code: JsonRpcErrorCode.ServiceUnavailable,
+      when: 'The workflow index has not finished building yet.',
+      recovery: 'Retry after the server has finished initializing its workflow index.' },
+  ],
+  handler(input, ctx) {
+    const svc = getWorkflowIndexService();
+    if (!svc.ready) throw ctx.fail('index_unavailable', 'Index not ready', ctx.recoveryFor('index_unavailable'));
+    // ... filter and return results
+    return { workflows: [], totalCount: 0 };
+  },
+  format: (result) => [{ type: 'text', text: `**Total:** ${result.totalCount}` }],
+});
+```
+
+### Server config
+
+```ts
+// src/config/server-config.ts — lazy-parsed, separate from framework config
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+
+const ServerConfigSchema = z.object({
+  workflowsDir: z
+    .string()
+    .default('./workflows-yaml')
+    .describe('Absolute or relative path to the workflows root directory'),
+  globalInstructionsPath: z
+    .string()
+    .default('')
+    .describe('Path to the global instructions markdown file. Empty string means derive from WORKFLOWS_DIR.'),
+  watcherDebounceMs: z.coerce
+    .number()
+    .default(500)
+    .describe('Milliseconds to debounce filesystem change events before rebuilding the index'),
+});
+
+let _config: z.infer<typeof ServerConfigSchema> | undefined;
+export function getServerConfig() {
+  _config ??= parseEnvConfig(ServerConfigSchema, {
+    workflowsDir: 'WORKFLOWS_DIR',
+    globalInstructionsPath: 'GLOBAL_INSTRUCTIONS_PATH',
+    watcherDebounceMs: 'WATCHER_DEBOUNCE_MS',
+  });
+  return _config;
+}
+```
+
+`parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`WORKFLOWS_DIR`) not the path (`workflowsDir`). 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
+
+Framework identity (`name`, `version`, `description`, `keywords`) and a relative `LOGS_DIR` resolve against the **application root** — the nearest `package.json` at or above the process entry module — never the launching client's working directory. Server-specific paths like `WORKFLOWS_DIR` are this server's own config and still resolve against `process.cwd()`, so a relative default points at the caller's workflow library rather than the installed package.
+
+`createApp()` declares `name` + `title` only. `description`, `version`, and `keywords` derive from `package.json` — restating them in the call is drift, not configuration. `instructions` is optional server-level orientation sent on every `initialize`; use it for deployment guidance instead of repeating the same context across tool descriptions.
+
+---
+
+## Context
+
+Handlers receive a unified `ctx` object. Key properties:
+
+| Property | Description |
+|:---------|:------------|
+| `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.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present, but a 2025-era HTTP client cannot answer under `MCP_SESSION_MODE=stateless` — treat an unanswered round as terminal, never as consent. |
+| `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 that reaches both `structuredContent` and `content[]` when the definition declares an `enrichment` block. |
+| `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.signal` | `AbortSignal` for cancellation. |
+| `ctx.requestId` | Unique request ID. |
+| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
+| `ctx.fail` | Typed error factory for declared error contracts — `ctx.fail('reason', msg, ctx.recoveryFor('reason'))`. |
+
+---
+
+## Errors
+
+Handlers throw — the framework catches, classifies, and formats.
+
+**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 at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) 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 wire (`data.recovery.hint`, mirrored into `content[]` text); override it explicitly when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
+
+```ts
+errors: [
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No item matched the query',
+    recovery: 'Broaden the query or check the spelling and try again.' },
+],
+async handler(input, ctx) {
+  const item = await db.find(input.id);
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
+  return item;
+}
+```
+
+**Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
+
+**Fallback (no contract entry fits):** throw via factories or plain `Error`.
+
+```ts
+// Error factories — explicit code
+import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+throw notFound('Item not found', { itemId });
+throw serviceUnavailable('API unavailable', { url }, { cause: err });
+
+// Plain Error — framework auto-classifies from message patterns
+throw new Error('Item not found');           // → NotFound
+throw new Error('Invalid query format');     // → ValidationError
+
+// McpError — when no factory exists for the code
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
+```
+
+See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
+
+---
+
+## Structure
+
+```text
+src/
+  index.ts                              # createApp() entry point — registers tools, inits WorkflowIndexService
+  config/
+    server-config.ts                    # Server-specific env vars (WORKFLOWS_DIR, GLOBAL_INSTRUCTIONS_PATH, WATCHER_DEBOUNCE_MS)
+  services/
+    workflow-index/
+      workflow-index-service.ts         # WorkflowIndexService — index build, watcher, semver lookup, write helpers
+      types.ts                          # ParsedWorkflow, WorkflowEntry, WorkflowIndex types
+  mcp-server/
+    tools/definitions/
+      workflow-list.tool.ts             # workflow_list — list permanent workflows with filters
+      workflow-get.tool.ts              # workflow_get — retrieve full workflow + global instructions
+      workflow-create.tool.ts           # workflow_create — write permanent workflow YAML
+      workflow-create-temp.tool.ts      # workflow_create_temp — write temporary workflow
+      index.ts                          # Barrel export
+workflows-yaml/                         # Workflow library root (configurable via WORKFLOWS_DIR)
+  categories/                           # Permanent workflows organized by category
+  temp/                                 # Temporary workflows (gitignored)
+  global_instructions.md                # Global instructions injected into every workflow_get response
+  _index.json                           # Auto-generated snapshot (gitignored)
+```
+
+---
+
+## Naming
+
+| What | Convention | Example |
+|:-----|:-----------|:--------|
+| Files | kebab-case with suffix | `search-docs.tool.ts` |
+| Tool/resource/prompt names | snake_case | `search_docs` |
+| Directories | kebab-case | `src/services/doc-search/` |
+| Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` |
+
+---
+
+## Skills
+
+Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
+
+**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
+
+Available skills:
+
+| Skill | Purpose |
+|:------|:--------|
+| `setup` | Post-init project orientation |
+| `design-mcp-server` | Design tool surface, resources, and services for a new server |
+| `add-tool` | Scaffold a new tool definition |
+| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
+| `add-resource` | Scaffold a new resource definition |
+| `add-prompt` | Scaffold a new prompt definition |
+| `add-service` | Scaffold a new service integration |
+| `add-test` | Scaffold test file for a tool, resource, or service |
+| `add-export` | Add or evolve a public framework export without leaking internal module paths |
+| `add-provider` | Add a provider integration with config, lifecycle, errors, and tests |
+| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
+| `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
+| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
+| `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
+| `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
+| `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
+| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
+| `orchestrations` | Chain task skills into a gated multi-phase pipeline when sub-agents are available |
+| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
+| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
+| `api-auth` | Auth modes, scopes, JWT/OAuth |
+| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
+| `api-config` | AppConfig, parseConfig, env vars |
+| `api-context` | Context interface, logger, state, and multi-round-trip input |
+| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
+| `api-mirror` | MirrorService for a persistent, self-refreshing local mirror of a bulk upstream dataset |
+| `api-services` | LLM, Speech, Graph services |
+| `api-testing` | createMockContext, fixtures, fetch mocks, and definition contract tests |
+| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
+| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
+| `api-workers` | Cloudflare Workers runtime |
+
+When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
+
+---
+
+## Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| `bun run build` | Compile TypeScript |
+| `bun run rebuild` | Clean + build |
+| `bun run clean` | Remove build artifacts |
+| `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
+| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
+| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
+| `bun run list-skills` | Print the skill registry |
+| `bun run tree` | Generate directory structure doc |
+| `bun run format` | Auto-fix formatting (safe fixes only) |
+| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
+| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
+| `bun run test:coverage` | Run tests with Istanbul coverage |
+| `bun run start:stdio` | Production mode (stdio) |
+| `bun run start:http` | Production mode (HTTP) |
+| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
+| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
+| `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+
+---
+
+## Bundling
+
+`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 (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+
+**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
+
+**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
+
+---
+
+## Changelog
+
+Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
+
+Each per-version file opens with YAML frontmatter:
+
+```markdown
+---
+summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
+breaking: false                            # optional — true flags breaking changes
+security: false                            # optional — true ONLY for a source-code security fix, never a dependency CVE bump
+---
+
+# 0.1.0 — YYYY-MM-DD
+...
+```
+
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+
+`agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
+
+**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
+
+**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
+
+---
+
+## Imports
+
+```ts
+// Framework — z is re-exported, no separate zod import needed
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+// Server's own code — via path alias
+import { getMyService } from '@/services/my-domain/my-service.js';
+```
+
+---
+
+## Checklist
+
+- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
+- [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
+- [ ] JSDoc `@fileoverview` + `@module` on every file
+- [ ] `ctx.log` for logging, `ctx.state` for storage
+- [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
+- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
+- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
+- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
+- [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
+- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
+- [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = package name; `interface.shortDescription` from `package.json` description
+- [ ] `.codex-plugin/mcp.json` updated — server name key matches `package.json` name; env vars added for any required API keys
+- [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; inline `mcpServers` entry with server name key, env vars for any required API keys
+- [ ] `bun run devcheck` passes

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Agent Protocol
 
 **Server:** @cyanheads/workflows-mcp-server
-**Version:** 0.2.0
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.10.10`
+**Version:** 0.3.1
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.12.5`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
-**Zod:** ^4.4.3
+**MCP SDK:** `@modelcontextprotocol/server` ^2.0.0
+**Zod:** ^4.5.4
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -35,7 +35,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
 - **Use `ctx.log`** for request-scoped logging. No `console` calls.
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
-- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
+- **Need caller input?** Return `ctx.requestInput(...)`; the handler is re-entered with answers in `ctx.inputs`. Never await input mid-handler.
 - **Secrets in env vars only** — never hardcoded.
 - **Close the loop on issues.** When implementing work tracked by a GitHub issue, comment on the issue with what landed and close it. Do both — a comment without a close leaves stale issues open; a close without a comment leaves no record of what shipped. The comment is for future readers — state the concrete changes, not the conversation that produced them.
 
@@ -112,6 +112,14 @@ export function getServerConfig() {
 
 `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`WORKFLOWS_DIR`) not the path (`workflowsDir`). 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
+
+Framework identity (`name`, `version`, `description`, `keywords`) and a relative `LOGS_DIR` resolve against the **application root** — the nearest `package.json` at or above the process entry module — never the launching client's working directory. Server-specific paths like `WORKFLOWS_DIR` are this server's own config and still resolve against `process.cwd()`, so a relative default points at the caller's workflow library rather than the installed package.
+
+`createApp()` declares `name` + `title` only. `description`, `version`, and `keywords` derive from `package.json` — restating them in the call is drift, not configuration. `instructions` is optional server-level orientation sent on every `initialize`; use it for deployment guidance instead of repeating the same context across tool descriptions.
+
 ---
 
 ## Context
@@ -120,10 +128,15 @@ Handlers receive a unified `ctx` object. Key properties:
 
 | Property | Description |
 |:---------|:------------|
-| `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
+| `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.requestInput` | Suspend and ask the caller for more input — `return ctx.requestInput({ inputRequests: { key: inputRequired.elicit({ message, requestedSchema }) } })`. Never returns; the handler is re-entered with the answers. Always present, but a 2025-era HTTP client cannot answer under `MCP_SESSION_MODE=stateless` — treat an unanswered round as terminal, never as consent. |
+| `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 that reaches both `structuredContent` and `content[]` when the definition declares an `enrichment` block. |
+| `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.signal` | `AbortSignal` for cancellation. |
 | `ctx.requestId` | Unique request ID. |
-| `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
+| `ctx.tenantId` | Tenant ID from JWT; `'default'` for stdio or HTTP with auth off. |
 | `ctx.fail` | Typed error factory for declared error contracts — `ctx.fail('reason', msg, ctx.recoveryFor('reason'))`. |
 
 ---
@@ -132,7 +145,7 @@ Handlers receive a unified `ctx` object. Key properties:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**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 at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+**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 at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required (≥ 5 words, lint-validated) 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 wire (`data.recovery.hint`, mirrored into `content[]` text); override it explicitly when dynamic runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble freely and don't need declaring.
 
 ```ts
 errors: [
@@ -210,7 +223,7 @@ workflows-yaml/                         # Workflow library root (configurable vi
 
 ## Skills
 
-Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
+Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry.
 
 **Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
@@ -226,25 +239,29 @@ Available skills:
 | `add-prompt` | Scaffold a new prompt definition |
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
+| `add-export` | Add or evolve a public framework export without leaking internal module paths |
+| `add-provider` | Add a provider integration with config, lifecycle, errors, and tests |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `tool-defs-analysis` | Read-only audit of MCP definition language across the surface — voice, leaks, defaults, recovery hints, output descriptions |
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
 | `code-simplifier` | Post-session cleanup against `git diff` — modernize syntax, consolidate duplication, align with the codebase |
-| `devcheck` | Lint, format, typecheck, audit |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `git-wrapup` | Land working-tree changes as a versioned commit + annotated tag — version bump, changelog, verify, tag. Local only. |
 | `release-and-publish` | Push + npm + MCP Registry + GH Release + Docker. Picks up from `git-wrapup` |
 | `maintenance` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
+| `orchestrations` | Chain task skills into a gated multi-phase pipeline when sub-agents are available |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
-| `api-context` | Context interface, logger, state, progress |
+| `api-context` | Context interface, logger, state, and multi-round-trip input |
 | `api-errors` | McpError, JsonRpcErrorCode, error patterns |
 | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
+| `api-mirror` | MirrorService for a persistent, self-refreshing local mirror of a bulk upstream dataset |
 | `api-services` | LLM, Speech, Graph services |
-| `api-testing` | createMockContext, test patterns |
+| `api-testing` | createMockContext, fixtures, fetch mocks, and definition contract tests |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
 | `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
@@ -262,9 +279,14 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run clean` | Remove build artifacts |
 | `bun run devcheck` | Lint + format + typecheck + security + changelog sync |
 | `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
+| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
+| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
+| `bun run list-skills` | Print the skill registry |
 | `bun run tree` | Generate directory structure doc |
-| `bun run format` | Auto-fix formatting |
-| `bun run test` | Run tests |
+| `bun run format` | Auto-fix formatting (safe fixes only) |
+| `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
+| `bun run test` | Run tests (Vitest — use `bun run test`, not `bun test`) |
+| `bun run test:coverage` | Run tests with Istanbul coverage |
 | `bun run start:stdio` | Production mode (stdio) |
 | `bun run start:http` | Production mode (HTTP) |
 | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
@@ -275,44 +297,11 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Bundling
 
-`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`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 (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match.
 
-**README install badges.** Drop these into the project README to give users one-click install paths. Fill in `<OWNER>` / `<REPO>` / `<PACKAGE_NAME>` and encode the per-server config. Cursor + VS Code badges assume the server is published to npm; Claude Desktop downloads the `.mcpb` directly so npm publishing isn't required.
-
-| Client | Mechanism |
-|:-------|:----------|
-| Claude Desktop | Browser downloads the `.mcpb` from the latest GitHub Release; OS file handler routes it to Claude Desktop, which opens the install dialog. No deep-link URL scheme yet — this is the canonical path. |
-| Cursor | Official `https://cursor.com/en/install-mcp` endpoint with base64 JSON config. |
-| VS Code / Insiders | Official `vscode:mcp/install?...` deep link, wrapped in `https://vscode.dev/redirect?url=` so GitHub-rendered markdown doesn't strip the non-HTTP scheme. |
-| Claude Code / Codex | CLI only (`claude mcp add` / `codex mcp add`); no URL scheme. |
-
-```markdown
-[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/<OWNER>/<REPO>/releases/latest/download/<PACKAGE_NAME>.mcpb)
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=<PACKAGE_NAME>&config=<BASE64_CONFIG>)
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?<URLENCODED_JSON>)
-```
-
-Both install links route through HTTPS endpoints (`cursor.com/en/install-mcp` and `vscode.dev/redirect`) — GitHub-rendered markdown strips non-HTTP URL schemes from anchors, so a raw `cursor://` or `vscode:` link won't click through from github.com.
-
-Generate the encoded configs (replace `<PACKAGE_NAME>` and add env vars for any required API keys):
-
-```bash
-# Cursor: base64-encoded JSON. Split command/args, add env when keys are needed.
-echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"],"env":{"API_KEY":"your-api-key"}}' | base64
-# Without env (no required keys):
-echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
-
-# VS Code: URL-encoded JSON. Same shape plus a `name` field.
-node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"],env:{API_KEY:"your-api-key"}}))'
-# Without env:
-node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
-```
-
-Both clients use the same `{command, args, env}` shape (matching `mcp.json` schema). VS Code adds a top-level `name` field. Omit `env` entirely when no API keys are needed — don't include empty objects or framework-only vars like `MCP_TRANSPORT_TYPE`.
-
-The Claude Desktop badge requires the bundle to ship with a stable filename — `bun run bundle` outputs `dist/<PACKAGE_NAME>.mcpb`, and `release-and-publish` attaches that file to the GitHub Release. `releases/latest/download/<PACKAGE_NAME>.mcpb` then redirects to the most recent release.
+**README install badges** (Claude Desktop `.mcpb`, Cursor, VS Code) and the `base64` / `encodeURIComponent` config-generation commands are ship-time concerns — run the `polish-docs-meta` skill, which carries the badge format, layout, and generation snippets in `skills/polish-docs-meta/references/readme.md`.
 
 ---
 
@@ -326,14 +315,14 @@ Each per-version file opens with YAML frontmatter:
 ---
 summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
 breaking: false                            # optional — true flags breaking changes
-security: false                            # optional — true flags security fixes
+security: false                            # optional — true ONLY for a source-code security fix, never a dependency CVE bump
 ---
 
 # 0.1.0 — YYYY-MM-DD
 ...
 ```
 
-`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section — set it only for a security fix in this server's *own source code*, never for a routine dependency or transitive CVE bump (record those under `## Dependencies`). When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
 
 `agent-notes` is an optional free-form field for maintenance agents processing the release downstream. Content here won't appear in the rendered CHANGELOG — it's consumed by agents running the `maintenance` skill. Use it for adoption instructions that don't fit the human-facing sections: new files to create, fields to populate, one-time migration steps. Omit entirely when there's nothing to say.
 

package/Dockerfile

@@ -3,16 +3,28 @@
 #
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
+#
+# Pinned to $BUILDPLATFORM rather than the target platform: `bun run build` emits
+# JavaScript, and only `dist/` crosses into the production stage, which runs its
+# own target-arch install. Built for the target instead, the non-native leg of a
+# `--platform linux/amd64,linux/arm64` build runs under QEMU, where bun >= 1.4
+# aborts with a JavaScriptCore allocator assertion and fails the multi-arch push.
+#
+# The constraint this assumes: the build stage produces platform-independent
+# output. A stage that compiles a native addon needs the target-arch toolchain
+# and cannot cross-compile this way — drop the flag there.
 # ==============================================================================
-FROM oven/bun:1.3 AS build
+FROM --platform=$BUILDPLATFORM oven/bun:1.4.0 AS build
 
 WORKDIR /usr/src/app
 
 # Copy dependency manifests for optimized layer caching
 COPY package.json bun.lock ./
 
-# Install all dependencies (including dev dependencies for building)
-RUN bun install --frozen-lockfile
+# Install all dependencies (including dev dependencies for building).
+# The BuildKit cache mount persists Bun's global package cache across builds.
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --frozen-lockfile --ignore-scripts
 
 # Copy the rest of the source code
 COPY . .
@@ -28,7 +40,7 @@ RUN bun run build
 # application. It uses a slim base image and only includes production
 # dependencies and build artifacts.
 # ==============================================================================
-FROM oven/bun:1.3-slim AS production
+FROM oven/bun:1.4.0-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -37,24 +49,30 @@ WORKDIR /usr/src/app
 ENV NODE_ENV=production
 
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
-LABEL org.opencontainers.image.title="@cyanheads/workflows-mcp-server"
+ARG APP_VERSION
+LABEL org.opencontainers.image.title="workflows-mcp-server"
 LABEL org.opencontainers.image.description="Store, query, and create YAML workflow playbooks for LLM agents via MCP."
 LABEL org.opencontainers.image.source="https://github.com/cyanheads/workflows-mcp-server"
 LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.version="${APP_VERSION}"
+LABEL io.modelcontextprotocol.server.name="io.github.cyanheads/workflows-mcp-server"
 
 # Copy dependency manifests
 COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
-# that are not needed in the final production image.
-RUN bun install --production --frozen-lockfile --ignore-scripts
+# that are not needed in the final production image. `--omit=peer` drops the
+# framework's optional service/test tiers; runtime imports remain direct deps.
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --production --omit=peer --frozen-lockfile --ignore-scripts
 
 # Conditionally install OpenTelemetry optional peer dependencies (Tier 3).
 # These are not bundled by default to keep the base image lean. Enable at build time
 # with: docker build --build-arg OTEL_ENABLED=true
 ARG OTEL_ENABLED=true
-RUN if [ "$OTEL_ENABLED" = "true" ]; then \
-      bun add @hono/otel \
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    if [ "$OTEL_ENABLED" = "true" ]; then \
+      bun add --omit=dev --omit=peer --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \
@@ -95,5 +113,8 @@ ENV MCP_FORCE_CONSOLE_LOGGING="true"
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}
 
+# Health check using a bun-native fetch (slim image ships no curl/wget)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD bun -e "fetch('http://localhost:'+(process.env.MCP_HTTP_PORT??'3010')+'/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
 # The command to start the server
 CMD ["bun", "run", "dist/index.js"]

package/LICENSE

@@ -186,7 +186,7 @@ Apache License
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Casey Hand @cyanheads
+   Copyright 2026 Casey Hand @cyanheads
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/workflows-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/workflows-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/workflows-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.3.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/workflows-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-v2-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/workflows-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/workflows-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -191,7 +191,7 @@ The repository ships a `workflows-yaml/` directory with example workflows organi
 
 ### Prerequisites
 
-- [Bun v1.3.2](https://bun.sh/) or higher (or Node.js v24+).
+- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).
 - A local directory containing YAML workflow files (or use the bundled `workflows-yaml/` seed).
 
 ### Installation

package/changelog/0.3.x/0.3.0.md

@@ -0,0 +1,40 @@
+---
+summary: "MCP SDK v2 maintenance with strict tool inputs, modern advertised schemas, TypeScript 7, Bun 1.4, supply-chain guards, and refreshed packaging and agent guidance."
+breaking: true
+security: false
+---
+
+# 0.3.0 — 2026-08-21
+
+## Added
+
+- **Supply-chain controls** — installs hold newly published third-party packages for three days and run the Socket security scanner; first-party `@cyanheads/mcp-ts-core` releases remain exempt from the age hold.
+- **Community health files** — adds contribution, conduct, funding, and private vulnerability-reporting guidance, plus repository-wide line-ending and generated-file attributes.
+
+## Changed
+
+- **MCP SDK v2** — `@cyanheads/mcp-ts-core` now serves protocol revision `2026-07-28` alongside 2025-era clients. Root tool inputs reject unknown keys instead of stripping them, and advertised input/output schemas use the SDK v2 contract, including the structured error envelope.
+- **TypeScript and test gate** — TypeScript 7 now typechecks both `src/` and `tests/`; test fixtures and handler assertions follow the framework's current async and output-schema types.
+- **Runtime packaging** — Bun 1.4 images use BuildKit caches, omit optional peer tiers in production, carry OCI/MCP identity labels and a health check, and build for the requested target platform.
+- **MCPB and release tooling** — bundle cleanup strips platform-specific DuckDB native bindings as well as dependency-shipped agent docs; packaging lint verifies both classes, and GitHub Release creation uses the repository release script.
+- **Framework maintenance surface** — development scripts, changelog conventions, and agent skills are synchronized with `@cyanheads/mcp-ts-core` 0.12.3, including SDK v2 context, testing, schema, cache-hint, and header-parameter guidance.
+- **Project metadata** — package authorship and MCPB author metadata use Casey Hand's canonical identity, and the Apache-2.0 copyright year is 2026.
+
+## Dependencies
+
+Runtime:
+
+- `@cyanheads/mcp-ts-core` `^0.10.10` → `^0.12.3`
+
+Development:
+
+- `@biomejs/biome` `^2.5.1` → `2.5.9`
+- `@socketsecurity/bun-security-scanner` added at `^1.1.2`
+- `@types/node` `^25.9.3` → `26.2.0`
+- `@types/semver` `^7.7.1` → `^7.8.0`
+- `@vitest/coverage-istanbul` `^4.1.9` → `4.1.11`
+- `fast-check` `^4.8.0` → `^4.9.0`
+- `ignore` `^7.0.5` → `^7.0.6`
+- `tsc-alias` `^1.8.17` → `^1.9.2`
+- `typescript` `^6.0.3` → `^7.0.2`
+- `vitest` `^4.1.9` → `^4.1.11`

package/changelog/0.3.x/0.3.1.md

@@ -0,0 +1,33 @@
+---
+summary: "Server identity now resolves from the served package instead of the caller's working directory, pre-init logs are no longer dropped, and MCP_SESSION_MODE settles to stateless. mcp-ts-core bumps to 0.12.5, zod to 4.5.4."
+breaking: false
+security: false
+---
+
+# 0.3.1 — 2026-09-04
+
+## Changed
+
+- **`.env.example` `MCP_SESSION_MODE`: `auto` → `stateless`**, matching the Docker image — this server declares no `ctx.requestInput` call sites and so needs no session-backed 2025-era elicitation shim. Verified: `GET /mcp` now advertises `sessionMode: "stateless"`.
+- **Server identity resolves from the served package, not the caller's working directory** (mcp-ts-core 0.12.5) — `resolveAppRoot()` reads the nearest `package.json` above the process entry module. Verified: launched from a scratch directory whose own `package.json` declared an unrelated project, `GET /mcp` still returned this server's own name, version, and description.
+- **Pre-init log records are replayed instead of dropped** (mcp-ts-core 0.12.5) — verified in the startup log: `createStorageProvider` and `OpenRouterProvider.constructor` records now appear despite predating `loggerInit`.
+- A caller disconnect mid-call now classifies as `RequestCancelled` (-32011) rather than `InternalError`, and the HTTP transport answers 499 (mcp-ts-core 0.12.4).
+- `manifest.json` `author.name`: `Casey Hand` → `cyanheads`, matching fleet convention.
+- Dockerfile build stage carries a new comment explaining why it pins `$BUILDPLATFORM`.
+- Skills and agent docs synced with mcp-ts-core 0.12.5 — 11 `skills/` files plus the `CLAUDE.md`/`AGENTS.md` templates.
+
+## Dependencies
+
+Runtime:
+
+- `@cyanheads/mcp-ts-core` `^0.12.3` → `^0.12.5`
+- `zod` `^4.4.3` → `^4.5.4`
+
+Development:
+
+- `@biomejs/biome` `2.5.9` → `2.5.11`
+- `@types/node` `26.2.0` → `26.4.0`
+- `ignore` `^7.0.6` → `^7.0.8`
+- `tsc-alias` `^1.9.2` → `^1.9.3`
+
+The lockfile re-resolve also cleared 8 transitive advisories (`fast-uri` `3.1.5` → `3.1.6`, `browserslist` `4.28.4` → `4.28.8`, `qs` `6.15.3` → `6.16.0`); `bun audit` now reports no vulnerabilities across 375 packages.

package/changelog/template.md

@@ -4,10 +4,11 @@
 # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
 # with a concrete date.
 
-# Required. One-line GitHub Release-style headline. 350 character cap.
-# Default short and scannable. Don't pad, don't stitch unrelated changes with
-# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
-# inside the value as a key separator and fails GitHub's strict parser.
+# Required. One-line GitHub Release-style headline. 350 character cap — a
+# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
+# unrelated changes with commas/semicolons into an inventory — pick the
+# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
 # Set `true` when consumers must change code to upgrade: API removals,
@@ -15,16 +16,19 @@ summary: ""
 # usage. Flagged as `Breaking` in the rollup.
 breaking: false
 
-# Set `true` if this release contains any security fix. Pairs with the
-# `## Security` section below. Flagged as `Security` in the rollup so
-# users can triage upgrade urgency at a glance.
+# Set `true` ONLY for a security fix in THIS project's own source code — a
+# vulnerability or hardening in code you ship. A dependency or transitive CVE
+# bump is routine maintenance, NOT a security release: record it under
+# `## Dependencies` (with the advisory ID) and leave this `false`. When true,
+# pairs with the `## Security` section below and flags `Security` in the rollup.
 security: false
 
 # Optional free-form notes for maintenance agents processing this release.
 # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
-# downstream servers. Use for adoption instructions that don't fit the
-# human-facing sections: new files to create, fields to populate, one-time
-# migration steps. Omit the field entirely when there's nothing to say.
+# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
+# populate, one-time migration steps. Never a second rendering of the body:
+# if a body bullet already says it, name the bullet's symbol instead of
+# re-explaining. Omit the field entirely when there's nothing to say.
 # agent-notes: |
 #   <instructions for downstream maintenance agents>
 ---
@@ -39,17 +43,54 @@ security: false
   each bullet with the symbol or concept name in **bold** so they can skip
   what's irrelevant and zoom in on what's not.
 
-  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
-  name the symbol, state what changed, stop. Use a second sentence only when
-  it carries weight. If a bullet feels long, it is.
-
-  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
-  relevant skill), ceremonial framings ("This release introduces…",
-  backwards-compat paragraphs), file-by-file test enumerations, internal
-  implementation notes. Prefer code/symbol names over English re-explanations.
+  Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
+  changed + at most one consumer-facing caveat. One sentence by default, two
+  when the second carries weight — a bullet past ~40 words or three sentences
+  is wrong. The depth lives one hop away: the linked issue carries the why,
+  the commit diff carries the how. The changelog names what changed and what
+  a consumer does about it; a reader who wants mechanism opens the link.
+
+  Model length on THIS guide, never on the previous entry — entries modeled
+  on entries compound.
+
+  Cut (each has shipped as a wall of text; these are the cruft):
+  - History/justification narration — how the bug worked, why the old
+    behavior was wrong. One short clause at most; the issue carries the story.
+  - Design-rationale defense — "chosen over Y because…", "guarding the
+    getter is not enough…". That is the author arguing with a reviewer;
+    reviewers read the PR, not the changelog.
+  - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
+    <prev>". Keep one only where its absence would cause a real misread,
+    as a short parenthetical.
+  - Edge-case inventories — marker lists, not-flagged lists, escape tables.
+    Tests and the issue carry those.
+  - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
+    skill own those), ceremonial framings ("This release introduces…"),
+    backwards-compat paragraphs, file-by-file test enumerations. Prefer
+    code/symbol names over English re-explanations.
+
+  Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
+  the TRUTH of what you write, never the AMOUNT.
+
+  Example — same fact, right size:
+
+    TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
+    (#341). `fetch` resolves once headers arrive and the deadline was
+    cleared as the helper returned, so a peer that answered promptly and
+    then stalled the stream held the request open indefinitely. A 2xx
+    carrying a body now comes back as a passthrough wrapper that disarms
+    the deadline when the body closes, errors, or is cancelled; …
+    [+90 more words of mechanism and edge cases]
+
+    RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
+    exchange, not just the headers** (#341). A stalled body aborts with
+    the same `Timeout` error; the returned `Response` is a wrapper, so
+    identity assertions (`toBe(response)`) no longer hold.
 
   Narrative intro: skip by default. Add one short sentence only when the
-  release theme genuinely needs framing the bullets can't carry.
+  release theme genuinely needs framing the bullets can't carry. When many
+  bullets share one upgrade consequence, state it ONCE — intro line or
+  agent-notes — never per bullet.
 
   Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
   Fixed, Security. Include only sections with entries; delete the rest

package/dist/mcp-server/tools/definitions/index.d.ts

@@ -8,43 +8,6 @@ export { workflowDelete } from './workflow-delete.tool.js';
 export { workflowGet } from './workflow-get.tool.js';
 export { workflowList } from './workflow-list.tool.js';
 export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
-    name: import("zod").ZodString;
-    version: import("zod").ZodString;
-    description: import("zod").ZodString;
-    author: import("zod").ZodString;
-    category: import("zod").ZodString;
-    tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
-    steps: import("zod").ZodArray<import("zod").ZodObject<{
-        server: import("zod").ZodString;
-        tool: import("zod").ZodString;
-        action: import("zod").ZodOptional<import("zod").ZodString>;
-        description: import("zod").ZodOptional<import("zod").ZodString>;
-        name: import("zod").ZodOptional<import("zod").ZodString>;
-        params: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
-        forEach: import("zod").ZodOptional<import("zod").ZodString>;
-    }, import("zod/v4/core").$strip>>;
-}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
-    status: import("zod").ZodLiteral<"created">;
-    filePath: import("zod").ZodString;
-    key: import("zod").ZodString;
-    created_date: import("zod").ZodString;
-    last_updated_date: import("zod").ZodString;
-}, import("zod/v4/core").$strip>, readonly [{
-    readonly reason: "invalid_input";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "A field passed schema validation but is semantically invalid: a blank/whitespace-only category, a category that slugifies to empty, or a name that slugifies to empty or exceeds the filename length limit.";
-    readonly recovery: "Provide a category and workflow name that each contain alphanumeric characters, and keep the name under 200 characters after slugification.";
-}, {
-    readonly reason: "already_exists";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Conflict;
-    readonly when: "A permanent workflow with this name@version already exists in the index.";
-    readonly recovery: "Change the version field or use a different name to avoid the conflict.";
-}, {
-    readonly reason: "write_failed";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InternalError;
-    readonly when: "Filesystem write error such as insufficient permissions or a full disk.";
-    readonly recovery: "Check that the workflows directory is writable and has sufficient disk space, then retry.";
-}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     name: import("zod").ZodString;
     version: import("zod").ZodString;
     description: import("zod").ZodString;
@@ -76,33 +39,29 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
     readonly when: "Filesystem write error such as insufficient permissions or a full disk.";
     readonly recovery: "Check that the workflows directory is writable and has sufficient disk space, then retry.";
 }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
-    name: import("zod").ZodString;
-    version: import("zod").ZodOptional<import("zod").ZodString>;
+    query: import("zod").ZodOptional<import("zod").ZodString>;
+    category: import("zod").ZodOptional<import("zod").ZodString>;
+    tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    includeTools: import("zod").ZodOptional<import("zod").ZodBoolean>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
-    status: import("zod").ZodLiteral<"deleted">;
-    name: import("zod").ZodString;
-    version: import("zod").ZodString;
+    workflows: import("zod").ZodArray<import("zod").ZodObject<{
+        name: import("zod").ZodString;
+        version: import("zod").ZodString;
+        description: import("zod").ZodString;
+        author: import("zod").ZodString;
+        category: import("zod").ZodOptional<import("zod").ZodString>;
+        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        tools: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    }, import("zod/v4/core").$strip>>;
+    totalCount: import("zod").ZodNumber;
 }, import("zod/v4/core").$strip>, readonly [{
-    readonly reason: "not_found";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
-    readonly when: "No permanent workflow matches the given name, or the given name and version.";
-    readonly recovery: "Use workflow_list to see available workflow names and versions, then retry; omit version to target the latest.";
-}, {
-    readonly reason: "temp_not_allowed";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
-    readonly when: "The resolved workflow is temporary, and temporary workflows cannot be deleted.";
-    readonly recovery: "Leave temporary workflows to expire on their own — only permanent workflows can be deleted here.";
-}, {
-    readonly reason: "delete_failed";
-    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InternalError;
-    readonly when: "Filesystem error while removing the workflow file, such as insufficient permissions.";
-    readonly recovery: "Check that the workflows directory is writable, then retry the deletion.";
-}, {
     readonly reason: "index_unavailable";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
     readonly when: "The workflow index has not finished building yet.";
     readonly recovery: "Retry after the server has finished initializing its workflow index.";
-}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}], {
+    readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
+}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     name: import("zod").ZodString;
     version: import("zod").ZodOptional<import("zod").ZodString>;
 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
@@ -128,8 +87,8 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
     }, import("zod/v4/core").$strip>;
     globalInstructions: import("zod").ZodNullable<import("zod").ZodString>;
     source: import("zod").ZodEnum<{
-        temp: "temp";
         permanent: "permanent";
+        temp: "temp";
     }>;
 }, import("zod/v4/core").$strip>, readonly [{
     readonly reason: "not_found";
@@ -147,27 +106,68 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
     readonly when: "The workflow index has not finished building yet.";
     readonly recovery: "Retry after the server has finished initializing its workflow index.";
 }], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
-    query: import("zod").ZodOptional<import("zod").ZodString>;
-    category: import("zod").ZodOptional<import("zod").ZodString>;
+    name: import("zod").ZodString;
+    version: import("zod").ZodString;
+    description: import("zod").ZodString;
+    author: import("zod").ZodString;
+    category: import("zod").ZodString;
     tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
-    includeTools: import("zod").ZodOptional<import("zod").ZodBoolean>;
-}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
-    workflows: import("zod").ZodArray<import("zod").ZodObject<{
-        name: import("zod").ZodString;
-        version: import("zod").ZodString;
-        description: import("zod").ZodString;
-        author: import("zod").ZodString;
-        category: import("zod").ZodOptional<import("zod").ZodString>;
-        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
-        tools: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    steps: import("zod").ZodArray<import("zod").ZodObject<{
+        server: import("zod").ZodString;
+        tool: import("zod").ZodString;
+        action: import("zod").ZodOptional<import("zod").ZodString>;
+        description: import("zod").ZodOptional<import("zod").ZodString>;
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        params: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
+        forEach: import("zod").ZodOptional<import("zod").ZodString>;
     }, import("zod/v4/core").$strip>>;
-    totalCount: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    status: import("zod").ZodLiteral<"created">;
+    filePath: import("zod").ZodString;
+    key: import("zod").ZodString;
+    created_date: import("zod").ZodString;
+    last_updated_date: import("zod").ZodString;
 }, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "invalid_input";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "A field passed schema validation but is semantically invalid: a blank/whitespace-only category, a category that slugifies to empty, or a name that slugifies to empty or exceeds the filename length limit.";
+    readonly recovery: "Provide a category and workflow name that each contain alphanumeric characters, and keep the name under 200 characters after slugification.";
+}, {
+    readonly reason: "already_exists";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.Conflict;
+    readonly when: "A permanent workflow with this name@version already exists in the index.";
+    readonly recovery: "Change the version field or use a different name to avoid the conflict.";
+}, {
+    readonly reason: "write_failed";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InternalError;
+    readonly when: "Filesystem write error such as insufficient permissions or a full disk.";
+    readonly recovery: "Check that the workflows directory is writable and has sufficient disk space, then retry.";
+}], undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    name: import("zod").ZodString;
+    version: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    status: import("zod").ZodLiteral<"deleted">;
+    name: import("zod").ZodString;
+    version: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "No permanent workflow matches the given name, or the given name and version.";
+    readonly recovery: "Use workflow_list to see available workflow names and versions, then retry; omit version to target the latest.";
+}, {
+    readonly reason: "temp_not_allowed";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "The resolved workflow is temporary, and temporary workflows cannot be deleted.";
+    readonly recovery: "Leave temporary workflows to expire on their own — only permanent workflows can be deleted here.";
+}, {
+    readonly reason: "delete_failed";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InternalError;
+    readonly when: "Filesystem error while removing the workflow file, such as insufficient permissions.";
+    readonly recovery: "Check that the workflows directory is writable, then retry the deletion.";
+}, {
     readonly reason: "index_unavailable";
     readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
     readonly when: "The workflow index has not finished building yet.";
     readonly recovery: "Retry after the server has finished initializing its workflow index.";
-}], {
-    readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
-}>)[];
+}], undefined>)[];
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/tools/definitions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAQvD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAM9B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAQvD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM9B,CAAC"}

package/dist/mcp-server/tools/definitions/workflow-get.tool.d.ts

@@ -30,8 +30,8 @@ export declare const workflowGet: import("@cyanheads/mcp-ts-core").ToolDefinitio
     }, z.core.$strip>;
     globalInstructions: z.ZodNullable<z.ZodString>;
     source: z.ZodEnum<{
-        temp: "temp";
         permanent: "permanent";
+        temp: "temp";
     }>;
 }, z.core.$strip>, readonly [{
     readonly reason: "not_found";

package/dist/services/workflow-index/workflow-index-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-index-service.d.ts","sourceRoot":"","sources":["../../../src/services/workflow-index/workflow-index-service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,OAAO,KAAK,EAAiB,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+C9F,qEAAqE;AACrE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7C;AA0CD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,kBAAkB,CAA8B;IACxD,OAAO,CAAC,cAAc,CAA4C;IAClE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAE/B,YAAY,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM;IAQ3F,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,mCAAmC;IACnC,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,oEAAoE;IAC9D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,6BAA6B;IAC7B,QAAQ,IAAI,IAAI;IAOhB,8DAA8D;IAC9D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE;IAQzC,oFAAoF;IACpF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAUvE,yEAAyE;IACnE,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUtD,6DAA6D;IACvD,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAuD/D,6DAA6D;IACvD,SAAS,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB1D;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;YA6BlF,OAAO;YAuBP,aAAa;YAwBb,QAAQ;YAwCR,aAAa;IAsB3B,OAAO,CAAC,YAAY;IAiCpB,OAAO,CAAC,gBAAgB;CAKzB;AAQD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,MAAM,EACpB,sBAAsB,EAAE,MAAM,EAC9B,iBAAiB,EAAE,MAAM,GACxB,IAAI,CAKN;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAO9D"}
+{"version":3,"file":"workflow-index-service.d.ts","sourceRoot":"","sources":["../../../src/services/workflow-index/workflow-index-service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,OAAO,KAAK,EAAiB,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+C9F,qEAAqE;AACrE,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7C;AA0CD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,kBAAkB,CAA8B;IACxD,OAAO,CAAC,cAAc,CAA4C;IAClE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C,YAAY,YAAY,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAI1F;IAID,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,mCAAmC;IACnC,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,oEAAoE;IAC9D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAS1B;IAED,6BAA6B;IAC7B,QAAQ,IAAI,IAAI,CAGf;IAID,8DAA8D;IAC9D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAMxC;IAED,oFAAoF;IACpF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAQtE;IAED,yEAAyE;IACnE,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMrD;IAID,6DAA6D;IACvD,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAqD9D;IAED,6DAA6D;IACvD,SAAS,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAezD;IAED;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAyB/F;YAIa,OAAO;YAuBP,aAAa;YAwBb,QAAQ;YAwCR,aAAa;IAsB3B,OAAO,CAAC,YAAY;IAiCpB,OAAO,CAAC,gBAAgB;CAKzB;AAQD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,SAAS,EAClB,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,MAAM,EACpB,sBAAsB,EAAE,MAAM,EAC9B,iBAAiB,EAAE,MAAM,GACxB,IAAI,CAKN;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAO9D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/workflows-mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "mcpName": "io.github.cyanheads/workflows-mcp-server",
   "description": "Store, query, and create YAML workflow playbooks for LLM agents via MCP. STDIO or Streamable HTTP.",
   "type": "module",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "build": "bun run scripts/build.ts",
-    "rebuild": "bun run scripts/clean.ts && bun run build",
+    "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
     "clean": "bun run scripts/clean.ts",
     "devcheck": "bun run scripts/devcheck.ts",
     "audit:refresh": "rm -f bun.lock && bun install && bun audit",
@@ -34,8 +34,10 @@
     "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/workflows-mcp-server.mcpb && bun run scripts/clean-mcpb.ts dist/workflows-mcp-server.mcpb",
     "changelog:build": "bun run scripts/build-changelog.ts",
     "changelog:check": "bun run scripts/build-changelog.ts --check",
+    "release:github": "bun run scripts/release-github.ts",
     "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
-    "test": "bunx vitest run",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "start:stdio": "MCP_TRANSPORT_TYPE=stdio bun ./dist/index.js",
     "start:http": "MCP_TRANSPORT_TYPE=http bun ./dist/index.js"
   },
@@ -62,7 +64,7 @@
   "bugs": {
     "url": "https://github.com/cyanheads/workflows-mcp-server/issues"
   },
-  "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/workflows-mcp-server#readme)",
+  "author": "Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)",
   "funding": [
     {
       "type": "github",
@@ -74,31 +76,32 @@
     }
   ],
   "license": "Apache-2.0",
-  "packageManager": "bun@1.3.2",
+  "packageManager": "bun@1.4.0",
   "engines": {
-    "bun": ">=1.3.2",
+    "bun": ">=1.3.0",
     "node": ">=24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.10.10",
+    "@cyanheads/mcp-ts-core": "^0.12.5",
     "pino-pretty": "^13.1.3",
     "semver": "^7.8.5",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.1",
-    "@types/node": "^25.9.3",
-    "@types/semver": "^7.7.1",
-    "@vitest/coverage-istanbul": "^4.1.9",
+    "@biomejs/biome": "2.5.11",
+    "@socketsecurity/bun-security-scanner": "^1.1.2",
+    "@types/node": "26.4.0",
+    "@types/semver": "^7.8.0",
+    "@vitest/coverage-istanbul": "4.1.11",
     "depcheck": "^1.4.7",
-    "fast-check": "^4.8.0",
-    "ignore": "^7.0.5",
-    "tsc-alias": "^1.8.17",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "fast-check": "^4.9.0",
+    "ignore": "^7.0.8",
+    "tsc-alias": "^1.9.3",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
   }
 }

package/server.json

@@ -6,14 +6,14 @@
     "url": "https://github.com/cyanheads/workflows-mcp-server",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.3.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/workflows-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.2.0",
+      "version": "0.3.1",
       "packageArguments": [
         { "type": "positional", "value": "run" },
         { "type": "positional", "value": "start:stdio" }
@@ -57,7 +57,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/workflows-mcp-server",
       "runtimeHint": "bun",
-      "version": "0.2.0",
+      "version": "0.3.1",
       "packageArguments": [
         { "type": "positional", "value": "run" },
         { "type": "positional", "value": "start:http" }