@pyreon/mcp 0.13.0 → 0.14.0

package/src/index.ts

@@ -13,6 +13,10 @@
  *   get_routes                — List all routes in the current project
  *   get_components            — List all components with their props and signals
  *   get_browser_smoke_status  — Report which browser-categorized packages have smoke coverage
+ *   get_pattern               — Fetch a "how do I do X" pattern body from docs/patterns/
+ *   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)
  *
  * Usage:
  *   bunx @pyreon/mcp          # stdio transport (for IDE integration)
@@ -20,42 +24,75 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { detectReactPatterns, diagnoseError, migrateReactCode } from '@pyreon/compiler'
+import {
+  type AuditRisk,
+  auditTestEnvironment,
+  detectPyreonPatterns,
+  detectReactPatterns,
+  diagnoseError,
+  formatTestAudit,
+  migrateReactCode,
+} from '@pyreon/compiler'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import { z } from 'zod'
 import packageJson from '../package.json' with { type: 'json' }
+import {
+  ANTI_PATTERN_CATEGORIES,
+  type AntiPatternCategory,
+  formatAntiPatterns,
+  parseAntiPatterns,
+} from './anti-patterns'
 import { API_REFERENCE } from './api-reference'
+import {
+  findChangelog,
+  formatChangelog,
+  formatChangelogIndex,
+  loadChangelogRegistry,
+  suggestChangelogs,
+} from './changelog'
+import {
+  findPattern,
+  formatPatternBody,
+  formatPatternIndex,
+  loadPatternRegistry,
+  suggestPatterns,
+} from './patterns'
 import { generateContext, type ProjectContext } from './project-scanner'
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// Server setup
+// Server setup — exported as a factory so tests can stand up a server with an
+// in-memory transport instead of stdio.
 // ═══════════════════════════════════════════════════════════════════════════════
 
-const server = new McpServer({
-  name: 'pyreon',
-  version: packageJson.version,
-})
-
-// Cache project context (regenerated on demand)
-let cachedContext: ProjectContext | null = null
-let contextCwd = process.cwd()
-
-function getContext(): ProjectContext {
-  if (!cachedContext || contextCwd !== process.cwd()) {
-    contextCwd = process.cwd()
-    cachedContext = generateContext(contextCwd)
-  }
-  return cachedContext
-}
-
 function textResult(text: string) {
   return { content: [{ type: 'text' as const, text }] }
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// Tool: get_api
-// ═══════════════════════════════════════════════════════════════════════════════
+export function createServer(): McpServer {
+  const server = new McpServer({
+    name: 'pyreon',
+    version: packageJson.version,
+  })
+
+  // Project context cache is per-server-instance so the test server and the
+  // prod server do not share state.
+  let cachedContext: ProjectContext | null = null
+  let contextCwd = process.cwd()
+
+  function getContext(): ProjectContext {
+    if (!cachedContext || contextCwd !== process.cwd()) {
+      contextCwd = process.cwd()
+      cachedContext = generateContext(contextCwd)
+    }
+    return cachedContext
+  }
 
-server.tool(
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tool: get_api
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  server.tool(
   'get_api',
   {
     package: z.string(),
@@ -97,13 +134,33 @@ server.tool(
     filename: z.string().optional(),
   },
   async ({ code, filename }) => {
-    const diagnostics = detectReactPatterns(code, filename ?? 'snippet.tsx')
-
-    if (diagnostics.length === 0) {
+    // Run both detectors. The React detector flags "coming from React"
+    // mistakes (useState, className, .value writes) — relevant when the
+    // code has not yet committed to Pyreon. The Pyreon detector flags
+    // "using Pyreon wrong" mistakes (missing <For by>, destructured
+    // props, typeof-process dev gates) — relevant once the imports are
+    // Pyreon. A single snippet may trigger both sets, so we merge.
+    const fname = filename ?? 'snippet.tsx'
+    const reactDiags = detectReactPatterns(code, fname)
+    const pyreonDiags = detectPyreonPatterns(code, fname)
+
+    if (reactDiags.length === 0 && pyreonDiags.length === 0) {
       return textResult('✓ No issues found. The code follows Pyreon patterns correctly.')
     }
 
-    const issueText = diagnostics
+    type Diag = {
+      code: string
+      message: string
+      line: number
+      column: number
+      current: string
+      suggested: string
+      fixable: boolean
+    }
+    const merged: Diag[] = [...reactDiags, ...pyreonDiags]
+    merged.sort((a, b) => a.line - b.line || a.column - b.column)
+
+    const issueText = merged
       .map(
         (d, i) =>
           `${i + 1}. **${d.code}** (line ${d.line})\n   ${d.message}\n   Current: \`${d.current}\`\n   Fix: \`${d.suggested}\`\n   Auto-fixable: ${d.fixable ? 'yes' : 'no'}`,
@@ -111,7 +168,7 @@ server.tool(
       .join('\n\n')
 
     return textResult(
-      `Found ${diagnostics.length} issue${diagnostics.length === 1 ? '' : 's'}:\n\n${issueText}`,
+      `Found ${merged.length} issue${merged.length === 1 ? '' : 's'}:\n\n${issueText}`,
     )
   },
 )
@@ -393,16 +450,205 @@ server.tool(
   },
 )
 
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tool: get_pattern — serves docs/patterns/<name>.md
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  server.tool(
+    'get_pattern',
+    {
+      name: z
+        .string()
+        .optional()
+        .describe(
+          'Pattern slug (e.g. "dev-warnings", "controllable-state"). Omit to list available patterns.',
+        ),
+    },
+    async ({ name }) => {
+      const registry = loadPatternRegistry()
+      if (!name) return textResult(formatPatternIndex(registry))
+
+      const pattern = findPattern(registry, name)
+      if (pattern) return textResult(formatPatternBody(pattern))
+
+      const suggestions = suggestPatterns(registry, name)
+      const suggestText =
+        suggestions.length > 0
+          ? `Did you mean one of these?\n${suggestions.map((s) => `  - ${s}`).join('\n')}\n\nOr call get_pattern() with no arg to see the full list.`
+          : 'Call get_pattern() with no arg to see available patterns.'
+      return textResult(`Pattern "${name}" not found.\n\n${suggestText}`)
+    },
+  )
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tool: get_anti_patterns — parses .claude/rules/anti-patterns.md
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  server.tool(
+    'get_anti_patterns',
+    {
+      category: z
+        .enum([
+          'reactivity',
+          'jsx',
+          'context',
+          'architecture',
+          'testing',
+          'lifecycle',
+          'documentation',
+          'all',
+        ])
+        .optional()
+        .describe(
+          `Category filter: ${ANTI_PATTERN_CATEGORIES.join(', ')}, or "all" (default).`,
+        ),
+    },
+    async ({ category = 'all' }) => {
+      const cat = category as AntiPatternCategory | 'all'
+      const doc = loadAntiPatternsDoc()
+      if (!doc) {
+        return textResult(
+          'Could not locate `.claude/rules/anti-patterns.md`. This tool reads the file from the Pyreon monorepo — running in a consumer project without the rules directory surfaces this miss. File issues against pyreon/pyreon if the file exists but is not being found.',
+        )
+      }
+      const all = parseAntiPatterns(doc)
+      const filtered = cat === 'all' ? all : all.filter((e) => e.category === cat)
+      return textResult(formatAntiPatterns(filtered, cat))
+    },
+  )
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tool: get_changelog — recent release notes for @pyreon/* packages
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  server.tool(
+    'get_changelog',
+    {
+      package: z
+        .string()
+        .optional()
+        .describe(
+          'Package name, e.g. "query" or "@pyreon/query". Omit to list every package with a CHANGELOG.',
+        ),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Maximum number of substantive versions to return. Default 5.'),
+      includeDependencyUpdates: z
+        .boolean()
+        .optional()
+        .describe('Include `Updated dependencies` bullets. Default false (usually noise).'),
+      since: z
+        .string()
+        .optional()
+        .describe(
+          'Only include versions strictly newer than this one (e.g. "0.12.0"). Useful when an agent knows the version it was trained against and wants just the delta.',
+        ),
+    },
+    async ({ package: pkg, limit, includeDependencyUpdates, since }) => {
+      const registry = loadChangelogRegistry()
+      if (!pkg) return textResult(formatChangelogIndex(registry))
+
+      const changelog = findChangelog(registry, pkg)
+      if (changelog) {
+        return textResult(
+          formatChangelog(changelog, {
+            limit,
+            includeDependencyUpdates,
+            since,
+          }),
+        )
+      }
+
+      const suggestions = suggestChangelogs(registry, pkg)
+      const suggestText =
+        suggestions.length > 0
+          ? `Did you mean one of these?\n${suggestions.map((s) => `  - ${s}`).join('\n')}\n\nOr call get_changelog() with no arg for the full list.`
+          : 'Call get_changelog() with no arg for the list of packages that ship a CHANGELOG.'
+      return textResult(`Changelog for "${pkg}" not found.\n\n${suggestText}`)
+    },
+  )
+
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // Tool: audit_test_environment — mock-vnode pattern audit (T2.5.7)
+  // ═══════════════════════════════════════════════════════════════════════════════
+
+  server.tool(
+    'audit_test_environment',
+    {
+      minRisk: z
+        .enum(['high', 'medium', 'low'])
+        .optional()
+        .describe(
+          'Minimum risk level to surface. Default "medium" — HIGH + MEDIUM files. Use "high" for only the riskiest, "low" to see everything.',
+        ),
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Maximum entries to show per risk group. Default 20.'),
+    },
+    async ({ minRisk, limit }) => {
+      const result = auditTestEnvironment(process.cwd())
+      return textResult(
+        formatTestAudit(result, {
+          minRisk: minRisk as AuditRisk | undefined,
+          limit,
+        }),
+      )
+    },
+  )
+
+  return server
+}
+
+/**
+ * Locate `.claude/rules/anti-patterns.md` by walking up from cwd.
+ * Returns the file contents or null if not found within 30 levels.
+ * Separate from the patterns loader because the doc path is fixed
+ * (`.claude/rules/`) — no glob needed.
+ */
+function loadAntiPatternsDoc(startDir: string = process.cwd()): string | null {
+  let dir = resolve(startDir)
+  for (let i = 0; i < 30; i++) {
+    const candidate = join(dir, '.claude', 'rules', 'anti-patterns.md')
+    if (existsSync(candidate)) {
+      try {
+        return readFileSync(candidate, 'utf8')
+      } catch {
+        return null
+      }
+    }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+  return null
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════
-// Start server
+// Start server (stdio transport) when invoked directly as a binary.
+// Imports for tests do NOT auto-start — the integration test in
+// `tests/validate.test.ts` wires up an in-memory transport instead.
 // ═══════════════════════════════════════════════════════════════════════════════
 
 async function main(): Promise<void> {
+  const server = createServer()
   const transport = new StdioServerTransport()
   await server.connect(transport)
 }
 
-main().catch((err) => {
-  console.error('MCP server error:', err)
-  process.exit(1)
-})
+// `import.meta.main` is Bun's "entry module" flag. The compiled Node bin
+// (via bun build) preserves this — the bunx / tsx invocation of the
+// shebang sets it truthy; `import { createServer } from '...'` does not.
+// Covers both "run as CLI" and "imported by a test" without needing
+// require.main shims.
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error('MCP server error:', err)
+    process.exit(1)
+  })
+}

package/src/manifest.ts

@@ -0,0 +1,187 @@
+import { defineManifest } from '@pyreon/manifest'
+
+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',
+  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).',
+  category: 'server',
+  features: [
+    'Eleven tools covering 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/',
+  ],
+  longExample: `// .mcp/config.json — register the server with any MCP-aware client
+{
+  "mcpServers": {
+    "pyreon": {
+      "command": "bunx",
+      "args": ["@pyreon/mcp"]
+    }
+  }
+}
+
+// Then from the client (Claude Code, Cursor, etc.):
+//   get_api({ package: 'flow', symbol: 'createFlow' })
+//     → signature, example, common mistakes
+//   validate({ code: '<MyButton onClick={handler}>...' })
+//     → React-pattern + Pyreon-pattern diagnostics with line/col
+//   get_pattern({ name: 'controllable-state' })
+//     → canonical pattern body from docs/patterns/
+//   get_anti_patterns({ category: 'reactivity' })
+//     → reactivity foot-guns from .claude/rules/anti-patterns.md
+//   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`,
+  api: [
+    {
+      name: 'get_browser_smoke_status',
+      kind: 'constant',
+      signature: 'tool: get_browser_smoke_status — no args',
+      summary:
+        "Companion to the `pyreon/require-browser-smoke-test` lint rule. Reports which browser-categorized Pyreon packages have at least one `*.browser.test.{ts,tsx}` file under `src/`. Uses the same `.claude/rules/browser-packages.json` single source of truth as the rule + the CI script. Lets an AI agent check coverage before writing a new browser package (so it adds a smoke test in the same PR) instead of discovering the failure when CI runs. Falls back with a clear message if the JSON isn't present (e.g. consumer apps that don't ship the Pyreon monorepo layout).",
+      example: `// Ask the MCP server:
+//   "which Pyreon packages are missing browser smoke coverage?"
+// Tool walks packages/, matches against .claude/rules/browser-packages.json,
+// returns a coverage report.`,
+      mistakes: [
+        "Using the tool's output as a substitute for running the CI script — this tool only checks file existence, not the self-expiring-exemption check that `bun run lint:browser-smoke` performs",
+      ],
+      seeAlso: ['audit_test_environment'],
+    },
+    {
+      name: 'get_api',
+      kind: 'constant',
+      signature: 'tool: get_api({ package: string; symbol: string }) → APIEntry',
+      summary:
+        'Look up any Pyreon API by `package` (e.g. `"flow"` or `"@pyreon/flow"`) and `symbol` (e.g. `"createFlow"`). Returns the canonical signature, example, foot-gun catalogue, and cross-references — drawn from `api-reference.ts`, which is regenerated from each package\\\'s `manifest.ts`. The single agent-facing entry point for "what does this API do and how do I avoid the common mistakes."',
+      example: `// Agent-side
+get_api({ package: 'flow', symbol: 'createFlow' })
+get_api({ package: '@pyreon/router', symbol: 'useTypedSearchParams' })`,
+      seeAlso: ['validate', 'get_pattern'],
+    },
+    {
+      name: 'validate',
+      kind: 'constant',
+      signature: 'tool: validate({ code: string; filename?: string }) → Diagnostics[]',
+      summary:
+        'Two AST-based detectors run in parallel: `detectReactPatterns` flags "coming from React" mistakes (`useState`, `useEffect`, `className`, `onChange` on inputs, React-package imports), and `detectPyreonPatterns` flags "using Pyreon wrong" mistakes (`<For>` missing `by`, props destructured at component signature, `typeof process` dev gates, raw `addEventListener`, `Date.now() + Math.random()` IDs). Diagnostics are merged + sorted by line / column for top-down reading.',
+      example: `validate({ code: \`
+function MyComp(props) {
+  const { value } = props          // → props-destructured
+  return <For each={items}>{...}</For>  // → for-missing-by
+}
+\` })`,
+      seeAlso: ['get_anti_patterns', 'migrate_react'],
+    },
+    {
+      name: 'migrate_react',
+      kind: 'constant',
+      signature: 'tool: migrate_react({ code: string; filename?: string }) → MigrationResult',
+      summary:
+        'Convert React code to idiomatic Pyreon. Handles `useState` → `signal()`, `useEffect` → `effect()`, `className` → `class`, `onChange` → `onInput`, `useMemo` → `computed()`, React imports → Pyreon imports. Reports per-edit fixable diagnostics so callers can apply or review.',
+      example: `migrate_react({ code: \`
+import { useState, useEffect } from 'react'
+function Counter() {
+  const [count, setCount] = useState(0)
+  useEffect(() => { console.log(count) }, [count])
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+\` })`,
+      seeAlso: ['validate'],
+    },
+    {
+      name: 'diagnose',
+      kind: 'constant',
+      signature: 'tool: diagnose({ error: string }) → DiagnoseResult',
+      summary:
+        'Parse a Pyreon runtime / build error message into structured fix information: probable cause, recommended fix, related docs, and the `.claude/rules/anti-patterns.md` entry (if any) the error matches. Useful when an agent sees a stack trace and wants to skip the "search the codebase for similar errors" step.',
+      example: `diagnose({ error: 'Cannot redefine property X on object [object Object]' })
+// → cause: configurable: false on a getter; fix: set configurable: true`,
+      seeAlso: ['validate', 'get_anti_patterns'],
+    },
+    {
+      name: 'get_routes',
+      kind: 'constant',
+      signature: 'tool: get_routes() → Route[]',
+      summary:
+        'List every route in the current project — path, loader presence, guards, params, and named-route name. Walks the project source from `process.cwd()` down. Cached per server instance with auto-invalidation on `cwd` change.',
+      example: `get_routes()
+// → [{ path: '/', name: 'home', hasLoader: true, params: [] }, ...]`,
+      seeAlso: ['get_components'],
+    },
+    {
+      name: 'get_components',
+      kind: 'constant',
+      signature: 'tool: get_components() → ComponentInfo[]',
+      summary:
+        'List every component in the current project with its props and signal usage. Same scanner as `get_routes`. Useful for an agent before generating new code that needs to reference existing components.',
+      example: `get_components()
+// → [{ name: 'Button', file: 'src/Button.tsx', props: ['onClick', 'children'], signals: ['count'] }, ...]`,
+      seeAlso: ['get_routes'],
+    },
+    {
+      name: 'get_pattern',
+      kind: 'constant',
+      signature: 'tool: get_pattern({ name?: string }) → PatternBody | string[]',
+      summary:
+        'Fetch a canonical "how do I do X" pattern body from `docs/patterns/`. Eight foundational patterns ship: `dev-warnings`, `controllable-state`, `ssr-safe-hooks`, `signal-writes`, `keyed-lists`, `reactive-context`, `event-listeners`, `form-fields`. Omit `name` to list available patterns. Drop a new `docs/patterns/<slug>.md` file to add one — picked up on next call.',
+      example: `get_pattern({ name: 'controllable-state' })
+// → full canonical pattern body
+get_pattern({})
+// → [{ name: 'controllable-state', summary: '...' }, ...]`,
+      seeAlso: ['get_anti_patterns'],
+    },
+    {
+      name: 'get_anti_patterns',
+      kind: 'constant',
+      signature:
+        "tool: get_anti_patterns({ category?: 'reactivity' | 'jsx' | 'context' | 'architecture' | 'testing' | 'lifecycle' | 'documentation' | 'all' }) → AntiPattern[]",
+      summary:
+        'Browse the anti-patterns catalog parsed from `.claude/rules/anti-patterns.md`. Each entry surfaces its `[detector: <code>]` tag inline so an agent can pair the catalog entry with the live static detector exposed by `validate`. Optional `category` filter; default returns all categories.',
+      example: `get_anti_patterns({ category: 'reactivity' })
+// → ['Bare signal in JSX text', 'Stale closures', 'Destructuring props', ...]`,
+      seeAlso: ['validate', 'get_pattern'],
+    },
+    {
+      name: 'get_changelog',
+      kind: 'constant',
+      signature:
+        'tool: get_changelog({ package?: string; limit?: number; includeDependencyUpdates?: boolean; since?: string }) → ChangelogEntry[]',
+      summary:
+        'Recent release notes for any `@pyreon/*` package without scraping `git log`. Parses `packages/**/CHANGELOG.md` into version entries (`{ version, changes[], dependencyUpdates[], empty }`) and returns the N most recent substantive versions (default 5). Filters out ceremonial version bumps (pure dependency-update releases with no user-facing body) by default — opt back in with `includeDependencyUpdates: true`. `since: "0.12.0"` returns the delta from a known floor — useful when an agent knows the version it was trained against.',
+      example: `get_changelog({ package: 'flow', limit: 5 })
+get_changelog({ package: '@pyreon/router', since: '0.12.0' })`,
+      seeAlso: ['get_api'],
+    },
+    {
+      name: 'audit_test_environment',
+      kind: 'constant',
+      signature:
+        "tool: audit_test_environment({ minRisk?: 'high' | 'medium' | 'low'; limit?: number }) → AuditReport",
+      summary:
+        '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'],
+    },
+  ],
+  gotchas: [
+    {
+      label: 'Project-context caching',
+      note:
+        'Each `createServer()` instance maintains its own cached context (routes, components, islands). The cache auto-resets when `process.cwd()` changes between tool invocations, so the same server can operate across multiple projects in one session.',
+    },
+    {
+      label: 'Manifest-driven',
+      note:
+        '`get_api` reads `api-reference.ts`, which is generated from each package\\\'s `manifest.ts`. The marker-pair protocol (`<gen-docs:api-reference:start @pyreon/<name>>`) lets some packages be generated and others stay hand-written during incremental migration.',
+    },
+  ],
+})