@cyanheads/mcp-ts-core 0.10.7 → 0.10.9

package/scripts/lint-packaging.ts

@@ -32,6 +32,15 @@
  *      `createWorkerHandler()` (src/index.ts, src/worker.ts) and manifest
  *      `display_name` must equal the unscoped package name; a partial
  *      `name`/`title` pair warns without failing (issue #231).
+ *  10. Plugin marketplace manifests (`.claude-plugin/plugin.json`,
+ *      `.codex-plugin/plugin.json`, `.codex-plugin/mcp.json`): non-empty
+ *      descriptions, and identity/install correctness — display fields
+ *      (`name`, server key, `interface.displayName`) carry the unscoped machine
+ *      name while the `npx -y` install arg carries the full `package.json`
+ *      name (scoped if scoped). An unscoped install arg for a scoped package
+ *      is a guaranteed install 404. Gated by `devcheck.config.json`
+ *      `packaging.pluginManifests` (default on); each manifest is skipped
+ *      cleanly when absent (issue #240).
  *
  * Every check skips cleanly when its input is absent — consumers who deleted
  * `manifest.json` for an HTTP-only deploy, or who haven't built a bundle,
@@ -374,6 +383,128 @@ export function checkManifestIdentity(manifest: Manifest, unscopedName: string):
   return [];
 }
 
+/** Parsed plugin marketplace manifests; an absent manifest is `undefined`. */
+export interface PluginManifestInputs {
+  claudePlugin?: unknown;
+  codexMcp?: unknown;
+  codexPlugin?: unknown;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null;
+const isNonEmptyString = (v: unknown): boolean => typeof v === 'string' && v.trim().length > 0;
+
+/** The `npx -y <pkg>` install target is the arg after the `-y` flag (args[1]). */
+function installArg(entry: Record<string, unknown>): unknown {
+  return Array.isArray(entry.args) ? entry.args[1] : undefined;
+}
+
+/**
+ * Check 10: plugin marketplace manifests. Display fields (`name`, server key,
+ * `interface.displayName`) must equal the unscoped machine name; the install
+ * arg must equal the full `package.json` name (the real `npx` target). Empty
+ * descriptions ship blank marketplace cards. Each manifest is validated only
+ * when present, so HTTP-only and non-plugin consumers are unaffected. The
+ * caller gates the whole check on `packaging.pluginManifests`.
+ */
+export function checkPluginManifests(
+  inputs: PluginManifestInputs,
+  unscopedName: string,
+  fullName: string,
+): string[] {
+  const errors: string[] = [];
+  const optOut =
+    '(or set "packaging": { "pluginManifests": false } in devcheck.config.json to opt out)';
+
+  // ── .claude-plugin/plugin.json ──
+  const claude = inputs.claudePlugin;
+  if (isRecord(claude)) {
+    const f = '.claude-plugin/plugin.json';
+    if (!isNonEmptyString(claude.description)) {
+      errors.push(`${f} "description" is empty — populate it ${optOut}`);
+    }
+    if (claude.name !== unscopedName) {
+      errors.push(
+        `${f} "name" is "${String(claude.name)}" — must equal the unscoped package name "${unscopedName}"`,
+      );
+    }
+    const servers = claude.mcpServers;
+    if (isRecord(servers)) {
+      if (!(unscopedName in servers)) {
+        errors.push(
+          `${f} mcpServers has no "${unscopedName}" entry — the server key must be the unscoped package name`,
+        );
+      }
+      const entry = servers[unscopedName];
+      if (isRecord(entry) && installArg(entry) !== fullName) {
+        errors.push(
+          `${f} mcpServers["${unscopedName}"] install arg is "${String(installArg(entry))}" — ` +
+            `must be the full package name "${fullName}" (the npx -y target; an unscoped arg for a scoped package 404s)`,
+        );
+      }
+    }
+  }
+
+  // ── .codex-plugin/plugin.json ──
+  const codex = inputs.codexPlugin;
+  if (isRecord(codex)) {
+    const f = '.codex-plugin/plugin.json';
+    if (!isNonEmptyString(codex.description)) {
+      errors.push(`${f} "description" is empty — populate it ${optOut}`);
+    }
+    if (codex.name !== unscopedName) {
+      errors.push(
+        `${f} "name" is "${String(codex.name)}" — must equal the unscoped package name "${unscopedName}"`,
+      );
+    }
+    const iface = codex.interface;
+    if (isRecord(iface)) {
+      if (iface.displayName !== unscopedName) {
+        errors.push(
+          `${f} interface.displayName is "${String(iface.displayName)}" — must equal the unscoped package name "${unscopedName}"`,
+        );
+      }
+      if (!isNonEmptyString(iface.shortDescription)) {
+        errors.push(`${f} interface.shortDescription is empty — populate it ${optOut}`);
+      }
+      if (!isNonEmptyString(iface.longDescription)) {
+        errors.push(`${f} interface.longDescription is empty — populate it ${optOut}`);
+      }
+    } else {
+      errors.push(
+        `${f} is missing the "interface" object (displayName / shortDescription / longDescription)`,
+      );
+    }
+  }
+
+  // ── .codex-plugin/mcp.json ──
+  const codexMcp = inputs.codexMcp;
+  if (isRecord(codexMcp)) {
+    const f = '.codex-plugin/mcp.json';
+    if (!(unscopedName in codexMcp)) {
+      errors.push(
+        `${f} has no "${unscopedName}" server entry — the server key must be the unscoped package name`,
+      );
+    }
+    const entry = codexMcp[unscopedName];
+    if (isRecord(entry) && installArg(entry) !== fullName) {
+      errors.push(
+        `${f} "${unscopedName}" install arg is "${String(installArg(entry))}" — ` +
+          `must be the full package name "${fullName}" (the npx -y target)`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+/** Read `packaging.pluginManifests` from devcheck.config.json; default on. */
+function pluginManifestsEnabled(): boolean {
+  const cfg = tryReadJson<{ packaging?: { pluginManifests?: boolean } }>(
+    resolve('devcheck.config.json'),
+  );
+  return cfg?.packaging?.pluginManifests ?? true;
+}
+
 async function main(): Promise<void> {
   const errors: string[] = [];
   const warnings: string[] = [];
@@ -496,6 +627,27 @@ async function main(): Promise<void> {
     }
   }
 
+  // ── Plugin marketplace manifests (check 10) ──
+  if (unscopedName && pkg?.name) {
+    if (pluginManifestsEnabled()) {
+      errors.push(
+        ...checkPluginManifests(
+          {
+            claudePlugin: tryReadJson(resolve('.claude-plugin/plugin.json')),
+            codexPlugin: tryReadJson(resolve('.codex-plugin/plugin.json')),
+            codexMcp: tryReadJson(resolve('.codex-plugin/mcp.json')),
+          },
+          unscopedName,
+          pkg.name,
+        ),
+      );
+    } else {
+      notes.push(
+        'Plugin-manifest checks disabled via devcheck.config.json packaging.pluginManifests.',
+      );
+    }
+  }
+
   for (const note of notes) console.log(note);
   for (const warning of warnings) console.warn(`  ⚠ ${warning}`);
 

package/skills/add-tool/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
 metadata:
   author: cyanheads
-  version: "2.14"
+  version: "2.15"
   audience: external
   type: reference
 ---
@@ -252,6 +252,20 @@ enrichmentTrailer: {
 
 `structuredContent` always keeps the full structured value; `enrichmentTrailer` only controls the human-facing `content[]` line.
 
+### Image / audio output belongs in `ctx.content`
+
+When a tool produces image or audio bytes for the calling model to *see or hear* — a rendered chart, a generated frame, synthesized speech — emit them via `ctx.content`, not an `output` field. `ctx.content.image(data, mimeType)` / `.audio(data, mimeType)` prepend a content block to `content[]` after `format()` runs and **never** write to `structuredContent`, so the base64 is carried once instead of duplicating into the typed output. Like `ctx.enrich`, it lives on the base `Context` and is callable from the service layer.
+
+```ts
+async handler(input, ctx) {
+  const png = await render(input.spec);                 // base64 PNG
+  ctx.content.image(png, 'image/png');                  // → content[] block, not structuredContent
+  return { width: input.spec.w, height: input.spec.h }; // typed result stays small
+},
+```
+
+The alternative — declaring `previewData: z.string()` in `output` and emitting the block from `format()` — ships the bytes twice (once in `structuredContent`, once in the block). Reserve `output` for data the agent reasons over; route raw media through `ctx.content`. Test with `getContentBlocks(ctx)`. Full reference: `skills/api-context` § `ctx.content`.
+
 ### Capped lists must disclose truncation
 
 When a tool accepts a cap-like input (`limit`, `per_page`, `page_size`, `max_results`, `max_items`) and returns an array, disclose when the cap was hit — the agent otherwise treats a partial set as complete.

package/skills/api-canvas/SKILL.md

@@ -4,7 +4,7 @@ description: >
   DataCanvas primitive reference — a Tier 3 SQL/analytical workspace for tabular MCP servers, backed by DuckDB. Use when registering tables from upstream APIs, running ad-hoc SQL across them, and exporting results. Covers the acquire → register → query → export flow, per-table TTL, the token-sharing pattern for multi-agent collaboration, env config, and Cloudflare Workers fail-closed behavior.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: reference
 ---
@@ -150,6 +150,8 @@ Run SQL across registered tables. Returns at most `rowLimit` rows (default 10 00
 
 Querying a table that does not exist throws `NotFound` (`data.reason: 'missing_table'`) with a recovery hint to re-stage the table or call `describe()`. This happens when a table has expired (per-table TTL), been dropped, or the name is mistyped. The error is `NotFound`, not `ValidationError` — agents should re-stage, not fix the SQL shape.
 
+A `SELECT` that parses but fails to prepare for any other reason — a mistyped column, an unknown function, an invalid expression — throws `ValidationError` (`data.reason: 'invalid_sql'`) and preserves the DuckDB binder detail in `data.binderMessage` (e.g. `Referenced column "x" not found...`, often with a candidate suggestion). This is distinct from `non_select_statement`, reserved for statements that genuinely aren't `SELECT`s — here the shape is fine, so the agent should fix the named column or function.
+
 ```ts
 const result = await instance.query(`
   SELECT germplasmName, COUNT(*) AS n

package/skills/api-config/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables with defaults, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
 metadata:
   author: cyanheads
-  version: "1.7"
+  version: "1.8"
   audience: external
   type: reference
 ---
@@ -167,7 +167,7 @@ Activated when both `SUPABASE_URL` and `SUPABASE_ANON_KEY` are set.
 | Env Var | `AppConfig` field | Default | Notes |
 |:--------|:-----------------|:--------|:------|
 | `OTEL_ENABLED` | `openTelemetry.enabled` | `false` | Enable OpenTelemetry export |
-| `OTEL_SERVICE_NAME` | `openTelemetry.serviceName` | `package.json` `name` | |
+| `OTEL_SERVICE_NAME` | `openTelemetry.serviceName` | `createApp` `name` → `package.json` `name` | Seeded from `createApp({ name })` when unset; an env value wins |
 | `OTEL_SERVICE_VERSION` | `openTelemetry.serviceVersion` | `package.json` `version` | |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | `openTelemetry.tracesEndpoint` | — | OTLP traces endpoint URL |
 | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | `openTelemetry.metricsEndpoint` | — | OTLP metrics endpoint URL |

package/skills/api-context/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: api-context
 description: >
-  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.progress`, `ctx.enrich`), and when to use each.
+  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.progress`, `ctx.enrich`, `ctx.content`), and when to use each.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -63,6 +63,12 @@ interface Context {
   // declared fields. Kind-tagged helpers: enrich.notice / .total / .echo.
   readonly enrich: Enrich;
 
+  // Non-text content blocks (image/audio bytes) for the calling model — prepended
+  // to content[] after format() runs, never placed in structuredContent. Always
+  // present (no-op when never called). Helpers: content.image / .audio; content(block)
+  // pushes a raw ContentBlock.
+  readonly content: ContentCollect;
+
   // Opt-in contract resolver — always present (returns {} when no contract is attached
   // or the reason is unknown), strictly typed on HandlerContext<R> against declared reasons.
   recoveryFor(reason: string): { recovery: { hint: string } } | {};
@@ -637,6 +643,52 @@ See `add-tool`'s **Tool Response Design** and `skills/api-linter` (`enrichment-*
 
 ---
 
+## `ctx.content`
+
+Always present on `Context`. Collects **non-text content blocks** — image or audio bytes the calling model should see or hear — and prepends them to the tool's `content[]` after `format()` runs. Collected blocks **never** enter `structuredContent`, so the base64 payload is carried once (in `content[]`) instead of duplicating into the typed output field. The media counterpart to `ctx.enrich`: both ride alongside the domain result without bloating it.
+
+```ts
+export const renderChart = tool('render_chart', {
+  description: 'Render a chart from a series and return its summary.',
+  input: z.object({ series: z.array(z.number()).describe('Data points') }),
+  output: z.object({ points: z.number().describe('Number of points plotted') }),
+  async handler(input, ctx) {
+    const png = await draw(input.series);          // base64 PNG
+    ctx.content.image(png, 'image/png');           // → content[] block, NOT structuredContent
+    return { points: input.series.length };        // the typed result stays small
+  },
+});
+```
+
+Without `ctx.content`, the only way to surface bytes to the model is to declare them in `output` and emit an image block from `format()` — which ships the base64 twice (once in `structuredContent`, once in the block). `ctx.content` removes the duplication.
+
+### Signature
+
+```ts
+// Callable — push a raw ContentBlock (escape hatch for embedded resources, resource links):
+ctx.content(block: ContentBlock): void
+
+// Typed helpers for the two base64 media blocks:
+ctx.content.image(data: string, mimeType: string): void   // → { type: 'image', data, mimeType }
+ctx.content.audio(data: string, mimeType: string): void   // → { type: 'audio', data, mimeType }
+```
+
+### Behavior
+
+| Aspect | Detail |
+|:-------|:-------|
+| `content[]` only | Blocks are prepended to `content[]` and never written to `structuredContent`. Data meant for the typed result stays on the handler's return value. |
+| Order | `content[]` is `[...collected blocks, ...format()/JSON output, ...enrichment trailer]` — media first, domain content next, enrichment trailer last. |
+| Accumulation | Each call appends; blocks render in call order. |
+| No-op | A handler that never calls `ctx.content` produces a `content[]` / `structuredContent` byte-identical to before — the feature is purely additive and opt-in. |
+| Error path | If the handler throws, collected blocks are dropped — a failed call returns the error result only, never a partial image. |
+| Service usage | Services accepting `ctx: Context` can call `ctx.content(...)`; the blocks reach `content[]` exactly as if the handler had. |
+| No schema involvement | Blocks bypass `output` entirely, so no linter rule requires them in `format()` and they never appear in the advertised `outputSchema`. |
+
+Test content blocks with `getContentBlocks(ctx)` from `@cyanheads/mcp-ts-core/testing`.
+
+---
+
 ## Quick reference
 
 | Property | Type | Present when |
@@ -652,6 +704,7 @@ See `add-tool`'s **Tool Response Design** and `skills/api-linter` (`enrichment-*
 | `ctx.state` | `ContextState` | Always (throws if `tenantId` missing) |
 | `ctx.signal` | `AbortSignal` | Always |
 | `ctx.enrich` | `Enrich` | Always; typed on `HandlerContext<R, E>` when an `enrichment` block is declared |
+| `ctx.content` | `ContentCollect` | Always — prepends image/audio blocks to `content[]`, never `structuredContent` |
 | `ctx.elicit` | `function \| undefined` | Client supports elicitation |
 | `ctx.notifyResourceListChanged` | `function \| undefined` | Always in handler ctx; delivery request-scoped (see [§ list-changed notifications](#list-changed-notifications-ctxnotify)) |
 | `ctx.notifyResourceUpdated` | `function \| undefined` | Always in handler ctx; delivery request-scoped |

package/skills/api-telemetry/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Catalog of OpenTelemetry instrumentation built into framework `@cyanheads/mcp-ts-core` — spans, metrics, completion logs, env config, runtime caveats, custom instrumentation patterns, and cardinality rules. Use when enabling OTel export, adding custom spans or metrics in services, debugging missing telemetry, looking up attribute names, or deciding what's safe to put on a metric attribute vs. a span.
 metadata:
   author: cyanheads
-  version: "1.1"
+  version: "1.2"
   audience: external
   type: reference
 ---
@@ -28,7 +28,7 @@ OTel is **off by default**. `OTEL_ENABLED=true` alone does nothing — you also
 | `OTEL_ENABLED` | `false` | Master switch. Must be `true` to start the SDK. |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | — | OTLP/HTTP traces endpoint (e.g. `http://localhost:4318/v1/traces`). |
 | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | — | OTLP/HTTP metrics endpoint (e.g. `http://localhost:4318/v1/metrics`). |
-| `OTEL_SERVICE_NAME` | `package.json` `name` | `service.name` resource attribute. |
+| `OTEL_SERVICE_NAME` | `createApp` `name` → `package.json` `name` | `service.name` resource attribute. Seeded from `createApp({ name })` when unset; an env value wins. |
 | `OTEL_SERVICE_VERSION` | `package.json` `version` | `service.version` resource attribute. |
 | `OTEL_TRACES_SAMPLER_ARG` | `1.0` | Trace sampling ratio (0–1) for `TraceIdRatioBasedSampler`. |
 | `OTEL_LOG_LEVEL` | `INFO` | OTel diagnostic logger level (`NONE`/`ERROR`/`WARN`/`INFO`/`DEBUG`/`VERBOSE`/`ALL`). |

package/skills/polish-docs-meta/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.7"
+  version: "2.9"
   audience: external
   type: workflow
 ---
@@ -76,7 +76,7 @@ Key fields: `name`, `description`, `repository`, `author`, `homepage`, `bugs`, `
 
 **`name` must communicate the server's domain at a glance.** See `references/package-meta.md` for the naming convention — ambiguous abbreviations and acronym-only names fail the scannability test for humans and agents alike.
 
-**`name` and `title` in `createApp()` / `createWorkerHandler()` must match the unscoped `package.json` `name`** — display identity is the machine name on every surface; `lint:packaging` (run by `devcheck`) enforces the match and warns when the pair is partial. `description` is never duplicated into the entrypoint — `package.json` is the canonical source (the framework derives the served description from it).
+**`name` and `title` in `createApp()` / `createWorkerHandler()` must match the unscoped `package.json` `name`** — display identity is the machine name on every surface; `lint:packaging` (run by `devcheck`) enforces the match and warns when the pair is partial. `description` is never duplicated into the entrypoint — `package.json` is the canonical source (the framework derives the served description from it). Adopting the pair also seeds `OTEL_SERVICE_NAME` when unset, so telemetry's `service.name` switches to the machine name on first boot — expect a one-time series split in backends keyed on the old scoped label.
 
 **`description` is the canonical source.** Every other surface (README header, `server.json`, Dockerfile OCI label, GitHub repo description) derives from it. Write it here first, then propagate.
 
@@ -169,20 +169,22 @@ Never hand-edit `CHANGELOG.md` when using this pattern — it's a build artifact
 
 ### 10. Plugin Metadata (Codex / Claude Code)
 
+`lint:packaging` (run by `devcheck`) now enforces the high-value subset automatically when these manifests are present: non-empty descriptions, and identity/install correctness — display fields (`name`, server key, `interface.displayName`) must be the **unscoped** machine name, while the `npx -y` install arg must be the full `package.json` `name` (scoped if scoped). Opt out per project with `"packaging": { "pluginManifests": false }` in `devcheck.config.json`. The checks below cover the fields the gate doesn't (version / repository / license sync, category, env vars).
+
 If `.codex-plugin/plugin.json` exists, verify it's populated and in sync with `package.json` and `server.json`:
 
-- `name` matches `package.json` `name`
+- `name` is the unscoped `package.json` `name` (display identity is the machine name on every surface)
 - `version` matches `package.json` `version`
 - `description` matches `package.json` `description`
 - `repository` matches `package.json` `repository.url`
 - `license` matches `package.json` `license`
-- `interface.displayName` = `package.json` `name`
+- `interface.displayName` is the unscoped `package.json` `name`
 - `interface.shortDescription` matches `package.json` `description`
 - `interface.category` is set to a meaningful category
 
-If `.codex-plugin/mcp.json` exists, verify the server name key matches `package.json` `name` and env vars include any required API keys from the server config schema.
+If `.codex-plugin/mcp.json` exists, verify the server-name key is the unscoped `package.json` `name`, the `npx -y` install arg is the full `package.json` `name`, and env vars include any required API keys from the server config schema.
 
-If `.claude-plugin/plugin.json` exists, apply the same checks: `name`, `version`, `description`, `repository`, `license` from `package.json`. Verify the inline `mcpServers` entry key matches `package.json` `name` and env vars include any required API keys.
+If `.claude-plugin/plugin.json` exists, apply the same checks: `name` (unscoped), `version`, `description`, `repository`, `license` from `package.json`. Verify the inline `mcpServers` entry key is the unscoped name, its `npx -y` install arg is the full `package.json` `name`, and env vars include any required API keys.
 
 ### 11. MCPB Bundling Artifacts
 

package/templates/devcheck.config.json

@@ -12,5 +12,8 @@
   },
   "outdated": {
     "allowlist": []
+  },
+  "packaging": {
+    "pluginManifests": true
   }
 }