@cyanheads/cyanheads-mcp-server 0.3.2 → 0.4.0

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** cyanheads-mcp-server
-**Version:** 0.3.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.21`
+**Version:** 0.4.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -15,11 +15,13 @@
 
 A fleet discovery surface for the cyanheads MCP ecosystem. Two tools:
 
-- **`cyanheads_search`** — semantic search across fleet tools and servers using cosine similarity over Matryoshka-truncated 256-dim embeddings from `Snowflake/snowflake-arctic-embed-m-v1.5`.
-- **`cyanheads_describe`** — returns the description, connection URL, and per-client install snippet for any named tool or server.
+- **`cyanheads_search_catalog`** — semantic search across fleet tools and servers using cosine similarity over Matryoshka-truncated 256-dim embeddings from `Snowflake/snowflake-arctic-embed-m-v1.5`.
+- **`cyanheads_describe_entry`** — returns the description, connection URL, and per-client install snippet for any named tool or server.
 
 The catalog (`fleet.json`) is produced by `caseyjhand-portfolio/scripts/build-fleet-json.ts` at portfolio deploy time. Document vectors are baked into the JSON. The server only embeds the user's query at runtime via `@huggingface/transformers`. See `docs/design.md` for the full architecture.
 
+The generated catalog does not include this server, so `src/services/catalog/self-record.ts` supplies a static `CatalogRecord` for `cyanheads-mcp-server` that `CatalogService.getServer()` / `getTool()` consult **only after** the remote index misses. A remote entry always wins, so the fallback self-heals to dead code if the generator ever starts emitting one. The record is never part of the vector index, so semantic search does not surface it — only exact-name resolution does.
+
 ---
 
 ## What's Next?
@@ -46,7 +48,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.
+- **Check `ctx.elicit`** for presence before calling.
 - **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.
 
@@ -160,8 +162,7 @@ Handlers receive a unified `ctx` object. Key properties:
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
-| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
 | `ctx.signal` | `AbortSignal` for cancellation. |
 | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.requestId` | Unique request ID. |
@@ -246,7 +247,7 @@ src/
 
 ## 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.
 
@@ -266,7 +267,6 @@ Available skills:
 | `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 |
 | `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` |
@@ -274,13 +274,14 @@ Available skills:
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `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 |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
 | `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-errors` | McpError, JsonRpcErrorCode, error patterns |
 | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
-| `api-mirror` | MirrorService: persistent, self-refreshing local mirror of a bulk upstream dataset (embedded SQLite + FTS5) |
+| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
@@ -295,31 +296,34 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Commands
 
-**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. `bun` is slightly faster for script invocation but not required.
+**Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).
 
 | Command | Purpose |
 |:--------|:--------|
-| `npm run build` | Compile TypeScript |
-| `npm run rebuild` | Clean + build |
-| `npm run clean` | Remove build artifacts |
-| `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
+| `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, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
-| `npm run tree` | Generate directory structure doc |
-| `npm run format` | Auto-fix formatting (safe fixes only) |
-| `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
-| `npm test` | Run tests |
-| `npm run start:stdio` | Production mode (stdio) |
-| `npm run start:http` | Production mode (HTTP) |
-| `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
-| `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
-| `npm run release:github` | Create GitHub Release from annotated tag (title format: `v<VERSION>: <subject>`) |
-| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+| `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 and plugin manifest identity (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 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 release:github` | Create GitHub Release from annotated tag (title format: `v<VERSION>: <subject>`) |
+| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
 ---
 
 ## Bundling
 
-`npm 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.
+`npm 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 dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. 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.
 

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** cyanheads-mcp-server
-**Version:** 0.3.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.21`
+**Version:** 0.4.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
 **Zod:** ^4.4.3
@@ -15,11 +15,13 @@
 
 A fleet discovery surface for the cyanheads MCP ecosystem. Two tools:
 
-- **`cyanheads_search`** — semantic search across fleet tools and servers using cosine similarity over Matryoshka-truncated 256-dim embeddings from `Snowflake/snowflake-arctic-embed-m-v1.5`.
-- **`cyanheads_describe`** — returns the description, connection URL, and per-client install snippet for any named tool or server.
+- **`cyanheads_search_catalog`** — semantic search across fleet tools and servers using cosine similarity over Matryoshka-truncated 256-dim embeddings from `Snowflake/snowflake-arctic-embed-m-v1.5`.
+- **`cyanheads_describe_entry`** — returns the description, connection URL, and per-client install snippet for any named tool or server.
 
 The catalog (`fleet.json`) is produced by `caseyjhand-portfolio/scripts/build-fleet-json.ts` at portfolio deploy time. Document vectors are baked into the JSON. The server only embeds the user's query at runtime via `@huggingface/transformers`. See `docs/design.md` for the full architecture.
 
+The generated catalog does not include this server, so `src/services/catalog/self-record.ts` supplies a static `CatalogRecord` for `cyanheads-mcp-server` that `CatalogService.getServer()` / `getTool()` consult **only after** the remote index misses. A remote entry always wins, so the fallback self-heals to dead code if the generator ever starts emitting one. The record is never part of the vector index, so semantic search does not surface it — only exact-name resolution does.
+
 ---
 
 ## What's Next?
@@ -46,7 +48,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.
+- **Check `ctx.elicit`** for presence before calling.
 - **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.
 
@@ -160,8 +162,7 @@ Handlers receive a unified `ctx` object. Key properties:
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
-| `ctx.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
-| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `ctx.elicit` | Ask user for structured input — form call `(message, schema)` or `.url(message, url)` for an external link. **Check for presence first:** `if (ctx.elicit) { ... }` |
 | `ctx.signal` | `AbortSignal` for cancellation. |
 | `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
 | `ctx.requestId` | Unique request ID. |
@@ -246,7 +247,7 @@ src/
 
 ## 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.
 
@@ -266,7 +267,6 @@ Available skills:
 | `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 |
 | `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` |
@@ -274,13 +274,14 @@ Available skills:
 | `orchestrations` | Chain task skills into a gated multi-phase pipeline — build-out, QA-fix, update-ship — when you can spawn sub-agents |
 | `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 |
+| `techniques` | Catalog of response/data-shaping techniques — overflow handling, payload shaping, retrieval patterns |
 | `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-errors` | McpError, JsonRpcErrorCode, error patterns |
 | `api-linter` | Definition linter rule catalog — invoked by `bun run lint:mcp` and `devcheck` |
-| `api-mirror` | MirrorService: persistent, self-refreshing local mirror of a bulk upstream dataset (embedded SQLite + FTS5) |
+| `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |
 | `api-services` | LLM, Speech, Graph services |
 | `api-testing` | createMockContext, test patterns |
 | `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
@@ -295,31 +296,34 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Commands
 
-**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. `bun` is slightly faster for script invocation but not required.
+**Runtime:** Scripts use Bun's native TypeScript execution — `bun run <cmd>` is the standard invocation. `npm run <cmd>` also works (npm delegates to bun).
 
 | Command | Purpose |
 |:--------|:--------|
-| `npm run build` | Compile TypeScript |
-| `npm run rebuild` | Clean + build |
-| `npm run clean` | Remove build artifacts |
-| `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
+| `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, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — Bun's `update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
-| `npm run tree` | Generate directory structure doc |
-| `npm run format` | Auto-fix formatting (safe fixes only) |
-| `npm run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
-| `npm test` | Run tests |
-| `npm run start:stdio` | Production mode (stdio) |
-| `npm run start:http` | Production mode (HTTP) |
-| `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
-| `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
-| `npm run release:github` | Create GitHub Release from annotated tag (title format: `v<VERSION>: <subject>`) |
-| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+| `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 and plugin manifest identity (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 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 release:github` | Create GitHub Release from annotated tag (title format: `v<VERSION>: <subject>`) |
+| `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
 ---
 
 ## Bundling
 
-`npm 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.
+`npm 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 dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach. 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.
 

package/Dockerfile

@@ -4,15 +4,17 @@
 # This stage installs all dependencies (including dev), builds the TypeScript
 # source code into JavaScript, and prepares the production assets.
 # ==============================================================================
-FROM oven/bun:1.3 AS build
+FROM oven/bun:1.3.14 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 . .
@@ -29,7 +31,7 @@ RUN bun scripts/build.ts
 # 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.3.14-slim AS production
 
 WORKDIR /usr/src/app
 
@@ -38,9 +40,11 @@ WORKDIR /usr/src/app
 ENV NODE_ENV=production
 
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+ARG APP_VERSION
 LABEL org.opencontainers.image.title="cyanheads-mcp-server"
 LABEL org.opencontainers.image.description="Fleet discovery server for the cyanheads MCP ecosystem."
 LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.version="${APP_VERSION}"
 LABEL org.opencontainers.image.source="https://github.com/cyanheads/cyanheads-mcp-server"
 
 # Copy dependency manifests
@@ -48,14 +52,16 @@ 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
+RUN --mount=type=cache,target=/root/.bun/install/cache \
+    bun install --production --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 --ignore-scripts @hono/otel \
         @opentelemetry/instrumentation-http \
         @opentelemetry/exporter-metrics-otlp-http \
         @opentelemetry/exporter-trace-otlp-http \
@@ -96,5 +102,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/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/cyanheads-mcp-server</h1>
-  <p><b>Discover MCP servers via semantic search. One endpoint, 40+ hosted servers, per-client install snippets. STDIO or Streamable HTTP.</b>
+  <p><b>Fleet discovery for the cyanheads MCP ecosystem — semantic search + install snippets.</b>
   <div>2 Tools • 0 Resources • 0 Prompts</div>
   </p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.3.2-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/cyanheads-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/cyanheads-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/cyanheads-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-%3E=1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.4.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/cyanheads-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/cyanheads-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/cyanheads-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-%3E=1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -33,24 +33,25 @@ Two tools, semantic ranking, hosted catalog. The catalog itself lives at [`casey
 
 | Tool | Description |
 |:---|:---|
-| `cyanheads_search` | Search fleet tools and servers by natural-language query. Returns ranked matches with brief summaries and the owning server. |
-| `cyanheads_describe` | Return the connection URL and per-client install snippets for a named tool or server. |
+| `cyanheads_search_catalog` | Search fleet tools and servers by natural-language query. Returns ranked matches with brief summaries and the owning server. |
+| `cyanheads_describe_entry` | Return the connection URL and per-client install snippets for a named tool or server. |
 
-### `cyanheads_search`
+### `cyanheads_search_catalog`
 
 Semantic search across the fleet. Embeds the query with [Snowflake Arctic Embed M v1.5](https://huggingface.co/Snowflake/snowflake-arctic-embed-m-v1.5) (Matryoshka-truncated to 256 dimensions) and computes cosine similarity against the catalog's pre-computed document vectors.
 
+- `query` accepts 1-500 characters
 - `scope: "tools"` (default) returns individual tool matches; `scope: "servers"` returns server-level matches
 - `category` filter narrows to one of `research`, `government`, `public-data`, `utility`
 - Configurable `limit` (1-20, default 5) and a server-side `SIMILARITY_FLOOR` threshold drop low-confidence hits
 - Returns `score` (cosine similarity in [0, 1]) on every result for trust calibration
-- `totalMatched` reports the count above the floor before the limit was applied
+- `totalCount` reports the count above the floor before the limit was applied
 
 ---
 
-### `cyanheads_describe`
+### `cyanheads_describe_entry`
 
-Resolve a name to its install instructions. Accepts either a tool name (snake_case, e.g. `earthquake_search`) or a server name (kebab-case, e.g. `earthquake-mcp-server`) — auto-detected from the format, or pinned via the `kind` parameter.
+Resolve a name to its install instructions. Accepts either a tool name (snake_case, e.g. `earthquake_search`) or a server name (kebab-case, e.g. `earthquake-mcp-server`), up to 64 characters — auto-detected from the format, or pinned via the `kind` parameter.
 
 - For tools: returns the description and the owning server name
 - For servers: returns description, version, npm package, GitHub URL, the full tool list (each tool's name and description), and per-client install snippets — **local (stdio, via `npx`) for every server, plus remote (Streamable HTTP) when a hosted endpoint exists**
@@ -77,7 +78,7 @@ Fleet-specific:
 
 ## What's in the fleet
 
-40+ MCP servers spanning four categories. Each is open source and individually addressable — `cyanheads_describe` returns its direct connection URL alongside the install snippet.
+100+ MCP servers spanning four categories. Each is open source and individually addressable — `cyanheads_describe_entry` returns its direct connection URL alongside the install snippet. It also describes this server: ask for `cyanheads-mcp-server` and you get the front door's own endpoint and install snippets.
 
 | Category | Examples |
 |:--|:--|
@@ -204,11 +205,11 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
 | `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted | `/mcp` |
 | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
 | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |
-| `CATALOG_URL` | Remote fleet.json endpoint (schema v2 with baked embeddings). Override to front your own fleet. | `https://caseyjhand.com/fleet.json` |
-| `CATALOG_FETCH_TIMEOUT_MS` | Per-request timeout for fleet.json fetches in ms | `10000` |
-| `CATALOG_REFRESH_SECONDS` | Background poll interval for fleet.json refresh. `0` disables. | `3600` |
+| `CATALOG_URL` | Remote fleet.json endpoint (schema v2 with baked embeddings). Must be an absolute URL. Override to front your own fleet. | `https://caseyjhand.com/fleet.json` |
+| `CATALOG_FETCH_TIMEOUT_MS` | Per-request timeout for fleet.json fetches in ms. Must be > 0. | `10000` |
+| `CATALOG_REFRESH_SECONDS` | Background poll interval for fleet.json refresh. `0` disables; otherwise must be > 0. | `3600` |
 | `EMBEDDING_MODEL_ID` | Hugging Face model id for query embedding. Must match `fleet.json.embeddingModel`. | `Snowflake/snowflake-arctic-embed-m-v1.5` |
-| `SIMILARITY_FLOOR` | Cosine similarity cutoff for `cyanheads_search` results (0-1) | `0.3` |
+| `SIMILARITY_FLOOR` | Cosine similarity cutoff for `cyanheads_search_catalog` results. Must be within `[0, 1]`. | `0.3` |
 | `OTEL_ENABLED` | Enable OpenTelemetry | `false` |
 
 To point at a different catalog, change `CATALOG_URL` to your own hosted JSON file. See [`docs/design.md`](./docs/design.md) for the producer-side script and schema.
@@ -239,9 +240,8 @@ To point at a different catalog, change `CATALOG_URL` to your own hosted JSON fi
 
 | Directory | Purpose |
 |:---|:---|
-| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Two tools — `cyanheads_search` and `cyanheads_describe`. |
-| `src/services/catalog` | Catalog service — remote fleet.json provider with atomic-swap refresh, vector index, snippet builders. |
-| `src/services/embeddings` | Embedding runtime — query-time inference via `@huggingface/transformers`, with an injectable interface for deterministic tests. |
+| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Two tools — `cyanheads_search_catalog` and `cyanheads_describe_entry`. |
+| `src/services/catalog` | Catalog service — remote fleet.json provider with atomic-swap refresh, vector index, snippet builders, the self-description fallback record, and the query-time embedding runtime (`@huggingface/transformers`, behind an injectable interface for deterministic tests). |
 | `src/config` | Server-specific environment variable parsing and validation with Zod. |
 | `tests/` | Unit and integration tests, mirroring the `src/` structure. |
 | `docs/` | Design doc and schema reference. |
@@ -252,7 +252,7 @@ See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rule
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
 - Use `ctx.log` for logging, `ctx.state` for storage
-- Register new tools in `src/mcp-server/tools/definitions/index.ts`
+- Register new tools in the `tools` array passed to `createApp()` in `src/index.ts`
 
 ## Contributing
 

package/changelog/0.3.x/0.3.3.md

@@ -0,0 +1,24 @@
+---
+summary: "Adopt @cyanheads/mcp-ts-core ^0.10.6 — server name/title identity, Docker HEALTHCHECK + version label, bundle cleaner, tsx → bun run script migration."
+breaking: false
+security: false
+---
+
+# 0.3.3 — 2026-06-11
+
+## Added
+
+- **Server identity pair** — `createApp()` now sets an explicit `name` / `title` of `cyanheads-mcp-server`, so the hyphenated machine name is the display identity on every surface ([#231](https://github.com/cyanheads/mcp-ts-core/issues/231)).
+- **`stdio` / `streamable-http` keywords** added to `package.json` to surface both supported transports in registry search.
+- **`Dockerfile` `HEALTHCHECK`** — bun-native `fetch` against `/healthz` every 30s (slim image ships no `curl`/`wget`), plus an `APP_VERSION` build arg that stamps `org.opencontainers.image.version` ([#217](https://github.com/cyanheads/mcp-ts-core/issues/217)).
+- **`scripts/clean-mcpb.ts`** — post-pack bundle cleaner wired into `bundle`; runs `mcpb clean` then strips dependency-shipped agent docs (`node_modules/**` `skills/`, `.claude/`, `.agents/`, `SKILL.md`) that root-anchored `.mcpbignore` patterns cannot reach ([#230](https://github.com/cyanheads/mcp-ts-core/issues/230)).
+- **`lint-packaging` checks 8–9** — post-bundle content guard (zero `node_modules/**` agent-doc entries) and entrypoint/manifest identity check (`name`/`title`/`display_name` must equal the unscoped package name) ([#230](https://github.com/cyanheads/mcp-ts-core/issues/230), [#231](https://github.com/cyanheads/mcp-ts-core/issues/231)).
+- **`coerce-boolean-env-flag` antipattern rule** in `check-framework-antipatterns.ts` — flags `z.coerce.boolean()` on env flags (`Boolean("false") === true`), recommending `z.stringbool()`; the scanner now skips comment lines ([#201](https://github.com/cyanheads/mcp-ts-core/issues/201)).
+- **`techniques` skill** — catalog of reusable response/data-shaping patterns; first reference documents outline-on-overflow ([#204](https://github.com/cyanheads/mcp-ts-core/issues/204)).
+
+## Changed
+
+- **`cyanheads_describe`** — the `ambiguous_kind` error code moved from `InvalidParams` to `ValidationError`; a name colliding across catalog kinds is an application-level validation failure, not a malformed-params protocol error.
+- **Build scripts run under Bun** — every `package.json` script switched from `tsx scripts/*.ts` to `bun run scripts/*.ts`, and `tsx` was dropped from devDependencies ([#205](https://github.com/cyanheads/mcp-ts-core/issues/205)).
+- **`.mcpbignore` dev-dir patterns root-anchored** — leading `/` added to `/.claude/`, `/.agents/`, `/Dockerfile`, etc. so they match only at bundle root and can't strip nested `node_modules` runtime paths ([#207](https://github.com/cyanheads/mcp-ts-core/issues/207)).
+- Dependencies: `@cyanheads/mcp-ts-core` ^0.9.21 → ^0.10.6, `@types/node` ^25.9.1 → ^25.9.3.

package/changelog/0.3.x/0.3.4.md

@@ -0,0 +1,33 @@
+---
+summary: "Fix unbounded config env vars (#8); adopt @cyanheads/mcp-ts-core ^0.11.0 with a supply-chain install guard, floating-specifier and plugin-manifest lint checks, and native-binding bundle stripping."
+breaking: false
+security: false
+---
+
+# 0.3.4 — 2026-07-26
+
+## Fixed
+
+- **`server-config.ts` bounds enforcement** — the Zod schema now rejects values outside the bounds it documents: `SIMILARITY_FLOOR` constrained to `[0, 1]`, `CATALOG_FETCH_TIMEOUT_MS` must be positive, `CATALOG_REFRESH_SECONDS` must be `0` or positive, `CATALOG_URL` must be an absolute URL (`z.url()`), and `EMBEDDING_MODEL_ID` must be non-empty. Previously all five accepted any coerced value, including negative timeouts and an out-of-range similarity floor ([#8](https://github.com/cyanheads/cyanheads-mcp-server/issues/8)).
+- New `tests/config/server-config.test.ts` covers the documented defaults and the accept/reject boundary for each of the five env vars.
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core`** `^0.10.6` → `^0.11.0`; `typescript` `^6.0.3` → `^7.0.2`; `@biomejs/biome` `^2.4.16` → `^2.5.5`; `@types/node` `^25.9.3` → `^26.1.1`; `tsc-alias` `^1.8.17` → `^1.9.1`; `vitest` `^4.1.8` → `^4.1.10`; `ignore` `^7.0.5` → `^7.0.6`.
+- **`package.json` `author`** — canonicalized to `Casey Hand <casey@caseyjhand.com> (https://caseyjhand.com)`; `packageManager` field pinned to `bun@1.3.14`.
+- **`bunfig.toml` supply-chain guard** — `[install].minimumReleaseAge` set to 259200s (3 days), blocking newly-published package versions from install; `@cyanheads/mcp-ts-core` is excluded via `minimumReleaseAgeExcludes` so framework releases adopt same-day. `[install.security].scanner` set to `@socketsecurity/bun-security-scanner`.
+- **`Dockerfile`** — base image pinned to `oven/bun:1.3.14` (both stages); `bun install` steps now use a BuildKit cache mount (`--mount=type=cache,target=/root/.bun/install/cache`); the build-stage install adds `--ignore-scripts`; the OTEL peer-dependency install adds `--omit=dev --ignore-scripts`.
+- **`devcheck`'s Outdated check** no longer flags a package as a finding when `Update === Current` — covers versions held back by the new `minimumReleaseAge` guard or a deliberately capped range, and stops flagging `peerDependency` rows (a peer range states a floor, not a version to track).
+- **`devcheck`'s git-dependent checks** (TODOs/FIXMEs, Tracked Secrets, Framework Antipatterns) skip cleanly instead of failing when `.git` is absent (fresh scaffold before `git init`).
+- **`lint-mcp.ts`** passes `packageJson` to the linter only when present, instead of always.
+- **`scripts/clean-mcpb.ts`** / **`lint-packaging.ts` check 8** now also strip and verify zero `node_modules/@duckdb/node-bindings-*/` entries in a built `.mcpb` — a native binding otherwise locks the bundle to the build host's platform and blows past the 25 MB registry cap; `NATIVE_BINDING_ENTRY` is kept identical across both files (unit-tested).
+- **`.gitignore`** — `data/` anchored to `/data/` (was matching `data/` at any depth).
+
+## Added
+
+- **`scripts/check-dependency-specifiers.ts`** (new `devcheck` step, "Dependency Specifiers") — rejects floating specifiers (`latest`, `*`, `next`/`beta`/`canary`/`rc`) in `package.json`'s dependency sections and `bun.lock`'s `workspaces` maps; `overrides` is held to the strictest rule since a floating override silently re-resolves the vulnerable transitive it was meant to pin. `peerDependencies`/`optionalDependencies` allow `*`/dist-tags but never `latest`.
+- **`lint-packaging.ts` check 10** — validates the new plugin marketplace manifests (`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.codex-plugin/mcp.json`): non-empty descriptions, and that display fields (`name`, server key, `interface.displayName`) carry the unscoped machine name while the `npx -y` install arg carries the full (possibly scoped) `package.json` name. Gated by `devcheck.config.json` `packaging.pluginManifests` (default on).
+- **`.claude-plugin/plugin.json`**, **`.codex-plugin/plugin.json`**, **`.codex-plugin/mcp.json`** — plugin marketplace manifests for Claude Code and Codex install flows.
+- **`.gitattributes`** — normalizes line endings to LF, marks binary asset extensions, and flags `bun.lock`/`CHANGELOG.md`/`docs/tree.md` as `linguist-generated`.
+- **`.github/SECURITY.md`** — vulnerability reporting policy (GitHub Security tab or `casey@caseyjhand.com`).
+- **`.github/FUNDING.yml`** — GitHub Sponsors / Buy Me a Coffee funding links.

package/changelog/0.4.x/0.4.0.md

@@ -0,0 +1,21 @@
+---
+summary: "Breaking tool rename (cyanheads_search_catalog / cyanheads_describe_entry), input-length bounds, and a self-description fallback for the front door's own server entry"
+breaking: true
+security: false
+---
+
+# 0.4.0 — 2026-07-26
+
+## Added
+
+- **Self-description fallback.** `cyanheads_describe_entry` now resolves `cyanheads-mcp-server` and its own two tools even though the generated fleet catalog excludes the discovery front door. `src/services/catalog/self-record.ts` supplies a static `CatalogRecord` built from this package's own `package.json` (version, description) and its registered tool definitions; `CatalogService.getServer()` / `getTool()` consult it only after a remote-catalog lookup misses, so a future catalog entry for this server takes precedence automatically. The record is excluded from the vector index, so `cyanheads_search_catalog` does not surface it — only exact-name resolution does. ([#7](https://github.com/cyanheads/cyanheads-mcp-server/issues/7))
+
+## Changed
+
+- **Breaking: both public tools renamed.** `cyanheads_search` → `cyanheads_search_catalog`; `cyanheads_describe` → `cyanheads_describe_entry`. No compatibility aliases — the old names are gone from `tools/list`. Inputs, outputs, errors, and runtime behavior are unchanged. Clients that call either old name directly must switch to the new name; clients that discover tools dynamically pick up the new names automatically on next connect. ([#10](https://github.com/cyanheads/cyanheads-mcp-server/issues/10))
+- **Input length bounds.** `cyanheads_search_catalog.query` is now capped at 500 characters; `cyanheads_describe_entry.name` at 64. Both previously accepted unbounded strings, letting oversized input reach the local embedding model before domain logic could reject it. ([#9](https://github.com/cyanheads/cyanheads-mcp-server/issues/9))
+- **`CatalogService` accessor moved.** `getCatalogService()` now lives in the new leaf module `src/services/catalog/service-instance.ts` instead of `catalog-service.ts`, breaking an import cycle between the tool definitions and the self-record (which derives its tool list from those same definitions). `initCatalogService()` stays in `catalog-service.ts` and installs the instance via the new module's `setCatalogService()`. `shutdown()` is promoted from `CatalogService` onto the `ICatalogService` interface.
+
+## Fixed
+
+- **`docs/design.md` reconciled against current code.** The search-tool output schema, error contract, and `format()` parity note were stale from before the servers roll-up and enrichment-block rework; the `ICatalogService` sketch was missing `shutdown()`. All brought back in sync with the current definition files. ([#11](https://github.com/cyanheads/cyanheads-mcp-server/issues/11))

package/changelog/template.md

@@ -15,9 +15,11 @@ 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.

package/dist/config/server-config.d.ts

@@ -5,7 +5,7 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 declare const ServerConfigSchema: z.ZodObject<{
-    catalogUrl: z.ZodDefault<z.ZodString>;
+    catalogUrl: z.ZodDefault<z.ZodURL>;
     catalogFetchTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     catalogRefreshSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     embeddingModelId: z.ZodDefault<z.ZodString>;

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;iBAgDtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAS9C;AAED,uCAAuC;AACvC,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;iBAyDtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAS9C;AAED,uCAAuC;AACvC,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/config/server-config.js

@@ -11,25 +11,29 @@ const ServerConfigSchema = z.object({
      * Loaded at server startup via RemoteJsonCatalogProvider.
      */
     catalogUrl: z
-        .string()
+        .url()
         .default('https://caseyjhand.com/fleet.json')
         .describe('URL of the remote fleet.json catalog endpoint.'),
     /**
-     * Timeout in milliseconds for the remote catalog fetch.
+     * Timeout in milliseconds for the remote catalog fetch. Must be a positive,
+     * finite duration — a zero or negative timeout aborts every fetch before it
+     * can complete. `z.coerce.number()` already rejects NaN and Infinity.
      */
     catalogFetchTimeoutMs: z.coerce
         .number()
+        .positive()
         .default(10000)
-        .describe('HTTP timeout for remote catalog fetch in milliseconds.'),
+        .describe('HTTP timeout for remote catalog fetch in milliseconds. Must be > 0.'),
     /**
      * Background poll interval. The service re-fetches fleet.json on this cadence
      * and swaps in the new vector index if `generatedAt` changed.
-     * Set to 0 to disable background refresh.
+     * Set to 0 to disable background refresh; any other value must be positive.
      */
     catalogRefreshSeconds: z.coerce
         .number()
+        .nonnegative()
         .default(3600)
-        .describe('Seconds between background catalog re-fetches. 0 disables background refresh.'),
+        .describe('Seconds between background catalog re-fetches. 0 disables background refresh; otherwise must be > 0.'),
     /**
      * Embedding model identifier. Must match `embeddingModel` declared in fleet.json,
      * or the server refuses to load (since vectors live in the same space as the
@@ -37,14 +41,17 @@ const ServerConfigSchema = z.object({
      */
     embeddingModelId: z
         .string()
+        .min(1)
         .default('Snowflake/snowflake-arctic-embed-m-v1.5')
         .describe('Hugging Face model id used for query embedding at search time. Must match fleet.json.embeddingModel.'),
     /**
-     * Minimum cosine similarity for a result to surface in cyanheads_search output.
+     * Minimum cosine similarity for a result to surface in cyanheads_search_catalog output.
      * Tunable post-launch based on observed query patterns.
      */
     similarityFloor: z.coerce
         .number()
+        .min(0)
+        .max(1)
         .default(0.3)
         .describe('Minimum cosine similarity in [0, 1] for a match to appear in search results.'),
 });