@agjs/tsforge 0.1.7 → 0.1.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/config/tsforge-config.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { isRecord } from "../lib/guards";
 import { PACK_REGISTRY } from "../stack-detection";
+import { parseMcpServers, type IMcpServerConfig } from "../mcp";
 
 /**
  * User-defined configuration from tsforge.config.json
@@ -23,6 +24,13 @@ export interface ITsforgeProjectConfig {
    * Values: "error" | "warn" | "off" (off silences the rule).
    */
   readonly rules?: Readonly<Record<string, "error" | "warn" | "off">>;
+
+  /**
+   * External MCP (Model Context Protocol) servers whose tools are offered to the
+   * agent. Keyed by a short server name. `${VAR}` references in string values are
+   * interpolated from the environment at load time. Opt-in: absent ⇒ no MCP.
+   */
+  readonly mcpServers?: Readonly<Record<string, IMcpServerConfig>>;
 }
 
 function warnConfig(msg: string): void {
@@ -158,6 +166,54 @@ function validateRules(
   return Object.keys(rulesFields).length > 0 ? rulesFields : undefined;
 }
 
+/** Validate each known field of an already-parsed config object, dropping any
+ *  that fail their per-field validator. Kept separate from the file IO so the
+ *  loader stays simple. */
+function buildConfigFields(
+  parsed: Record<string, unknown>
+): ITsforgeProjectConfig {
+  const configFields: {
+    stack?: string;
+    packs?: { include?: readonly string[]; exclude?: readonly string[] };
+    rules?: Record<string, "error" | "warn" | "off">;
+    mcpServers?: Record<string, IMcpServerConfig>;
+  } = {};
+
+  if (parsed.stack !== undefined) {
+    const stack = validateStack(parsed.stack);
+
+    if (stack !== undefined) {
+      configFields.stack = stack;
+    }
+  }
+
+  if (parsed.packs !== undefined) {
+    const packs = validatePacks(parsed.packs);
+
+    if (packs !== undefined) {
+      configFields.packs = packs;
+    }
+  }
+
+  if (parsed.rules !== undefined) {
+    const rules = validateRules(parsed.rules);
+
+    if (rules !== undefined) {
+      configFields.rules = rules;
+    }
+  }
+
+  if (parsed.mcpServers !== undefined) {
+    const servers = parseMcpServers(parsed.mcpServers, process.env);
+
+    if (Object.keys(servers).length > 0) {
+      configFields.mcpServers = servers;
+    }
+  }
+
+  return configFields;
+}
+
 /** Load tsforge.config.json from cwd, defaulting to empty config on missing/invalid files. */
 export async function loadTsforgeConfig(
   cwd: string
@@ -181,37 +237,7 @@ export async function loadTsforgeConfig(
       return {};
     }
 
-    const configFields: {
-      stack?: string;
-      packs?: { include?: readonly string[]; exclude?: readonly string[] };
-      rules?: Record<string, "error" | "warn" | "off">;
-    } = {};
-
-    if (parsed.stack !== undefined) {
-      const stack = validateStack(parsed.stack);
-
-      if (stack !== undefined) {
-        configFields.stack = stack;
-      }
-    }
-
-    if (parsed.packs !== undefined) {
-      const packs = validatePacks(parsed.packs);
-
-      if (packs !== undefined) {
-        configFields.packs = packs;
-      }
-    }
-
-    if (parsed.rules !== undefined) {
-      const rules = validateRules(parsed.rules);
-
-      if (rules !== undefined) {
-        configFields.rules = rules;
-      }
-    }
-
-    return configFields;
+    return buildConfigFields(parsed);
   } catch (err) {
     if (err instanceof SyntaxError) {
       const firstLine = err.message.split("\n")[0];

package/src/loop/rule-docs.generated.json

@@ -299,6 +299,21 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/client-hooks-require-use-client": {
+    "what": "Require the 'use client' directive in app-router page/layout/template files that call client-only hooks. Server Components cannot use state/effect/navigation hooks — doing so crashes at runtime.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-next-head-in-app": {
+    "what": "Disallow importing 'next/head' in app-router files. The <Head> component is a no-op under app/ — use the Metadata API (export const metadata / generateMetadata) instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-pages-router-data-fetching-in-app": {
+    "what": "Disallow pages-router data-fetching exports (getServerSideProps, getStaticProps, getStaticPaths, getInitialProps) in app-router files. Next.js ignores them under app/, so they are silent dead code — use async Server Components or route handlers instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/pkce-required-for-oidc": {
     "what": "OIDC providers must use PKCE: `buildAuthorizationURL` must call `generateCodeVerifier()` and pass it to `createAuthorizationURL`.",
     "bad": "// Example that violates the rule",

package/src/loop/session.ts

@@ -25,6 +25,7 @@ import {
   normalizeRuleOverrides,
   resolveActivePacks,
 } from "../config/tsforge-config";
+import { connectMcpServers } from "../mcp";
 import { LOOP_LIMITS, RUN_STATUS } from "./loop.constants";
 import type { Reporter } from "./loop.types";
 import { CHAT_SYSTEM, COMPACT_SYSTEM } from "./prompt";
@@ -439,6 +440,16 @@ export class Session {
     };
     const ruleOverrides = normalizeRuleOverrides(projectConfig);
 
+    // Opt-in: connect any configured MCP servers so their tools are offered to
+    // the agent. A bad server is reported and skipped (connectMcpServers never
+    // throws), so MCP can never block an interactive session from starting.
+    const mcpRegistry =
+      projectConfig.mcpServers === undefined
+        ? null
+        : await connectMcpServers(projectConfig.mcpServers, (message) => {
+            report({ kind: "tool", task: SESSION_ID, message });
+          });
+
     const ctx: ILoopCtx = {
       task,
       cwd: cfg.cwd,
@@ -447,6 +458,7 @@ export class Session {
       parse: cfg.parse,
       report,
       stackProfile,
+      ...(mcpRegistry === null ? {} : { mcpRegistry }),
       ...(Object.keys(ruleOverrides).length > 0 ? { ruleOverrides } : {}),
       messages:
         cfg.history !== undefined && cfg.history.length > 0
@@ -916,13 +928,18 @@ export class Session {
     // enforces a read-only command allowlist) — the model never sees a write
     // tool. Filtered per call, so `this.tools` is untouched and toggling the
     // mode off restores the full set with zero bookkeeping.
-    const offeredTools = this.planMode
+    const baseTools = this.planMode
       ? this.tools.filter(
           (t) =>
             READ_ONLY_TOOL_NAMES.has(t.function.name) ||
             t.function.name === TOOL_NAME.run
         )
       : this.tools;
+    // MCP tools are external context sources (not workspace writes), so they ride
+    // alongside the built-ins even in plan mode — appended after the filter.
+    const mcpSchemas = this.ctx.mcpRegistry?.toolSchemas() ?? [];
+    const offeredTools =
+      mcpSchemas.length > 0 ? [...baseTools, ...mcpSchemas] : baseTools;
     const res = await this.provider.complete(ctx.messages, {
       tools: offeredTools,
       temperature: this.cfg.temperature ?? 0,

package/src/loop/tools/execute-tool.ts

@@ -55,6 +55,13 @@ export async function executeTool(
   call: IToolCall,
   ctx: IToolContext
 ): Promise<string> {
+  // MCP tools (mcp__<server>__<tool>) are dispatched to their server. They are
+  // external context sources — never workspace mutations — so they bypass the
+  // built-in name table and the plan-mode write guard below.
+  if (ctx.mcpRegistry?.has(call.name) === true) {
+    return ctx.mcpRegistry.callTool(call.name, call.arguments);
+  }
+
   if (!isToolName(call.name)) {
     return `unknown tool: ${call.name}`;
   }

package/src/loop/tools/tool-context.ts

@@ -2,6 +2,7 @@ import { repairArgs } from "../../agent/tool-repair";
 import type { TsService } from "../../lsp";
 import type { Reporter } from "../loop.types";
 import type { SessionSnapshotStore } from "../../files/hashline";
+import type { McpRegistry } from "../../mcp";
 
 export interface IToolContext {
   cwd: string;
@@ -28,6 +29,10 @@ export interface IToolContext {
   readOnly?: boolean;
   /** Hashline snapshot store for stale-anchor recovery (per-session, lazily initialized). */
   snapshotStore?: SessionSnapshotStore;
+  /** Connected MCP servers. When present, `mcp__<server>__<tool>` calls are routed
+   *  here. These are external context/tool sources — they never touch the editable
+   *  scope or the deterministic gate. Absent ⇒ no MCP configured. */
+  mcpRegistry?: McpRegistry;
 }
 
 /** A required string arg, or "" if missing/wrong-type. */

package/src/loop/turn.ts

@@ -32,6 +32,7 @@ import {
   TOOL_NAME,
 } from "../agent";
 import { TsService, type ITsDiagnostic } from "../lsp";
+import type { McpRegistry } from "../mcp";
 import type { FileLinter, IFileLintProblem } from "../detect-gate";
 import {
   buildMetaRuleContext,
@@ -115,6 +116,9 @@ export interface ILoopCtx {
   /** PLAN MODE (set via Session.setPlanMode): threaded into the tool context so
    *  mutating tools are rejected at dispatch — the model only plans. */
   readOnly?: boolean;
+  /** Connected MCP servers (opt-in via tsforge.config.json `mcpServers`). Threaded
+   *  into the tool context so `mcp__<server>__<tool>` calls dispatch to them. */
+  mcpRegistry?: McpRegistry;
 }
 
 /** Mutable state threaded across turns (the gradient the loop descends). */
@@ -448,6 +452,9 @@ export async function runToolCalls(
       ...(ctx.signal === undefined ? {} : { signal: ctx.signal }),
       ...(ctx.setupWeb === undefined ? {} : { setupWeb: ctx.setupWeb }),
       ...(ctx.readOnly === undefined ? {} : { readOnly: ctx.readOnly }),
+      ...(ctx.mcpRegistry === undefined
+        ? {}
+        : { mcpRegistry: ctx.mcpRegistry }),
     });
 
     let feedback = "";

package/src/mcp/config.ts

@@ -0,0 +1,106 @@
+import { isRecord } from "../lib/guards";
+import type { IMcpServerConfig } from "./mcp.types";
+
+type EnvLookup = Readonly<Record<string, string | undefined>>;
+
+/** Interpolate `${VAR}` references from `env` into a string (missing → ""). */
+export function interpolateEnv(value: string, env: EnvLookup): string {
+  return value.replace(
+    /\$\{([A-Za-z0-9_]+)\}/g,
+    (_match: string, name: string) => env[name] ?? ""
+  );
+}
+
+function stringArray(value: unknown, env: EnvLookup): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const out = value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => interpolateEnv(item, env));
+
+  return out.length > 0 ? out : undefined;
+}
+
+function envRecord(
+  value: unknown,
+  env: EnvLookup
+): Record<string, string> | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const out: Record<string, string> = {};
+
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw === "string") {
+      out[key] = interpolateEnv(raw, env);
+    }
+  }
+
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Parse one server entry, applying env interpolation. Returns null if the entry
+ *  is malformed or missing the field its transport requires. */
+function parseOne(value: unknown, env: EnvLookup): IMcpServerConfig | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const type = value.type === "http" ? "http" : "stdio";
+  const command =
+    typeof value.command === "string"
+      ? interpolateEnv(value.command, env)
+      : undefined;
+  const url =
+    typeof value.url === "string" ? interpolateEnv(value.url, env) : undefined;
+  const timeoutMs =
+    typeof value.timeoutMs === "number" && value.timeoutMs > 0
+      ? value.timeoutMs
+      : undefined;
+
+  if (type === "stdio" && (command === undefined || command.length === 0)) {
+    return null;
+  }
+
+  if (type === "http" && (url === undefined || url.length === 0)) {
+    return null;
+  }
+
+  return {
+    type,
+    command,
+    args: stringArray(value.args, env),
+    env: envRecord(value.env, env),
+    url,
+    timeoutMs,
+  };
+}
+
+/**
+ * Parse the `mcpServers` block of tsforge.config.json into validated configs,
+ * keyed by server name. Malformed or incomplete entries are dropped (the loader
+ * warns); a missing/invalid block yields {}.
+ */
+export function parseMcpServers(
+  raw: unknown,
+  env: EnvLookup
+): Record<string, IMcpServerConfig> {
+  if (!isRecord(raw)) {
+    return {};
+  }
+
+  const servers: Record<string, IMcpServerConfig> = {};
+
+  for (const [name, value] of Object.entries(raw)) {
+    const parsed = parseOne(value, env);
+
+    if (parsed !== null) {
+      servers[name] = parsed;
+    }
+  }
+
+  return servers;
+}

package/src/mcp/index.ts

@@ -0,0 +1,11 @@
+export type {
+  IMcpServerConfig,
+  IMcpToolInfo,
+  IMcpTransport,
+} from "./mcp.types";
+export { McpRegistry } from "./registry";
+export { connectMcpServers } from "./setup";
+export { StdioMcpTransport } from "./stdio-transport";
+export { parseMcpServers, interpolateEnv } from "./config";
+export { mcpToolName, mapMcpTool, type IToolSchema } from "./schema-mapping";
+export { LineDecoder, encodeMessage } from "./jsonrpc";

package/src/mcp/jsonrpc.ts

@@ -0,0 +1,74 @@
+import { isRecord } from "../lib/guards";
+import type { IJsonRpcResponse } from "./mcp.types";
+
+/** Encode a JSON-RPC message as a single newline-terminated line.
+ *  MCP's stdio transport frames each message as one line of UTF-8 JSON. */
+export function encodeMessage(message: unknown): string {
+  return `${JSON.stringify(message)}\n`;
+}
+
+/**
+ * Incremental decoder for newline-delimited JSON. Feed it raw stdout chunks
+ * (which may split or join messages); it returns whichever complete JSON values
+ * are now available and retains any partial trailing line. Malformed lines are
+ * skipped rather than throwing, so one bad line can't wedge the stream.
+ */
+export class LineDecoder {
+  private buffer = "";
+
+  push(chunk: string): unknown[] {
+    this.buffer += chunk;
+
+    const out: unknown[] = [];
+    let newline = this.buffer.indexOf("\n");
+
+    while (newline !== -1) {
+      const line = this.buffer.slice(0, newline).trim();
+
+      this.buffer = this.buffer.slice(newline + 1);
+
+      if (line.length > 0) {
+        const parsed = tryParse(line);
+
+        if (parsed !== undefined) {
+          out.push(parsed);
+        }
+      }
+
+      newline = this.buffer.indexOf("\n");
+    }
+
+    return out;
+  }
+}
+
+function tryParse(line: string): unknown {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Type guard for a JSON-RPC response carrying the given request id. */
+export function isResponseFor(
+  value: unknown,
+  id: number
+): value is IJsonRpcResponse {
+  return isRecord(value) && value.jsonrpc === "2.0" && value.id === id;
+}
+
+/** Extract a human-readable error string from a JSON-RPC error member. */
+export function errorText(value: unknown): string | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const error = value.error;
+
+  if (isRecord(error) && typeof error.message === "string") {
+    return error.message;
+  }
+
+  return null;
+}

package/src/mcp/mcp.types.ts

@@ -0,0 +1,66 @@
+/** JSON-RPC 2.0 request (has an id; expects a response). */
+export interface IJsonRpcRequest {
+  readonly jsonrpc: "2.0";
+  readonly id: number;
+  readonly method: string;
+  readonly params?: unknown;
+}
+
+/** JSON-RPC 2.0 notification (no id; fire-and-forget). */
+export interface IJsonRpcNotification {
+  readonly jsonrpc: "2.0";
+  readonly method: string;
+  readonly params?: unknown;
+}
+
+/** JSON-RPC 2.0 response (result xor error). */
+export interface IJsonRpcResponse {
+  readonly jsonrpc: "2.0";
+  readonly id: number;
+  readonly result?: unknown;
+  readonly error?: { readonly code: number; readonly message: string };
+}
+
+/** A tool advertised by an MCP server (one `tools/list` entry). */
+export interface IMcpToolInfo {
+  readonly name: string;
+  readonly description?: string;
+  /** JSON Schema for the tool's arguments. */
+  readonly inputSchema: Record<string, unknown>;
+}
+
+/**
+ * A connection to a single MCP server. The stdio implementation spawns a child
+ * process; tests use an in-memory fake. Methods reject on protocol/transport
+ * failure — the registry decides how to degrade so a dead server never breaks
+ * the agent loop.
+ */
+export interface IMcpTransport {
+  /** Open the connection and perform the MCP `initialize` handshake. */
+  connect(): Promise<void>;
+
+  /** List the server's tools (`tools/list`). */
+  listTools(): Promise<IMcpToolInfo[]>;
+
+  /** Call a tool (`tools/call`) and return its result rendered as text. */
+  callTool(name: string, args: Record<string, unknown>): Promise<string>;
+
+  /** Shut the connection down. */
+  close(): Promise<void>;
+}
+
+/** Config for one MCP server, declared under `mcpServers` in tsforge.config.json. */
+export interface IMcpServerConfig {
+  /** Transport kind. `stdio` (default) spawns `command`; `http` POSTs to `url`. */
+  readonly type?: "stdio" | "http";
+  /** stdio: executable to spawn. */
+  readonly command?: string;
+  /** stdio: arguments for `command`. */
+  readonly args?: readonly string[];
+  /** stdio: extra environment variables (merged over the parent env). */
+  readonly env?: Readonly<Record<string, string>>;
+  /** http: server URL. */
+  readonly url?: string;
+  /** Per-call timeout in milliseconds (default 30000). */
+  readonly timeoutMs?: number;
+}

package/src/mcp/registry.ts

@@ -0,0 +1,91 @@
+import type { IMcpTransport } from "./mcp.types";
+import { mapMcpTool, mcpToolName, type IToolSchema } from "./schema-mapping";
+
+interface IRegisteredTool {
+  readonly server: string;
+  readonly toolName: string;
+  readonly transport: IMcpTransport;
+}
+
+/**
+ * Holds the live MCP connections and the tools they expose. Tools are advertised
+ * to the model under a namespaced `mcp__<server>__<tool>` name and dispatched back
+ * to the owning transport. Designed to fail soft: a tool call that throws is
+ * returned as text (the model sees a tool failure and adapts) rather than
+ * crashing the agent loop.
+ */
+export class McpRegistry {
+  private readonly schemas: IToolSchema[] = [];
+  private readonly byName = new Map<string, IRegisteredTool>();
+  private readonly transports: IMcpTransport[] = [];
+
+  /** Connect a server, list its tools, and register each under its namespaced
+   *  name. Returns the number of tools registered. May reject if the server
+   *  fails to connect or list — the caller catches per-server so one bad server
+   *  does not abort startup. */
+  async addServer(server: string, transport: IMcpTransport): Promise<number> {
+    await transport.connect();
+    this.transports.push(transport);
+
+    const tools = await transport.listTools();
+    let count = 0;
+
+    for (const tool of tools) {
+      const name = mcpToolName(server, tool.name);
+
+      if (this.byName.has(name)) {
+        continue;
+      }
+
+      this.byName.set(name, { server, toolName: tool.name, transport });
+      this.schemas.push(mapMcpTool(server, tool));
+      count += 1;
+    }
+
+    return count;
+  }
+
+  /** Tool schemas to append to the model's advertised tool list. */
+  toolSchemas(): IToolSchema[] {
+    return [...this.schemas];
+  }
+
+  /** Number of registered MCP tools. */
+  get size(): number {
+    return this.byName.size;
+  }
+
+  /** True if `name` is a registered MCP tool. */
+  has(name: string): boolean {
+    return this.byName.has(name);
+  }
+
+  /** Call a registered MCP tool. Never throws: a transport failure is returned
+   *  as text so the model treats it as a tool result. */
+  async callTool(name: string, args: Record<string, unknown>): Promise<string> {
+    const entry = this.byName.get(name);
+
+    if (entry === undefined) {
+      return `unknown MCP tool: ${name}`;
+    }
+
+    try {
+      return await entry.transport.callTool(entry.toolName, args);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+
+      return `MCP tool '${name}' failed: ${message}`;
+    }
+  }
+
+  /** Close every connected transport (best effort). */
+  async closeAll(): Promise<void> {
+    for (const transport of this.transports) {
+      try {
+        await transport.close();
+      } catch {
+        // best effort — a server that already died needs no clean shutdown
+      }
+    }
+  }
+}

package/src/mcp/schema-mapping.ts

@@ -0,0 +1,45 @@
+import type { IMcpToolInfo } from "./mcp.types";
+
+/** A tool schema in the OpenAI "function" wire shape the model is given. */
+export interface IToolSchema {
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+  };
+}
+
+/** OpenAI function names allow [a-zA-Z0-9_-]; replace anything else with "_". */
+function sanitize(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/** The namespaced name advertised to the model for an MCP tool. The double-underscore
+ *  separators mirror the conventional `mcp__<server>__<tool>` form. */
+export function mcpToolName(server: string, tool: string): string {
+  return `mcp__${sanitize(server)}__${sanitize(tool)}`;
+}
+
+/** A tool with no declared parameters still needs a valid object schema. */
+function paramsOrEmptyObject(
+  schema: Record<string, unknown>
+): Record<string, unknown> {
+  if (Object.keys(schema).length === 0) {
+    return { type: "object", properties: {} };
+  }
+
+  return schema;
+}
+
+/** Map one MCP tool to the OpenAI function schema the model is given. */
+export function mapMcpTool(server: string, tool: IMcpToolInfo): IToolSchema {
+  return {
+    type: "function",
+    function: {
+      name: mcpToolName(server, tool.name),
+      description: tool.description ?? `${server}: ${tool.name}`,
+      parameters: paramsOrEmptyObject(tool.inputSchema),
+    },
+  };
+}

package/src/mcp/setup.ts

@@ -0,0 +1,53 @@
+import type { IMcpServerConfig } from "./mcp.types";
+import { McpRegistry } from "./registry";
+import { StdioMcpTransport } from "./stdio-transport";
+
+/**
+ * Connect every configured MCP server and return a registry, or null if none are
+ * configured or none connected. Per-server failures are reported and skipped so
+ * a single bad server can never block the run. Only the stdio transport is wired
+ * today; http entries are reported and skipped.
+ */
+export async function connectMcpServers(
+  servers: Readonly<Record<string, IMcpServerConfig>>,
+  report: (message: string) => void
+): Promise<McpRegistry | null> {
+  const names = Object.keys(servers);
+
+  if (names.length === 0) {
+    return null;
+  }
+
+  const registry = new McpRegistry();
+
+  for (const name of names) {
+    const config = servers[name];
+
+    if (config === undefined) {
+      continue;
+    }
+
+    if (config.type === "http") {
+      report(
+        `MCP server '${name}': http transport not yet supported (stdio only)`
+      );
+
+      continue;
+    }
+
+    try {
+      const count = await registry.addServer(
+        name,
+        new StdioMcpTransport(name, config)
+      );
+
+      report(`MCP server '${name}': ${count} tool(s) registered`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+
+      report(`MCP server '${name}' failed to connect: ${message}`);
+    }
+  }
+
+  return registry.size > 0 ? registry : null;
+}

package/src/mcp/stdio-transport.ts

@@ -0,0 +1,209 @@
+import { isRecord } from "../lib/guards";
+import { LineDecoder, encodeMessage, errorText } from "./jsonrpc";
+import type {
+  IMcpServerConfig,
+  IMcpToolInfo,
+  IMcpTransport,
+} from "./mcp.types";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const DEFAULT_TIMEOUT_MS = 30000;
+
+interface IPending {
+  readonly resolve: (value: unknown) => void;
+  readonly reject: (err: Error) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+}
+
+/** Render an MCP `tools/list` result into typed tool info, dropping bad entries. */
+function extractTools(result: unknown): IMcpToolInfo[] {
+  if (!isRecord(result) || !Array.isArray(result.tools)) {
+    return [];
+  }
+
+  const tools: IMcpToolInfo[] = [];
+
+  for (const entry of result.tools) {
+    if (!isRecord(entry) || typeof entry.name !== "string") {
+      continue;
+    }
+
+    tools.push({
+      name: entry.name,
+      description:
+        typeof entry.description === "string" ? entry.description : undefined,
+      inputSchema: isRecord(entry.inputSchema) ? entry.inputSchema : {},
+    });
+  }
+
+  return tools;
+}
+
+/** Render an MCP `tools/call` result's content array into plain text. */
+function extractText(result: unknown): string {
+  if (!isRecord(result) || !Array.isArray(result.content)) {
+    return JSON.stringify(result);
+  }
+
+  const parts: string[] = [];
+
+  for (const item of result.content) {
+    if (isRecord(item) && typeof item.text === "string") {
+      parts.push(item.text);
+    }
+  }
+
+  return parts.length > 0 ? parts.join("\n") : JSON.stringify(result);
+}
+
+/**
+ * MCP transport over a child process's stdio, framed as newline-delimited
+ * JSON-RPC. Performs the `initialize` handshake on connect, multiplexes requests
+ * by id, and enforces a per-call timeout so a hung server cannot stall the loop.
+ */
+export class StdioMcpTransport implements IMcpTransport {
+  private proc: Bun.Subprocess<"pipe", "pipe", "inherit"> | null = null;
+  private readonly decoder = new LineDecoder();
+  private readonly pending = new Map<number, IPending>();
+  private readonly timeoutMs: number;
+  private nextId = 0;
+
+  constructor(
+    private readonly name: string,
+    private readonly config: IMcpServerConfig
+  ) {
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  async connect(): Promise<void> {
+    if (this.config.command === undefined) {
+      throw new Error(`MCP server '${this.name}' has no command`);
+    }
+
+    const proc = Bun.spawn({
+      cmd: [this.config.command, ...(this.config.args ?? [])],
+      env: { ...process.env, ...(this.config.env ?? {}) },
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "inherit",
+    });
+
+    this.proc = proc;
+    void this.readLoop(proc.stdout);
+
+    await this.request("initialize", {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "tsforge", version: "0" },
+    });
+    this.notify("notifications/initialized", {});
+  }
+
+  async listTools(): Promise<IMcpToolInfo[]> {
+    return extractTools(await this.request("tools/list", {}));
+  }
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<string> {
+    return extractText(
+      await this.request("tools/call", { name, arguments: args })
+    );
+  }
+
+  close(): Promise<void> {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("transport closed"));
+    }
+
+    this.pending.clear();
+    this.proc?.kill();
+    this.proc = null;
+
+    return Promise.resolve();
+  }
+
+  private async readLoop(stdout: ReadableStream<Uint8Array>): Promise<void> {
+    const reader = stdout.getReader();
+    const textDecoder = new TextDecoder();
+    let done = false;
+
+    while (!done) {
+      const result = await reader.read();
+
+      done = result.done;
+
+      if (result.value !== undefined) {
+        const text = textDecoder.decode(result.value, { stream: true });
+
+        for (const message of this.decoder.push(text)) {
+          this.handleMessage(message);
+        }
+      }
+    }
+  }
+
+  private handleMessage(message: unknown): void {
+    if (!isRecord(message) || typeof message.id !== "number") {
+      return;
+    }
+
+    const pending = this.pending.get(message.id);
+
+    if (pending === undefined) {
+      return;
+    }
+
+    clearTimeout(pending.timer);
+    this.pending.delete(message.id);
+
+    const err = errorText(message);
+
+    if (err !== null) {
+      pending.reject(new Error(err));
+
+      return;
+    }
+
+    pending.resolve(message.result);
+  }
+
+  private request(method: string, params: unknown): Promise<unknown> {
+    const proc = this.proc;
+
+    if (proc === null) {
+      return Promise.reject(new Error("transport not connected"));
+    }
+
+    const id = this.nextId;
+
+    this.nextId += 1;
+
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(
+          new Error(
+            `MCP request '${method}' timed out after ${this.timeoutMs}ms`
+          )
+        );
+      }, this.timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+      void proc.stdin.write(
+        encodeMessage({ jsonrpc: "2.0", id, method, params })
+      );
+      void proc.stdin.flush();
+    });
+  }
+
+  private notify(method: string, params: unknown): void {
+    const proc = this.proc;
+
+    if (proc === null) {
+      return;
+    }
+
+    void proc.stdin.write(encodeMessage({ jsonrpc: "2.0", method, params }));
+    void proc.stdin.flush();
+  }
+}

package/src/rule-packs/index.ts

@@ -9,6 +9,7 @@ import { envAccessPack } from "./env-access";
 import { i18nKeysPack } from "./i18n-keys";
 import { jwtCookiesPack } from "./jwt-cookies";
 import { moduleBoundariesPack } from "./module-boundaries";
+import { nextjsPack } from "./nextjs";
 import { oauthSecurityPack } from "./oauth-security";
 import { reactComponentArchitecturePack } from "./react-component-architecture";
 import { structuredLoggingPack } from "./structured-logging";
@@ -27,6 +28,7 @@ export const RULE_PACKS = {
   "i18n-keys": i18nKeysPack,
   "jwt-cookies": jwtCookiesPack,
   "module-boundaries": moduleBoundariesPack,
+  nextjs: nextjsPack,
   "oauth-security": oauthSecurityPack,
   "react-component-architecture": reactComponentArchitecturePack,
   "structured-logging": structuredLoggingPack,

package/src/rule-packs/nextjs/index.ts

@@ -0,0 +1,26 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+
+import { clientHooksRequireUseClientRule } from "./rules/client-hooks-require-use-client";
+import { noNextHeadInAppRule } from "./rules/no-next-head-in-app";
+import { noPagesRouterDataFetchingInAppRule } from "./rules/no-pages-router-data-fetching-in-app";
+import type { IRulePack } from "../rule-packs.types";
+
+const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "client-hooks-require-use-client": clientHooksRequireUseClientRule,
+  "no-next-head-in-app": noNextHeadInAppRule,
+  "no-pages-router-data-fetching-in-app": noPagesRouterDataFetchingInAppRule,
+};
+
+export const nextjsPack: IRulePack = {
+  id: "nextjs",
+  description:
+    "Next.js app-router correctness: server/client component boundaries and dead pages-router APIs.",
+  rules,
+  rulesConfig: {
+    "client-hooks-require-use-client": "error",
+    "no-next-head-in-app": "error",
+    "no-pages-router-data-fetching-in-app": "error",
+  },
+};
+
+export default nextjsPack;

package/src/rule-packs/nextjs/rules/client-hooks-require-use-client.ts

@@ -0,0 +1,74 @@
+import { createRule } from "../../create-rule";
+import {
+  calleeName,
+  hasDirective,
+  isAppRouterFile,
+  isRouteEntryFile,
+} from "../utils";
+
+export const RULE_NAME = "client-hooks-require-use-client";
+
+type MessageIds = "missingUseClient";
+
+/** Hooks that only work in Client Components — calling them in a Server
+ *  Component throws at runtime. */
+const CLIENT_HOOKS = new Set<string>([
+  "useState",
+  "useEffect",
+  "useLayoutEffect",
+  "useReducer",
+  "useImperativeHandle",
+  "useSyncExternalStore",
+  "useRouter",
+  "usePathname",
+  "useSearchParams",
+  "useParams",
+]);
+
+export const clientHooksRequireUseClientRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Require the 'use client' directive in app-router page/layout/template files that call client-only hooks. Server Components cannot use state/effect/navigation hooks — doing so crashes at runtime.",
+    },
+    schema: [],
+    messages: {
+      missingUseClient:
+        "'{{hook}}' is a client-only hook but this Server Component has no 'use client' directive. Add 'use client' at the top of the file or move the interactivity into a Client Component.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (
+      !isAppRouterFile(context.filename) ||
+      !isRouteEntryFile(context.filename)
+    ) {
+      return {};
+    }
+
+    let clientComponent = false;
+
+    return {
+      Program(node) {
+        clientComponent = hasDirective(node, "use client");
+      },
+      CallExpression(node) {
+        if (clientComponent) {
+          return;
+        }
+
+        const name = calleeName(node.callee);
+
+        if (name !== null && CLIENT_HOOKS.has(name)) {
+          context.report({
+            node,
+            messageId: "missingUseClient",
+            data: { hook: name },
+          });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/no-next-head-in-app.ts

@@ -0,0 +1,36 @@
+import { createRule } from "../../create-rule";
+import { isAppRouterFile } from "../utils";
+
+export const RULE_NAME = "no-next-head-in-app";
+
+type MessageIds = "nextHeadInApp";
+
+export const noNextHeadInAppRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow importing 'next/head' in app-router files. The <Head> component is a no-op under app/ — use the Metadata API (export const metadata / generateMetadata) instead.",
+    },
+    schema: [],
+    messages: {
+      nextHeadInApp:
+        "'next/head' does nothing in the app router. Use the Metadata API (export const metadata or generateMetadata) instead.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!isAppRouterFile(context.filename)) {
+      return {};
+    }
+
+    return {
+      ImportDeclaration(node) {
+        if (node.source.value === "next/head") {
+          context.report({ node: node.source, messageId: "nextHeadInApp" });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/rules/no-pages-router-data-fetching-in-app.ts

@@ -0,0 +1,71 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import { isAppRouterFile } from "../utils";
+
+export const RULE_NAME = "no-pages-router-data-fetching-in-app";
+
+type MessageIds = "pagesDataFnInApp";
+
+/** Pages-router data-fetching exports — inert (dead code) under the app router. */
+const PAGES_DATA_FNS = new Set<string>([
+  "getServerSideProps",
+  "getStaticProps",
+  "getStaticPaths",
+  "getInitialProps",
+]);
+
+export const noPagesRouterDataFetchingInAppRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow pages-router data-fetching exports (getServerSideProps, getStaticProps, getStaticPaths, getInitialProps) in app-router files. Next.js ignores them under app/, so they are silent dead code — use async Server Components or route handlers instead.",
+    },
+    schema: [],
+    messages: {
+      pagesDataFnInApp:
+        "'{{name}}' is a pages-router API and is ignored under app/. Fetch data inside an async Server Component or a route handler instead.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    if (!isAppRouterFile(context.filename)) {
+      return {};
+    }
+
+    function reportName(node: TSESTree.Node, name: string): void {
+      context.report({ node, messageId: "pagesDataFnInApp", data: { name } });
+    }
+
+    return {
+      ExportNamedDeclaration(node) {
+        const decl = node.declaration;
+
+        if (
+          decl?.type === "FunctionDeclaration" &&
+          decl.id !== null &&
+          PAGES_DATA_FNS.has(decl.id.name)
+        ) {
+          reportName(decl.id, decl.id.name);
+        } else if (decl?.type === "VariableDeclaration") {
+          for (const d of decl.declarations) {
+            if (d.id.type === "Identifier" && PAGES_DATA_FNS.has(d.id.name)) {
+              reportName(d.id, d.id.name);
+            }
+          }
+        }
+
+        for (const spec of node.specifiers) {
+          if (
+            spec.exported.type === "Identifier" &&
+            PAGES_DATA_FNS.has(spec.exported.name)
+          ) {
+            reportName(spec, spec.exported.name);
+          }
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/nextjs/utils.ts

@@ -0,0 +1,55 @@
+import type { TSESTree } from "@typescript-eslint/utils";
+
+/** True if the file lives under a Next.js app-router directory (an `app` segment). */
+export function isAppRouterFile(filename: string): boolean {
+  return filename.split(/[\\/]/).includes("app");
+}
+
+/** True if the file is an app-router route-entry file (page/layout/template),
+ *  which default to React Server Components. */
+export function isRouteEntryFile(filename: string): boolean {
+  const base = filename.split(/[\\/]/).pop() ?? "";
+
+  return /^(?:page|layout|template)\.(?:tsx|ts|jsx|js)$/.test(base);
+}
+
+/** True if the program's directive prologue contains `directive`
+ *  (e.g. "use client" / "use server"). */
+export function hasDirective(
+  program: TSESTree.Program,
+  directive: string
+): boolean {
+  for (const stmt of program.body) {
+    if (
+      stmt.type !== "ExpressionStatement" ||
+      stmt.expression.type !== "Literal" ||
+      typeof stmt.expression.value !== "string"
+    ) {
+      return false; // directive prologue has ended
+    }
+
+    if (stmt.expression.value === directive) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** Resolve a call's callee to a simple name: `useState` or `React.useState`
+ *  → "useState". Returns null for computed or complex callees. */
+export function calleeName(callee: TSESTree.Node): string | null {
+  if (callee.type === "Identifier") {
+    return callee.name;
+  }
+
+  if (
+    callee.type === "MemberExpression" &&
+    !callee.computed &&
+    callee.property.type === "Identifier"
+  ) {
+    return callee.property.name;
+  }
+
+  return null;
+}

package/src/stack-detection/packs.ts

@@ -61,6 +61,17 @@ export const PACK_REGISTRY = {
     guidance: "Follow Elysia patterns for HTTP routing and middleware.",
   } as const satisfies IRulePackDescriptor,
 
+  nextjs: {
+    id: "nextjs",
+    label: "Next.js",
+    description:
+      "App-router correctness: server/client boundaries and dead pages-router APIs",
+    category: "framework",
+    appliesWhen: { anyDeps: ["next"] },
+    guidance:
+      "Follow Next.js app-router conventions: mark interactive files 'use client' and use the Metadata API and Server Components instead of pages-router APIs.",
+  } as const satisfies IRulePackDescriptor,
+
   bullmq: {
     id: "bullmq",
     label: "BullMQ",