tina4-nodejs 3.13.33 → 3.13.35

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.33)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.35)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -946,7 +946,7 @@ The `tina4` Rust CLI is the sole file watcher for the Tina4 stack — there is n
 
 No configuration needed — set `TINA4_DEBUG=true` to enable. If you're running without the Rust CLI (e.g. Docker), there is no automatic reload; the production path is unaffected.
 
-**AI dual-port mode:** when `TINA4_DEBUG=true` and `TINA4_NO_AI_PORT` is unset, the main port suppresses reload/toolbar injection (so AI tools never trigger a refresh) and a second server on `port+1000` provides the normal hot-reload experience for browser testing.
+**AI dual-port mode:** when `TINA4_DEBUG=true` and `TINA4_NO_AI_PORT` is unset, the **main port** provides the normal hot-reload experience (dev toolbar + `/__dev_reload` injected) for the human dev, and a second server on `port+1000` is the **stable AI port** — it suppresses reload/toolbar injection (and returns 404 for `/__dev_reload`) so an AI tool can drive it without its own edits triggering a refresh. The `tina4` client posts `/__dev/api/reload` to the **main port**. Matches Python (master), PHP, and Ruby.
 
 ## Conventions You Must Follow
 
@@ -1133,7 +1133,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **QueryBuilder** with NoSQL/MongoDB support (`toMongo()`)
 - **WebSocket backplane** (Redis pub/sub) for horizontal scaling
 - **SameSite=Lax** default on session cookies (`TINA4_SESSION_SAMESITE`)
-- **`tina4 init`** generates Dockerfile and .dockerignore
+- **`tina4 deploy docker`** generates Dockerfile and .dockerignore
 - **Gallery**: 7 interactive examples with Try It deploy at `/_dev/`
 - **SSE/Streaming**: `response.stream()` for Server-Sent Events — pass an async generator, framework handles chunked transfer encoding and keep-alive
 

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.33",
+  "version": "3.13.35",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/cli/src/commands/init.ts

@@ -63,11 +63,11 @@ export async function initProject(name: string): Promise<void> {
         private: true,
         type: "module",
         scripts: {
-          dev: "tina4 serve",
-          serve: "tina4 serve",
+          dev: "npx tina4nodejs serve",
+          serve: "npx tina4nodejs serve",
         },
         dependencies: {
-          "tina4-nodejs": "^0.0.1",
+          "tina4-nodejs": "^3.0.0",
         },
         devDependencies: {
           typescript: "^5.7.0",

package/packages/core/src/devAdmin.ts

@@ -19,6 +19,7 @@ import { DevMailbox } from "./devMailbox.js";
 import { isTruthy } from "./dotenv.js";
 import { quickMetrics, fullAnalysis, fileDetail } from "./metrics.js";
 import { registerFeedbackRoutes } from "./feedback.js";
+import { getDefaultDevServer } from "./mcp.js";
 
 const cpuCount = osCpus().length;
 
@@ -560,9 +561,18 @@ export class DevAdmin {
       { method: "POST", pattern: "/__dev/api/deps/install", handler: handleDepsInstall },
       // Git status
       { method: "GET", pattern: "/__dev/api/git/status", handler: handleGitStatus },
-      // MCP tool introspection over the built-in MCP server
+      // MCP tool introspection over the built-in MCP server (browser dev-admin REST shim)
       { method: "GET", pattern: "/__dev/api/mcp/tools", handler: handleMcpTools },
       { method: "POST", pattern: "/__dev/api/mcp/call", handler: handleMcpCall },
+      // MCP JSON-RPC + SSE endpoints that REAL MCP clients (Claude Code/Desktop)
+      // speak. POST /__dev/mcp[/message] -> JSON-RPC handleMessage; GET
+      // /__dev/mcp/sse -> SSE handshake announcing the message endpoint. Mounted
+      // through the same dispatch as the REST shim above and gated by the same
+      // /__dev public-route rule. Mirrors the Python v3 fix (POST /__dev/mcp +
+      // /__dev/mcp/message, GET /__dev/mcp/sse).
+      { method: "POST", pattern: "/__dev/mcp", handler: handleMcpMessage },
+      { method: "POST", pattern: "/__dev/mcp/message", handler: handleMcpMessage },
+      { method: "GET", pattern: "/__dev/mcp/sse", handler: handleMcpSse },
       // Scaffolding
       { method: "GET", pattern: "/__dev/api/scaffold", handler: handleScaffoldList },
       { method: "POST", pattern: "/__dev/api/scaffold/run", handler: handleScaffoldRun },
@@ -599,6 +609,13 @@ export class DevAdmin {
         handler: route.handler,
       });
     }
+
+    // Ensure the default /__dev/mcp MCP server exists with its dev tools
+    // registered. This is the single shared instance behind both the REST shim
+    // and the JSON-RPC + SSE endpoints registered above. Doing it here (gated by
+    // the same TINA4_DEBUG check that gates DevAdmin.register) means tools/list
+    // and the REST shim return tools immediately, before any first call.
+    getDefaultDevServer();
   }
 
   /**
@@ -1931,7 +1948,11 @@ const handleGitStatus: RouteHandler = async (_req, res) => {
 
 const handleMcpTools: RouteHandler = async (_req, res) => {
   try {
-    const { McpServer } = await import("./mcp.js");
+    // Ensure the default /__dev/mcp server exists with its dev tools registered,
+    // then enumerate every registered MCP server instance (app-defined servers
+    // register themselves on construction too).
+    const { McpServer, getDefaultDevServer } = await import("./mcp.js");
+    getDefaultDevServer();
     const instances = (McpServer as unknown as { _instances: Array<any> })._instances || [];
     const tools: Array<{ server: string; name: string; description: string; inputSchema: unknown }> = [];
     for (const s of instances) {
@@ -1950,7 +1971,8 @@ const handleMcpCall: RouteHandler = async (req, res) => {
   const name = (body.name as string) || "";
   const args = (body.arguments as Record<string, unknown>) || {};
   try {
-    const { McpServer } = await import("./mcp.js");
+    const { McpServer, getDefaultDevServer } = await import("./mcp.js");
+    getDefaultDevServer();
     const instances = (McpServer as unknown as { _instances: Array<any> })._instances || [];
     for (const s of instances) {
       const tool = ((s as any)._tools as Map<string, any>).get(name);
@@ -1966,6 +1988,59 @@ const handleMcpCall: RouteHandler = async (req, res) => {
   }
 };
 
+/**
+ * JSON-RPC message endpoint for real MCP clients.
+ *
+ * Mounted at POST /__dev/mcp and POST /__dev/mcp/message. Forwards the request
+ * body to the default dev MCP server's handleMessage() and returns the JSON-RPC
+ * response. Notifications / id-less requests yield an empty 204. Mirrors the
+ * Python v3 fix. The /__dev path is always public (auth-bypassed), so MCP
+ * clients connect without a token.
+ */
+const handleMcpMessage: RouteHandler = async (req, res) => {
+  try {
+    const { getDefaultDevServer } = await import("./mcp.js");
+    const server = getDefaultDevServer();
+    const body = req.body;
+    let raw: string | Record<string, unknown>;
+    if (typeof body === "object" && body !== null) {
+      raw = body as Record<string, unknown>;
+    } else {
+      raw = typeof body === "string" ? body : String(body ?? "");
+    }
+    const result = await server.handleMessage(raw);
+    if (!result) {
+      // Notification / no id — nothing to return.
+      res.send("", 204);
+      return;
+    }
+    res.json(JSON.parse(result));
+  } catch (e) {
+    res.json({ error: (e as Error).message }, 500);
+  }
+};
+
+/**
+ * SSE handshake endpoint for real MCP clients.
+ *
+ * Mounted at GET /__dev/mcp/sse. Announces the JSON-RPC message endpoint via an
+ * `endpoint` event, exactly like the canonical McpServer.registerRoutes() and
+ * the Python v3 fix. Content-Type text/event-stream, status 200.
+ */
+const handleMcpSse: RouteHandler = async (req, res) => {
+  // req.path is the path only (no query); turn /__dev/mcp/sse into the message
+  // endpoint /__dev/mcp/message that the client should POST to.
+  const reqPath = req.path || "/__dev/mcp/sse";
+  const endpointUrl = reqPath.replace(/\/sse$/, "/message");
+  const sseData = `event: endpoint\ndata: ${endpointUrl}\n\n`;
+  res.raw.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  });
+  res.raw.end(sseData);
+};
+
 const handleScaffoldList: RouteHandler = (_req, res) => {
   res.json({
     scaffolds: [

package/packages/core/src/index.ts

@@ -121,7 +121,7 @@ export type { WebSocketConnection } from "./websocketConnection.js";
 export { RedisBackplane, NATSBackplane, createBackplane } from "./websocketBackplane.js";
 export type { WebSocketBackplane } from "./websocketBackplane.js";
 export {
-  McpServer, mcpTool, mcpResource, registerDevTools,
+  McpServer, mcpTool, mcpResource, registerDevTools, getDefaultDevServer,
   encodeResponse, encodeError, encodeNotification, decodeRequest,
   schemaFromParams, isLocalhost, mcpEnabled, mcpPort,
   PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INVALID_PARAMS, INTERNAL_ERROR,

package/packages/core/src/mcp.test.ts

@@ -116,7 +116,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server", "0.1.0");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "initialize",
     params: {
       protocolVersion: "2024-11-05", capabilities: {},
@@ -131,7 +131,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 2, method: "ping", params: {},
   }));
   assert("ping — result empty", JSON.stringify(resp.result) === "{}");
@@ -140,7 +140,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 3, method: "nonexistent", params: {},
   }));
   assert("method not found — code", resp.error.code === -32601);
@@ -149,7 +149,7 @@ console.log("\nMcpServer Core");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-mcp", "Test Server");
-  const resp = server.handleMessage({
+  const resp = await server.handleMessage({
     jsonrpc: "2.0", method: "notifications/initialized",
   });
   assert("notification — empty response", resp === "");
@@ -169,7 +169,7 @@ console.log("\nTool Registration and Call");
     schemaFromParams([{ name: "name", type: "string" }]),
   );
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "tools/list", params: {},
   }));
   const tools = resp.result.tools;
@@ -189,7 +189,7 @@ console.log("\nTool Registration and Call");
     schemaFromParams([{ name: "a", type: "integer" }, { name: "b", type: "integer" }]),
   );
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 2, method: "tools/call",
     params: { name: "add", arguments: { a: 3, b: 5 } },
   }));
@@ -202,7 +202,7 @@ console.log("\nTool Registration and Call");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-tools", "Tool Test");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 3, method: "tools/call",
     params: { name: "missing", arguments: {} },
   }));
@@ -215,7 +215,7 @@ console.log("\nTool Registration and Call");
   server.registerTool("echo", (args) => args.msg as string, "Echo",
     schemaFromParams([{ name: "msg", type: "string" }]));
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 4, method: "tools/call",
     params: { name: "echo", arguments: { msg: "hello" } },
   }));
@@ -227,7 +227,7 @@ console.log("\nTool Registration and Call");
   const server = new McpServer("/test-tools", "Tool Test");
   server.registerTool("data", () => ({ a: 1, b: 2 }), "Return data");
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 5, method: "tools/call",
     params: { name: "data", arguments: {} },
   }));
@@ -262,7 +262,7 @@ console.log("\nResource Registration and Read");
   const server = new McpServer("/test-resources", "Resource Test");
   server.registerResource("app://tables", () => ["users", "products"], "Database tables");
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "resources/list", params: {},
   }));
   const resources = resp.result.resources;
@@ -275,7 +275,7 @@ console.log("\nResource Registration and Read");
   const server = new McpServer("/test-resources", "Resource Test");
   server.registerResource("app://info", () => ({ version: "1.0", name: "Test App" }), "App info");
 
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 2, method: "resources/read",
     params: { uri: "app://info" },
   }));
@@ -288,7 +288,7 @@ console.log("\nResource Registration and Read");
 {
   McpServer._instances = [];
   const server = new McpServer("/test-resources", "Resource Test");
-  const resp = JSON.parse(server.handleMessage({
+  const resp = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 3, method: "resources/read",
     params: { uri: "app://missing" },
   }));
@@ -335,7 +335,7 @@ console.log("\nFile Sandbox");
     const server = new McpServer("/test-sandbox", "Sandbox Test");
     registerDevTools(server);
 
-    const resp = JSON.parse(server.handleMessage({
+    const resp = JSON.parse(await server.handleMessage({
       jsonrpc: "2.0", id: 1, method: "tools/call",
       params: { name: "file_read", arguments: { path: "../../../etc/passwd" } },
     }));
@@ -361,7 +361,7 @@ console.log("\nFile Sandbox");
     const server = new McpServer("/test-sandbox2", "Sandbox Test 2");
     registerDevTools(server);
 
-    const resp = JSON.parse(server.handleMessage({
+    const resp = JSON.parse(await server.handleMessage({
       jsonrpc: "2.0", id: 1, method: "tools/call",
       params: { name: "file_write", arguments: { path: "../../evil.txt", content: "hacked" } },
     }));
@@ -401,11 +401,11 @@ console.log("\nDefensive Write Helpers");
  * For string returns the inner text is the raw string; for object returns
  * it is JSON-encoded — try to parse it back, fall through to the raw text.
  */
-function callTool(server: McpServer, name: string, args: Record<string, unknown>): {
+async function callTool(server: McpServer, name: string, args: Record<string, unknown>): Promise<{
   rpc: { jsonrpc?: string; id?: unknown; result?: unknown; error?: { code: number; message: string } };
   result: Record<string, unknown> | string | null;
-} {
-  const rpc = JSON.parse(server.handleMessage({
+}> {
+  const rpc = JSON.parse(await server.handleMessage({
     jsonrpc: "2.0", id: 1, method: "tools/call",
     params: { name, arguments: args },
   }));
@@ -431,7 +431,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-prose", "Prose Test");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "The plan requires implementing a new feature for users.ts",
       content: "x",
     });
@@ -455,7 +455,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-normalize", "Normalize Test");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "routes/foo.ts",
       content: "export default async function (req, res) {}\n",
     });
@@ -492,7 +492,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.writeFileSync(target, "original content\n", "utf-8");
 
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/foo.ts",
       content: "new content that is reasonably similar in length to the old one\n",
     });
@@ -531,7 +531,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     fs.writeFileSync(target, original, "utf-8");
 
     // Overwrite with 50 bytes — should be REFUSED (50/500 = 10% < 30%)
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/big.ts",
       content: "y".repeat(50),
     });
@@ -562,7 +562,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-passthrough", "Passthrough Test");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/foo.ts",
       content: "export default async function (req, res) {}\n",
     });
@@ -602,7 +602,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
   try {
     const server = new McpServer("/test-verify-js", "Verify JS");
     registerDevTools(server);
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/routes/broken.js",
       content: "const x = ;\n",
     });
@@ -635,7 +635,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     const server = new McpServer("/test-verify-skip-ext", "Verify Skip Ext");
     registerDevTools(server);
     // .twig content that would obviously fail any JS parser
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "src/templates/page.twig",
       content: "{% if not valid js %}<h1>Hi</h1>{% endif %}\n",
     });
@@ -668,7 +668,7 @@ function callTool(server: McpServer, name: string, args: Record<string, unknown>
     const server = new McpServer("/test-verify-skip-outside", "Verify Skip Outside");
     registerDevTools(server);
     // Broken JS placed under tests/ — must NOT be checked
-    const { result } = callTool(server, "file_write", {
+    const { result } = await callTool(server, "file_write", {
       path: "tests/foo.js",
       content: "const x = ;\n",
     });

package/packages/core/src/mcp.ts

@@ -18,6 +18,32 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+// Synchronous CommonJS-style require that works under real ESM (where the
+// bare `require` global is undefined). Dev-tool handlers are synchronous, so
+// they can't `await import()` — this gives them a working require. Mirrors the
+// pattern already used by the ORM adapters (mysql.ts, postgres.ts, etc.).
+const req = createRequire(import.meta.url);
+
+/**
+ * Require a sibling @tina4 workspace package (orm / swagger / frond) in a way
+ * that works whether we're running from source (monorepo, where the package's
+ * `exports` only exposes the TS `import` condition that `require()` can't see)
+ * or as an installed dependency (where the package name resolves directly).
+ *
+ * Tries the package name first; on failure falls back to the in-repo source
+ * path relative to this file (packages/core/src → packages/<name>/src). This
+ * is why `route_list`, `database_query`, `swagger_spec`, etc. work when a real
+ * MCP client hits /__dev/mcp from a from-source dev server.
+ */
+function reqSibling(pkg: "orm" | "swagger" | "frond"): Record<string, unknown> {
+  try {
+    return req(`@tina4/${pkg}`) as Record<string, unknown>;
+  } catch {
+    return req(`../../${pkg}/src/index.ts`) as Record<string, unknown>;
+  }
+}
 
 // ── Types ─────────────────────────────────────────────────────
 
@@ -34,7 +60,11 @@ export interface McpToolDefinition {
   name: string;
   description: string;
   inputSchema: JsonSchema;
-  handler: (args: Record<string, unknown>) => unknown;
+  // Handlers may be sync or async — the dispatch (`_handleToolsCall`) awaits the
+  // return value, so DB tools that hit the async Database wrapper resolve before
+  // the result is formatted. A sync handler's plain return passes through awaiting
+  // unchanged.
+  handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
 }
 
 export interface McpResourceDefinition {
@@ -251,7 +281,13 @@ export class McpServer {
     });
   }
 
-  handleMessage(rawData: string | Record<string, unknown>): string {
+  // Async since the DB dev-tool handlers (database_query/execute/tables/columns,
+  // migration_*, seed_table, project_overview) reach the Database wrapper on
+  // `globalThis.__tina4_db`, whose read/write methods are async. The handler is
+  // awaited below; sync handlers (the file/plan/route tools) are unaffected
+  // because awaiting a non-Promise resolves immediately. Returns a
+  // Promise<string> — every caller must await it.
+  async handleMessage(rawData: string | Record<string, unknown>): Promise<string> {
     let method: string;
     let params: Record<string, unknown>;
     let requestId: number | string | null;
@@ -278,7 +314,7 @@ export class McpServer {
     }
 
     try {
-      const result = handler(params);
+      const result = await handler(params);
       if (requestId === null) {
         return ""; // Notification — no response
       }
@@ -323,7 +359,7 @@ export class McpServer {
     return { tools };
   }
 
-  private _handleToolsCall(params: Record<string, unknown>): Record<string, unknown> {
+  private async _handleToolsCall(params: Record<string, unknown>): Promise<Record<string, unknown>> {
     const toolName = params.name as string | undefined;
     if (!toolName) {
       throw new Error("Missing tool name");
@@ -335,7 +371,9 @@ export class McpServer {
     }
 
     const args = (params.arguments as Record<string, unknown>) || {};
-    const result = tool.handler(args);
+    // Tool handlers may be async (the DB tools await the Database wrapper); a
+    // sync handler's plain return value passes through `await` unchanged.
+    const result = await tool.handler(args);
 
     // Format result as MCP content
     let content: { type: string; text: string }[];
@@ -412,7 +450,7 @@ export class McpServer {
     const ssePath = `${this.path}/sse`;
 
     router
-      .post(msgPath, (req: unknown, res: unknown) => {
+      .post(msgPath, async (req: unknown, res: unknown) => {
         const request = req as { body: unknown; url?: string };
         const response = res as ((data: unknown, status?: number, contentType?: string) => unknown);
         const body = request.body;
@@ -422,7 +460,7 @@ export class McpServer {
         } else {
           raw = typeof body === "string" ? body : String(body);
         }
-        const result = server.handleMessage(raw);
+        const result = await server.handleMessage(raw);
         if (!result) {
           return response("", 204);
         }
@@ -484,6 +522,7 @@ export class McpServer {
 // ── Decorator API ──────────────────────────────────────────────
 
 let _defaultServer: McpServer | null = null;
+let _defaultToolsRegistered = false;
 
 function _getDefaultServer(): McpServer {
   if (_defaultServer === null) {
@@ -492,6 +531,24 @@ function _getDefaultServer(): McpServer {
   return _defaultServer;
 }
 
+/**
+ * The default `/__dev/mcp` MCP server with the built-in dev tools registered.
+ *
+ * This is the single shared instance backing BOTH the browser REST shim
+ * (`/__dev/api/mcp/tools` + `/__dev/api/mcp/call`) and the JSON-RPC + SSE
+ * endpoints (`/__dev/mcp[/message]` + `/__dev/mcp/sse`) that real MCP clients
+ * (Claude Code/Desktop) speak. Tools are registered exactly once (idempotent).
+ * Mirrors Python's default MCP server used by `get_api_handlers()`.
+ */
+export function getDefaultDevServer(): McpServer {
+  const server = _getDefaultServer();
+  if (!_defaultToolsRegistered) {
+    registerDevTools(server);
+    _defaultToolsRegistered = true;
+  }
+  return server;
+}
+
 /**
  * Register a function as an MCP tool.
  *
@@ -787,13 +844,12 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_query",
-    (args) => {
+    async (args) => {
       try {
-        const { initDatabase } = require("@tina4/orm");
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
         const params = typeof args.params === "string" ? JSON.parse(args.params as string) : (args.params || []);
-        const result = db.fetch(args.sql as string, params);
+        const result = await db.fetch(args.sql as string, params);
         return { records: result.records || [], count: result.count || 0 };
       } catch (e) {
         return { error: (e as Error).message };
@@ -808,14 +864,14 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_execute",
-    (args) => {
+    async (args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
         const params = typeof args.params === "string" ? JSON.parse(args.params as string) : (args.params || []);
-        const result = db.execute(args.sql as string, params);
-        db.commit?.();
-        return { success: true, affected_rows: result?.count ?? 0 };
+        const result = await db.execute(args.sql as string, params);
+        await db.commit?.();
+        return { success: true, affected_rows: (result as any)?.count ?? 0 };
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -829,11 +885,11 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_tables",
-    (_args) => {
+    async (_args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return db.getTables?.() ?? [];
+        return (await db.getTables?.()) ?? [];
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -844,11 +900,11 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "database_columns",
-    (args) => {
+    async (args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return db.getColumns?.(args.table as string) ?? [];
+        return (await db.getColumns?.(args.table as string)) ?? [];
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -863,8 +919,16 @@ export function registerDevTools(server: McpServer): void {
     "route_list",
     (_args) => {
       try {
-        const { defaultRouter } = require("@tina4/core");
-        const routes = defaultRouter?.listRoutes?.() ?? [];
+        // Prefer the active server router (set by startServer) so file-discovered
+        // routes are included; startServer builds a fresh Router rather than using
+        // defaultRouter. Fall back to defaultRouter when no server is running.
+        // route_list lives inside @tina4/core, so reach the router via the local
+        // module — req("@tina4/core") depends on a built dist/ and fails under a
+        // from-source ESM runtime (the real MCP-client code path).
+        const { defaultRouter } = req("./router.js") as typeof import("./router.js");
+        const activeRouter = (globalThis as any).__tina4_router;
+        const router = activeRouter ?? defaultRouter;
+        const routes = router?.listRoutes?.() ?? [];
         return routes.map((r: any) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
@@ -901,10 +965,12 @@ export function registerDevTools(server: McpServer): void {
     "swagger_spec",
     (_args) => {
       try {
-        const { generateSpec } = require("@tina4/swagger");
-        return generateSpec?.() ?? { info: "Swagger not available" };
-      } catch {
-        return { info: "Swagger package not loaded" };
+        const { generate } = reqSibling("swagger") as { generate?: (routes: unknown[], models?: unknown) => unknown };
+        const { defaultRouter } = req("./router.js") as typeof import("./router.js");
+        const routes = defaultRouter?.getRoutes?.() ?? [];
+        return generate?.(routes, []) ?? { info: "Swagger not available" };
+      } catch (e) {
+        return { error: (e as Error).message };
       }
     },
     "Return the OpenAPI 3.0.3 JSON spec",
@@ -917,9 +983,11 @@ export function registerDevTools(server: McpServer): void {
     "template_render",
     (args) => {
       try {
-        const { renderTemplate } = require("@tina4/twig");
+        const { Frond } = reqSibling("frond") as { Frond?: new (dir?: string) => { renderString: (s: string, d?: Record<string, unknown>) => string } };
+        if (!Frond) return "Template engine not available";
         const data = typeof args.data === "string" ? JSON.parse(args.data as string) : (args.data || {});
-        return renderTemplate?.(args.template as string, data) ?? "Template engine not available";
+        const frond = new Frond(path.join(projectRoot, "src", "templates"));
+        return frond.renderString(args.template as string, data as Record<string, unknown>);
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -1066,7 +1134,7 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "migration_status",
-    (_args) => {
+    async (_args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
@@ -1099,7 +1167,7 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "migration_run",
-    (_args) => {
+    async (_args) => {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
@@ -1118,7 +1186,7 @@ export function registerDevTools(server: McpServer): void {
     "queue_status",
     (args) => {
       try {
-        const { Queue } = require("@tina4/core");
+        const { Queue } = req("./queue.js") as typeof import("./queue.js");
         const topic = (args.topic as string) || "default";
         const q = new Queue({ topic });
         return {
@@ -1166,7 +1234,7 @@ export function registerDevTools(server: McpServer): void {
       // latest snapshot once available. The very first call may report the
       // pending placeholder; subsequent calls return live figures.
       try {
-        const mod = require("@tina4/core");
+        const mod = req("./cache.js") as typeof import("./cache.js");
         const stats = mod.cacheStats?.();
         if (stats && typeof stats.then === "function") {
           stats.then((s: unknown) => { _lastCacheStats = s as Record<string, unknown>; }).catch(() => {});
@@ -1222,12 +1290,9 @@ export function registerDevTools(server: McpServer): void {
     "error_log",
     (args) => {
       try {
-        const { DevAdmin } = require("@tina4/core");
-        const tracker = DevAdmin?.errorTracker;
-        if (tracker?.get) {
-          return tracker.get(args.limit || 20);
-        }
-        return [];
+        const { ErrorTracker } = req("./devAdmin.js") as typeof import("./devAdmin.js");
+        const limit = (args.limit as number) || 20;
+        return ErrorTracker.get().slice(0, limit);
       } catch {
         return [];
       }
@@ -1256,13 +1321,13 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "seed_table",
-    (args) => {
+    async (args) => {
       try {
-        const { seedTable } = require("@tina4/orm");
+        const { seedTable } = reqSibling("orm") as { seedTable?: (db: unknown, table: string, count: number) => number | Promise<number> };
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
         const count = (args.count as number) || 10;
-        const inserted = seedTable?.(db, args.table as string, count) ?? 0;
+        const inserted = (await seedTable?.(db, args.table as string, count)) ?? 0;
         return { table: args.table, inserted };
       } catch (e) {
         return { error: (e as Error).message };
@@ -1305,9 +1370,9 @@ export function registerDevTools(server: McpServer): void {
   // Ported from Python's tina4_python.mcp.tools — names match exactly.
   // The Plan storage format is byte-for-byte compatible across frameworks.
 
-  const loadPlan = () => require("./plan.js").Plan as typeof import("./plan.js").Plan;
+  const loadPlan = () => req("./plan.js").Plan as typeof import("./plan.js").Plan;
   const loadIndex = () =>
-    require("./projectIndex.js").ProjectIndex as typeof import("./projectIndex.js").ProjectIndex;
+    req("./projectIndex.js").ProjectIndex as typeof import("./projectIndex.js").ProjectIndex;
 
   server.registerTool(
     "plan_current",
@@ -1429,14 +1494,14 @@ export function registerDevTools(server: McpServer): void {
 
   server.registerTool(
     "project_overview",
-    () => {
+    async () => {
       const out: Record<string, unknown> = {};
       try { out.index = loadIndex().overview(); } catch (e) { out.index = { error: (e as Error).message }; }
       try { out.plans = loadPlan().listPlans(); } catch (e) { out.plans = { error: (e as Error).message }; }
       try { out.current_plan = loadPlan().current(); } catch (e) { out.current_plan = { error: (e as Error).message }; }
       try {
         const db = (globalThis as any).__tina4_db;
-        out.tables = db?.getTables?.() ?? [];
+        out.tables = (await db?.getTables?.()) ?? [];
       } catch (e) { out.tables = { error: (e as Error).message }; }
       return out;
     },
@@ -1633,7 +1698,7 @@ export function registerDevTools(server: McpServer): void {
     "git_status",
     () => {
       try {
-        const { execFileSync } = require("node:child_process") as typeof import("node:child_process");
+        const { execFileSync } = req("node:child_process") as typeof import("node:child_process");
         const cwd = path.resolve(process.cwd());
         const run = (args: string[]): string => {
           return execFileSync("git", args, { cwd, timeout: 3000, encoding: "utf-8" }).toString().trim();
@@ -1685,7 +1750,7 @@ export function registerDevTools(server: McpServer): void {
     (args) => {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        const { Docs } = req("./docs.js") as typeof import("./docs.js");
         return Docs.mcpSearch(
           (args.query as string) || "",
           parseInt(String(args.k ?? 5), 10) || 5,
@@ -1711,7 +1776,7 @@ export function registerDevTools(server: McpServer): void {
     (args) => {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        const { Docs } = req("./docs.js") as typeof import("./docs.js");
         const spec = Docs.mcpClass((args.name as string) || "");
         return spec ?? { error: `class not found: ${args.name}` };
       } catch (e) {
@@ -1727,7 +1792,7 @@ export function registerDevTools(server: McpServer): void {
     (args) => {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Docs } = require("./docs.js") as typeof import("./docs.js");
+        const { Docs } = req("./docs.js") as typeof import("./docs.js");
         // PHP names the param `class`, Python names it `class_` — Node.js MCP
         // accepts the raw `class` field from the JSON-RPC payload.
         const cls = (args.class as string) || (args.class_name as string) || "";

package/packages/core/src/server.ts

@@ -756,6 +756,13 @@ ${reset}
   const router = new Router();
   const middleware = new MiddlewareChain();
 
+  // Expose the active server router globally so dev tools (e.g. the MCP
+  // route_list tool) can introspect the real, fully-populated route table —
+  // startServer builds a fresh Router rather than using defaultRouter, so
+  // file-discovered routes only live here. Mirrors the globalThis.__tina4_db
+  // hook other dev tools read.
+  (globalThis as any).__tina4_router = router;
+
   // Merge routes registered via top-level get(), post(), etc.
   for (const route of defaultRouter.getRoutes()) {
     router.addRoute(route);
@@ -1379,17 +1386,11 @@ ${reset}
   // Assign to module-level so handle() can dispatch without a server reference
   _dispatchFn = dispatch;
 
-  // When dual-port is active (debug mode + no TINA4_NO_AI_PORT), tag main port requests
-  // as AI port to suppress reload/toolbar injection. Test port (port+1000) gets full reload.
-  const _dualPortActive = isTruthy(process.env.TINA4_DEBUG ?? "") &&
-    !isTruthy(process.env.TINA4_NO_AI_PORT ?? "");
-  const mainPortDispatch = _dualPortActive
-    ? async (req: IncomingMessage, res: ServerResponse) => {
-        (req as any)._tina4AiPort = true;
-        await dispatch(req, res);
-      }
-    : dispatch;
-  const server = createServer(mainPortDispatch);
+  // Dual-port (debug + no TINA4_NO_AI_PORT): the MAIN port hot-reloads for the human
+  // dev; the stable AI port (port+1000, created below) suppresses reload/toolbar so an
+  // AI tool can drive it without its own edits triggering refreshes. The tina4 client
+  // posts /__dev/api/reload to the MAIN port. Matches Python (master).
+  const server = createServer(dispatch);
 
   return new Promise((resolvePromise) => {
     server.listen(port, host, () => {
@@ -1405,16 +1406,17 @@ ${reset}
       // Determine server mode label
       const serverMode = isDebug ? "single" : (cluster.isWorker ? "cluster-worker" : "single");
 
-      // AI dual-port: main port = AI dev port (no reload), port+1000 = user testing port (hot-reload)
-      // When TINA4_DEBUG=true and TINA4_NO_AI_PORT is not set, main server suppresses reload/toolbar
-      // and a second server on port+1000 provides the normal hot-reload experience.
+      // AI dual-port: main port = hot-reload (human dev); port+1000 = stable AI port
+      // (reload/toolbar suppressed) so an AI tool can drive it without its edits
+      // triggering refreshes. The tina4 client fires reloads at the MAIN port. Matches Python.
       const noAiPort = isTruthy(process.env.TINA4_NO_AI_PORT ?? "");
       let aiServer: ReturnType<typeof createServer> | null = null;
       let testPort = port + 1000;
 
       if (isDebug && !noAiPort) {
-        // Test port (port+1000): normal dispatch with full hot-reload
+        // Stable AI port (port+1000): tag requests so /__dev_reload + toolbar are suppressed.
         aiServer = createServer(async (req, res) => {
+          (req as any)._tina4AiPort = true;
           await dispatch(req, res);
         });
 
@@ -1451,11 +1453,8 @@ ${reset}
       }
       const noBrowser = isTruthy(process.env.TINA4_NO_BROWSER);
       if (!noBrowser) {
-        // Open browser on test port (hot-reload) if available, otherwise main port
-        const browserTarget = (isDebug && !noAiPort && aiServer)
-          ? `http://${displayHost}:${testPort}`
-          : `http://${displayHost}:${port}`;
-        openBrowser(browserTarget);
+        // Open the browser on the MAIN port — that's the hot-reload port.
+        openBrowser(`http://${displayHost}:${port}`);
       }
       resolvePromise({
         close: () => {

package/packages/orm/src/database.ts

@@ -161,6 +161,21 @@ export function setAdapter(adapter: DatabaseAdapter): DatabaseAdapter {
   return activeAdapter;
 }
 
+/**
+ * Publish the live Database wrapper on `globalThis.__tina4_db` so framework
+ * tooling that runs outside the request/ORM path can reach it. The built-in
+ * MCP dev-tool handlers (database_query/execute/tables/columns, migration_*,
+ * seed_table, project_overview in `@tina4/core`'s mcp.ts) read this global; it
+ * is the single chokepoint every `initDatabase()` / `Database.create()` return
+ * path flows through, so the global is always set once a connection exists.
+ *
+ * Returns the same instance so it composes cleanly around a `return`.
+ */
+function exposeDb(db: Database): Database {
+  (globalThis as any).__tina4_db = db;
+  return db;
+}
+
 /**
  * Clear the request-scoped query cache on every live connection at the start of
  * each HTTP request, so request-scoped caching never serves rows across
@@ -535,7 +550,7 @@ export class Database {
       db.adapter = null;  // Don't use single-adapter path
       db.adapterFactory = async () => wrapWithCache(await createAdapterFromUrl(url, username, password), { sharedCache });
       db.dbType = parsed.type;
-      return db;
+      return exposeDb(db);
     }
 
     // Single-connection mode — wrap once and share the SAME wrapped adapter
@@ -545,7 +560,7 @@ export class Database {
     const wrapped = setAdapter(adapter);
     const db = new Database(wrapped);
     db.dbType = parsed.type;
-    return db;
+    return exposeDb(db);
   }
 
   /**
@@ -1217,10 +1232,11 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
     if (pool > 0) {
       // Pool-aware path — delegate to Database.create which manages
       // round-robin adapter rotation and async-local-storage transaction pinning.
-      return Database.create(url, resolvedUser, resolvedPassword, pool);
+      // Database.create already exposes the global; exposeDb here is idempotent.
+      return exposeDb(await Database.create(url, resolvedUser, resolvedPassword, pool));
     }
     const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);
-    return new Database(setAdapter(adapter));
+    return exposeDb(new Database(setAdapter(adapter)));
   }
 
   // Legacy config path — normalize "sqlserver" to "mssql"
@@ -1245,7 +1261,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
     case "sqlite": {
       const { SQLiteAdapter } = await import("./adapters/sqlite.js");
       const adapter = new SQLiteAdapter(config?.path ?? "./data/tina4.db");
-      return new Database(setAdapter(adapter));
+      return exposeDb(new Database(setAdapter(adapter)));
     }
     case "postgres": {
       const { PostgresAdapter } = await import("./adapters/postgres.js");
@@ -1257,7 +1273,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return new Database(setAdapter(adapter));
+      return exposeDb(new Database(setAdapter(adapter)));
     }
     case "mysql": {
       const { MysqlAdapter } = await import("./adapters/mysql.js");
@@ -1269,7 +1285,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return new Database(setAdapter(adapter));
+      return exposeDb(new Database(setAdapter(adapter)));
     }
     case "mssql": {
       const { MssqlAdapter } = await import("./adapters/mssql.js");
@@ -1281,7 +1297,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return new Database(setAdapter(adapter));
+      return exposeDb(new Database(setAdapter(adapter)));
     }
     case "firebird": {
       const { FirebirdAdapter } = await import("./adapters/firebird.js");
@@ -1293,7 +1309,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      return new Database(setAdapter(adapter));
+      return exposeDb(new Database(setAdapter(adapter)));
     }
     case "mongodb": {
       const { MongodbAdapter } = await import("./adapters/mongodb.js");
@@ -1306,14 +1322,14 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
       const connectionString = `mongodb://${creds}${host}:${port}/${database}`;
       const adapter = new MongodbAdapter(connectionString);
       await adapter.connect();
-      return new Database(setAdapter(adapter));
+      return exposeDb(new Database(setAdapter(adapter)));
     }
     case "odbc": {
       const { OdbcAdapter } = await import("./adapters/odbc.js");
       const connStr = config?.connectionString ?? config?.url?.replace(/^odbc:\/\/\//, "") ?? "";
       const adapter = new OdbcAdapter({ connectionString: connStr });
       await adapter.connect();
-      return new Database(setAdapter(adapter));
+      return exposeDb(new Database(setAdapter(adapter)));
     }
     default:
       throw new Error(`Unknown database type: ${type}`);