@cyanheads/mcp-ts-core 0.3.4 → 0.3.5

package/README.md

@@ -1,11 +1,11 @@
 <div align="center">
   <h1>@cyanheads/mcp-ts-core</h1>
-  <p><b>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.</b></p>
+  <p><b>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 Bun/Node/Cloudflare Workers.</b></p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.3.4-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.29.0-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.3.5-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.29.0-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-^6.0.2-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/)
 
@@ -243,18 +243,16 @@ Also exports `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, and `ADVERSARIAL_ST
 
 ## Documentation
 
-- **[CLAUDE.md](CLAUDE.md)** — Complete API reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package.
+- **[CLAUDE.md](CLAUDE.md)** — Framework reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package.
 - **[CHANGELOG.md](CHANGELOG.md)** — Version history
 
 ## Development
 
 ```bash
-bun run build          # tsc && tsc-alias
+bun run rebuild          # tsc && tsc-alias
 bun run devcheck       # lint, format, typecheck, security
 bun run lint:mcp       # validate MCP definitions against spec
-bun run test           # vitest
-bun run dev:stdio      # dev mode (stdio)
-bun run dev:http       # dev mode (HTTP)
+bun run test:all           # vitest
 ```
 
 ## Contributing
@@ -263,7 +261,7 @@ Issues and pull requests welcome. Run checks before submitting:
 
 ```bash
 bun run devcheck
-bun run test
+bun run test:all
 ```
 
 ## License

package/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.11/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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",
@@ -141,10 +141,10 @@
     "publish-mcp": "bunx mcp-publisher publish"
   },
   "resolutions": {
-    "@hono/node-server": "1.19.13",
+    "@hono/node-server": "1.19.14",
     "chrono-node": "2.9.0",
     "diff": "8.0.4",
-    "dotenv": "17.4.1",
+    "dotenv": "17.4.2",
     "brace-expansion": "1.1.13",
     "flatted": "3.4.2",
     "handlebars": "4.7.9",
@@ -156,8 +156,8 @@
     "zod": "4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.10",
-    "@cloudflare/workers-types": "^4.20260409.1",
+    "@biomejs/biome": "2.4.11",
+    "@cloudflare/workers-types": "^4.20260413.1",
     "@hono/otel": "^1.1.1",
     "@opentelemetry/instrumentation-http": "^0.214.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.214.0",
@@ -168,17 +168,17 @@
     "@opentelemetry/sdk-node": "^0.214.0",
     "@opentelemetry/sdk-trace-node": "^2.6.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
-    "@supabase/supabase-js": "^2.102.1",
-    "@types/bun": "^1.3.11",
+    "@supabase/supabase-js": "^2.103.0",
+    "@types/bun": "^1.3.12",
     "@types/diff": "^8.0.0",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.2",
+    "@types/node": "^25.6.0",
     "@types/papaparse": "^5.5.2",
     "@types/sanitize-html": "^2.16.1",
     "@types/validator": "^13.15.10",
-    "@vitest/coverage-istanbul": "4.1.3",
-    "@vitest/ui": "4.1.3",
-    "bun-types": "^1.3.11",
+    "@vitest/coverage-istanbul": "4.1.4",
+    "@vitest/ui": "4.1.4",
+    "bun-types": "^1.3.12",
     "chrono-node": "^2.9.0",
     "clipboardy": "^5.3.1",
     "depcheck": "^1.4.7",
@@ -196,12 +196,12 @@
     "sanitize-html": "^2.17.2",
     "repomix": "^1.13.1",
     "tsc-alias": "^1.8.16",
-    "typedoc": "^0.28.18",
+    "typedoc": "^0.28.19",
     "typescript": "^6.0.2",
-    "unpdf": "^1.4.0",
+    "unpdf": "^1.5.0",
     "validator": "^13.15.35",
     "vite": "8.0.8",
-    "vitest": "^4.1.3"
+    "vitest": "^4.1.4"
   },
   "keywords": [
     "agent",

package/skills/add-test/SKILL.md

@@ -4,14 +4,14 @@ description: >
   Scaffold a test file for an existing tool, resource, or service. Use when the user asks to add tests, improve coverage, or when a definition exists without a matching test file.
 metadata:
   author: cyanheads
-  version: "1.2"
+  version: "1.3"
   audience: external
   type: reference
 ---
 
 ## Context
 
-Tests use Vitest and `createMockContext` from `@cyanheads/mcp-ts-core/testing`. Freshly scaffolded servers place tests under `tests/` (for example `tests/tools/echo.tool.test.ts`), and the default Vitest config also supports `src/**/*.test.ts`. Match the repo's existing layout instead of forcing one.
+Tests use Vitest and `createMockContext` from `@cyanheads/mcp-ts-core/testing`. If the repo already has tests, match the existing layout. If the repo has no existing tests, create a root `tests/` directory that mirrors the `src/` structure (e.g. `tests/mcp-server/tools/definitions/echo.tool.test.ts` for `src/mcp-server/tools/definitions/echo.tool.ts`).
 
 For the full `createMockContext` API and testing patterns, read:
 

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

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.1"
+  version: "2.2"
   audience: external
   type: workflow
 ---
@@ -117,9 +117,7 @@ const gitBranch = tool('git_branch', {
 ```ts
 // Workflow tool — search + local filter pipeline, not a raw API proxy
 const findEligibleStudies = tool('clinicaltrials_find_eligible_studies', {
-  description: 'Matches patient demographics and medical profile to eligible clinical trials. '
-    + 'Filters by age, sex, conditions, location, and healthy volunteer status. '
-    + 'Returns ranked list of matching studies with eligibility explanations.',
+  description: 'Matches patient demographics and medical profile to eligible clinical trials. Filters by age, sex, conditions, location, and healthy volunteer status. Returns ranked list of matching studies with eligibility explanations.',
   // handler: listStudies() → filter by eligibility → rank by location proximity → slice
 });
 ```
@@ -142,21 +140,20 @@ The description is the LLM's primary signal for tool selection. It must answer:
 
 - **Be concrete about capability.** "Search for clinical trial studies using queries and filters" beats "Interact with studies."
 - **Include operational guidance when it matters.** If the tool has prerequisites, constraints, or gotchas the LLM needs to know, say so in the description. Don't add boilerplate workflow hints when the tool is self-explanatory.
+- **Don't leak implementation details.** Descriptions are for the consumer, not the author. Internal endpoint paths, API call counts, internal parameter name mappings, and routing logic don't belong — describe what the tool does and when to use it, not how it's wired up.
 
 ```ts
 // Good — describes a prerequisite the LLM must know
-description: 'Set the session working directory for all git operations. '
-  + 'This allows subsequent git commands to omit the path parameter.'
+description: 'Set the session working directory for all git operations. This allows subsequent git commands to omit the path parameter.'
 
 // Good — self-explanatory, no workflow hints needed
 description: 'Show the working tree status including staged, unstaged, and untracked files.'
 
 // Good — warns about constraints
-description: 'Fetches trial results data for completed studies. '
-  + 'Only available for studies where hasResults is true.'
+description: 'Fetches trial results data for completed studies. Only available for studies where hasResults is true.'
 ```
 
-Context-dependent: a simple read-only tool needs a one-line description. A tool with prerequisites, modes, or non-obvious behavior needs more. Match depth of description to complexity of tool.
+Descriptions should be as long as needed — concise but complete. Don't artificially truncate, and don't pad with filler.
 
 #### Parameter descriptions
 
@@ -171,14 +168,11 @@ Every `.describe()` is prompt text the LLM reads. Parameters should convey: what
 ```ts
 // Good — explains cost, recommends action, names the alternative
 fields: z.array(z.string()).optional()
-  .describe('Specific fields to return (reduces payload size). '
-    + 'STRONGLY RECOMMENDED — without this, the full study record (~70KB each) is returned. '
-    + 'Use full data only when you need detailed eligibility criteria, locations, or results.'),
+  .describe('Specific fields to return (reduces payload size). Without this, the full study record (~70KB each) is returned. Use full data only when you need detailed eligibility criteria, locations, or results.'),
 
 // Good — explains what the flag does AND how to override
 autoExclude: z.boolean().default(true)
-  .describe('Automatically exclude lock files and generated files from diff output '
-    + 'to reduce context bloat. Set to false if you need to inspect these files.'),
+  .describe('Automatically exclude lock files and generated files from diff output to reduce context bloat. Set to false if you need to inspect these files.'),
 
 // Good — names the format and gives one example
 nctIds: z.union([z.string(), z.array(z.string()).max(5)])
@@ -201,8 +195,7 @@ The output schema and `format` function control what the LLM reads back. Design
 output: z.object({
   diff: z.string().describe('Unified diff output.'),
   excludedFiles: z.array(z.string()).optional()
-    .describe('Files automatically excluded from the diff (e.g., lock files). '
-      + 'Call again with autoExclude=false to include them.'),
+    .describe('Files automatically excluded from the diff (e.g., lock files). Call again with autoExclude=false to include them.'),
 }),
 ```
 
@@ -244,9 +237,7 @@ When a tool wraps a complex query language or filter system, provide a simple sh
 ```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.'),
+  .describe('Convenience shortcut: full-text search across title and abstract. For structured filters or field-specific matching, use the query parameter instead.'),
 query: z.record(z.unknown()).optional()
   .describe('Full query object for structured filters. Supports operators: _eq, _gt, _and, _or, ...'),
 ```

package/templates/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** {{PACKAGE_NAME}}
-**Version:** 0.1.0
+**Version:** 0.1.1
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -224,6 +224,7 @@ Available skills:
 | `setup` | Post-init project orientation |
 | `design-mcp-server` | Design tool surface, resources, and services for a new server |
 | `add-tool` | Scaffold a new tool definition |
+| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
 | `add-service` | Scaffold a new service integration |

package/templates/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** {{PACKAGE_NAME}}
-**Version:** 0.1.0
+**Version:** 0.1.1
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -25,7 +25,7 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 
 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
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
 4. **Add services** — scaffold domain service integrations using the `add-service` skill
 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
@@ -224,6 +224,7 @@ Available skills:
 | `setup` | Post-init project orientation |
 | `design-mcp-server` | Design tool surface, resources, and services for a new server |
 | `add-tool` | Scaffold a new tool definition |
+| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
 | `add-service` | Scaffold a new service integration |