@cyanheads/mcp-ts-core 0.1.0 → 0.1.2

package/scripts/tree.ts

@@ -0,0 +1,324 @@
+/**
+ * @fileoverview Generates a visual tree representation of the project's directory structure.
+ * @module scripts/tree
+ *   Respects .gitignore patterns and common exclusions (e.g., node_modules).
+ *   Saves the tree to a markdown file (default: docs/tree.md).
+ *   Supports custom output path, depth limitation, and additional ignore patterns.
+ *
+ * @example
+ * // Generate tree with default settings:
+ * // bun run tree
+ *
+ * @example
+ * // Specify custom output path and depth:
+ * // bun run scripts/tree.ts ./documentation/structure.md --depth=3
+ *
+ * @example
+ * // Add additional ignore patterns:
+ * // bun run scripts/tree.ts --ignore=coverage --ignore="*.log"
+ *
+ * @example
+ * // Preview tree without writing to disk:
+ * // bun run scripts/tree.ts --dry-run
+ */
+import type { Dirent } from 'node:fs';
+import { mkdir, readdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path';
+import ignore from 'ignore';
+
+type Ignore = ReturnType<typeof ignore>;
+
+const KNOWN_FLAGS = ['--depth', '--ignore', '--help', '--dry-run'] as const;
+
+const DEFAULT_IGNORE_PATTERNS: string[] = [
+  '.git',
+  'node_modules',
+  '.DS_Store',
+  'dist',
+  'build',
+  'coverage',
+  'logs',
+  '.husky/_',
+];
+
+interface ParsedArgs {
+  dryRun: boolean;
+  extraIgnorePatterns: string[];
+  maxDepth: number;
+  outputPath: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const result: ParsedArgs = {
+    outputPath: 'docs/tree.md',
+    maxDepth: Infinity,
+    extraIgnorePatterns: [],
+    dryRun: false,
+  };
+
+  for (const arg of argv) {
+    if (arg === '--dry-run') {
+      result.dryRun = true;
+    } else if (arg.startsWith('--depth=')) {
+      const depthValue = parseInt(arg.split('=')[1] ?? '', 10);
+      if (!Number.isNaN(depthValue) && depthValue >= 0) {
+        result.maxDepth = depthValue;
+      } else {
+        console.warn(`Invalid depth value: "${arg}". Using unlimited depth.`);
+      }
+    } else if (arg.startsWith('--ignore=')) {
+      const pattern = arg.slice('--ignore='.length);
+      if (pattern) {
+        result.extraIgnorePatterns.push(pattern);
+      }
+    } else if (arg.startsWith('--')) {
+      const flagName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+      if (!KNOWN_FLAGS.some((known) => flagName === known)) {
+        console.warn(`Unknown flag: "${arg}". Ignoring.`);
+      }
+    } else {
+      result.outputPath = arg;
+    }
+  }
+
+  return result;
+}
+
+function validateOutputPath(outputPath: string, root: string): string {
+  const resolved = resolve(root, outputPath);
+  if (!resolved.startsWith(root + sep)) {
+    throw new Error(`Output path "${outputPath}" resolves outside project root: ${resolved}`);
+  }
+  const resolvedDir = dirname(resolved);
+  if (resolvedDir !== root && !resolvedDir.startsWith(root + sep)) {
+    throw new Error(`Output directory "${resolvedDir}" is outside project root`);
+  }
+  return resolved;
+}
+
+async function loadIgnoreHandler(
+  root: string,
+  extraPatterns: string[],
+  outputFile: string,
+): Promise<Ignore> {
+  const ig = ignore();
+  ig.add(DEFAULT_IGNORE_PATTERNS);
+
+  if (extraPatterns.length > 0) {
+    ig.add(extraPatterns);
+  }
+
+  // Auto-ignore the output file so the generated artifact doesn't list itself
+  const outputRelative = relative(root, outputFile).split(sep).join(posix.sep);
+  ig.add(outputRelative);
+
+  try {
+    const gitignoreContent = await readFile(join(root, '.gitignore'), 'utf-8');
+    ig.add(gitignoreContent);
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+      console.warn(
+        'Info: No .gitignore file found at project root. Using default ignore patterns only.',
+      );
+    } else {
+      const msg = error instanceof Error ? error.message : String(error);
+      console.error(`Error reading .gitignore: ${msg}`);
+    }
+  }
+  return ig;
+}
+
+function isIgnored(entryPath: string, root: string, ig: Ignore): boolean {
+  const rel = relative(root, entryPath).split(sep).join(posix.sep);
+  return ig.ignores(rel);
+}
+
+/**
+ * Recursively generates a string representation of the directory tree.
+ * Uses sequential traversal to avoid unbounded file-descriptor pressure.
+ * Tracks visited real paths to prevent symlink cycles.
+ */
+async function generateTree(
+  dir: string,
+  root: string,
+  ig: Ignore,
+  maxDepth: number,
+  prefix = '',
+  currentDepth = 0,
+  visited = new Set<string>(),
+): Promise<string> {
+  const resolvedDir = resolve(dir);
+  if (!resolvedDir.startsWith(root + sep) && resolvedDir !== root) {
+    console.warn(`Security: Skipping directory outside project root: ${resolvedDir}`);
+    return '';
+  }
+
+  if (currentDepth > maxDepth) {
+    return '';
+  }
+
+  // Resolve symlinks and detect cycles
+  let realDir: string;
+  try {
+    realDir = await realpath(resolvedDir);
+  } catch {
+    return '';
+  }
+  if (visited.has(realDir)) {
+    return '';
+  }
+  visited.add(realDir);
+
+  let entries: Dirent[];
+  try {
+    entries = await readdir(resolvedDir, { withFileTypes: true });
+  } catch (error: unknown) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(`Error reading directory ${resolvedDir}: ${msg}`);
+    return '';
+  }
+
+  const filteredEntries = entries
+    .filter((entry) => !isIgnored(join(resolvedDir, entry.name), root, ig))
+    .sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+  // Sequential traversal — prevents unbounded concurrent readdir calls
+  let result = '';
+  for (let i = 0; i < filteredEntries.length; i++) {
+    const entry = filteredEntries[i];
+    const isLast = i === filteredEntries.length - 1;
+    const connector = isLast ? '\u2514\u2500\u2500 ' : '\u251C\u2500\u2500 ';
+    const newPrefix = prefix + (isLast ? '    ' : '\u2502   ');
+    const displayName = entry.isDirectory() ? `${entry.name}/` : entry.name;
+
+    result += `${prefix + connector + displayName}\n`;
+
+    if (entry.isDirectory()) {
+      result += await generateTree(
+        join(resolvedDir, entry.name),
+        root,
+        ig,
+        maxDepth,
+        newPrefix,
+        currentDepth + 1,
+        visited,
+      );
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extracts the raw tree body from an existing output file for diffing.
+ * Returns null if the file doesn't exist or the tree block can't be parsed.
+ */
+async function readExistingTree(outputFile: string, projectName: string): Promise<string | null> {
+  let content: string;
+  try {
+    content = await readFile(outputFile, 'utf-8');
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return null;
+    const msg = error instanceof Error ? error.message : String(error);
+    console.warn(`Warning: Could not read existing output file for comparison: ${msg}`);
+    return null;
+  }
+
+  const escaped = projectName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const regex = new RegExp(
+    `^\\s*\`\`\`(?:[^\\n]*)\\n${escaped}/?\\n([\\s\\S]*?)\\n\`\`\`\\s*$`,
+    'm',
+  );
+  const match = content.match(regex);
+  return match && typeof match[1] === 'string' ? match[1] : null;
+}
+
+function buildOutputContent(projectName: string, treeContent: string, maxDepth: number): string {
+  const timestamp = new Date().toISOString().replace(/T/, ' ').replace(/\..+/, '');
+  const header = `# ${projectName} - Directory Structure\n\nGenerated on: ${timestamp}\n`;
+  const depthInfo = maxDepth !== Infinity ? `\n_Depth limited to ${maxDepth} levels_\n\n` : '\n';
+  const treeBlock = `\`\`\`\n${projectName}/\n${treeContent}\`\`\`\n`;
+  const footer = `\n_Note: This tree excludes files and directories matched by .gitignore and default patterns._\n`;
+  return header + depthInfo + treeBlock + footer;
+}
+
+const normalize = (str: string | null) => str?.replace(/\r\n/g, '\n').trimEnd() ?? null;
+
+const generateDirectoryTree = async (): Promise<void> => {
+  try {
+    const root = process.cwd();
+    const args = process.argv.slice(2);
+
+    if (args.includes('--help')) {
+      console.log(`
+Generate Tree - Project directory structure visualization tool
+
+Usage:
+  bun run scripts/tree.ts [output-path] [options]
+
+Options:
+  output-path        Custom file path for the tree output (relative to project root, default: docs/tree.md)
+  --depth=<number>   Maximum directory depth to display (default: unlimited)
+  --ignore=<pattern> Additional ignore pattern (can be specified multiple times)
+  --dry-run          Print tree to stdout without writing to disk
+  --help             Show this help message
+`);
+      process.exit(0);
+    }
+
+    const parsed = parseArgs(args);
+    const projectName = basename(root);
+    const resolvedOutputFile = validateOutputPath(parsed.outputPath, root);
+    const ignoreHandler = await loadIgnoreHandler(
+      root,
+      parsed.extraIgnorePatterns,
+      resolvedOutputFile,
+    );
+
+    console.log(`Generating directory tree for project: ${projectName}`);
+    if (!parsed.dryRun) {
+      console.log(`Output will be saved to: ${resolvedOutputFile}`);
+    }
+    if (parsed.maxDepth !== Infinity) {
+      console.log(`Maximum depth set to: ${parsed.maxDepth}`);
+    }
+    if (parsed.extraIgnorePatterns.length > 0) {
+      console.log(`Additional ignore patterns: ${parsed.extraIgnorePatterns.join(', ')}`);
+    }
+
+    const treeContent = await generateTree(root, root, ignoreHandler, parsed.maxDepth);
+
+    if (parsed.dryRun) {
+      console.log(`\n${projectName}/`);
+      process.stdout.write(treeContent);
+      return;
+    }
+
+    const existingTree = await readExistingTree(resolvedOutputFile, projectName);
+
+    if (normalize(existingTree) === normalize(treeContent)) {
+      console.log(
+        `Directory structure is unchanged. Output file not updated: ${resolvedOutputFile}`,
+      );
+      return;
+    }
+
+    await mkdir(dirname(resolvedOutputFile), { recursive: true });
+    await writeFile(
+      resolvedOutputFile,
+      buildOutputContent(projectName, treeContent, parsed.maxDepth),
+    );
+    console.log(`Successfully generated and updated tree structure in: ${resolvedOutputFile}`);
+  } catch (error: unknown) {
+    console.error(
+      `Error generating tree: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  }
+};
+
+void generateDirectoryTree();

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

@@ -0,0 +1,191 @@
+---
+name: design-mcp-server
+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: "1.1"
+  audience: external
+  type: workflow
+---
+
+## When to Use
+
+- User says "I want to build a ___ MCP server"
+- User has an API, database, or system they want to expose to LLMs
+- User wants to plan tools before scaffolding
+- Existing server needs a new capability area (design the addition, not just a single tool)
+
+Do NOT use for single-tool additions — use `add-tool` directly.
+
+## Inputs
+
+Gather before designing. Ask the user if not obvious from context:
+
+1. **Domain** — what system, API, or capability is this server wrapping?
+2. **Data sources** — APIs, databases, file systems, external services?
+3. **Target users** — what will the LLM (and its human) be trying to accomplish?
+4. **Scope constraints** — read-only? write access? admin operations? what's off-limits?
+
+If the domain has a public API, read its docs before designing. Don't design from vibes.
+
+## Steps
+
+### 1. Research External Dependencies
+
+Before designing, verify the APIs and services the server will wrap.
+
+If the Agent tool is available, spawn background agents to research in parallel while you proceed with domain mapping:
+
+- Fetch API docs, confirm endpoint availability, auth methods, rate limits
+- Check for official SDKs or client libraries (npm packages)
+- Note any API quirks, pagination patterns, or data format considerations
+
+If the Agent tool is not available, do this research inline — fetch docs, read SDK readmes, confirm assumptions before committing them to the design.
+
+### 2. Map the Domain
+
+List the concrete operations the underlying system supports. Group by domain noun.
+
+Example for a project management API:
+
+| Noun | Operations |
+|:-----|:-----------|
+| Project | list, get, create, archive |
+| Task | list (by project), get, create, update status, assign, comment |
+| User | list, get current |
+
+This is the raw material. Not everything becomes a tool.
+
+### 3. Classify into MCP Primitives
+
+| Primitive | Use when | Examples |
+|:----------|:---------|:--------|
+| **Tool** | Needs parameters beyond a simple ID, has side effects, or requires LLM decisions about inputs | Search, create, update, analyze, transform |
+| **Resource** | Addressable by stable URI, read-only, useful as injectable context | Config, schemas, status, entity-by-ID lookups |
+| **Prompt** | Reusable message template that structures how the LLM approaches a task | Analysis framework, report template, review checklist |
+| **Neither** | Internal detail, admin-only, not useful to an LLM | Token refresh, webhook setup, migrations |
+
+**Common traps:**
+
+- **Everything-is-a-tool**: "Fetch by ID" with no other params is a resource. Resources let clients inject context without a tool call.
+- **CRUD explosion**: Don't map every REST endpoint to a tool. One `update_task` beats `update_task_status` + `assign_task` + `update_task_fields`.
+- **Ignoring resources**: If the server has reference data, schemas, or entities the LLM should read — expose them as resources.
+
+### 4. Design Tools
+
+For each tool:
+
+| Aspect | Decision |
+|:-------|:---------|
+| **Name** | `snake_case`, verb-noun: `search_papers`, `create_task`. Prefix with server domain if ambiguous. |
+| **Granularity** | One tool per user intent, not per API call. A tool can call multiple APIs internally. |
+| **Input schema** | What the LLM provides. `.describe()` on every field. Prefer enums/literals over free strings. Optional fields with defaults over required where reasonable. |
+| **Output schema** | What the LLM needs to see. Curate — not a raw API dump. Design for the LLM's next decision, not for a UI. |
+| **Annotations** | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Helps clients auto-approve safely. |
+| **Auth scopes** | `tool:noun:read`, `tool:noun:write`. Skip for read-only or stdio-only servers. |
+
+### 5. Design Resources
+
+For each resource:
+
+| Aspect | Decision |
+|:-------|:---------|
+| **URI template** | `scheme://{param}/path`. Server domain as scheme. Keep shallow. |
+| **Params** | Minimal — typically just an identifier. Complex queries belong in tools. |
+| **Pagination** | Needed if lists exceed ~50 items. Opaque cursors via `extractCursor`/`paginateArray`. |
+| **list()** | Provide if discoverable. Top-level categories or recent items, not exhaustive dumps. |
+
+### 6. Design Prompts (if needed)
+
+Optional. Use when the server has recurring interaction patterns worth structuring:
+- Analysis frameworks, report templates, multi-step workflows
+
+Skip for purely data/action-oriented servers.
+
+### 7. Plan Services and Config
+
+**Services** — one per external dependency. Init/accessor pattern. Skip if all tools are thin wrappers with no shared state.
+
+**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
+
+Create `docs/design.md` with the structure below. The MCP surface (tools, resources, prompts) goes first — it's what matters most and what the developer will reference during implementation.
+
+```markdown
+# {{Server Name}} — Design
+
+## MCP Surface
+
+### Tools
+| Name | Description | Key Inputs | Annotations |
+|:-----|:------------|:-----------|:------------|
+
+### Resources
+| URI Template | Description | Pagination |
+|:-------------|:------------|:-----------|
+
+### Prompts
+| Name | Description | Args |
+|:-----|:------------|:-----|
+
+## Overview
+
+What this server does, what system it wraps, who it's for.
+
+## Requirements
+
+- Bullet list of capabilities and constraints
+- Auth requirements, rate limits, data access scope
+
+## Services
+| Service | Wraps | Used By |
+|:--------|:------|:--------|
+
+## Config
+| Env Var | Required | Description |
+|:--------|:---------|:------------|
+
+## Implementation Order
+
+1. Config and server setup
+2. Services (external API clients)
+3. Read-only tools
+4. Write tools
+5. Resources
+6. Prompts
+
+Each step is independently testable.
+```
+
+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.
+
+### 9. Confirm and Proceed
+
+If the user has already authorized implementation (e.g., "build me a ___ server"), proceed directly to scaffolding using the design doc as the plan. Otherwise, present the design doc to the user for review before implementing.
+
+## After Design
+
+Execute the plan using the scaffolding skills:
+
+1. `add-service` for each service
+2. `add-tool` for each tool
+3. `add-resource` for each resource
+4. `add-prompt` for each prompt
+5. `devcheck` after each addition
+
+## Checklist
+
+- [ ] External APIs/dependencies researched and verified (docs fetched, SDKs identified)
+- [ ] Domain operations mapped (nouns + verbs)
+- [ ] Each operation classified as tool, resource, prompt, or excluded
+- [ ] Tool names follow verb-noun `snake_case` convention
+- [ ] Tool outputs designed for LLM consumption, not raw API passthrough
+- [ ] Annotations set correctly (`readOnlyHint`, `destructiveHint`, etc.)
+- [ ] Input schemas use constrained types (enums, literals) where the domain allows
+- [ ] Resource URIs use `{param}` templates, pagination planned for large lists
+- [ ] Service layer planned (or explicitly skipped with reasoning)
+- [ ] Server config env vars identified
+- [ ] Design doc written to `docs/design.md`
+- [ ] Design confirmed with user (or user pre-authorized implementation)

package/skills/setup/SKILL.md

@@ -80,13 +80,17 @@ The init creates echo definitions for tools, resources, and prompts. They're fun
 
 ## Skill Sync
 
-Your agent skill directory (e.g., `.claude/skills/`) must stay in sync with the project's `skills/` directory. `skills/` is the source of truth.
+Copy all project skills into your agent's skill directory so they're available as context. `skills/` is the source of truth.
 
-1. Compare your agent skill directory against `skills/`
-2. Copy any missing or updated skills into your agent directory
-3. Do not remove server-specific skills from either location
+**For Claude Code:**
 
-For detailed sync procedures, see the `/maintenance` skill.
+```bash
+mkdir -p .claude/skills && cp -R skills/* .claude/skills/
+```
+
+**For other agents** (Codex, Cursor, Windsurf, etc.) — copy to the equivalent directory (e.g., `.codex/skills/`, `.cursor/skills/`).
+
+After the initial copy, use the `maintenance` skill to keep them in sync after package updates.
 
 ## Project Scaffolding
 
@@ -101,6 +105,7 @@ After `bun install`, complete these one-time setup tasks:
 - [ ] `{{PACKAGE_NAME}}` placeholders replaced in agent protocol file (if not auto-substituted by init)
 - [ ] Core framework CLAUDE.md read (`node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`)
 - [ ] Unused echo definitions deleted (and unregistered from `src/index.ts`)
-- [ ] Agent skill directory in sync with project `skills/`
+- [ ] Skills copied to agent directory (`cp -R skills/* .claude/skills/` or equivalent)
 - [ ] Project structure understood (definitions directories, entry point)
 - [ ] `bun run devcheck` passes
+- [ ] If new server: proceed to `design-mcp-server` skill to plan the tool surface

package/templates/AGENTS.md

@@ -1,13 +1,23 @@
 # Agent Protocol
 
 **Server:** {{PACKAGE_NAME}}
-**Version:** 0.1.0
+**Version:** 0.1.2
 **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.
 
 ---
 
+## First Session
+
+> **Remove this section** from CLAUDE.md / AGENTS.md after completing these steps. The skills and conventions below remain — this block is one-time onboarding only.
+
+1. **Read the framework API** — `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md`
+2. **Run the `setup` skill** — read `skills/setup/SKILL.md` and follow its checklist (project orientation, agent protocol file selection, echo definition cleanup, skill sync)
+3. **Design the server** — read `skills/design-mcp-server/SKILL.md` and work through it with the user to map the domain into tools, resources, and services before scaffolding
+
+---
+
 ## 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.
@@ -173,6 +183,7 @@ src/
 | Files | kebab-case with suffix | `search-docs.tool.ts` |
 | Tool/resource/prompt names | snake_case | `search_docs` |
 | Directories | kebab-case | `src/services/doc-search/` |
+| Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` |
 
 ---
 
@@ -187,6 +198,7 @@ Available skills:
 | Skill | Purpose |
 |:------|:--------|
 | `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-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
@@ -211,12 +223,18 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 | Command | Purpose |
 |:--------|:--------|
-| `bun run build` | Compile TypeScript |
-| `bun run devcheck` | Lint + format + typecheck |
-| `bun run test` | Run tests |
-| `bun run format` | Auto-fix formatting |
-| `bun run dev:stdio` | Dev mode (stdio) |
-| `bun run dev:http` | Dev mode (HTTP) |
+| `npm run build` | Compile TypeScript |
+| `npm run clean` | Remove build artifacts |
+| `bun run devcheck` | Lint + format + typecheck + security |
+| `bun run tree` | Generate directory structure doc |
+| `npm run format` | Auto-fix formatting |
+| `npm test` | Run tests |
+| `npm run dev:stdio` | Dev mode (stdio) |
+| `npm run dev:http` | Dev mode (HTTP) |
+| `npm run start:stdio` | Production mode (stdio) |
+| `npm run start:http` | Production mode (HTTP) |
+
+**Bun requirement:** `devcheck` and `tree` scripts use Bun-specific APIs (`spawn` from `'bun'`). Install [Bun](https://bun.sh) to run them. All other commands work with any Node-compatible package manager.
 
 ---
 
@@ -239,6 +257,6 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage
 - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
-- [ ] Registered in `src/index.ts` arrays
+- [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
 - [ ] `bun run devcheck` passes