@cyanheads/mcp-ts-core 0.1.28 → 0.2.0

package/dist/utils/network/retry.d.ts

@@ -0,0 +1,83 @@
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/** Configuration for {@link withRetry}. */
+export interface RetryOptions {
+    /**
+     * Base delay in milliseconds before the first retry.
+     * Subsequent delays are `baseDelayMs * 2^attempt`. Default: `1000`.
+     *
+     * Calibrate to the upstream's recovery time:
+     * - 200–500ms for ephemeral failures (connection pool)
+     * - 1–2s for rate-limited APIs
+     * - 2–5s for service degradation / outages
+     */
+    baseDelayMs?: number;
+    /**
+     * Request context for correlated logging. When provided, log entries
+     * include `requestId`, `traceId`, etc.
+     */
+    context?: RequestContext;
+    /**
+     * Custom predicate to determine if an error is transient and should be
+     * retried. When provided, this replaces the default `McpError` code check.
+     * Return `true` to retry, `false` to fail immediately.
+     */
+    isTransient?: (error: unknown) => boolean;
+    /**
+     * Jitter factor applied to each delay. `0` = no jitter, `1` = full jitter
+     * (delay randomized between 0 and calculated delay). Default: `0.25`.
+     */
+    jitter?: number;
+    /**
+     * Maximum delay cap in milliseconds. Prevents unbounded growth on high
+     * retry counts. Default: `30000` (30s).
+     */
+    maxDelayMs?: number;
+    /**
+     * Maximum number of retry attempts after the initial call.
+     * Total attempts = `maxRetries + 1`. Default: `3`.
+     */
+    maxRetries?: number;
+    /**
+     * Operation name for structured log messages. Used in log context and
+     * enriched error messages on exhaustion.
+     */
+    operation?: string;
+    /**
+     * Optional AbortSignal. When aborted, the retry loop exits immediately
+     * without further attempts.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Executes `fn` with retry logic and exponential backoff.
+ *
+ * The retry boundary should wrap the **full pipeline** — HTTP fetch, response
+ * parsing, and validation — not just the network call. This ensures that
+ * transient upstream errors (e.g., HTTP 200 with an error body) are retried.
+ *
+ * When retries exhaust, the final error is enriched with attempt count in both
+ * the message and structured data, so callers know retries were already attempted.
+ *
+ * @typeParam T - Return type of the operation.
+ * @param fn - The async operation to execute with retries.
+ * @param options - Retry configuration. All fields optional with sensible defaults.
+ * @returns The result of `fn` on success.
+ * @throws The enriched final error when all attempts are exhausted, or the original
+ *   error immediately if it is not classified as transient.
+ *
+ * @example
+ * ```ts
+ * // Service method — retry covers fetch + parse
+ * async function fetchStudy(id: string, ctx: Context): Promise<Study> {
+ *   return withRetry(
+ *     async () => {
+ *       const text = await apiClient.get(`/studies/${id}`);
+ *       return responseHandler.parse<Study>(text);
+ *     },
+ *     { operation: 'fetchStudy', context: ctx, baseDelayMs: 1000 },
+ *   );
+ * }
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/network/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAYzE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA6DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAiD/F"}

package/dist/utils/network/retry.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Retry utility with exponential backoff for wrapping operations that
+ * may fail transiently. Designed so the retry boundary covers the full pipeline
+ * (HTTP fetch + response parsing/validation), not just the network call.
+ * @module src/utils/network/retry
+ * @see docs/service-resilience.md
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+/**
+ * Error codes considered transient — eligible for retry.
+ * Matches the framework's error classification in `mappings.ts`.
+ */
+const TRANSIENT_CODES = new Set([
+    JsonRpcErrorCode.ServiceUnavailable,
+    JsonRpcErrorCode.Timeout,
+    JsonRpcErrorCode.RateLimited,
+]);
+/**
+ * Computes the backoff delay for a given attempt with optional jitter.
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry).
+ * @param baseDelayMs - Base delay in milliseconds.
+ * @param maxDelayMs - Maximum delay cap.
+ * @param jitter - Jitter factor (0–1).
+ * @returns Delay in milliseconds.
+ */
+function computeDelay(attempt, baseDelayMs, maxDelayMs, jitter) {
+    const exponential = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+    if (jitter <= 0)
+        return exponential;
+    const jitterRange = exponential * jitter;
+    return exponential - jitterRange + Math.random() * jitterRange * 2;
+}
+/**
+ * Default transient check: `McpError` with a transient code, or any non-McpError
+ * (network failures, unexpected throws) which are assumed transient.
+ */
+function defaultIsTransient(error) {
+    if (error instanceof McpError) {
+        return TRANSIENT_CODES.has(error.code);
+    }
+    // Non-McpError (raw network errors, unexpected throws) — assume transient
+    return true;
+}
+/**
+ * Enriches an error with retry exhaustion context.
+ * Appends attempt count to the message and to `data` for programmatic access.
+ */
+function enrichExhaustedError(error, totalAttempts, operation) {
+    if (error instanceof McpError) {
+        const suffix = `(failed after ${totalAttempts} attempt${totalAttempts > 1 ? 's' : ''})`;
+        const enrichedMessage = error.message ? `${error.message} ${suffix}` : suffix;
+        const enrichedData = {
+            ...error.data,
+            retryAttempts: totalAttempts,
+            ...(operation ? { operation } : {}),
+        };
+        return new McpError(error.code, enrichedMessage, enrichedData, { cause: error });
+    }
+    if (error instanceof Error) {
+        const suffix = `(failed after ${totalAttempts} attempt${totalAttempts > 1 ? 's' : ''})`;
+        const wrapped = new Error(`${error.message} ${suffix}`, { cause: error });
+        wrapped.name = error.name;
+        return wrapped;
+    }
+    return error;
+}
+/**
+ * Executes `fn` with retry logic and exponential backoff.
+ *
+ * The retry boundary should wrap the **full pipeline** — HTTP fetch, response
+ * parsing, and validation — not just the network call. This ensures that
+ * transient upstream errors (e.g., HTTP 200 with an error body) are retried.
+ *
+ * When retries exhaust, the final error is enriched with attempt count in both
+ * the message and structured data, so callers know retries were already attempted.
+ *
+ * @typeParam T - Return type of the operation.
+ * @param fn - The async operation to execute with retries.
+ * @param options - Retry configuration. All fields optional with sensible defaults.
+ * @returns The result of `fn` on success.
+ * @throws The enriched final error when all attempts are exhausted, or the original
+ *   error immediately if it is not classified as transient.
+ *
+ * @example
+ * ```ts
+ * // Service method — retry covers fetch + parse
+ * async function fetchStudy(id: string, ctx: Context): Promise<Study> {
+ *   return withRetry(
+ *     async () => {
+ *       const text = await apiClient.get(`/studies/${id}`);
+ *       return responseHandler.parse<Study>(text);
+ *     },
+ *     { operation: 'fetchStudy', context: ctx, baseDelayMs: 1000 },
+ *   );
+ * }
+ * ```
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxRetries = 3, baseDelayMs = 1000, maxDelayMs = 30_000, jitter = 0.25, operation, context, signal, isTransient = defaultIsTransient, } = options;
+    const totalAttempts = maxRetries + 1;
+    for (let attempt = 0; attempt < totalAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            // Abort signal — exit immediately, no more retries
+            if (signal?.aborted) {
+                throw error;
+            }
+            const isLastAttempt = attempt >= maxRetries;
+            // Non-transient errors fail immediately
+            if (!isTransient(error)) {
+                throw error;
+            }
+            if (isLastAttempt) {
+                throw enrichExhaustedError(error, totalAttempts, operation);
+            }
+            // Log and backoff
+            const delay = computeDelay(attempt, baseDelayMs, maxDelayMs, jitter);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.debug(`Retry ${attempt + 1}/${maxRetries} for ${operation ?? 'operation'}: ${errorMessage} — waiting ${Math.round(delay)}ms`, context);
+            await sleep(delay, signal);
+        }
+    }
+    // Unreachable — the loop always returns or throws
+    throw new McpError(JsonRpcErrorCode.InternalError, 'withRetry: unexpected loop exit');
+}
+/** Sleeps for the given duration, aborting early if the signal fires. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        let onAbort;
+        const timer = setTimeout(() => {
+            if (onAbort)
+                signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal) {
+            onAbort = () => {
+                clearTimeout(timer);
+                reject(signal.reason);
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/network/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.1.28",
+  "version": "0.2.0",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Build tools, not infrastructure. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Node.js and Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -83,6 +83,10 @@
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
     },
+    "./testing/fuzz": {
+      "types": "./dist/testing/fuzz.d.ts",
+      "import": "./dist/testing/fuzz.js"
+    },
     "./tsconfig.base.json": "./tsconfig.base.json",
     "./vitest.config": "./vitest.config.base.ts",
     "./biome": "./biome.json",
@@ -244,7 +248,7 @@
   "dependencies": {
     "@hono/mcp": "^0.2.4",
     "@hono/node-server": "^1.19.11",
-    "@modelcontextprotocol/ext-apps": "^1.2.2",
+    "@modelcontextprotocol/ext-apps": "^1.3.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/api": "^1.9.0",
     "dotenv": "^17.3.1",
@@ -267,7 +271,7 @@
     "@supabase/supabase-js": "^2.99.3",
     "chrono-node": "^2.9.0",
     "diff": "^8.0.4",
-    "fast-xml-parser": "^5.5.9",
+    "fast-xml-parser": "latest",
     "js-yaml": "^4.1.0",
     "node-cron": "^4.2.1",
     "openai": "^6.32.0",

package/skills/add-service/SKILL.md

@@ -98,6 +98,58 @@ handler: async (input, ctx) => {
 },
 ```
 
+## Resilience (External API Services)
+
+When a service wraps an external API, apply these patterns. See `docs/service-resilience.md` for full rationale.
+
+### Retry wraps the full pipeline
+
+Place retry at the service method level — covering both HTTP fetch and response parsing/validation. The HTTP client should be single-attempt; the service owns retry. Use `withRetry` from `@cyanheads/mcp-ts-core/utils`:
+
+```typescript
+import { withRetry, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
+import type { Context } from '@cyanheads/mcp-ts-core';
+
+async fetchItem(id: string, ctx: Context): Promise<Item> {
+  return withRetry(
+    async () => {
+      const response = await fetchWithTimeout(
+        `${this.baseUrl}/items/${id}`,
+        10_000,
+        ctx,
+      );
+      const text = await response.text();
+      return this.parseResponse<Item>(text);
+    },
+    {
+      operation: 'fetchItem',
+      context: ctx,
+      baseDelayMs: 1000,    // calibrate to upstream recovery time
+      signal: ctx.signal,
+    },
+  );
+}
+```
+
+### Key principles
+
+1. **Calibrate backoff to the upstream.** 200–500ms for ephemeral failures, 1–2s for rate-limited APIs, 2–5s for service degradation. The default `baseDelayMs: 1000` suits most APIs.
+2. **Check HTTP status before parsing.** `fetchWithTimeout` already throws `ServiceUnavailable` on non-OK responses — this prevents feeding HTML error pages into XML/JSON parsers.
+3. **Classify parse failures by content.** If the upstream returns HTTP 200 with an HTML error page, detect it and throw `ServiceUnavailable` (transient) instead of `SerializationError` (non-transient).
+4. **Exhausted retries say so.** `withRetry` automatically enriches the final error with attempt count — callers know retries were already attempted.
+
+### Response handler pattern
+
+```typescript
+parseResponse<T>(text: string): T {
+  // Detect HTML error pages masquerading as successful responses
+  if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+    throw serviceUnavailable('API returned HTML instead of expected format — likely rate-limited.');
+  }
+  // Parse and validate...
+}
+```
+
 ## Checklist
 
 - [ ] Directory created at `src/services/{{domain}}/`
@@ -106,4 +158,5 @@ handler: async (input, ctx) => {
 - [ ] Service methods accept `Context` for logging and storage
 - [ ] `init` function registered in `setup()` callback in `src/index.ts`
 - [ ] Accessor throws `Error` if not initialized
+- [ ] If wrapping external API: retry covers full pipeline (fetch + parse), backoff calibrated
 - [ ] `bun run devcheck` passes

package/skills/api-utils/SKILL.md

@@ -30,6 +30,7 @@ Utility exports from `@cyanheads/mcp-ts-core/utils`. Utilities with complex APIs
 | Export | API | Notes |
 |:-------|:----|:------|
 | `fetchWithTimeout` | `(url, timeoutMs, context: RequestContext, options?: FetchWithTimeoutOptions) -> Promise<Response>` | Wraps `fetch` with `AbortController` timeout. `FetchWithTimeoutOptions` extends `RequestInit` (minus `signal`) and adds `rejectPrivateIPs?: boolean` and `signal?: AbortSignal` (external cancellation). SSRF protection: blocks RFC 1918, loopback, link-local, CGNAT, cloud metadata. DNS validation on Node; hostname-only on Workers. Manual redirect following (max 5) with per-hop SSRF check. |
+| `withRetry` | `<T>(fn: () => Promise<T>, options?: RetryOptions) -> Promise<T>` | Executes `fn` with exponential backoff. Retries on transient errors (`ServiceUnavailable`, `Timeout`, `RateLimited`); non-transient errors fail immediately. On exhaustion, enriches the final error with attempt count in message and `data.retryAttempts`. **Place the retry boundary around the full pipeline** (fetch + parse), not just the network call. See `docs/service-resilience.md`. `RetryOptions`: `maxRetries` (default `3`), `baseDelayMs` (default `1000`), `maxDelayMs` (default `30000`), `jitter` (default `0.25`), `operation` (log label), `context` (RequestContext), `signal` (AbortSignal), `isTransient` (custom predicate). |
 
 ---
 

package/skills/design-mcp-server/SKILL.md

@@ -120,6 +120,8 @@ const findEligibleStudies = tool('clinicaltrials_find_eligible_studies', {
 
 There is no fixed ceiling on tool count — tools need to earn their keep, but don't artificially limit the surface. If the domain genuinely has 20 distinct workflows, expose 20 tools.
 
+**Audit: does each tool earn its keep?** After mapping tools, review the full list critically. A tool that covers a niche use case, serves a tiny fraction of agents, or duplicates what another tool already handles is a candidate for deferral. Drop it from the design and note it as a future addition if demand warrants. Every tool in the surface is cognitive load for tool selection — a tight surface outperforms a comprehensive one.
+
 #### Tool descriptions
 
 The description is the LLM's primary signal for tool selection. It must answer: *what does this do, and when should I use it?*
@@ -193,6 +195,22 @@ output: z.object({
 - **Truncate large output with counts.** When a list exceeds a reasonable display size, show the top N and append "...and X more". Don't silently drop results.
 - **Use the `format` function for readable summaries** while keeping the full structured data in the output object for programmatic use.
 
+#### Convenience shortcuts for complex inputs
+
+When a tool wraps a complex query language or filter system, provide a simple shortcut parameter for the 80% case alongside the full-power escape hatch. This keeps simple queries simple while preserving full expressiveness.
+
+```ts
+// text_search handles the common case; query handles everything else
+text_search: z.string().optional()
+  .describe('Convenience shortcut: full-text search across title and abstract. '
+    + 'Equivalent to {"_or":[{"_text_any":{"title":"..."}},{"_text_any":{"abstract":"..."}}]}. '
+    + 'For more control, use the query parameter directly.'),
+query: z.record(z.unknown()).optional()
+  .describe('Full query object for structured filters. Supports operators: _eq, _gt, _and, _or, ...'),
+```
+
+The pattern: name the shortcut for what it does (`text_search`, `name_search`), document what it expands to, and point to the full parameter for advanced use. Validate that at least one of the two is provided.
+
 #### Error messages as LLM guidance
 
 When a tool throws, the error message is the agent's only signal for recovery. A good error message tells the LLM *what happened and what to do next*.
@@ -219,7 +237,7 @@ Summarize each tool:
 
 | Aspect | Decision |
 |:-------|:---------|
-| **Name** | `snake_case`, verb-noun: `search_papers`, `create_task`. Prefix with server domain if ambiguous. |
+| **Name** | `snake_case`, `{domain}_{verb}_{noun}` — aim for 3 words: `patentsview_search_patents`, `clinicaltrials_find_studies`. Use the **canonical platform/brand name** as prefix (not abbreviations — `patentsview_` not `patents_`, `clinicaltrials_` not `ct_`). The verb+noun pair should be unambiguous within the server — if two tools could plausibly share a name, the noun isn't specific enough (e.g., `read_fulltext` not `read_text` when structured metadata is a separate concept). |
 | **Granularity** | One tool per user-meaningful workflow, not per API call. Consolidate related operations with `operation`/`mode` enum. |
 | **Description** | Concrete capability statement. Add operational guidance (prerequisites, constraints, gotchas) when non-obvious. |
 | **Input schema** | `.describe()` on every field. Constrained types (enums, literals, regex). Explain costs/tradeoffs of parameter choices. |
@@ -251,6 +269,16 @@ Skip for purely data/action-oriented servers.
 
 **Services** — one per external dependency. Init/accessor pattern. Skip if all tools are thin wrappers with no shared state.
 
+For services wrapping external APIs, plan the resilience layer. See `docs/service-resilience.md` for full rationale.
+
+| Concern | Decision |
+|:--------|:---------|
+| **Retry boundary** | Service method wraps full pipeline (fetch + parse), not just the network call. Use `withRetry` from `/utils`. |
+| **Backoff calibration** | Match base delay to upstream recovery time: 200–500ms (ephemeral), 1–2s (rate-limited), 2–5s (degraded). |
+| **HTTP status check** | `fetchWithTimeout` already handles this — non-OK → `ServiceUnavailable`. |
+| **Parse failure classification** | Response handler detects HTML error pages and throws transient errors, not `SerializationError`. |
+| **Exhausted retry messaging** | `withRetry` enriches the final error with attempt count automatically. |
+
 **Config** — list env vars (API keys, base URLs). Goes in `src/config/server-config.ts` as a separate Zod schema.
 
 ### 8. Write the Design Doc
@@ -301,6 +329,13 @@ What this server does, what system it wraps, who it's for.
 6. Prompts
 
 Each step is independently testable.
+
+<!-- Optional sections for API-wrapping servers: -->
+## Domain Mapping          <!-- nouns × operations → API endpoints -->
+## Workflow Analysis        <!-- how tools chain for real tasks -->
+## Design Decisions         <!-- rationale for consolidation, naming, tradeoffs -->
+## Known Limitations        <!-- inherent API/data constraints the server can't solve -->
+## API Reference            <!-- query language, pagination, rate limits -->
 ```
 
 Keep it concise. The design doc is a working reference, not a spec document — enough to orient a developer (or agent) implementing the server, not more.
@@ -333,6 +368,7 @@ Execute the plan using the scaffolding skills:
 - [ ] Annotations set correctly (`readOnlyHint`, `destructiveHint`, etc.)
 - [ ] Resource URIs use `{param}` templates, pagination planned for large lists
 - [ ] Service layer planned (or explicitly skipped with reasoning)
+- [ ] Resilience planned for external API services (retry boundary, backoff, parse classification)
 - [ ] Server config env vars identified
 - [ ] Design doc written to `docs/design.md`
 - [ ] Design confirmed with user (or user pre-authorized implementation)

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: "1.1"
+  version: "1.2"
   audience: external
   type: workflow
 ---
@@ -48,6 +48,8 @@ Capture: tool count, resource count, prompt count, service count, required env v
 
 Read `references/readme.md` for structure and conventions. If `README.md` doesn't exist, create it from scratch. If it exists, diff the current content against the audit — update tool/resource/prompt tables, env var lists, and descriptions to match the actual surface area. Don't rewrite sections that are already accurate.
 
+The header tagline (`<p><b>...</b></p>`) must match the `package.json` `description`.
+
 ### 3. Agent Protocol (CLAUDE.md / AGENTS.md)
 
 Update the project's agent protocol file to reflect the actual server.
@@ -70,6 +72,8 @@ Check for empty or placeholder metadata fields. Read `references/package-meta.md
 
 Key fields: `description`, `repository`, `author`, `homepage`, `bugs`, `keywords`.
 
+**`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.
+
 ### 6. `server.json`
 
 Read `references/server-json.md` for the official MCP server manifest schema. If `server.json` doesn't exist, create it from the surface area audit. If it exists, diff against current state and update stale fields.
@@ -82,7 +86,26 @@ Key sync points:
 - `environmentVariables` reflect the server config Zod schema — server-specific required vars in both entries, transport vars only in HTTP entry
 - Two package entries: one for stdio, one for HTTP (if both transports supported)
 
-### 7. `bunfig.toml`
+### 7. GitHub Repository Metadata
+
+Sync the GitHub repo with `package.json` using the `gh` CLI. Skip if the repo isn't hosted on GitHub or `gh` isn't available.
+
+**Description:**
+
+```bash
+gh repo edit <owner>/<repo> --description "<package.json description>"
+```
+
+**Topics ↔ Keywords:**
+
+Compare GitHub topics (`gh repo view --json repositoryTopics`) against `package.json` `keywords`. They should be the union — add any that exist in one but not the other:
+
+- Missing from GitHub → `gh repo edit --add-topic <topic>`
+- Missing from `package.json` → add to `keywords` array
+
+Common keywords shared across MCP servers (e.g., `mcp`, `mcp-server`, `model-context-protocol`, `typescript`) should appear in both. Domain-specific keywords should also be present in both.
+
+### 8. `bunfig.toml`
 
 Verify a `bunfig.toml` exists at the project root. If not, create one:
 
@@ -95,7 +118,7 @@ frozenLockfile = false
 bun = true
 ```
 
-### 8. `CHANGELOG.md`
+### 9. `CHANGELOG.md`
 
 If `CHANGELOG.md` doesn't exist, create it with an initial entry. If it exists, verify the latest entry reflects the current state:
 
@@ -112,22 +135,22 @@ Initial release.
 
 Use a concrete version and date. Never `[Unreleased]`.
 
-### 9. `LICENSE`
+### 10. `LICENSE`
 
 Confirm a license file exists. If not, ask the user which license to use (default: Apache-2.0, matching the scaffolded `package.json`). Create the file.
 
-### 10. `Dockerfile`
+### 11. `Dockerfile`
 
 If a `Dockerfile` exists, verify the OCI labels and runtime config match the actual server:
 
 - `org.opencontainers.image.title` matches the package name
-- `org.opencontainers.image.description` is filled in (not empty placeholder)
+- `org.opencontainers.image.description` matches `package.json` `description`
 - `org.opencontainers.image.source` points to the real repository URL (add if missing)
 - Log directory path in `mkdir` and `LOGS_DIR` uses the correct server name
 
 If no `Dockerfile` exists and the server is deployed via HTTP transport, consider scaffolding one — the template is available via `npx @cyanheads/mcp-ts-core init`.
 
-### 11. `docs/tree.md`
+### 12. `docs/tree.md`
 
 Regenerate the directory structure:
 
@@ -137,7 +160,7 @@ bun run tree
 
 Review the output for anything unexpected (leftover files, missing directories).
 
-### 12. Final Verification
+### 13. Final Verification
 
 Run the full check suite one last time:
 
@@ -156,6 +179,7 @@ Both must pass clean.
 - [ ] `.env.example` in sync with server config schema
 - [ ] `package.json` metadata complete (`description`, `mcpName`, `repository`, `author`, `keywords`, `engines`, `packageManager`)
 - [ ] `server.json` matches official MCP schema, versions synced, env vars current
+- [ ] GitHub repo description matches `package.json` description; topics ↔ keywords in sync
 - [ ] `bunfig.toml` present
 - [ ] `CHANGELOG.md` exists with current entry
 - [ ] `LICENSE` file present