@cyanheads/mcp-ts-core 0.1.18 → 0.1.19

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.1.18
+**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.1.19
 **npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
 
 > **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
@@ -400,6 +400,7 @@ Detailed method signatures, options, and examples live in skill files. Read the
 | `add-prompt` | `skills/add-prompt/SKILL.md` | Scaffold a new MCP prompt definition |
 | `add-service` | `skills/add-service/SKILL.md` | Scaffold a new domain service |
 | `add-test` | `skills/add-test/SKILL.md` | Scaffold test file for a tool, resource, or service |
+| `field-test` | `skills/field-test/SKILL.md` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `add-provider` | `skills/add-provider/SKILL.md` | Add a new provider implementation |
 | `add-export` | `skills/add-export/SKILL.md` | Add a new subpath export |
 | `design-mcp-server` | `skills/design-mcp-server/SKILL.md` | Design tool surface, resources, and service layer for a new server |

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.18-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.1.19-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "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",

package/scripts/devcheck.ts

@@ -229,9 +229,31 @@ const Shell = {
 
 const ROOT_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 
-// Packages allowed to be outdated without failing the check.
-// zod is pinned due to the MCP SDK's hard version requirement.
-const OUTDATED_ALLOWLIST = new Set(['zod']);
+// ── Project-local config (devcheck.config.json) ─────────────────────
+
+interface DevcheckConfig {
+  depcheck?: {
+    ignores?: string[];
+    ignorePatterns?: string[];
+  };
+  outdated?: {
+    allowlist?: string[];
+  };
+}
+
+function loadDevcheckConfig(rootDir: string): DevcheckConfig {
+  try {
+    return JSON.parse(
+      readFileSync(path.join(rootDir, 'devcheck.config.json'), 'utf-8'),
+    ) as DevcheckConfig;
+  } catch {
+    return {};
+  }
+}
+
+const DEVCHECK_CONFIG = loadDevcheckConfig(ROOT_DIR);
+
+const OUTDATED_ALLOWLIST = new Set(DEVCHECK_CONFIG.outdated?.allowlist ?? []);
 
 /** Use bun for package management commands if available, otherwise npm. */
 const PM_CMD = spawnSync('bun', ['--version'], { stdio: 'ignore' }).status === 0 ? 'bun' : 'npm';
@@ -433,13 +455,16 @@ const ALL_CHECKS: Check[] = [
     flag: '--no-depcheck',
     canFix: false,
     slowCheck: true,
-    getCommand: (ctx) => [
-      path.join(ctx.rootDir, 'node_modules', '.bin', 'depcheck'),
-      '--ignores=@types/*,pino-pretty,typescript,bun-types,@vitest/coverage-istanbul,repomix,bun,tsc-alias,@cyanheads/mcp-ts-core,@modelcontextprotocol/ext-apps,typedoc',
-      '--ignore-patterns=examples',
-    ],
+    getCommand: (ctx) => {
+      const cmd = [path.join(ctx.rootDir, 'node_modules', '.bin', 'depcheck')];
+      const ignores = DEVCHECK_CONFIG.depcheck?.ignores ?? ['@types/*'];
+      if (ignores.length > 0) cmd.push(`--ignores=${ignores.join(',')}`);
+      const patterns = DEVCHECK_CONFIG.depcheck?.ignorePatterns ?? [];
+      if (patterns.length > 0) cmd.push(`--ignore-patterns=${patterns.join(',')}`);
+      return cmd;
+    },
     tip: (c) =>
-      `Remove unused packages with ${c.bold(`${PM_CMD} remove <pkg>`)} or add to depcheck ignores.`,
+      `Remove unused packages with ${c.bold(`${PM_CMD} remove <pkg>`)} or add to ${c.bold('devcheck.config.json')} ignores.`,
   },
   // Slow checks last (network-bound operations)
   {
@@ -519,7 +544,7 @@ const ALL_CHECKS: Check[] = [
       return unexpected.length === 0;
     },
     tip: (c) =>
-      `Run ${c.bold(`${PM_CMD} update`)} to upgrade dependencies. Allowlisted packages: ${[...OUTDATED_ALLOWLIST].join(', ')}.`,
+      `Run ${c.bold(`${PM_CMD} update`)} to upgrade dependencies. Configure allowlist in ${c.bold('devcheck.config.json')}.`,
   },
 ];
 

package/skills/field-test/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: field-test
+description: >
+  Exercise tools, resources, and prompts with real-world inputs to verify behavior end-to-end. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface. Calls each definition with realistic and adversarial inputs and produces a report of issues, pain points, and recommendations.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: debug
+---
+
+## Context
+
+Unit tests (`add-test` skill) verify handler logic with mocked context. Field testing verifies the full picture: real server, real transport, real inputs, real outputs. It catches issues that unit tests miss — bad descriptions, awkward input shapes, unhelpful error messages, missing format functions, schema mismatches, and surprising edge-case behavior.
+
+**Actively use** the tools — don't just read their code.
+
+---
+
+## Steps
+
+### 1. Surface available definitions
+
+List the MCP tools, resources, and prompts available in your environment. This confirms the server is connected and gives you everything you need — names, descriptions, parameter schemas — to plan your tests.
+
+If you don't see any MCP tools from this server, ask the user to connect it first (e.g. `claude mcp add` for Claude Code, or the equivalent for their client). Don't proceed until the tools are visible.
+
+Present what you find: each definition's name, parameters (with types and descriptions), and any notable schema details (optional fields, enums, constraints). This is your test surface.
+
+### 2. Test each definition
+
+For every tool, resource, and prompt, run through these categories:
+
+#### Tools
+
+| Category | What to test |
+|:---------|:-------------|
+| **Happy path** | Realistic input that should succeed. Verify output shape matches the output schema. Verify format function produces sensible content blocks. |
+| **Variations** | Different valid input combinations — optional fields omitted, optional fields included, different enum values, min/max boundaries. |
+| **Edge cases** | Empty strings, zero values, very long inputs, special characters, Unicode. |
+| **Error paths** | Missing required fields, wrong types, nonexistent IDs, inputs that should trigger domain errors. Verify errors are clear and actionable. |
+| **Descriptions** | Read every field's `.describe()` — would a user/LLM understand what to provide? Flag vague or missing descriptions. |
+
+#### Resources
+
+| Category | What to test |
+|:---------|:-------------|
+| **Happy path** | Valid URI with known params. Verify returned content and MIME type. |
+| **List** | Call `list` if defined. Verify returned resources have names and valid URIs. |
+| **Not found** | URI with nonexistent params. Verify a clear error, not a crash. |
+| **Pagination** | If the resource uses `extractCursor`/`paginateArray`, test with varying limits and cursors. |
+
+#### Prompts
+
+| Category | What to test |
+|:---------|:-------------|
+| **Happy path** | Valid args. Verify generated messages are well-formed. |
+| **Defaults** | Omit optional args. Verify the output still makes sense. |
+| **Content quality** | Read the generated messages — are they clear, well-structured prompts? |
+
+### 3. Track progress
+
+Use a todo list to track each definition and its test status. Mark each as you go — don't batch.
+
+### 4. Produce the report
+
+After testing everything, present a structured report:
+
+#### Summary table
+
+| Definition | Type | Status | Issues |
+|:-----------|:-----|:-------|:-------|
+| `search_items` | tool | pass | — |
+| `get_item` | tool | issues | Error message unhelpful for missing ID |
+| `item://` | resource | fail | Crashes on nonexistent ID |
+
+#### Detailed findings
+
+For each definition with issues, include:
+
+- **What happened** — the input, the output or error, and what was expected
+- **Severity** — `bug` (broken behavior), `ux` (works but confusing/unhelpful), `nit` (minor polish)
+- **Recommendation** — specific fix suggestion
+
+#### Pain points
+
+Cross-cutting observations that aren't tied to a single definition:
+
+- Inconsistent error message patterns across tools
+- Missing format functions (raw JSON returned to user)
+- Description quality issues (vague, missing, or misleading)
+- Schema design issues (required fields that should be optional, missing defaults, overly broad types)
+- Performance observations (unexpectedly slow responses)
+
+---
+
+## Checklist
+
+- [ ] All registered tools tested (happy path + edge cases)
+- [ ] All registered resources tested (happy path + not found)
+- [ ] All registered prompts tested (happy path + defaults)
+- [ ] Error messages reviewed for clarity and actionability
+- [ ] Descriptions reviewed for completeness and accuracy
+- [ ] Format functions verified (or absence noted)
+- [ ] Summary report presented to user

package/templates/.env.example

@@ -11,6 +11,9 @@
 # ── Storage ───────────────────────────────────────────────────────────
 # STORAGE_PROVIDER_TYPE=in-memory   # in-memory | filesystem | supabase | cloudflare-r2 | cloudflare-kv | cloudflare-d1
 
+# ── Session ──────────────────────────────────────────────────────────
+# MCP_SESSION_MODE=stateful         # stateful | stateless (default: stateful)
+
 # ── Logging ───────────────────────────────────────────────────────────
 # MCP_LOG_LEVEL=info                # debug | info | notice | warning | error
 

package/templates/AGENTS.md

@@ -19,6 +19,24 @@
 
 ---
 
+## What's Next?
+
+When the user asks what to do next, what's left, or needs direction, suggest relevant options based on the current project state:
+
+1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
+2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills
+4. **Add services** — scaffold domain service integrations using the `add-service` skill
+5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
+6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
+7. **Run `devcheck`** — lint, format, typecheck, and security audit
+8. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
+9. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+
+Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
+
+---
+
 ## Core Rules
 
 - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
@@ -205,6 +223,7 @@ Available skills:
 | `add-prompt` | Scaffold a new prompt definition |
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
+| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `maintenance` | Sync skills and dependencies after updates |

package/templates/CLAUDE.md

@@ -19,6 +19,24 @@
 
 ---
 
+## What's Next?
+
+When the user asks what to do next, what's left, or needs direction, suggest relevant options based on the current project state:
+
+1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
+2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills
+4. **Add services** — scaffold domain service integrations using the `add-service` skill
+5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
+6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
+7. **Run `devcheck`** — lint, format, typecheck, and security audit
+8. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
+9. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+
+Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
+
+---
+
 ## Core Rules
 
 - **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
@@ -205,6 +223,7 @@ Available skills:
 | `add-prompt` | Scaffold a new prompt definition |
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
+| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `maintenance` | Sync skills and dependencies after updates |

package/templates/Dockerfile

@@ -46,10 +46,7 @@ COPY package.json bun.lock ./
 
 # Install only production dependencies, ignoring any lifecycle scripts (like 'prepare')
 # that are not needed in the final production image.
-# Remove platform-specific bun/rollup binaries pulled as optionalDependencies
-# by @modelcontextprotocol/ext-apps — only needed for its build toolchain, not runtime.
-RUN bun install --production --frozen-lockfile --ignore-scripts \
-    && rm -rf node_modules/@oven node_modules/@rollup
+RUN bun install --production --frozen-lockfile --ignore-scripts
 
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist

package/templates/devcheck.config.json

@@ -0,0 +1,15 @@
+{
+  "depcheck": {
+    "ignores": [
+      "@types/*",
+      "pino-pretty",
+      "typescript",
+      "tsc-alias",
+      "@cyanheads/mcp-ts-core"
+    ],
+    "ignorePatterns": []
+  },
+  "outdated": {
+    "allowlist": []
+  }
+}