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

package/skills/add-resource/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: add-resource
+description: >
+  Scaffold a new MCP resource definition. Use when the user asks to add a resource, expose data via URI, or create a readable endpoint.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Context
+
+Resources use the `resource()` builder from `@cyanheads/mcp-ts-core`. Each resource lives in `src/mcp-server/resources/definitions/` with a `.resource.ts` suffix and is registered in the barrel `index.ts`.
+
+For the full `resource()` API, pagination utilities, and `Context` interface, read:
+
+    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+
+## Steps
+
+1. **Ask the user** for the resource's URI template, purpose, and data shape
+2. **Design the URI** — use `{paramName}` for path parameters (e.g., `myscheme://{itemId}/data`)
+3. **Create the file** at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`
+4. **Register** the resource in `src/mcp-server/resources/definitions/index.ts`
+5. **Run `bun run devcheck`** to verify
+6. **Smoke-test** with `bun run dev:stdio` or `dev:http`
+
+## Template
+
+```typescript
+/**
+ * @fileoverview {{RESOURCE_DESCRIPTION}}
+ * @module mcp-server/resources/definitions/{{RESOURCE_NAME}}
+ */
+
+import { z } from 'zod';
+import { resource } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+export const {{RESOURCE_EXPORT}} = resource('{{scheme}}://{{{paramName}}}/data', {
+  description: '{{RESOURCE_DESCRIPTION}}',
+  mimeType: 'application/json',
+  params: z.object({
+    {{paramName}}: z.string().describe('{{PARAM_DESCRIPTION}}'),
+  }),
+  // auth: ['resource:{{resource_name}}:read'],
+
+  async handler(params, ctx) {
+    ctx.log.debug('Fetching resource', { {{paramName}}: params.{{paramName}} });
+    // Pure logic — throw McpError on failure, no try/catch
+    return { /* resource data */ };
+  },
+
+  list: async () => ({
+    resources: [
+      {
+        uri: '{{scheme}}://all',
+        name: '{{RESOURCE_LIST_NAME}}',
+        mimeType: 'application/json',
+      },
+    ],
+  }),
+});
+```
+
+### With pagination
+
+For resources returning large lists, use opaque cursor pagination:
+
+```typescript
+import { extractCursor, paginateArray } from '@cyanheads/mcp-ts-core/utils/pagination';
+
+async handler(params, ctx) {
+  const allItems = await fetchAllItems(params);
+  const cursor = extractCursor(params);
+  const page = paginateArray(allItems, cursor, 20, 100, ctx);
+  return {
+    items: page.items,
+    nextCursor: page.nextCursor,
+  };
+},
+```
+
+### Barrel registration
+
+```typescript
+// src/mcp-server/resources/definitions/index.ts
+import { {{RESOURCE_EXPORT}} } from './{{resource-name}}.resource.js';
+export const allResourceDefinitions = [
+  // ... existing resources
+  {{RESOURCE_EXPORT}},
+];
+```
+
+## Checklist
+
+- [ ] File created at `src/mcp-server/resources/definitions/{{resource-name}}.resource.ts`
+- [ ] URI template uses `{paramName}` syntax for path parameters
+- [ ] All Zod `params` fields have `.describe()` annotations
+- [ ] JSDoc `@fileoverview` and `@module` header present
+- [ ] `handler(params, ctx)` is pure — throws `McpError`, no try/catch
+- [ ] `list()` function provided if the resource is discoverable
+- [ ] Pagination used for large result sets (`extractCursor`/`paginateArray`)
+- [ ] Registered in `definitions/index.ts` barrel and `allResourceDefinitions`
+- [ ] `bun run devcheck` passes
+- [ ] Smoke-tested with `bun run dev:stdio` or `dev:http`

package/skills/add-service/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: add-service
+description: >
+  Scaffold a new service integration. Use when the user asks to add a service, integrate an external API, or create a reusable domain module with its own initialization and state.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Context
+
+Services use the init/accessor pattern: initialized once in `createApp`'s `setup()` callback, then accessed at request time via a lazy getter. Each service lives in `src/services/[domain]/` with an init function and accessor.
+
+Service methods receive `Context` for correlated logging (`ctx.log`) and tenant-scoped storage (`ctx.state`). Convention: `ctx.elicit` and `ctx.sample` should only be called from tool handlers, not from services.
+
+For the full service pattern, `CoreServices`, and `Context` interface, read:
+
+    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+
+## Steps
+
+1. **Ask the user** for the service domain name and what it integrates with
+2. **Create the directory** at `src/services/{{domain}}/`
+3. **Create the service file** at `src/services/{{domain}}/{{domain}}-service.ts`
+4. **Create types** at `src/services/{{domain}}/types.ts` if needed
+5. **Register in `setup()`** in the server's entry point (`src/index.ts`)
+6. **Run `bun run devcheck`** to verify
+
+## Template
+
+### Service file
+
+```typescript
+/**
+ * @fileoverview {{SERVICE_DESCRIPTION}}
+ * @module services/{{domain}}/{{domain}}-service
+ */
+
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { Context } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+export class {{ServiceName}} {
+  constructor(
+    private readonly config: AppConfig,
+    private readonly storage: StorageService,
+  ) {}
+
+  async doWork(input: string, ctx: Context): Promise<string> {
+    ctx.log.debug('Processing', { input });
+    // Domain logic here
+    return `result: ${input}`;
+  }
+}
+
+// --- Init/accessor pattern ---
+
+let _service: {{ServiceName}} | undefined;
+
+export function init{{ServiceName}}(config: AppConfig, storage: StorageService): void {
+  _service = new {{ServiceName}}(config, storage);
+}
+
+export function get{{ServiceName}}(): {{ServiceName}} {
+  if (!_service) {
+    throw new McpError(
+      JsonRpcErrorCode.InitializationFailed,
+      '{{ServiceName}} not initialized',
+    );
+  }
+  return _service;
+}
+```
+
+### Entry point registration
+
+```typescript
+// src/index.ts
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { init{{ServiceName}} } from './services/{{domain}}/{{domain}}-service.js';
+
+await createApp({
+  tools: allToolDefinitions,
+  resources: allResourceDefinitions,
+  prompts: allPromptDefinitions,
+  setup(core) {
+    init{{ServiceName}}(core.config, core.storage);
+  },
+});
+```
+
+### Usage in tool handlers
+
+```typescript
+import { get{{ServiceName}} } from '@/services/{{domain}}/{{domain}}-service.js';
+
+handler: async (input, ctx) => {
+  return get{{ServiceName}}().doWork(input.query, ctx);
+},
+```
+
+## Checklist
+
+- [ ] Directory created at `src/services/{{domain}}/`
+- [ ] Service file created with init/accessor pattern
+- [ ] JSDoc `@fileoverview` and `@module` header present
+- [ ] Service methods accept `Context` for logging and storage
+- [ ] `init` function registered in `setup()` callback in `src/index.ts`
+- [ ] Accessor throws `McpError(InitializationFailed)` if not initialized
+- [ ] `bun run devcheck` passes

package/skills/add-tool/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: add-tool
+description: >
+  Scaffold a new MCP tool definition. Use when the user asks to add a tool, create a new tool, or implement a new capability for the server.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Context
+
+Tools use the `tool()` builder from `@cyanheads/mcp-ts-core`. Each tool lives in `src/mcp-server/tools/definitions/` with a `.tool.ts` suffix and is registered in the barrel `index.ts`.
+
+For the full `tool()` API, `Context` interface, and error codes, read:
+
+    node_modules/@cyanheads/mcp-ts-core/CLAUDE.md
+
+## Steps
+
+1. **Ask the user** for the tool's name, purpose, and input/output shape
+2. **Determine if long-running** — if the tool involves streaming, polling, or
+   multi-step async work, it should use `task: true`
+3. **Create the file** at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
+4. **Register** the tool in `src/mcp-server/tools/definitions/index.ts`
+5. **Run `bun run devcheck`** to verify
+6. **Smoke-test** with `bun run dev:stdio` or `dev:http`
+
+## Template
+
+```typescript
+/**
+ * @fileoverview {{TOOL_DESCRIPTION}}
+ * @module mcp-server/tools/definitions/{{TOOL_NAME}}
+ */
+
+import { z } from 'zod';
+import { tool } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
+  description: '{{TOOL_DESCRIPTION}}',
+  annotations: { readOnlyHint: true },
+  input: z.object({
+    // All fields need .describe()
+  }),
+  output: z.object({
+    // All fields need .describe()
+  }),
+  // auth: ['tool:{{tool_name}}:read'],
+
+  async handler(input, ctx) {
+    ctx.log.info('Processing', { /* relevant input fields */ });
+    // Pure logic — throw McpError on failure, no try/catch
+    return { /* output */ };
+  },
+
+  format: (result) => [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+});
+```
+
+### Task tool variant
+
+Add `task: true` and use `ctx.progress` for long-running operations:
+
+```typescript
+export const {{TOOL_EXPORT}} = tool('{{tool_name}}', {
+  description: '{{TOOL_DESCRIPTION}}',
+  task: true,
+  input: z.object({ /* ... */ }),
+
+  async handler(input, ctx) {
+    await ctx.progress!.setTotal(totalSteps);
+    for (const step of steps) {
+      if (ctx.signal.aborted) break;
+      await ctx.progress!.update(`Processing: ${step}`);
+      // ... do work ...
+      await ctx.progress!.increment();
+    }
+    return { /* output */ };
+  },
+});
+```
+
+### Barrel registration
+
+```typescript
+// src/mcp-server/tools/definitions/index.ts
+export { {{TOOL_EXPORT}} } from './{{tool-name}}.tool.js';
+
+// Add to allToolDefinitions array
+import { {{TOOL_EXPORT}} } from './{{tool-name}}.tool.js';
+export const allToolDefinitions = [
+  // ... existing tools
+  {{TOOL_EXPORT}},
+];
+```
+
+## Checklist
+
+- [ ] File created at `src/mcp-server/tools/definitions/{{tool-name}}.tool.ts`
+- [ ] All Zod schema fields have `.describe()` annotations
+- [ ] JSDoc `@fileoverview` and `@module` header present
+- [ ] `handler(input, ctx)` is pure — throws `McpError`, no try/catch
+- [ ] `auth` scopes declared if the tool needs authorization
+- [ ] `task: true` added if the tool is long-running
+- [ ] Registered in `definitions/index.ts` barrel and `allToolDefinitions`
+- [ ] `bun run devcheck` passes
+- [ ] Smoke-tested with `bun run dev:stdio` or `dev:http`

package/skills/api-auth/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: api-auth
+description: >
+  Authentication, authorization, and multi-tenancy patterns for `@cyanheads/mcp-ts-core`. Use when implementing auth scopes on tools/resources, configuring auth modes (none/jwt/oauth), working with JWT/OAuth env vars, or understanding how tenantId flows through ctx.state.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+The framework handles auth at the handler factory level — tools and resources declare required scopes declaratively, and the framework enforces them before calling the handler. No try/catch or manual scope checking required for the common case.
+
+---
+
+## Inline Auth (Primary Pattern)
+
+Declare required scopes directly on the tool or resource definition via the `auth` property. The handler factory checks `ctx.auth.scopes` against these before calling `handler`.
+
+```ts
+import { tool } from '@cyanheads/mcp-ts-core';
+
+const myTool = tool('my_tool', {
+  auth: ['tool:my_tool:read'],
+  async handler(input, ctx) {
+    // Only reached if caller has 'tool:my_tool:read' scope
+  },
+});
+```
+
+When `MCP_AUTH_MODE=none`, auth checks are skipped and defaults are allowed.
+
+---
+
+## Dynamic Auth
+
+For runtime-computed scopes (e.g., scopes that depend on input values like a team or resource ID), use `checkScopes` from `@cyanheads/mcp-ts-core/auth` inside the handler:
+
+```ts
+import { checkScopes } from '@cyanheads/mcp-ts-core/auth';
+
+handler: async (input, ctx) => {
+  checkScopes(ctx, [`team:${input.teamId}:write`]);
+  // Continues only if scope is satisfied
+},
+```
+
+**Signature:** `checkScopes(ctx: Context, requiredScopes: string[]): void`
+
+**Throws:**
+- `McpError(Forbidden)` — auth is active and one or more required scopes are missing
+- `McpError(Unauthorized)` — auth is enabled but no auth context exists on the request
+- No-ops when `MCP_AUTH_MODE=none`
+
+---
+
+## Auth Modes
+
+Set via `MCP_AUTH_MODE` environment variable.
+
+| Mode | Value | Behavior |
+|:-----|:------|:---------|
+| Disabled | `none` | No auth enforcement. All requests allowed. |
+| JWT | `jwt` | Local secret verification via `MCP_AUTH_SECRET_KEY`. Requires explicit `DEV_MCP_AUTH_BYPASS=true` to bypass in development. |
+| OAuth | `oauth` | JWKS verification against an external issuer. |
+
+### JWT Config
+
+| Variable | Required | Purpose |
+|:---------|:---------|:--------|
+| `MCP_AUTH_SECRET_KEY` | Yes (unless bypass) | Signing secret for HS256 JWT verification. Must be ≥ 32 characters. |
+| `DEV_MCP_AUTH_BYPASS` | No | Set to `true` to skip JWT verification in development. Blocked in `NODE_ENV=production`. |
+| `DEV_MCP_CLIENT_ID` | No | Client ID injected when bypass is active (default: `'dev-client-id'`). |
+| `DEV_MCP_SCOPES` | No | Comma-separated scopes injected when bypass is active (default: `['dev-scope']`). |
+
+**Important:** With `MCP_AUTH_MODE=jwt`, a missing `MCP_AUTH_SECRET_KEY` is a **fatal startup error** unless `DEV_MCP_AUTH_BYPASS=true` is explicitly set. Setting `DEV_MCP_AUTH_BYPASS` in production (`NODE_ENV=production`) is rejected at config parse time.
+
+### OAuth Config
+
+| Variable | Required | Purpose |
+|:---------|:---------|:--------|
+| `OAUTH_ISSUER_URL` | Yes | Token issuer URL (used for JWKS discovery) |
+| `OAUTH_AUDIENCE` | Yes | Expected `aud` claim value |
+| `OAUTH_JWKS_URI` | No | Override JWKS endpoint (defaults to `{issuer}/.well-known/jwks.json`) |
+
+### JWT Claims Mapping
+
+| Claim | JWT Field | Purpose |
+|:------|:----------|:--------|
+| `clientId` | `cid` / `client_id` | Identifies the calling client |
+| `scopes` | `scp` / `scope` | Space-separated list of granted scopes |
+| `sub` | `sub` | Subject (user or service identity) |
+| `tenantId` | `tid` | Tenant identifier — drives `ctx.state` scoping |
+
+---
+
+## Endpoints
+
+| Endpoint | Protected |
+|:---------|:----------|
+| `GET /healthz` | No |
+| `GET /mcp` | No |
+| `POST /mcp` | Yes (when auth enabled) |
+| `OPTIONS /mcp` | Yes (when auth enabled) |
+
+**CORS:** Set `MCP_ALLOWED_ORIGINS` to a comma-separated list of allowed origins, or `*` for open access.
+
+**Stdio mode:** No HTTP auth layer. Authorization is handled entirely by the host process.
+
+---
+
+## Multi-Tenancy
+
+`ctx.state` is automatically scoped to the current tenant — no manual key prefixing needed.
+
+### tenantId Sources
+
+| Transport | Source | Value |
+|:----------|:-------|:------|
+| HTTP with auth | JWT `tid` claim | Auto-propagated from token |
+| Stdio | Hardcoded default | `'default'` |
+
+### Tenant ID Validation Rules
+
+- Max 128 characters
+- Characters: alphanumeric, hyphens, underscores, dots
+- Must start and end with an alphanumeric character
+- No path traversal sequences (`../`)
+- No consecutive dots (`..`)
+
+### Using ctx.state
+
+```ts
+handler: async (input, ctx) => {
+  // Automatically scoped to ctx.tenantId — no manual prefixing
+  await ctx.state.set('item:123', JSON.stringify(data));
+  const value = await ctx.state.get('item:123');
+  await ctx.state.delete('item:123');
+
+  const page = await ctx.state.list('item:', { cursor, limit: 20 });
+  // page: { items: Array<{ key, value }>, cursor?: string }
+},
+```
+
+`ctx.state` throws `McpError(InvalidRequest)` if `tenantId` is missing. In stdio mode, `tenantId` defaults to `'default'` so `ctx.state` works without auth.
+
+---
+
+## Auth Context Shape
+
+Available on `ctx.auth` inside handlers (when auth is enabled):
+
+```ts
+interface AuthContext {
+  clientId: string;        // Required — 'cid' or 'client_id' JWT claim
+  scopes: string[];        // Required — derived from 'scp' or 'scope' claim
+  sub: string;             // Required — 'sub' claim; falls back to clientId when absent
+  token: string;           // Required — raw JWT or OAuth bearer token string
+  tenantId?: string;       // Optional — 'tid' claim; present only for multi-tenant tokens
+  [key: string]: unknown;  // Additional token payload properties
+}
+```
+
+Access directly for conditional logic:
+
+```ts
+handler: async (input, ctx) => {
+  const isAdmin = ctx.auth?.scopes.includes('admin:write') ?? false;
+  // ...
+},
+```

package/skills/api-config/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: api-config
+description: >
+  Reference for core and server configuration in `@cyanheads/mcp-ts-core`. Covers env var tables, priority order, server-specific Zod schema pattern, and Workers lazy-parsing requirement.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+Configuration has two layers: **core config** (managed by the framework, env-driven) and **server config** (your own Zod schema for domain-specific env vars). Never merge them.
+
+Import: `AppConfig`, `parseConfig` from `@cyanheads/mcp-ts-core/config`.
+
+---
+
+## Core Config
+
+Managed by `@cyanheads/mcp-ts-core`. Validated via Zod from environment variables.
+
+**Priority (highest to lowest):**
+
+1. `name`/`version` overrides passed to `createApp()` or `createWorkerHandler()`
+2. Environment variables
+3. `package.json` fields
+
+| Category | Key Variables |
+|:---------|:-------------|
+| Transport | `MCP_TRANSPORT_TYPE` (`stdio`\|`http`), `MCP_HTTP_PORT`, `MCP_HTTP_HOST`, `MCP_HTTP_ENDPOINT_PATH` |
+| Auth | `MCP_AUTH_MODE` (`none`\|`jwt`\|`oauth`), `MCP_AUTH_SECRET_KEY`, `OAUTH_*` |
+| Storage | `STORAGE_PROVIDER_TYPE` (`in-memory`\|`filesystem`\|`supabase`\|`cloudflare-r2`\|`cloudflare-kv`\|`cloudflare-d1`) |
+| LLM | `OPENROUTER_API_KEY`, `OPENROUTER_APP_URL/NAME`, `LLM_DEFAULT_*` |
+| Telemetry | `OTEL_ENABLED`, `OTEL_SERVICE_NAME/VERSION`, `OTEL_EXPORTER_OTLP_*` |
+
+---
+
+## Server Config (Separate Schema)
+
+Servers define their own Zod schema for domain-specific env vars. **Never merge with core's schema.**
+
+Use the lazy init/accessor pattern — do not parse `process.env` at module top-level.
+
+```ts
+// src/config/server-config.ts
+import { z } from 'zod';
+
+const ServerConfigSchema = z.object({
+  myApiKey: z.string().describe('External API key'),
+  maxResults: z.coerce.number().default(100),
+});
+
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+
+let _config: ServerConfig | undefined;
+
+export function getServerConfig(): ServerConfig {
+  _config ??= ServerConfigSchema.parse({
+    myApiKey: process.env.MY_API_KEY,
+    maxResults: process.env.MY_MAX_RESULTS,
+  });
+  return _config;
+}
+```
+
+**Workers warning:** Do not eagerly parse `process.env` at module top-level. In Workers, env bindings are injected at request time via `injectEnvVars()` — after all static imports. Lazy parsing is mandatory for Worker compatibility.