@pyreon/mcp 0.15.0 → 0.16.0

package/src/changelog.ts

@@ -177,16 +177,16 @@ export function parseChangelog(body: string): ChangelogEntry[] {
 
     // `### Patch Changes` / `### Minor Changes` / `### Major Changes` — ignore
     // the heading itself but keep reading bullets under it.
-    if (/^### /.test(line)) {
+    if (line.startsWith('### ')) {
       flushBullet()
       continue
     }
 
     // Start of a new top-level bullet.
-    if (/^- /.test(line)) {
+    if (line.startsWith('- ')) {
       flushBullet()
       currentBuf = [line.replace(/^- /, '')]
-      bufKind = /^- Updated dependencies/.test(line) ? 'dep' : 'change'
+      bufKind = line.startsWith('- Updated dependencies') ? 'dep' : 'change'
       continue
     }
 

package/src/index.ts

@@ -6,6 +6,7 @@
  * to generate, validate, and migrate Pyreon code.
  *
  * Tools:
+ *   mcp_overview              — Discoverability map: every tool's "when to use" + example, in one call
  *   get_api                   — Look up any Pyreon API: signature, usage, common mistakes
  *   validate                  — Check a code snippet for Pyreon anti-patterns
  *   migrate_react             — Convert React code to idiomatic Pyreon
@@ -17,6 +18,7 @@
  *   get_anti_patterns         — Browse the anti-patterns catalog, optionally filtered by category
  *   get_changelog             — Recent release notes for a @pyreon/* package, parsed from CHANGELOG.md
  *   audit_test_environment    — Scan test files for mock-vnode patterns (PR #197 bug class)
+ *   audit_islands             — Project-wide islands audit (5 cross-file foot-guns)
  *
  * Usage:
  *   bunx @pyreon/mcp          # stdio transport (for IDE integration)
@@ -26,10 +28,12 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   type AuditRisk,
+  auditIslands,
   auditTestEnvironment,
   detectPyreonPatterns,
   detectReactPatterns,
   diagnoseError,
+  formatIslandAudit,
   formatTestAudit,
   migrateReactCode,
 } from '@pyreon/compiler'
@@ -602,6 +606,55 @@ server.tool(
     },
   )
 
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tool: audit_islands — project-wide islands audit (PR C of islands DX roadmap)
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  server.tool(
+    'audit_islands',
+    {
+      json: z
+        .boolean()
+        .optional()
+        .describe(
+          'Return raw JSON output instead of human-readable markdown. Useful when an agent wants to programmatically count findings by code or filter by location.',
+        ),
+    },
+    async ({ json }) => {
+      const result = auditIslands(process.cwd())
+      return textResult(formatIslandAudit(result, { json }))
+    },
+  )
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tool: mcp_overview — discoverability "what tool when" map (T2.5.9)
+  //
+  // Reads from this package's own manifest at runtime — single source of truth.
+  // Reuses the same data that drives api-reference.ts + llms-full.txt + the
+  // generated docs/docs/mcp.md sections. Adding a new tool to manifest.ts
+  // automatically surfaces it here on next call; no second wiring step.
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  server.tool('mcp_overview', {}, async () => {
+    const { default: manifest } = await import('./manifest')
+    const tools = manifest.api.filter((e) => e.signature.startsWith('tool: '))
+
+    const rows = tools.map((e) => {
+      const whenToUse = (e.summary.split(/(?<=[.!?])\s+/)[0] ?? e.summary)
+        .trim()
+        .replace(/\|/g, '\\|')
+      const example = (e.example.split('\n')[0] ?? '').trim().replace(/\|/g, '\\|')
+      return `| \`${e.name}\` | ${whenToUse} | \`${example}\` |`
+    })
+
+    return textResult(
+      `**MCP Tools (${tools.length}):**\n\n` +
+        '| Tool | When to use | Example |\n' +
+        '|---|---|---|\n' +
+        rows.join('\n'),
+    )
+  })
+
   return server
 }
 

package/src/manifest.ts

@@ -4,17 +4,17 @@ export default defineManifest({
   name: '@pyreon/mcp',
   title: 'MCP Server',
   tagline:
-    'Model Context Protocol server — live API lookup, validation, migration, anti-pattern catalog, changelog, test-environment audit',
+    'Model Context Protocol server — discoverability map, live API lookup, validation, migration, anti-pattern catalog, changelog, test-environment audit',
   description:
-    'MCP server (stdio transport) that exposes Pyreon\\\'s structured knowledge to AI coding assistants (Claude Code, Cursor, etc.). Eleven tools: `get_api` (look up any Pyreon API), `validate` (catch React + Pyreon-specific anti-patterns in a snippet), `migrate_react` (auto-convert React code), `diagnose` (parse a Pyreon error into structured fix info), `get_routes` / `get_components` (project introspection), `get_browser_smoke_status` (which packages need a browser smoke test), `get_pattern` (canonical "how do I do X" docs), `get_anti_patterns` (the catalog from `.claude/rules/anti-patterns.md`), `get_changelog` (recent release notes per package), and `audit_test_environment` (mock-vnode test scanner — PR #197 bug class).',
+    'MCP server (stdio transport) that exposes Pyreon\\\'s structured knowledge to AI coding assistants (Claude Code, Cursor, etc.). Thirteen tools: `mcp_overview` (start here — markdown table of every tool with "when to use" + example, read straight from this manifest), `get_api` (look up any Pyreon API), `validate` (catch React + Pyreon-specific anti-patterns in a snippet), `migrate_react` (auto-convert React code), `diagnose` (parse a Pyreon error into structured fix info), `get_routes` / `get_components` (project introspection), `get_browser_smoke_status` (which packages need a browser smoke test), `get_pattern` (canonical "how do I do X" docs), `get_anti_patterns` (the catalog from `.claude/rules/anti-patterns.md`), `get_changelog` (recent release notes per package), `audit_test_environment` (mock-vnode test scanner — PR #197 bug class), and `audit_islands` (project-wide islands cross-file audit — duplicate names, dead islands, registry drift, nested islands, never-with-registry).',
   category: 'server',
   features: [
-    'Eleven tools covering lookup, validation, migration, diagnosis, introspection, audit',
+    'Thirteen tools covering discovery, lookup, validation, migration, diagnosis, introspection, audit',
     'stdio transport — drop-in compatible with every MCP client',
     'Project context cached per server instance, auto-invalidates on cwd change',
     'Manifest-driven — `get_api` reads `api-reference.ts`, regenerated from package manifests',
     'AST-based detectors — `validate` catches React + Pyreon-specific patterns statically',
-    'Real-repo audit tools (`audit_test_environment`, `get_browser_smoke_status`) walk packages/',
+    'Real-repo audit tools (`audit_test_environment`, `audit_islands`, `get_browser_smoke_status`) walk packages/',
   ],
   longExample: `// .mcp/config.json — register the server with any MCP-aware client
 {
@@ -27,6 +27,8 @@ export default defineManifest({
 }
 
 // Then from the client (Claude Code, Cursor, etc.):
+//   mcp_overview()
+//     → markdown table: tool | when_to_use | example (start here)
 //   get_api({ package: 'flow', symbol: 'createFlow' })
 //     → signature, example, common mistakes
 //   validate({ code: '<MyButton onClick={handler}>...' })
@@ -38,8 +40,27 @@ export default defineManifest({
 //   get_changelog({ package: 'flow', limit: 5 })
 //     → recent release notes filtered through ceremonial-bump removal
 //   audit_test_environment({ minRisk: 'medium' })
-//     → mock-vnode test files ranked HIGH / MEDIUM / LOW`,
+//     → mock-vnode test files ranked HIGH / MEDIUM / LOW
+//   audit_islands({})
+//     → project-wide islands audit (5 cross-file foot-guns)`,
   api: [
+    {
+      name: 'mcp_overview',
+      kind: 'constant',
+      signature: 'tool: mcp_overview() → MarkdownTable',
+      summary:
+        'Returns a markdown table of every registered MCP tool with a one-sentence "when to use" description and a one-line example. Reads from this same manifest at runtime — single source of truth (the same data feeds `api-reference.ts`, `llms-full.txt`, and `docs/docs/mcp.md`). Intended as the first call for any AI agent connecting to the server: enumerates the surface so the agent can navigate by intent (e.g. "I need release notes" → `get_changelog`) rather than guessing tool names from `tools/list`.',
+      example: `mcp_overview()
+// → | Tool | When to use | Example |
+//   |------|-------------|---------|
+//   | mcp_overview | Returns a markdown table of every registered MCP tool... | mcp_overview() |
+//   | get_api | Look up any Pyreon API by package and symbol... | get_api({ package: 'flow', symbol: 'createFlow' }) |
+//   | ...`,
+      mistakes: [
+        'Skipping this tool and calling `tools/list` instead — that returns names + parameter schemas but no "when to use" guidance, so an agent has to call multiple tools to figure out which one fits the task.',
+      ],
+      seeAlso: ['get_api'],
+    },
     {
       name: 'get_browser_smoke_status',
       kind: 'constant',
@@ -169,7 +190,20 @@ get_changelog({ package: '@pyreon/router', since: '0.12.0' })`,
         'Scan every `*.test.{ts,tsx}` under `packages/` for the mock-vnode anti-pattern that caused PR #197\\\'s silent metadata drop. Files are classified HIGH / MEDIUM / LOW based on the balance of mock-vnode literals + helpers + helper-call sites vs real `h()` calls + `@pyreon/core` import. Three context-aware skips (helper-def vs binding discrimination, type-guard call-arg skip, template-string fixture mask) keep the false-positive rate low. Run before merging a new test file or after a framework change.',
       example: `audit_test_environment({ minRisk: 'medium', limit: 10 })
 // → grouped report with HIGH / MEDIUM / LOW sections`,
-      seeAlso: ['get_browser_smoke_status'],
+      seeAlso: ['get_browser_smoke_status', 'audit_islands'],
+    },
+    {
+      name: 'audit_islands',
+      kind: 'constant',
+      signature: 'tool: audit_islands({ json?: boolean }) → IslandAuditReport',
+      summary:
+        'Project-wide cross-file islands audit (PR C of the islands DX roadmap). Walks `packages/` + `examples/` and runs five detectors that auto-registry can\\\'t reach (manual `hydrateIslands({...})` for non-Vite consumers / library authors) AND PR G\\\'s per-file `island-never-with-registry-entry` detector misses (it only catches the same-file shape): `duplicate-name`, `never-with-registry-entry`, `registry-mismatch`, `nested-island`, `dead-island`. Each finding ships with file path + line/column + actionable fix suggestion. Companion to the `pyreon doctor --check-islands` CLI flag (same scanner, same five detectors). Run before merging an island PR; CI gate by piping `--json` and grepping `findings.length > 0`.',
+      example: `audit_islands({})
+// → markdown-grouped report with one section per finding code
+
+audit_islands({ json: true })
+// → machine-readable { root, findings: [...], summary: {...} }`,
+      seeAlso: ['audit_test_environment', 'get_anti_patterns'],
     },
   ],
   gotchas: [

package/src/tests/audit-islands-server.test.ts

@@ -0,0 +1,100 @@
+import { callTool, newClient } from './helpers'
+
+// MCP server <-> client round-trip for the PR C `audit_islands` tool.
+// Same InMemoryTransport shape as `test-audit-server.test.ts`, so we
+// exercise the registration, JSON-RPC framing, formatter, and zod
+// validation in one pass. Pairs with the unit-level test in the
+// compiler package (`island-audit.test.ts`) — those test the
+// underlying `auditIslands()` function directly; this one proves the
+// MCP wiring.
+
+// `audit_islands` walks the real repo (packages/ + examples/) — under CI's
+// parallel test load that can exceed vitest's 5s default. 30s per call is
+// well above empirical worst case (~2s locally) but safe headroom for
+// concurrent runs.
+const AUDIT_TIMEOUT_MS = 30_000
+
+describe('MCP server — audit_islands tool', () => {
+  it(
+    'renders the audit header + summary line',
+    async () => {
+      const { client, close } = await newClient()
+      try {
+        const text = await callTool(client, 'audit_islands', {})
+        // The header always renders the file/decl/registry counts.
+        expect(text).toMatch(/^# Islands audit — \d+ files scanned/)
+        expect(text).toMatch(/`island\(\)` declarations?/)
+        expect(text).toMatch(/`hydrateIslands` registry entr/)
+      } finally {
+        await close()
+      }
+    },
+    AUDIT_TIMEOUT_MS,
+  )
+
+  it(
+    'returns the green-light message when the audit is clean',
+    async () => {
+      const { client, close } = await newClient()
+      try {
+        const text = await callTool(client, 'audit_islands', {})
+        // Real-repo baseline: examples/islands-showcase has 6 islands
+        // and uses hydrateIslandsAuto() — no manual registry, so audit
+        // is clean. The bisect verification (planted typo + never-with-
+        // registry) lives in the unit suite. If THIS assertion fails,
+        // somebody added a real island defect to main, OR the audit
+        // started false-positive-ing.
+        expect(text).toContain('No island findings')
+      } finally {
+        await close()
+      }
+    },
+    AUDIT_TIMEOUT_MS,
+  )
+
+  it(
+    'emits machine-readable JSON when json=true',
+    async () => {
+      const { client, close } = await newClient()
+      try {
+        const text = await callTool(client, 'audit_islands', { json: true })
+        // Should be valid JSON with the expected shape.
+        const parsed = JSON.parse(text)
+        expect(parsed).toHaveProperty('root')
+        expect(parsed).toHaveProperty('findings')
+        expect(parsed).toHaveProperty('summary')
+        expect(parsed.summary).toHaveProperty('filesScanned')
+        expect(parsed.summary).toHaveProperty('islandsDeclared')
+        expect(parsed.summary).toHaveProperty('registryEntries')
+        expect(parsed.summary).toHaveProperty('findingsByCode')
+        // The 5 finding codes always appear in the summary, with 0 counts
+        // when no findings — useful for CI gates that map code → exit
+        // status.
+        const codes = Object.keys(parsed.summary.findingsByCode).sort()
+        expect(codes).toEqual([
+          'dead-island',
+          'duplicate-name',
+          'nested-island',
+          'never-with-registry-entry',
+          'registry-mismatch',
+        ])
+      } finally {
+        await close()
+      }
+    },
+    AUDIT_TIMEOUT_MS,
+  )
+
+  it('rejects a non-boolean json arg via zod', async () => {
+    const { client, close } = await newClient()
+    try {
+      const result = (await client.callTool({
+        name: 'audit_islands',
+        arguments: { json: 'yes' },
+      })) as { isError?: boolean; content: Array<{ type: string; text: string }> }
+      expect(result.isError).toBe(true)
+    } finally {
+      await close()
+    }
+  })
+})

package/src/tests/changelog-server.test.ts

@@ -1,39 +1,10 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js'
-import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
-import { createServer } from '../index'
+import { callTool, newClient } from './helpers'
 
 // Real MCP server <-> client round-trip for the T2.5.8 get_changelog
 // tool. Same InMemoryTransport shape as the patterns-server test —
 // exercises tool registration, JSON-RPC framing, and the formatter
 // response shape in one pass.
 
-async function newClient(): Promise<{ client: Client; close: () => Promise<void> }> {
-  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
-  const server = createServer()
-  await server.connect(serverTransport)
-  const client = new Client({ name: 'test', version: '0.0.0' })
-  await client.connect(clientTransport)
-  return {
-    client,
-    close: async () => {
-      await client.close()
-      await server.close()
-    },
-  }
-}
-
-async function callTool(
-  client: Client,
-  name: string,
-  args: Record<string, unknown>,
-): Promise<string> {
-  const result = (await client.callTool({ name, arguments: args })) as {
-    content: Array<{ type: string; text: string }>
-  }
-  expect(result.content[0]!.type).toBe('text')
-  return result.content[0]!.text
-}
-
 describe('MCP server — get_changelog tool', () => {
   it('lists every package when called with no arg', async () => {
     const { client, close } = await newClient()

package/src/tests/changelog.test.ts

@@ -168,7 +168,7 @@ describe('formatChangelog', () => {
   it('respects the limit option', () => {
     const q = findChangelog(registry, 'query')!
     const limited = formatChangelog(q, { limit: 1 })
-    const versionHeadings = limited.split('\n').filter((l) => /^## /.test(l))
+    const versionHeadings = limited.split('\n').filter((l) => l.startsWith('## '))
     expect(versionHeadings).toHaveLength(1)
   })
 

package/src/tests/diagnose-server.test.ts

@@ -0,0 +1,76 @@
+import { callTool, newClient } from './helpers'
+
+// Real MCP server <-> client round-trip for the `diagnose` tool. The
+// `ERROR_PATTERNS` catalog itself is unit-tested in the compiler's
+// `react-intercept.test.ts`; this test pins the JSON-RPC wiring +
+// the formatter that splits cause / fix / fixCode / related into
+// markdown sections.
+
+describe('MCP server — diagnose tool', () => {
+  it('matches a known pattern and emits cause + fix + code sections', async () => {
+    const { client, close } = await newClient()
+    try {
+      // The signal-not-callable pattern is one of the foundational
+      // entries in ERROR_PATTERNS — captures the `(name) is not a
+      // function` shape that almost every React refugee hits when they
+      // forget signals are callable.
+      const text = await callTool(client, 'diagnose', {
+        error: 'count is not a function',
+      })
+      expect(text).toContain('**Cause:**')
+      expect(text).toContain('**Fix:**')
+      // The fix-code section appears for patterns that produce one.
+      expect(text).toContain('**Code:**')
+      expect(text).toContain('count')
+    } finally {
+      await close()
+    }
+  })
+
+  it('includes the Related section when the pattern provides one', async () => {
+    const { client, close } = await newClient()
+    try {
+      // Hydration-mismatch is the canonical pattern that carries a
+      // `related` hint (typeof window guard / onMount). Verifies the
+      // formatter actually wires the `related` field through.
+      const text = await callTool(client, 'diagnose', {
+        error: 'Hydration mismatch at /about',
+      })
+      expect(text).toContain('**Cause:**')
+      expect(text).toContain('**Fix:**')
+      expect(text).toContain('**Related:**')
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns the generic fallback when no pattern matches', async () => {
+    const { client, close } = await newClient()
+    try {
+      // Arbitrary text that doesn't match any ERROR_PATTERNS regex —
+      // exercises the fallback branch (no diagnosis → suggestions
+      // list).
+      const text = await callTool(client, 'diagnose', {
+        error: 'something completely unfamiliar that no pattern would match',
+      })
+      expect(text).toContain('Could not identify a Pyreon-specific pattern')
+      expect(text).toContain('pyreon doctor')
+      expect(text).toContain('bun run typecheck')
+    } finally {
+      await close()
+    }
+  })
+
+  it('rejects missing `error` arg via zod', async () => {
+    const { client, close } = await newClient()
+    try {
+      const result = (await client.callTool({
+        name: 'diagnose',
+        arguments: {},
+      })) as { isError?: boolean; content: Array<{ type: string; text: string }> }
+      expect(result.isError).toBe(true)
+    } finally {
+      await close()
+    }
+  })
+})

package/src/tests/get-api-server.test.ts

@@ -0,0 +1,66 @@
+import { callTool, newClient } from './helpers'
+
+// Real MCP server <-> client round-trip for the `get_api` tool. The
+// unit-level coverage of `API_REFERENCE` itself lives in
+// `api-reference.test.ts` (manifest-generation contract + structural
+// shape). This test proves the JSON-RPC wiring: zod validates the
+// `package` + `symbol` args, the handler looks up `API_REFERENCE[key]`
+// against the merged manifest output, and the formatter assembles the
+// markdown response. Pairs with the manifest-driven docs pipeline
+// (T2.5.1) — every entry in `api-reference.ts` flows through this tool.
+
+describe('MCP server — get_api tool', () => {
+  it('returns signature + usage for a known symbol', async () => {
+    const { client, close } = await newClient()
+    try {
+      // `signal` is one of the foundational reactivity APIs — every
+      // manifest in the pipeline must publish it, so this is a stable
+      // assertion for the JSON-RPC contract.
+      const text = await callTool(client, 'get_api', {
+        package: 'reactivity',
+        symbol: 'signal',
+      })
+      expect(text).toContain('## @pyreon/reactivity — signal')
+      expect(text).toContain('**Signature:**')
+      expect(text).toContain('```typescript')
+      expect(text).toContain('**Usage:**')
+    } finally {
+      await close()
+    }
+  })
+
+  it('returns a not-found message with suggestions for an unknown symbol', async () => {
+    const { client, close } = await newClient()
+    try {
+      // `sig` is intentionally a substring of real entries (`signal`,
+      // `Signal`, ...) so the substring-match suggestion path fires —
+      // the handler does `allKeys.filter(k => k.includes(symbol))`.
+      const text = await callTool(client, 'get_api', {
+        package: 'reactivity',
+        symbol: 'sig',
+      })
+      expect(text).toContain("Symbol 'sig' not found")
+      expect(text).toContain('Did you mean')
+      // The matcher should surface real signal-related entries.
+      expect(text).toMatch(/reactivity\/\w*[Ss]ig/)
+    } finally {
+      await close()
+    }
+  })
+
+  it('rejects missing required args via zod', async () => {
+    // Both `package` and `symbol` are required; omitting one must
+    // produce a JSON-RPC error rather than silently returning an
+    // empty response.
+    const { client, close } = await newClient()
+    try {
+      const result = (await client.callTool({
+        name: 'get_api',
+        arguments: { package: 'reactivity' },
+      })) as { isError?: boolean; content: Array<{ type: string; text: string }> }
+      expect(result.isError).toBe(true)
+    } finally {
+      await close()
+    }
+  })
+})

package/src/tests/get-browser-smoke-server.test.ts

@@ -0,0 +1,75 @@
+import { callTool, newClient } from './helpers'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Real MCP server <-> client round-trip for the `get_browser_smoke_status`
+// tool. The tool walks `<cwd>/packages` looking for browser-categorised
+// packages from `.claude/rules/browser-packages.json` and checks each
+// for `*.browser.test.{ts,tsx}` files. CI script `check-browser-smoke.ts`
+// covers the same shape from a script entrypoint; this test pins the
+// JSON-RPC handler + formatter output.
+//
+// vitest runs from `packages/tools/mcp` by default — walking
+// `packages/tools/mcp/packages` would find nothing, exercising the
+// "unknown package" branch. To exercise the COVERED + MISSING paths
+// against real package directories, we `chdir` to the monorepo root
+// inside one of the specs (then restore). The repo-walk-from-cwd
+// pattern matches how the tool is intended to be used by an MCP
+// client (CLI invocation from project root).
+
+const _filename = fileURLToPath(import.meta.url)
+const _dirname = path.dirname(_filename)
+// .../packages/tools/mcp/src/tests → walk up 4 levels to the repo root.
+const REPO_ROOT = path.resolve(_dirname, '..', '..', '..', '..', '..')
+
+describe('MCP server — get_browser_smoke_status tool', () => {
+  it('emits the coverage header (covered / total)', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_browser_smoke_status', {})
+      // Header format: `**Browser smoke coverage** (N / M):`.
+      expect(text).toMatch(/^\*\*Browser smoke coverage\*\* \(\d+ \/ \d+\):/)
+    } finally {
+      await close()
+    }
+  })
+
+  it('flags packages as Covered / Missing / Unknown when run from repo root', async () => {
+    // chdir to the monorepo root so the walker finds real package
+    // directories instead of the default cwd's empty `packages/`.
+    // Restore in finally so adjacent tests aren't affected.
+    const originalCwd = process.cwd()
+    try {
+      process.chdir(REPO_ROOT)
+      const { client, close } = await newClient()
+      try {
+        const text = await callTool(client, 'get_browser_smoke_status', {})
+        // From the repo root, real browser packages are present and
+        // have shipped `*.browser.test.*` files (lint rule enforces
+        // this). So `Covered (N):` should appear with N > 0.
+        expect(text).toMatch(/✓ Covered \(\d+\):/)
+        // At least one canonical browser-package name in the body.
+        expect(text).toMatch(/- @pyreon\/(runtime-dom|router|styler)/)
+      } finally {
+        await close()
+      }
+    } finally {
+      process.chdir(originalCwd)
+    }
+  })
+
+  it('reports "not found in this repo" packages from outside the monorepo', async () => {
+    // Default cwd (`packages/tools/mcp`) means `<cwd>/packages` is
+    // missing — every browser-package becomes "unknown" (listed in
+    // the JSON catalog but absent from this directory). Exercises
+    // the unknown-package branch of the formatter.
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_browser_smoke_status', {})
+      expect(text).toContain('Listed in browser-packages.json but not found')
+      expect(text).toMatch(/- @pyreon\/runtime-dom/)
+    } finally {
+      await close()
+    }
+  })
+})

package/src/tests/get-components-server.test.ts

@@ -0,0 +1,57 @@
+import { callTool, newClient } from './helpers'
+
+// Real MCP server <-> client round-trip for the `get_components` tool.
+// Pairs with `get-routes-server.test.ts` — both flow through the
+// shared `generateContext` walker but render different fields. Unit
+// coverage of the scanner regex lives in
+// `compiler/src/tests/project-scanner.test.ts`; this proves the
+// JSON-RPC wiring + the formatter that renders each `ComponentInfo`
+// (name, file path, `props: { ... }`, `signals: [ ... ]`).
+
+describe('MCP server — get_components tool', () => {
+  it('emits the components header with count and at least one entry', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_components', {})
+      // Header format `**Components (N):**` for a non-empty repo.
+      expect(text).toMatch(/^\*\*Components \(\d+\):\*\*/)
+      // At least one component rendered: `  Name — relative/file.ts`.
+      expect(text).toMatch(/^ {2}\w+ — \S+/m)
+    } finally {
+      await close()
+    }
+  })
+
+  it('renders the optional props + signals details when present', async () => {
+    const { client, close } = await newClient()
+    try {
+      const text = await callTool(client, 'get_components', {})
+      // The fixture set carries components with both `props: { ... }`
+      // and `signals: [...]` — verifying the formatter wires the
+      // detail branches. The unit scanner test covers detection
+      // accuracy; this verifies the rendered detail format reaches
+      // the consumer over JSON-RPC.
+      expect(text).toMatch(/props: \{ [^}]+ \}/)
+      expect(text).toMatch(/signals: \[[^\]]+\]/)
+    } finally {
+      await close()
+    }
+  })
+
+  it('rejects unexpected args (no-args contract)', async () => {
+    const { client, close } = await newClient()
+    try {
+      const result = (await client.callTool({
+        name: 'get_components',
+        arguments: { unexpected: 'value' },
+      })) as { isError?: boolean; content: Array<{ type: string; text: string }> }
+      const text = result.content?.[0]?.text ?? ''
+      // Either zod rejects or the unknown arg is coerced into the
+      // no-args path. Both contracts are valid — assert the call
+      // didn't crash, returning at minimum the header.
+      expect(result.isError === true || text.includes('**Components')).toBe(true)
+    } finally {
+      await close()
+    }
+  })
+})