@pyreon/mcp 0.5.0

package/src/api-reference.ts

@@ -0,0 +1,447 @@
+/**
+ * Pyreon API reference database — structured documentation for every public export.
+ * Used by the MCP server's get_api tool and the llms.txt generator.
+ *
+ * Format: "package/symbol" → { signature, example, notes?, mistakes? }
+ */
+
+export interface ApiEntry {
+  signature: string
+  example: string
+  notes?: string
+  mistakes?: string
+}
+
+export const API_REFERENCE: Record<string, ApiEntry> = {
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/reactivity
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "reactivity/signal": {
+    signature: "signal<T>(initialValue: T, options?: { name?: string }): Signal<T>",
+    example: `const count = signal(0)
+
+// Read (subscribes to updates):
+count()          // 0
+
+// Write:
+count.set(5)     // sets to 5
+
+// Update:
+count.update(n => n + 1)  // 6
+
+// Read without subscribing:
+count.peek()     // 6`,
+    notes:
+      "Signals are callable functions, NOT .value getters. Components run once — signal reads in JSX auto-subscribe.",
+    mistakes: `- \`count.value\` → Use \`count()\` to read
+- \`{count}\` in JSX → Use \`{count()}\` to read (or let the compiler wrap it)
+- \`const [val, setVal] = signal(0)\` → Not destructurable. Use \`const val = signal(0)\``,
+  },
+
+  "reactivity/computed": {
+    signature:
+      "computed<T>(fn: () => T, options?: { equals?: (a: T, b: T) => boolean }): Computed<T>",
+    example: `const count = signal(0)
+const doubled = computed(() => count() * 2)
+
+doubled()  // 0
+count.set(5)
+doubled()  // 10`,
+    notes:
+      "Dependencies auto-tracked. No dependency array needed. Memoized — only recomputes when dependencies change.",
+    mistakes: `- \`computed(() => count)\` → Must call signal: \`computed(() => count())\`
+- Don't use for side effects — use effect() instead`,
+  },
+
+  "reactivity/effect": {
+    signature: "effect(fn: () => (() => void) | void): () => void",
+    example: `const count = signal(0)
+
+// Auto-tracks count() dependency:
+const dispose = effect(() => {
+  console.log("Count is:", count())
+})
+
+// With cleanup:
+effect(() => {
+  const handler = () => console.log(count())
+  window.addEventListener("resize", handler)
+  return () => window.removeEventListener("resize", handler)
+})`,
+    notes:
+      "Returns a dispose function. Dependencies auto-tracked on each run. For DOM-specific effects, use renderEffect().",
+    mistakes: `- Don't pass a dependency array — Pyreon auto-tracks
+- \`effect(() => { count })\` → Must call: \`effect(() => { count() })\``,
+  },
+
+  "reactivity/batch": {
+    signature: "batch(fn: () => void): void",
+    example: `const a = signal(1)
+const b = signal(2)
+
+// Updates subscribers only once:
+batch(() => {
+  a.set(10)
+  b.set(20)
+})`,
+    notes: "Defers all signal notifications until the batch completes. Nested batches are merged.",
+  },
+
+  "reactivity/createStore": {
+    signature: "createStore<T extends object>(initialValue: T): T",
+    example: `const store = createStore({
+  user: { name: "Alice", age: 30 },
+  items: [1, 2, 3]
+})
+
+// Granular reactivity — only rerenders what changed:
+store.user.name = "Bob"  // only name subscribers fire
+store.items.push(4)      // only items subscribers fire`,
+    notes:
+      "Deep proxy — nested objects are automatically reactive. Use reconcile() for bulk updates.",
+  },
+
+  "reactivity/createResource": {
+    signature:
+      "createResource<T>(fetcher: () => Promise<T>, options?: ResourceOptions): Resource<T>",
+    example: `const users = createResource(() => fetch("/api/users").then(r => r.json()))
+
+// In JSX:
+<Show when={!users.loading()}>
+  <For each={users()} by={u => u.id}>
+    {user => <li>{user.name}</li>}
+  </For>
+</Show>`,
+    notes:
+      "Integrates with Suspense. Access .loading(), .error(), and call resource() for the value.",
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/core
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "core/h": {
+    signature:
+      "h<P>(type: ComponentFn<P> | string | symbol, props: P | null, ...children: VNodeChild[]): VNode",
+    example: `// Usually use JSX instead:
+const vnode = h("div", { class: "container" },
+  h("h1", null, "Hello"),
+  h(Counter, { initial: 0 })
+)`,
+    notes: "Low-level API. Prefer JSX which compiles to h() calls (or _tpl() for templates).",
+  },
+
+  "core/Fragment": {
+    signature: "Fragment: symbol",
+    example: `// JSX:
+<>
+  <h1>Title</h1>
+  <p>Content</p>
+</>
+
+// h() API:
+h(Fragment, null, h("h1", null, "Title"), h("p", null, "Content"))`,
+  },
+
+  "core/onMount": {
+    signature: "onMount(fn: () => CleanupFn | undefined): void",
+    example: `const Timer = () => {
+  const count = signal(0)
+
+  onMount(() => {
+    const id = setInterval(() => count.update(n => n + 1), 1000)
+    return () => clearInterval(id)  // cleanup
+  })
+
+  return <div>{count()}</div>
+}`,
+    notes: "Must return undefined or a cleanup function. Do NOT return void.",
+    mistakes: `- \`onMount(() => { doStuff() })\` → Must return undefined: \`onMount(() => { doStuff(); return undefined })\`
+- Or return cleanup: \`onMount(() => { const id = setInterval(...); return () => clearInterval(id) })\``,
+  },
+
+  "core/onUnmount": {
+    signature: "onUnmount(fn: () => void): void",
+    example: `onUnmount(() => {
+  console.log("Component removed from DOM")
+})`,
+  },
+
+  "core/createContext": {
+    signature: "createContext<T>(defaultValue: T): Context<T>",
+    example: `const ThemeContext = createContext<"light" | "dark">("light")
+
+// Provide:
+const App = () => {
+  pushContext(new Map([[ThemeContext.id, "dark"]]))
+  onUnmount(() => popContext())
+  return <Child />
+}
+
+// Consume:
+const Child = () => {
+  const theme = useContext(ThemeContext)
+  return <div class={theme}>...</div>
+}`,
+  },
+
+  "core/useContext": {
+    signature: "useContext<T>(ctx: Context<T>): T",
+    example: `const theme = useContext(ThemeContext)  // returns provided value or default`,
+  },
+
+  "core/For": {
+    signature: "<For each={items} by={keyFn}>{renderFn}</For>",
+    example: `const items = signal([
+  { id: 1, name: "Apple" },
+  { id: 2, name: "Banana" },
+])
+
+<For each={items()} by={item => item.id}>
+  {item => <li>{item.name}</li>}
+</For>`,
+    notes: "Uses 'by' prop (not 'key') because JSX extracts 'key' as a special VNode prop.",
+    mistakes: `- \`<For each={items}>\` → Must call signal: \`<For each={items()}>\`
+- \`<For each={items()} key={...}>\` → Use \`by\` not \`key\`
+- \`{items().map(...)}\` → Use <For> for reactive list rendering`,
+  },
+
+  "core/Show": {
+    signature: "<Show when={condition} fallback={alternative}>{children}</Show>",
+    example: `<Show when={isLoggedIn()} fallback={<LoginForm />}>
+  <Dashboard />
+</Show>`,
+    notes:
+      "More efficient than ternary for signal-driven conditions. Only mounts/unmounts when condition changes.",
+  },
+
+  "core/Suspense": {
+    signature: "<Suspense fallback={loadingUI}>{children}</Suspense>",
+    example: `const LazyPage = lazy(() => import("./HeavyPage"))
+
+<Suspense fallback={<div>Loading...</div>}>
+  <LazyPage />
+</Suspense>`,
+  },
+
+  "core/lazy": {
+    signature:
+      "lazy(loader: () => Promise<{ default: ComponentFn }>, options?: LazyOptions): LazyComponent",
+    example: `const Settings = lazy(() => import("./pages/Settings"))
+
+// Use in JSX (wrap with Suspense):
+<Suspense fallback={<Spinner />}>
+  <Settings />
+</Suspense>`,
+  },
+
+  "core/Dynamic": {
+    signature: "<Dynamic component={comp} {...props} />",
+    example: `const components = { home: HomePage, about: AboutPage }
+const current = signal("home")
+
+<Dynamic component={components[current()]} />`,
+  },
+
+  "core/ErrorBoundary": {
+    signature: "<ErrorBoundary onCatch={handler} fallback={errorUI}>{children}</ErrorBoundary>",
+    example: `<ErrorBoundary
+  onCatch={(err) => console.error(err)}
+  fallback={(err) => <div>Error: {err.message}</div>}
+>
+  <App />
+</ErrorBoundary>`,
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/router
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "router/createRouter": {
+    signature: "createRouter(options: RouterOptions | RouteRecord[]): Router",
+    example: `const router = createRouter([
+  { path: "/", component: Home },
+  { path: "/user/:id", component: User, loader: ({ params }) => fetchUser(params.id) },
+  { path: "/admin", component: Admin, beforeEnter: requireAuth, children: [
+    { path: "settings", component: Settings },
+  ]},
+])`,
+  },
+
+  "router/RouterProvider": {
+    signature: "<RouterProvider router={router}>{children}</RouterProvider>",
+    example: `const App = () => (
+  <RouterProvider router={router}>
+    <nav><RouterLink to="/">Home</RouterLink></nav>
+    <RouterView />
+  </RouterProvider>
+)`,
+  },
+
+  "router/RouterView": {
+    signature: "<RouterView />",
+    example: `// Renders the matched route's component
+<RouterView />
+
+// Nested routes: parent component includes <RouterView /> for children
+const Admin = () => (
+  <div>
+    <h1>Admin</h1>
+    <RouterView />  {/* renders Settings, Users, etc. */}
+  </div>
+)`,
+  },
+
+  "router/RouterLink": {
+    signature: "<RouterLink to={path} activeClass={cls} exactActiveClass={cls} />",
+    example: `<RouterLink to="/" activeClass="nav-active">Home</RouterLink>
+<RouterLink to={{ name: "user", params: { id: "42" } }}>Profile</RouterLink>`,
+  },
+
+  "router/useRouter": {
+    signature: "useRouter(): Router",
+    example: `const router = useRouter()
+
+router.push("/settings")
+router.push({ name: "user", params: { id: "42" } })
+router.replace("/login")
+router.back()
+router.forward()
+router.go(-2)`,
+  },
+
+  "router/useRoute": {
+    signature: "useRoute<TPath extends string>(): () => ResolvedRoute<ExtractParams<TPath>>",
+    example: `// Type-safe params:
+const route = useRoute<"/user/:id">()
+const userId = route().params.id  // string
+
+// Access query, meta, etc:
+route().query
+route().meta`,
+  },
+
+  "router/useSearchParams": {
+    signature:
+      "useSearchParams<T>(defaults?: T): [get: () => T, set: (updates: Partial<T>) => Promise<void>]",
+    example: `const [search, setSearch] = useSearchParams({ page: "1", sort: "name" })
+
+// Read:
+search().page  // "1"
+
+// Write:
+setSearch({ page: "2" })`,
+  },
+
+  "router/useLoaderData": {
+    signature: "useLoaderData<T>(): T",
+    example: `// Route: { path: "/user/:id", component: User, loader: ({ params }) => fetchUser(params.id) }
+
+const User = () => {
+  const data = useLoaderData<UserData>()
+  return <div>{data.name}</div>
+}`,
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/head
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "head/useHead": {
+    signature: "useHead(input: UseHeadInput | (() => UseHeadInput)): void",
+    example: `// Static:
+useHead({ title: "My Page", meta: [{ name: "description", content: "..." }] })
+
+// Reactive (updates when signals change):
+useHead(() => ({
+  title: \`\${username()} — Profile\`,
+  meta: [{ property: "og:title", content: username() }]
+}))`,
+  },
+
+  "head/HeadProvider": {
+    signature: "<HeadProvider>{children}</HeadProvider>",
+    example: `// Client-side setup:
+mount(
+  <HeadProvider>
+    <App />
+  </HeadProvider>,
+  document.getElementById("app")!
+)`,
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/server
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "server/createHandler": {
+    signature: "createHandler(options: HandlerOptions): (req: Request) => Promise<Response>",
+    example: `import { createHandler } from "@pyreon/server"
+
+export default createHandler({
+  App,
+  routes,
+  clientEntry: "/src/entry-client.ts",
+  mode: "stream",  // or "string"
+})`,
+  },
+
+  "server/island": {
+    signature:
+      "island(loader: () => Promise<ComponentFn>, options: { name: string; hydrate?: HydrationStrategy }): ComponentFn",
+    example: `const SearchBar = island(
+  () => import("./SearchBar"),
+  { name: "SearchBar", hydrate: "visible" }
+)
+
+// Hydration strategies: "load" | "idle" | "visible" | "media" | "never"`,
+  },
+
+  "server/prerender": {
+    signature: "prerender(options: PrerenderOptions): Promise<PrerenderResult>",
+    example: `await prerender({
+  handler,
+  paths: ["/", "/about", "/blog/1", "/blog/2"],
+  outDir: "./dist",
+})`,
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // @pyreon/runtime-dom
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  "runtime-dom/mount": {
+    signature: "mount(root: VNodeChild, container: Element): () => void",
+    example: `import { mount } from "@pyreon/runtime-dom"
+
+const dispose = mount(<App />, document.getElementById("app")!)
+
+// To unmount:
+dispose()`,
+    mistakes: `- \`createRoot(container).render(<App />)\` → Use \`mount(<App />, container)\`
+- Container must not be null/undefined`,
+  },
+
+  "runtime-dom/hydrateRoot": {
+    signature: "hydrateRoot(root: VNodeChild, container: Element): () => void",
+    example: `import { hydrateRoot } from "@pyreon/runtime-dom"
+
+// Hydrate server-rendered HTML:
+hydrateRoot(<App />, document.getElementById("app")!)`,
+  },
+
+  "runtime-dom/Transition": {
+    signature: "<Transition name={name} mode={mode}>{children}</Transition>",
+    example: `<Transition name="fade" mode="out-in">
+  <Show when={visible()}>
+    <div>Content</div>
+  </Show>
+</Transition>
+
+/* CSS:
+.fade-enter-active, .fade-leave-active { transition: opacity 0.3s }
+.fade-enter-from, .fade-leave-to { opacity: 0 }
+*/`,
+  },
+}

package/src/index.ts

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * @pyreon/mcp — Model Context Protocol server for Pyreon
+ *
+ * Exposes tools that AI coding assistants (Claude Code, Cursor, etc.) can use
+ * to generate, validate, and migrate Pyreon code.
+ *
+ * Tools:
+ *   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
+ *   diagnose       — Parse an error message into structured fix information
+ *   get_routes     — List all routes in the current project
+ *   get_components — List all components with their props and signals
+ *
+ * Usage:
+ *   bunx @pyreon/mcp          # stdio transport (for IDE integration)
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { detectReactPatterns, diagnoseError, migrateReactCode } from "@pyreon/compiler"
+import { z } from "zod"
+import { API_REFERENCE } from "./api-reference"
+import { generateContext, type ProjectContext } from "./project-scanner"
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Server setup
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const server = new McpServer({
+  name: "pyreon",
+  version: "0.4.0",
+})
+
+// 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
+// ═══════════════════════════════════════════════════════════════════════════════
+
+// @ts-expect-error — MCP SDK + Zod generic inference is excessively deep
+server.tool(
+  "get_api",
+  {
+    package: z.string(),
+    symbol: z.string(),
+  },
+  async ({ package: pkg, symbol }) => {
+    const key = `${pkg}/${symbol}`
+    const entry = API_REFERENCE[key]
+
+    if (!entry) {
+      const allKeys = Object.keys(API_REFERENCE)
+      const suggestions = allKeys
+        .filter((k) => k.toLowerCase().includes(symbol.toLowerCase()))
+        .slice(0, 5)
+
+      return textResult(
+        `Symbol '${symbol}' not found in @pyreon/${pkg}.\n\n${
+          suggestions.length > 0
+            ? `Did you mean one of these?\n${suggestions.map((s) => `  - ${s}`).join("\n")}`
+            : "No similar symbols found."
+        }`,
+      )
+    }
+
+    return textResult(
+      `## @pyreon/${pkg} — ${symbol}\n\n**Signature:**\n\`\`\`typescript\n${entry.signature}\n\`\`\`\n\n**Usage:**\n\`\`\`typescript\n${entry.example}\n\`\`\`\n\n${entry.notes ? `**Notes:** ${entry.notes}\n\n` : ""}${entry.mistakes ? `**Common mistakes:**\n${entry.mistakes}\n` : ""}`,
+    )
+  },
+)
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool: validate
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "validate",
+  {
+    code: z.string(),
+    filename: z.string().optional(),
+  },
+  async ({ code, filename }) => {
+    const diagnostics = detectReactPatterns(code, filename ?? "snippet.tsx")
+
+    if (diagnostics.length === 0) {
+      return textResult("✓ No issues found. The code follows Pyreon patterns correctly.")
+    }
+
+    const issueText = diagnostics
+      .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"}`,
+      )
+      .join("\n\n")
+
+    return textResult(
+      `Found ${diagnostics.length} issue${diagnostics.length === 1 ? "" : "s"}:\n\n${issueText}`,
+    )
+  },
+)
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool: migrate_react
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "migrate_react",
+  {
+    code: z.string(),
+    filename: z.string().optional(),
+  },
+  async ({ code, filename }) => {
+    const result = migrateReactCode(code, filename ?? "component.tsx")
+
+    const changeList = result.changes.map((c) => `- Line ${c.line}: ${c.description}`).join("\n")
+
+    const remainingIssues = result.diagnostics.filter((d) => !d.fixable)
+    const manualText =
+      remainingIssues.length > 0
+        ? `\n\n**Remaining issues (manual fix needed):**\n${remainingIssues.map((d) => `- Line ${d.line}: ${d.message}\n  Suggested: \`${d.suggested}\``).join("\n")}`
+        : ""
+
+    return textResult(
+      `## Migrated Code\n\n\`\`\`tsx\n${result.code}\n\`\`\`\n\n**Changes applied (${result.changes.length}):**\n${changeList || "No changes needed."}${manualText}`,
+    )
+  },
+)
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool: diagnose
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool(
+  "diagnose",
+  {
+    error: z.string(),
+  },
+  async ({ error }) => {
+    const diagnosis = diagnoseError(error)
+
+    if (!diagnosis) {
+      return textResult(
+        `Could not identify a Pyreon-specific pattern in this error.\n\nError: ${error}\n\nSuggestions:\n- Check for typos in variable/function names\n- Verify all imports are correct\n- Run \`bun run typecheck\` for full TypeScript diagnostics\n- Run \`pyreon doctor\` for project-wide health check`,
+      )
+    }
+
+    let text = `**Cause:** ${diagnosis.cause}\n\n**Fix:** ${diagnosis.fix}`
+    if (diagnosis.fixCode) {
+      text += `\n\n**Code:**\n\`\`\`typescript\n${diagnosis.fixCode}\n\`\`\``
+    }
+    if (diagnosis.related) {
+      text += `\n\n**Related:** ${diagnosis.related}`
+    }
+
+    return textResult(text)
+  },
+)
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool: get_routes
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool("get_routes", {}, async () => {
+  const ctx = getContext()
+
+  if (ctx.routes.length === 0) {
+    return textResult(
+      "No routes detected. Routes are defined via createRouter() or a routes array.",
+    )
+  }
+
+  const routeTable = ctx.routes
+    .map((r) => {
+      const flags = [
+        r.hasLoader ? "loader" : "",
+        r.hasGuard ? "guard" : "",
+        r.params.length > 0 ? `params: ${r.params.join(", ")}` : "",
+        r.name ? `name: "${r.name}"` : "",
+      ]
+        .filter(Boolean)
+        .join(", ")
+
+      return `  ${r.path}${flags ? ` (${flags})` : ""}`
+    })
+    .join("\n")
+
+  return textResult(`**Routes (${ctx.routes.length}):**\n\n${routeTable}`)
+})
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Tool: get_components
+// ═══════════════════════════════════════════════════════════════════════════════
+
+server.tool("get_components", {}, async () => {
+  const ctx = getContext()
+
+  if (ctx.components.length === 0) {
+    return textResult("No components detected.")
+  }
+
+  const compList = ctx.components
+    .map((c) => {
+      const details = [
+        c.props.length > 0 ? `props: { ${c.props.join(", ")} }` : "",
+        c.hasSignals ? `signals: [${c.signalNames.join(", ")}]` : "",
+      ]
+        .filter(Boolean)
+        .join(", ")
+
+      return `  ${c.name} — ${c.file}${details ? `\n    ${details}` : ""}`
+    })
+    .join("\n")
+
+  return textResult(`**Components (${ctx.components.length}):**\n\n${compList}`)
+})
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Start server
+// ═══════════════════════════════════════════════════════════════════════════════
+
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+main().catch((err) => {
+  console.error("MCP server error:", err)
+  process.exit(1)
+})