@cyanheads/mcp-ts-core 0.1.0-beta.12

package/package.json

@@ -0,0 +1,377 @@
+{
+  "name": "@cyanheads/mcp-ts-core",
+  "version": "0.1.0-beta.12",
+  "mcpName": "io.github.cyanheads/mcp-ts-core",
+  "description": "TypeScript framework for building Model Context Protocol (MCP) servers. Declarative tool/resource/prompt definitions, pluggable auth, multi-backend storage, OpenTelemetry observability, and support for both local (stdio/HTTP) and edge (Cloudflare Workers) runtimes.",
+  "main": "dist/app.js",
+  "types": "dist/app.d.ts",
+  "files": [
+    "dist/",
+    "skills/",
+    "templates/",
+    "CLAUDE.md",
+    "tsconfig.base.json",
+    "vitest.config.base.ts",
+    "biome.json"
+  ],
+  "bin": {
+    "mcp-ts-core": "dist/cli/init.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/app.d.ts",
+      "import": "./dist/app.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
+    "./tools": {
+      "types": "./dist/mcp-server/tools/utils/newToolDefinition.d.ts",
+      "import": "./dist/mcp-server/tools/utils/newToolDefinition.js"
+    },
+    "./resources": {
+      "types": "./dist/mcp-server/resources/utils/newResourceDefinition.d.ts",
+      "import": "./dist/mcp-server/resources/utils/newResourceDefinition.js"
+    },
+    "./prompts": {
+      "types": "./dist/mcp-server/prompts/utils/newPromptDefinition.d.ts",
+      "import": "./dist/mcp-server/prompts/utils/newPromptDefinition.js"
+    },
+    "./tasks": {
+      "types": "./dist/mcp-server/tasks/utils/taskToolDefinition.d.ts",
+      "import": "./dist/mcp-server/tasks/utils/taskToolDefinition.js"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "import": "./dist/context.js"
+    },
+    "./errors": {
+      "types": "./dist/types-global/errors.d.ts",
+      "import": "./dist/types-global/errors.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./auth": {
+      "types": "./dist/mcp-server/transports/auth/lib/checkScopes.d.ts",
+      "import": "./dist/mcp-server/transports/auth/lib/checkScopes.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/core/StorageService.d.ts",
+      "import": "./dist/storage/core/StorageService.js"
+    },
+    "./storage/types": {
+      "types": "./dist/storage/core/IStorageProvider.d.ts",
+      "import": "./dist/storage/core/IStorageProvider.js"
+    },
+    "./utils/logger": {
+      "types": "./dist/utils/internal/logger.d.ts",
+      "import": "./dist/utils/internal/logger.js"
+    },
+    "./utils/requestContext": {
+      "types": "./dist/utils/internal/requestContext.d.ts",
+      "import": "./dist/utils/internal/requestContext.js"
+    },
+    "./utils/errorHandler": {
+      "types": "./dist/utils/internal/error-handler/errorHandler.d.ts",
+      "import": "./dist/utils/internal/error-handler/errorHandler.js"
+    },
+    "./utils/formatting": {
+      "types": "./dist/utils/formatting/index.d.ts",
+      "import": "./dist/utils/formatting/index.js"
+    },
+    "./utils/parsing": {
+      "types": "./dist/utils/parsing/index.d.ts",
+      "import": "./dist/utils/parsing/index.js"
+    },
+    "./utils/security": {
+      "types": "./dist/utils/security/index.d.ts",
+      "import": "./dist/utils/security/index.js"
+    },
+    "./utils/network": {
+      "types": "./dist/utils/network/fetchWithTimeout.d.ts",
+      "import": "./dist/utils/network/fetchWithTimeout.js"
+    },
+    "./utils/pagination": {
+      "types": "./dist/utils/pagination/pagination.d.ts",
+      "import": "./dist/utils/pagination/pagination.js"
+    },
+    "./utils/runtime": {
+      "types": "./dist/utils/internal/runtime.d.ts",
+      "import": "./dist/utils/internal/runtime.js"
+    },
+    "./utils/scheduling": {
+      "types": "./dist/utils/scheduling/scheduler.d.ts",
+      "import": "./dist/utils/scheduling/scheduler.js"
+    },
+    "./utils/types": {
+      "types": "./dist/utils/types/index.d.ts",
+      "import": "./dist/utils/types/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./vitest.config": "./vitest.config.base.ts",
+    "./biome.json": "./biome.json",
+    "./package.json": "./package.json"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyanheads/mcp-ts-template.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cyanheads/mcp-ts-template/issues"
+  },
+  "homepage": "https://github.com/cyanheads/mcp-ts-template#readme",
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "deploy:dev": "MCP_TRANSPORT_TYPE=http bunx wrangler dev",
+    "deploy:prod": "MCP_TRANSPORT_TYPE=http bunx wrangler deploy",
+    "start": "bun ./dist/index.js",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio bun ./dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http bun ./dist/index.js",
+    "dev": "bun --watch src/index.ts",
+    "dev:stdio": "MCP_LOG_LEVEL=debug MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts",
+    "dev:http": "MCP_LOG_LEVEL=debug MCP_TRANSPORT_TYPE=http bun --watch src/index.ts",
+    "devdocs": "bun run scripts/devdocs.ts",
+    "devcheck": "bun run scripts/devcheck.ts",
+    "rebuild": "bun run scripts/clean.ts && bun run build",
+    "prepublishOnly": "bun run build",
+    "docs:generate": "bunx typedoc",
+    "depcheck": "bunx depcheck",
+    "lint": "biome check",
+    "format": "biome check --write --unsafe",
+    "typecheck": "bunx tsc --noEmit",
+    "typecheck:scripts": "bunx tsc --project tsconfig.scripts.json --noEmit",
+    "tree": "bun run scripts/tree.ts",
+    "fetch-spec": "bun run scripts/fetch-openapi-spec.ts",
+    "prepare": "bunx husky",
+    "inspector": "bunx mcp-inspector --config mcp.json --server mcp-ts-core",
+    "test": "bunx vitest run",
+    "test:all": "bun run test && bun run test:integration",
+    "test:integration": "bunx vitest run --config vitest.integration.ts",
+    "test:fuzz": "bunx vitest run fuzz",
+    "test:report": "bun run scripts/test-report.ts",
+    "test:report:open": "bun run scripts/test-report.ts --open",
+    "test:ui": "bunx vitest --ui",
+    "test:coverage": "bunx vitest run --coverage",
+    "coverage:update": "bun run scripts/update-coverage.ts",
+    "coverage:commit": "bun run scripts/update-coverage.ts --commit",
+    "audit": "bun audit",
+    "audit:fix": "bun audit --fix",
+    "publish-mcp": "bunx mcp-publisher publish"
+  },
+  "resolutions": {
+    "escape-string-regexp": "4.0.0",
+    "@hono/node-server": "1.19.11",
+    "@isaacs/brace-expansion": "5.0.1",
+    "chrono-node": "2.9.0",
+    "diff": "8.0.3",
+    "dotenv": "17.3.1",
+    "hono": "4.12.7",
+    "markdown-it": "14.1.1",
+    "qs": "6.15.0",
+    "zod": "4.3.6",
+    "typescript": "5.9.3",
+    "minimatch": "3.1.5",
+    "ajv": "8.18.0",
+    "lodash": "4.17.23",
+    "rollup": "4.59.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.6",
+    "@cloudflare/workers-types": "^4.20260312.1",
+    "@types/bun": "^1.3.10",
+    "@types/diff": "^8.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.4.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/papaparse": "^5.5.2",
+    "@types/sanitize-html": "^2.16.1",
+    "@types/validator": "13.15.10",
+    "@vitest/coverage-istanbul": "4.0.18",
+    "@vitest/ui": "4.0.18",
+    "bun-types": "^1.3.10",
+    "clipboardy": "^5.3.1",
+    "depcheck": "^1.4.7",
+    "execa": "^9.6.1",
+    "fast-check": "^4.6.0",
+    "husky": "^9.1.7",
+    "ignore": "^7.0.5",
+    "msw": "^2.12.10",
+    "pino-pretty": "^13.1.3",
+    "repomix": "^1.12.0",
+    "tsc-alias": "^1.8.16",
+    "typedoc": "^0.28.17",
+    "typescript": "^5.9.3",
+    "vite": "7.3.1",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "ai-agent",
+    "authentication",
+    "cloudflare-workers",
+    "declarative-tools",
+    "core",
+    "error-handling",
+    "hono",
+    "llm-integration",
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "elicitation",
+    "observability",
+    "opentelemetry",
+    "otel",
+    "framework",
+    "typescript",
+    "zod"
+  ],
+  "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/mcp-ts-template#readme)",
+  "license": "Apache-2.0",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/cyanheads"
+    },
+    {
+      "type": "buy_me_a_coffee",
+      "url": "https://www.buymeacoffee.com/cyanheads"
+    }
+  ],
+  "packageManager": "bun@1.3.2",
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=22.0.0"
+  },
+  "depcheck": {
+    "ignores": [
+      "bun",
+      "repomix",
+      "tsc-alias",
+      "@cyanheads/mcp-ts-core",
+      "@modelcontextprotocol/ext-apps"
+    ],
+    "ignorePatterns": ["examples"]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hono/mcp": "^0.2.4",
+    "@hono/node-server": "^1.19.11",
+    "@modelcontextprotocol/ext-apps": "^1.2.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@opentelemetry/api": "^1.9.0",
+    "dotenv": "^17.3.1",
+    "hono": "^4.12.5",
+    "jose": "^6.2.1",
+    "pino": "^10.3.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.6",
+    "@hono/otel": "latest",
+    "@opentelemetry/auto-instrumentations-node": "latest",
+    "@opentelemetry/exporter-metrics-otlp-http": "latest",
+    "@opentelemetry/exporter-trace-otlp-http": "latest",
+    "@opentelemetry/instrumentation-pino": "latest",
+    "@opentelemetry/resources": "latest",
+    "@opentelemetry/sdk-metrics": "latest",
+    "@opentelemetry/sdk-node": "latest",
+    "@opentelemetry/sdk-trace-node": "latest",
+    "@opentelemetry/semantic-conventions": "latest",
+    "@supabase/supabase-js": "latest",
+    "chrono-node": "latest",
+    "diff": "^8.0.3",
+    "fast-xml-parser": "^5.4.1",
+    "js-yaml": "^3.14.2",
+    "node-cron": "latest",
+    "openai": "latest",
+    "papaparse": "latest",
+    "partial-json": "latest",
+    "pdf-lib": "latest",
+    "sanitize-html": "latest",
+    "unpdf": "latest",
+    "validator": "latest"
+  },
+  "peerDependenciesMeta": {
+    "@hono/otel": {
+      "optional": true
+    },
+    "@opentelemetry/auto-instrumentations-node": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-metrics-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-pino": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-metrics": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-node": {
+      "optional": true
+    },
+    "@opentelemetry/semantic-conventions": {
+      "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "chrono-node": {
+      "optional": true
+    },
+    "diff": {
+      "optional": true
+    },
+    "fast-xml-parser": {
+      "optional": true
+    },
+    "js-yaml": {
+      "optional": true
+    },
+    "node-cron": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    },
+    "papaparse": {
+      "optional": true
+    },
+    "partial-json": {
+      "optional": true
+    },
+    "pdf-lib": {
+      "optional": true
+    },
+    "sanitize-html": {
+      "optional": true
+    },
+    "unpdf": {
+      "optional": true
+    },
+    "validator": {
+      "optional": true
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,38 @@
+# Skills
+
+Agent Skills for `@cyanheads/mcp-ts-core`. Each subdirectory contains a `SKILL.md` following the [Agent Skills specification](https://agentskills.io/specification).
+
+## Three-Tier Distribution
+
+Skills flow through three locations. Each tier has a distinct role:
+
+| Tier | Location | Written by | Purpose |
+|:-----|:---------|:-----------|:--------|
+| 1. Package | `node_modules/@cyanheads/mcp-ts-core/skills/` | `npm publish` / `bun publish` | Canonical source. Ships with the package. |
+| 2. Project | `skills/` (project root) | `@cyanheads/mcp-ts-core init` CLI | Project's source of truth. Committed to git. Server-specific skills live here too. |
+| 3. Agent | `.claude/skills/`, `.codex/skills/`, etc. | The agent itself | Agent's working copy. Synced from project `skills/`. Checklists are checked here. |
+
+### Flow
+
+```
+npm publish                    init CLI                    agent sync
+[package skills/] ──────────> [project skills/] ──────────> [.claude/skills/]
+                                     │
+                                     ├── core skills (from package)
+                                     └── server-specific skills (added by devs)
+```
+
+## Audience
+
+Each skill declares `metadata.audience` in its SKILL.md frontmatter:
+
+- **`external`** — For consumers building MCP servers. Copied to project `skills/` by `init`.
+- **`internal`** — For core package developers. Stays in `node_modules`, not copied.
+
+## Versioning
+
+Skills declare `metadata.version` in frontmatter. When `init` is re-run after `bun update`, it compares versions and updates skills where the package version is newer. To pin a skill and prevent updates, bump its local `metadata.version` above the package's.
+
+## Adding Server-Specific Skills
+
+Create a new directory in `skills/` with a `SKILL.md` following the same format. The agent will pick it up on next sync. Use the core skills as examples for structure and checklist conventions.

package/skills/add-export/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: add-export
+description: >
+  Add a new subpath export to the @cyanheads/mcp-ts-core package. Use when creating a new public API surface that consumers import from a dedicated subpath (e.g., @cyanheads/mcp-ts-core/utils/newutil).
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: reference
+---
+
+## Context
+
+Subpath exports are defined in `package.json` under the `exports` field. Each subpath maps to a source entry point that gets compiled to `dist/`. The exports catalog in `CLAUDE.md` must stay in sync with `package.json`.
+
+## Steps
+
+1. **Create the entry point** source file (e.g., `src/utils/new-util.ts`)
+2. **Add the subpath** to `package.json` `exports`:
+   ```jsonc
+   "./utils/newutil": {
+     "types": "./dist/utils/new-util.d.ts",
+     "import": "./dist/utils/new-util.js"
+   }
+   ```
+3. **Update the exports catalog** in `CLAUDE.md` — add a row to the table
+4. **Build** with `bun run build` to generate `dist/` output
+5. **Verify the export** resolves correctly:
+   ```bash
+   node -e "import('@cyanheads/mcp-ts-core/utils/newutil').then(m => console.log(Object.keys(m)))"
+   ```
+6. **Run `bun run devcheck`** to verify
+
+## Naming Conventions
+
+| Convention | Rule |
+|:-----------|:-----|
+| Subpath | lowercase, no underscores (e.g., `utils/errorHandler`) |
+| Source file | kebab-case (e.g., `error-handler.ts`) |
+| Export name | camelCase for values, PascalCase for types |
+
+## Checklist
+
+- [ ] Source entry point file created with JSDoc header
+- [ ] Subpath added to `package.json` `exports` with `types` and `import` conditions
+- [ ] Exports catalog in `CLAUDE.md` updated with new row
+- [ ] `bun run build` succeeds
+- [ ] Export resolves correctly from `node_modules`
+- [ ] `bun run devcheck` passes

package/skills/add-prompt/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: add-prompt
+description: >
+  Scaffold a new MCP prompt template. Use when the user asks to add a prompt, create a reusable message template, or define a prompt for LLM interactions.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Context
+
+Prompts use the `prompt()` builder from `@cyanheads/mcp-ts-core`. Each prompt lives in `src/mcp-server/prompts/definitions/` with a `.prompt.ts` suffix and is registered in the barrel `index.ts`.
+
+Prompts are pure message templates — no `Context`, no auth, no side effects.
+
+For the full `prompt()` API, read:
+
+    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+
+## Steps
+
+1. **Ask the user** for the prompt's name, purpose, and arguments
+2. **Create the file** at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
+3. **Register** the prompt in `src/mcp-server/prompts/definitions/index.ts`
+4. **Run `bun run devcheck`** to verify
+
+## Template
+
+```typescript
+/**
+ * @fileoverview {{PROMPT_DESCRIPTION}}
+ * @module mcp-server/prompts/definitions/{{PROMPT_NAME}}
+ */
+
+import { z } from 'zod';
+import { prompt } from '@cyanheads/mcp-ts-core';
+
+export const {{PROMPT_EXPORT}} = prompt('{{prompt_name}}', {
+  description: '{{PROMPT_DESCRIPTION}}',
+  args: z.object({
+    // All fields need .describe()
+  }),
+  generate: (args) => [
+    {
+      role: 'user',
+      content: {
+        type: 'text',
+        text: `{{PROMPT_TEMPLATE_TEXT}}`,
+      },
+    },
+  ],
+});
+```
+
+### Multi-message prompt
+
+```typescript
+generate: (args) => [
+  {
+    role: 'user',
+    content: {
+      type: 'text',
+      text: `Here is the ${args.type} to review:\n\n${args.content}`,
+    },
+  },
+  {
+    role: 'assistant',
+    content: {
+      type: 'text',
+      text: 'I will analyze this carefully. Let me start with...',
+    },
+  },
+],
+```
+
+### Barrel registration
+
+```typescript
+// src/mcp-server/prompts/definitions/index.ts
+import { {{PROMPT_EXPORT}} } from './{{prompt-name}}.prompt.js';
+export const allPromptDefinitions = [
+  // ... existing prompts
+  {{PROMPT_EXPORT}},
+];
+```
+
+## Checklist
+
+- [ ] File created at `src/mcp-server/prompts/definitions/{{prompt-name}}.prompt.ts`
+- [ ] All Zod `args` fields have `.describe()` annotations
+- [ ] JSDoc `@fileoverview` and `@module` header present
+- [ ] `generate` function returns valid message array
+- [ ] No side effects — prompts are pure templates
+- [ ] Registered in `definitions/index.ts` barrel and `allPromptDefinitions`
+- [ ] `bun run devcheck` passes

package/skills/add-provider/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: add-provider
+description: >
+  Add a new storage or service provider to the core package. Use when implementing a new backend for StorageService (e.g., a new database) or a new service provider (e.g., a new LLM backend).
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: internal
+  type: reference
+---
+
+## Context
+
+Providers implement interfaces defined in core (e.g., `IStorageProvider`). 
+
+They are selected at runtime via config (e.g., `STORAGE_PROVIDER_TYPE`).
+
+Tier 3 providers lazy-load their dependencies to keep the core bundle small.
+
+## Steps
+
+1. **Identify the provider interface** — check the existing interface in the
+   relevant types file (e.g., `src/storage/core/IStorageProvider.ts`)
+2. **Create the provider file** in the appropriate directory
+   (e.g., `src/storage/providers/{{provider-name}}/{{provider-name}}Provider.ts`)
+3. **Implement the interface** — all methods must be implemented
+4. **Lazy-load dependencies** if Tier 3:
+   ```typescript
+   let _client: SomeClient | undefined;
+   async function getClient(): Promise<SomeClient> {
+     if (!_client) {
+       const { SomeClient } = await import('some-package');
+       _client = new SomeClient(/* config */);
+     }
+     return _client;
+   }
+   ```
+5. **Register the provider** in the factory/selector that maps config values
+   to provider instances
+6. **Update the serverless whitelist** if the provider is compatible with Workers
+7. **Add the dependency** as an optional peer dependency in `package.json`
+8. **Run `bun run devcheck`** to verify
+
+## Checklist
+
+- [ ] Provider file created with JSDoc header
+- [ ] Interface fully implemented
+- [ ] Tier 3 dependencies lazy-loaded (not top-level imports)
+- [ ] Registered in provider factory/selector
+- [ ] Serverless whitelist updated if Worker-compatible
+- [ ] Optional peer dependency added to `package.json`
+- [ ] `bun run devcheck` passes
+- [ ] Integration tested with the target backend