Add stdio entrypoint for local development

Enables running the MCP server locally via stdio transport for testing
with MCP clients without needing a full HTTP/Redis setup.

Also fixes import.meta.dirname compatibility issue with tsx by using
fileURLToPath(import.meta.url) instead.

Usage: npm run dev:stdio

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: jerome3o-anthropic

package.json

@@ -6,6 +6,7 @@
   "main": "dist/index.js",
   "scripts": {
     "dev": "tsx watch --inspect src/index.ts",
+    "dev:stdio": "tsx src/stdio.ts",
     "dev:internal": "AUTH_MODE=internal tsx watch --inspect src/index.ts",
     "dev:external": "concurrently \"AUTH_MODE=auth_server PORT=3001 BASE_URI=http://localhost:3001 tsx watch src/index.ts\" \"sleep 3 && AUTH_MODE=external AUTH_SERVER_URL=http://localhost:3001 tsx watch --inspect src/index.ts\"",
     "build": "tsc && npm run copy-static && npm run build:apps",

src/modules/mcp/services/mcp.ts

@@ -1,6 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   CallToolRequestSchema,
   CompleteRequestSchema,
@@ -293,7 +294,13 @@ export const createMcpServer = (): McpServerWrapper => {
 
     // MCP Apps UI resources
     if (uri === HELLO_WORLD_APP_URI) {
-      const distDir = path.join(import.meta.dirname, "../../../apps");
+      // Always resolve to dist/apps from project root, regardless of whether
+      // we're running from src/ (tsx dev) or dist/ (production)
+      const __dirname = path.dirname(fileURLToPath(import.meta.url));
+      const projectRoot = __dirname.includes("/dist/")
+        ? path.join(__dirname, "../../../..")
+        : path.join(__dirname, "../../..");
+      const distDir = path.join(projectRoot, "dist/apps");
       const html = await fs.readFile(path.join(distDir, "mcp-app.html"), "utf-8");
       return {
         contents: [

src/stdio.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Stdio entrypoint for the MCP example server.
+ * This allows running the server locally via stdio transport.
+ *
+ * Usage:
+ *   npx tsx src/stdio.ts
+ *   # or after building:
+ *   node dist/stdio.js
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./modules/mcp/services/mcp.js";
+
+async function main() {
+  const { server, cleanup } = createMcpServer();
+
+  const transport = new StdioServerTransport();
+
+  // Handle cleanup on exit
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});