@studiometa/forge-mcp 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Forge MCP Server — Stdio Transport
+ *
+ * This is the local execution mode using stdio transport.
+ * For remote HTTP deployment, use server.ts instead.
+ *
+ * Usage:
+ *   npx @studiometa/forge-mcp
+ *   npx @studiometa/forge-mcp --read-only
+ *   FORGE_READ_ONLY=true npx @studiometa/forge-mcp
+ *
+ * Or in Claude Desktop config:
+ *   {
+ *     "mcpServers": {
+ *       "forge": {
+ *         "command": "forge-mcp",
+ *         "args": ["--read-only"],
+ *         "env": { "FORGE_API_TOKEN": "your-token" }
+ *       }
+ *     }
+ *   }
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+/**
+ * Options for the stdio MCP server.
+ */
+export interface StdioServerOptions {
+    /** When true, forge_write tool is not registered and write operations are rejected. */
+    readOnly?: boolean;
+}
+/**
+ * Parse read-only flag from process.argv and environment.
+ */
+export declare function parseReadOnlyFlag(): boolean;
+/**
+ * Create and configure the MCP server.
+ */
+export declare function createStdioServer(options?: StdioServerOptions): Server;
+/**
+ * Start the stdio server.
+ */
+export declare function startStdioServer(options?: StdioServerOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAuCtE;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMlF"}

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import "./version-DaD5zvGh.js";
+import { n as parseReadOnlyFlag, r as startStdioServer, t as createStdioServer } from "./src-BdwavqrN.js";
+export { createStdioServer, parseReadOnlyFlag, startStdioServer };

package/dist/instructions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Server Instructions
+ *
+ * These instructions are sent to MCP clients during initialization
+ * and used as context/hints for the LLM. Ensures the AI agent
+ * knows how to properly use the Forge MCP server.
+ *
+ * The content is derived from skills/SKILL.md (without YAML frontmatter).
+ */
+export declare const INSTRUCTIONS: string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2BH,eAAO,MAAM,YAAY,QAAqB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Forge MCP Server - HTTP Transport (Streamable HTTP)
+ *
+ * Implements the official MCP Streamable HTTP transport specification.
+ * Credentials are passed via Bearer token in the Authorization header.
+ *
+ * Token format: raw Forge API token
+ *
+ * Usage:
+ *   forge-mcp-server
+ *   forge-mcp-server --read-only
+ *   FORGE_READ_ONLY=true forge-mcp-server
+ *   PORT=3000 forge-mcp-server
+ *
+ * Endpoints:
+ *   POST /mcp   - MCP Streamable HTTP (JSON-RPC messages)
+ *   GET  /mcp   - MCP Streamable HTTP (SSE stream for server notifications)
+ *   DELETE /mcp - MCP Streamable HTTP (session termination)
+ *   GET  /       - Service info
+ *   GET  /health - Health check
+ */
+import { type Server } from "node:http";
+/**
+ * Options for the HTTP server.
+ */
+export interface HttpStartOptions {
+    /** When true, forge_write tool is not registered. */
+    readOnly?: boolean;
+}
+/**
+ * Start the HTTP server with Streamable HTTP transport.
+ */
+export declare function startHttpServer(port?: number, host?: string, options?: HttpStartOptions): Promise<Server>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAUtD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,GAAE,MAAqB,EAC3B,IAAI,GAAE,MAAqB,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC,CA8CjB"}

package/dist/server.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { t as VERSION } from "./version-DaD5zvGh.js";
+import { n as parseReadOnlyFlag } from "./src-BdwavqrN.js";
+import { a as SessionManager, n as createMcpRequestHandler, t as createHealthApp } from "./http-CfjqK_e4.js";
+import { toNodeHandler } from "h3/node";
+import { createServer } from "node:http";
+/**
+* Forge MCP Server - HTTP Transport (Streamable HTTP)
+*
+* Implements the official MCP Streamable HTTP transport specification.
+* Credentials are passed via Bearer token in the Authorization header.
+*
+* Token format: raw Forge API token
+*
+* Usage:
+*   forge-mcp-server
+*   forge-mcp-server --read-only
+*   FORGE_READ_ONLY=true forge-mcp-server
+*   PORT=3000 forge-mcp-server
+*
+* Endpoints:
+*   POST /mcp   - MCP Streamable HTTP (JSON-RPC messages)
+*   GET  /mcp   - MCP Streamable HTTP (SSE stream for server notifications)
+*   DELETE /mcp - MCP Streamable HTTP (session termination)
+*   GET  /       - Service info
+*   GET  /health - Health check
+*/
+var DEFAULT_PORT = 3e3;
+var DEFAULT_HOST = "0.0.0.0";
+/**
+* Start the HTTP server with Streamable HTTP transport.
+*/
+function startHttpServer(port = DEFAULT_PORT, host = DEFAULT_HOST, options) {
+	return new Promise((resolve) => {
+		const readOnly = options?.readOnly ?? false;
+		const handleMcp = createMcpRequestHandler(new SessionManager(), { readOnly });
+		const healthHandler = toNodeHandler(createHealthApp());
+		const server = createServer(async (req, res) => {
+			const url = req.url ?? "/";
+			if (url === "/mcp" || url.startsWith("/mcp?")) {
+				await handleMcp(req, res);
+				return;
+			}
+			healthHandler(req, res);
+		});
+		server.listen(port, host, () => {
+			const displayHost = host === "0.0.0.0" ? "localhost" : host;
+			const mode = readOnly ? " (read-only)" : "";
+			console.log(`Forge MCP server v${VERSION}${mode}`);
+			console.log(`Node.js ${process.version}`);
+			console.log("");
+			console.log(`Running at http://${displayHost}:${port}`);
+			console.log("");
+			console.log("Endpoints:");
+			console.log(`  POST/GET/DELETE http://${displayHost}:${port}/mcp - MCP Streamable HTTP endpoint`);
+			console.log(`  GET  http://${displayHost}:${port}/health - Health check`);
+			console.log("");
+			console.log("Authentication:");
+			console.log("  Bearer token in Authorization header");
+			console.log("  Token format: your raw Forge API token");
+			if (readOnly) {
+				console.log("");
+				console.log("Mode: READ-ONLY (write operations disabled)");
+			}
+			console.log("");
+			resolve(server);
+		});
+	});
+}
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/forge-mcp-server") || process.argv[1]?.endsWith("\\forge-mcp-server")) startHttpServer(Number.parseInt(process.env.PORT || String(DEFAULT_PORT), 10), process.env.HOST || DEFAULT_HOST, { readOnly: parseReadOnlyFlag() }).catch((error) => {
+	console.error("Fatal error:", error);
+	process.exit(1);
+});
+export { startHttpServer };
+
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * Forge MCP Server - HTTP Transport (Streamable HTTP)\n *\n * Implements the official MCP Streamable HTTP transport specification.\n * Credentials are passed via Bearer token in the Authorization header.\n *\n * Token format: raw Forge API token\n *\n * Usage:\n *   forge-mcp-server\n *   forge-mcp-server --read-only\n *   FORGE_READ_ONLY=true forge-mcp-server\n *   PORT=3000 forge-mcp-server\n *\n * Endpoints:\n *   POST /mcp   - MCP Streamable HTTP (JSON-RPC messages)\n *   GET  /mcp   - MCP Streamable HTTP (SSE stream for server notifications)\n *   DELETE /mcp - MCP Streamable HTTP (session termination)\n *   GET  /       - Service info\n *   GET  /health - Health check\n */\n\nimport { toNodeHandler } from \"h3/node\";\nimport { createServer, type Server } from \"node:http\";\n\nimport { createHealthApp, createMcpRequestHandler } from \"./http.ts\";\nimport { parseReadOnlyFlag } from \"./index.ts\";\nimport { SessionManager } from \"./sessions.ts\";\nimport { VERSION } from \"./version.ts\";\n\nconst DEFAULT_PORT = 3000;\nconst DEFAULT_HOST = \"0.0.0.0\";\n\n/**\n * Options for the HTTP server.\n */\nexport interface HttpStartOptions {\n  /** When true, forge_write tool is not registered. */\n  readOnly?: boolean;\n}\n\n/**\n * Start the HTTP server with Streamable HTTP transport.\n */\nexport function startHttpServer(\n  port: number = DEFAULT_PORT,\n  host: string = DEFAULT_HOST,\n  options?: HttpStartOptions,\n): Promise<Server> {\n  return new Promise((resolve) => {\n    const readOnly = options?.readOnly ?? false;\n    const sessions = new SessionManager();\n    const handleMcp = createMcpRequestHandler(sessions, { readOnly });\n    const healthApp = createHealthApp();\n    const healthHandler = toNodeHandler(healthApp);\n\n    const server = createServer(async (req, res) => {\n      const url = req.url ?? \"/\";\n\n      // Route /mcp to MCP Streamable HTTP transport\n      if (url === \"/mcp\" || url.startsWith(\"/mcp?\")) {\n        await handleMcp(req, res);\n        return;\n      }\n\n      // Everything else goes to h3 (health checks, service info)\n      healthHandler(req, res);\n    });\n\n    server.listen(port, host, () => {\n      const displayHost = host === \"0.0.0.0\" ? \"localhost\" : host;\n      const mode = readOnly ? \" (read-only)\" : \"\";\n      console.log(`Forge MCP server v${VERSION}${mode}`);\n      console.log(`Node.js ${process.version}`);\n      console.log(\"\");\n      console.log(`Running at http://${displayHost}:${port}`);\n      console.log(\"\");\n      console.log(\"Endpoints:\");\n      console.log(\n        `  POST/GET/DELETE http://${displayHost}:${port}/mcp - MCP Streamable HTTP endpoint`,\n      );\n      console.log(`  GET  http://${displayHost}:${port}/health - Health check`);\n      console.log(\"\");\n      console.log(\"Authentication:\");\n      console.log(\"  Bearer token in Authorization header\");\n      console.log(\"  Token format: your raw Forge API token\");\n      if (readOnly) {\n        console.log(\"\");\n        console.log(\"Mode: READ-ONLY (write operations disabled)\");\n      }\n      console.log(\"\");\n      resolve(server);\n    });\n  });\n}\n\n// Start server when run directly\nconst isMainModule =\n  import.meta.url === `file://${process.argv[1]}` ||\n  process.argv[1]?.endsWith(\"/forge-mcp-server\") ||\n  process.argv[1]?.endsWith(\"\\\\forge-mcp-server\");\n\nif (isMainModule) {\n  const port = Number.parseInt(process.env.PORT || String(DEFAULT_PORT), 10);\n  const host = process.env.HOST || DEFAULT_HOST;\n  const readOnly = parseReadOnlyFlag();\n\n  startHttpServer(port, host, { readOnly }).catch((error) => {\n    console.error(\"Fatal error:\", error);\n    process.exit(1);\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAM,eAAe;AACrB,IAAM,eAAe;;;;AAarB,SAAgB,gBACd,OAAe,cACf,OAAe,cACf,SACiB;AACjB,QAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,WAAW,SAAS,YAAY;EAEtC,MAAM,YAAY,wBADD,IAAI,gBAAgB,EACe,EAAE,UAAU,CAAC;EAEjE,MAAM,gBAAgB,cADJ,iBAAiB,CACW;EAE9C,MAAM,SAAS,aAAa,OAAO,KAAK,QAAQ;GAC9C,MAAM,MAAM,IAAI,OAAO;AAGvB,OAAI,QAAQ,UAAU,IAAI,WAAW,QAAQ,EAAE;AAC7C,UAAM,UAAU,KAAK,IAAI;AACzB;;AAIF,iBAAc,KAAK,IAAI;IACvB;AAEF,SAAO,OAAO,MAAM,YAAY;GAC9B,MAAM,cAAc,SAAS,YAAY,cAAc;GACvD,MAAM,OAAO,WAAW,iBAAiB;AACzC,WAAQ,IAAI,qBAAqB,UAAU,OAAO;AAClD,WAAQ,IAAI,WAAW,QAAQ,UAAU;AACzC,WAAQ,IAAI,GAAG;AACf,WAAQ,IAAI,qBAAqB,YAAY,GAAG,OAAO;AACvD,WAAQ,IAAI,GAAG;AACf,WAAQ,IAAI,aAAa;AACzB,WAAQ,IACN,4BAA4B,YAAY,GAAG,KAAK,qCACjD;AACD,WAAQ,IAAI,iBAAiB,YAAY,GAAG,KAAK,wBAAwB;AACzE,WAAQ,IAAI,GAAG;AACf,WAAQ,IAAI,kBAAkB;AAC9B,WAAQ,IAAI,yCAAyC;AACrD,WAAQ,IAAI,2CAA2C;AACvD,OAAI,UAAU;AACZ,YAAQ,IAAI,GAAG;AACf,YAAQ,IAAI,8CAA8C;;AAE5D,WAAQ,IAAI,GAAG;AACf,WAAQ,OAAO;IACf;GACF;;AASJ,IAJE,OAAO,KAAK,QAAQ,UAAU,QAAQ,KAAK,QAC3C,QAAQ,KAAK,IAAI,SAAS,oBAAoB,IAC9C,QAAQ,KAAK,IAAI,SAAS,qBAAqB,CAO/C,iBAJa,OAAO,SAAS,QAAQ,IAAI,QAAQ,OAAO,aAAa,EAAE,GAAG,EAC7D,QAAQ,IAAI,QAAQ,cAGL,EAAE,UAFb,mBAAmB,EAEI,CAAC,CAAC,OAAO,UAAU;AACzD,SAAQ,MAAM,gBAAgB,MAAM;AACpC,SAAQ,KAAK,EAAE;EACf"}

package/dist/sessions.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Session manager for multi-tenant Streamable HTTP transport.
+ *
+ * Each MCP client session gets its own transport + server pair.
+ * Sessions are identified by UUID and tracked in a Map.
+ *
+ * Supports automatic TTL-based cleanup of idle sessions to prevent
+ * memory leaks from abandoned clients.
+ */
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+/**
+ * A managed session: transport + MCP server pair.
+ */
+export interface ManagedSession {
+    transport: StreamableHTTPServerTransport;
+    server: Server;
+    createdAt: number;
+    lastActiveAt: number;
+}
+export interface SessionManagerOptions {
+    /**
+     * Maximum idle time in milliseconds before a session is reaped.
+     * Default: 30 minutes. Set to 0 to disable automatic cleanup.
+     */
+    ttl?: number;
+    /**
+     * How often to check for expired sessions, in milliseconds.
+     * Default: 60 seconds.
+     */
+    sweepInterval?: number;
+}
+export declare class SessionManager {
+    private sessions;
+    private sweepTimer;
+    private readonly ttl;
+    constructor(options?: SessionManagerOptions);
+    /**
+     * Register a session after its ID has been assigned by the transport.
+     */
+    register(transport: StreamableHTTPServerTransport, server: Server): void;
+    /**
+     * Look up a session by its ID and refresh its activity timestamp.
+     */
+    get(sessionId: string): ManagedSession | undefined;
+    /**
+     * Remove a session and close its transport + server.
+     */
+    remove(sessionId: string): Promise<void>;
+    /**
+     * Get the number of active sessions.
+     */
+    get size(): number;
+    /**
+     * Sweep expired sessions. Called automatically by the sweep timer.
+     * Returns the number of sessions reaped.
+     */
+    sweep(): number;
+    /**
+     * Close all sessions, stop the sweep timer, and clean up.
+     */
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAExG;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,6BAA6B,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAKD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,CAAC,EAAE,qBAAqB;IAa3C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,6BAA6B,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAaxE;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAQlD;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,KAAK,IAAI,MAAM;IAsBf;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAchC"}

package/dist/src-BdwavqrN.js

@@ -0,0 +1,189 @@
+import { a as INSTRUCTIONS, i as getTools, n as executeToolWithCredentials, r as STDIO_ONLY_TOOLS, t as VERSION } from "./version-DaD5zvGh.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { getToken, setToken } from "@studiometa/forge-api";
+/**
+* Get all available tools (including stdio-only configuration tools).
+*
+* @param options - Optional filtering. When `readOnly` is true, forge_write is excluded.
+*/
+function getAvailableTools(options) {
+	return [...getTools(options), ...STDIO_ONLY_TOOLS];
+}
+/**
+* Handle the forge_configure tool.
+*/
+function handleConfigureTool(args) {
+	if (!args.apiToken || typeof args.apiToken !== "string" || args.apiToken.trim().length === 0) return {
+		content: [{
+			type: "text",
+			text: "Error: apiToken is required and must be a non-empty string."
+		}],
+		structuredContent: {
+			success: false,
+			error: "apiToken is required and must be a non-empty string."
+		},
+		isError: true
+	};
+	setToken(args.apiToken);
+	const data = {
+		success: true,
+		message: "Laravel Forge API token configured successfully",
+		apiToken: `***${args.apiToken.slice(-4)}`
+	};
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data, null, 2)
+		}],
+		structuredContent: data
+	};
+}
+/**
+* Handle the forge_get_config tool.
+*/
+function handleGetConfigTool() {
+	const token = getToken();
+	const data = {
+		apiToken: token ? `***${token.slice(-4)}` : "not configured",
+		configured: !!token
+	};
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data, null, 2)
+		}],
+		structuredContent: data
+	};
+}
+/**
+* Handle a tool call request.
+*
+* Routes to the appropriate handler based on tool name:
+* - forge_configure / forge_get_config — stdio-only config tools
+* - forge — read-only operations (list, get, help, schema)
+* - forge_write — write operations (create, update, delete, deploy, etc.)
+*/
+async function handleToolCall(name, args, options) {
+	if (name === "forge_configure") return handleConfigureTool(args);
+	if (name === "forge_get_config") return handleGetConfigTool();
+	if (name === "forge_write" && options?.readOnly) return {
+		content: [{
+			type: "text",
+			text: "Error: Server is running in read-only mode. Write operations are disabled."
+		}],
+		structuredContent: {
+			success: false,
+			error: "Server is running in read-only mode. Write operations are disabled."
+		},
+		isError: true
+	};
+	if (name === "forge" || name === "forge_write") {
+		const apiToken = getToken();
+		if (!apiToken) return {
+			content: [{
+				type: "text",
+				text: "Error: Forge API token not configured. Use \"forge_configure\" tool or set FORGE_API_TOKEN environment variable."
+			}],
+			structuredContent: {
+				success: false,
+				error: "Forge API token not configured. Use \"forge_configure\" tool or set FORGE_API_TOKEN environment variable."
+			},
+			isError: true
+		};
+		return executeToolWithCredentials(name, args, { apiToken });
+	}
+	return {
+		content: [{
+			type: "text",
+			text: `Error: Unknown tool "${name}".`
+		}],
+		structuredContent: {
+			success: false,
+			error: `Unknown tool "${name}".`
+		},
+		isError: true
+	};
+}
+/**
+* Forge MCP Server — Stdio Transport
+*
+* This is the local execution mode using stdio transport.
+* For remote HTTP deployment, use server.ts instead.
+*
+* Usage:
+*   npx @studiometa/forge-mcp
+*   npx @studiometa/forge-mcp --read-only
+*   FORGE_READ_ONLY=true npx @studiometa/forge-mcp
+*
+* Or in Claude Desktop config:
+*   {
+*     "mcpServers": {
+*       "forge": {
+*         "command": "forge-mcp",
+*         "args": ["--read-only"],
+*         "env": { "FORGE_API_TOKEN": "your-token" }
+*       }
+*     }
+*   }
+*/
+/**
+* Parse read-only flag from process.argv and environment.
+*/
+function parseReadOnlyFlag() {
+	return process.argv.includes("--read-only") || process.env.FORGE_READ_ONLY === "true";
+}
+/**
+* Create and configure the MCP server.
+*/
+function createStdioServer(options) {
+	const readOnly = options?.readOnly ?? false;
+	const server = new Server({
+		name: "forge-mcp",
+		version: VERSION
+	}, {
+		capabilities: { tools: {} },
+		instructions: INSTRUCTIONS
+	});
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		return { tools: getAvailableTools({ readOnly }) };
+	});
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			return await handleToolCall(name, args ?? {}, { readOnly });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{
+					type: "text",
+					text: `Error: ${message}`
+				}],
+				structuredContent: {
+					success: false,
+					error: message
+				},
+				isError: true
+			};
+		}
+	});
+	return server;
+}
+/**
+* Start the stdio server.
+*/
+async function startStdioServer(options) {
+	const server = createStdioServer(options);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	const mode = options?.readOnly ? " (read-only)" : "";
+	console.error(`Forge MCP server v${VERSION} running on stdio${mode}`);
+}
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/forge-mcp") || process.argv[1]?.endsWith("\\forge-mcp")) startStdioServer({ readOnly: parseReadOnlyFlag() }).catch((error) => {
+	console.error("Fatal error:", error);
+	process.exit(1);
+});
+export { parseReadOnlyFlag as n, startStdioServer as r, createStdioServer as t };
+
+//# sourceMappingURL=src-BdwavqrN.js.map

package/dist/src-BdwavqrN.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"src-BdwavqrN.js","names":[],"sources":["../src/stdio.ts","../src/index.ts"],"sourcesContent":["import { getToken, setToken } from \"@studiometa/forge-api\";\n\nimport type { ToolResult } from \"./handlers/types.ts\";\n\nimport { executeToolWithCredentials } from \"./handlers/index.ts\";\nimport { getTools, STDIO_ONLY_TOOLS } from \"./tools.ts\";\nimport type { GetToolsOptions } from \"./tools.ts\";\n\nexport type { ToolResult };\n\n/**\n * Get all available tools (including stdio-only configuration tools).\n *\n * @param options - Optional filtering. When `readOnly` is true, forge_write is excluded.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function getAvailableTools(options?: GetToolsOptions): any[] {\n  return [...getTools(options), ...STDIO_ONLY_TOOLS];\n}\n\n/**\n * Handle the forge_configure tool.\n */\nexport function handleConfigureTool(args: { apiToken: string }): ToolResult {\n  if (!args.apiToken || typeof args.apiToken !== \"string\" || args.apiToken.trim().length === 0) {\n    return {\n      content: [\n        {\n          type: \"text\",\n          text: \"Error: apiToken is required and must be a non-empty string.\",\n        },\n      ],\n      structuredContent: {\n        success: false,\n        error: \"apiToken is required and must be a non-empty string.\",\n      },\n      isError: true,\n    };\n  }\n\n  setToken(args.apiToken);\n\n  const maskedToken = `***${args.apiToken.slice(-4)}`;\n  const data = {\n    success: true,\n    message: \"Laravel Forge API token configured successfully\",\n    apiToken: maskedToken,\n  };\n\n  return {\n    content: [\n      {\n        type: \"text\",\n        text: JSON.stringify(data, null, 2),\n      },\n    ],\n    structuredContent: data,\n  };\n}\n\n/**\n * Handle the forge_get_config tool.\n */\nexport function handleGetConfigTool(): ToolResult {\n  const token = getToken();\n\n  const data = {\n    apiToken: token ? `***${token.slice(-4)}` : \"not configured\",\n    configured: !!token,\n  };\n\n  return {\n    content: [\n      {\n        type: \"text\",\n        text: JSON.stringify(data, null, 2),\n      },\n    ],\n    structuredContent: data,\n  };\n}\n\n/**\n * Options for handleToolCall.\n */\nexport interface HandleToolCallOptions {\n  /** When true, forge_write is rejected with an error. */\n  readOnly?: boolean;\n}\n\n/**\n * Handle a tool call request.\n *\n * Routes to the appropriate handler based on tool name:\n * - forge_configure / forge_get_config — stdio-only config tools\n * - forge — read-only operations (list, get, help, schema)\n * - forge_write — write operations (create, update, delete, deploy, etc.)\n */\nexport async function handleToolCall(\n  name: string,\n  args: Record<string, unknown>,\n  options?: HandleToolCallOptions,\n): Promise<ToolResult> {\n  if (name === \"forge_configure\") {\n    return handleConfigureTool(args as { apiToken: string });\n  }\n\n  if (name === \"forge_get_config\") {\n    return handleGetConfigTool();\n  }\n\n  // Reject forge_write in read-only mode\n  if (name === \"forge_write\" && options?.readOnly) {\n    return {\n      content: [\n        {\n          type: \"text\",\n          text: \"Error: Server is running in read-only mode. Write operations are disabled.\",\n        },\n      ],\n      structuredContent: {\n        success: false,\n        error: \"Server is running in read-only mode. Write operations are disabled.\",\n      },\n      isError: true,\n    };\n  }\n\n  // Both forge and forge_write require authentication\n  if (name === \"forge\" || name === \"forge_write\") {\n    const apiToken = getToken();\n    if (!apiToken) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: 'Error: Forge API token not configured. Use \"forge_configure\" tool or set FORGE_API_TOKEN environment variable.',\n          },\n        ],\n        structuredContent: {\n          success: false,\n          error:\n            'Forge API token not configured. Use \"forge_configure\" tool or set FORGE_API_TOKEN environment variable.',\n        },\n        isError: true,\n      };\n    }\n\n    return executeToolWithCredentials(name, args, { apiToken });\n  }\n\n  return {\n    content: [\n      {\n        type: \"text\",\n        text: `Error: Unknown tool \"${name}\".`,\n      },\n    ],\n    structuredContent: { success: false, error: `Unknown tool \"${name}\".` },\n    isError: true,\n  };\n}\n","#!/usr/bin/env node\n\n/**\n * Forge MCP Server — Stdio Transport\n *\n * This is the local execution mode using stdio transport.\n * For remote HTTP deployment, use server.ts instead.\n *\n * Usage:\n *   npx @studiometa/forge-mcp\n *   npx @studiometa/forge-mcp --read-only\n *   FORGE_READ_ONLY=true npx @studiometa/forge-mcp\n *\n * Or in Claude Desktop config:\n *   {\n *     \"mcpServers\": {\n *       \"forge\": {\n *         \"command\": \"forge-mcp\",\n *         \"args\": [\"--read-only\"],\n *         \"env\": { \"FORGE_API_TOKEN\": \"your-token\" }\n *       }\n *     }\n *   }\n */\n\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { CallToolRequestSchema, ListToolsRequestSchema } from \"@modelcontextprotocol/sdk/types.js\";\n\nimport { INSTRUCTIONS } from \"./instructions.ts\";\nimport { getAvailableTools, handleToolCall } from \"./stdio.ts\";\nimport { VERSION } from \"./version.ts\";\n\n/**\n * Options for the stdio MCP server.\n */\nexport interface StdioServerOptions {\n  /** When true, forge_write tool is not registered and write operations are rejected. */\n  readOnly?: boolean;\n}\n\n/**\n * Parse read-only flag from process.argv and environment.\n */\nexport function parseReadOnlyFlag(): boolean {\n  return process.argv.includes(\"--read-only\") || process.env.FORGE_READ_ONLY === \"true\";\n}\n\n/**\n * Create and configure the MCP server.\n */\nexport function createStdioServer(options?: StdioServerOptions): Server {\n  const readOnly = options?.readOnly ?? false;\n\n  const server = new Server(\n    {\n      name: \"forge-mcp\",\n      version: VERSION,\n    },\n    {\n      capabilities: {\n        tools: {},\n      },\n      instructions: INSTRUCTIONS,\n    },\n  );\n\n  server.setRequestHandler(ListToolsRequestSchema, async () => {\n    return { tools: getAvailableTools({ readOnly }) };\n  });\n\n  server.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const { name, arguments: args } = request.params;\n\n    try {\n      const result = await handleToolCall(name, (args as Record<string, unknown>) ?? {}, {\n        readOnly,\n      });\n      return result as unknown as Record<string, unknown>;\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      return {\n        content: [{ type: \"text\" as const, text: `Error: ${message}` }],\n        structuredContent: { success: false, error: message },\n        isError: true,\n      };\n    }\n  });\n\n  return server;\n}\n\n/**\n * Start the stdio server.\n */\nexport async function startStdioServer(options?: StdioServerOptions): Promise<void> {\n  const server = createStdioServer(options);\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n  const mode = options?.readOnly ? \" (read-only)\" : \"\";\n  console.error(`Forge MCP server v${VERSION} running on stdio${mode}`);\n}\n\n// Start server when run directly\nconst isMainModule =\n  import.meta.url === `file://${process.argv[1]}` ||\n  process.argv[1]?.endsWith(\"/forge-mcp\") ||\n  process.argv[1]?.endsWith(\"\\\\forge-mcp\");\n\nif (isMainModule) {\n  const readOnly = parseReadOnlyFlag();\n  startStdioServer({ readOnly }).catch((error) => {\n    console.error(\"Fatal error:\", error);\n    process.exit(1);\n  });\n}\n"],"mappings":"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"}

package/dist/stdio.d.ts

@@ -0,0 +1,36 @@
+import type { ToolResult } from "./handlers/types.ts";
+import type { GetToolsOptions } from "./tools.ts";
+export type { ToolResult };
+/**
+ * Get all available tools (including stdio-only configuration tools).
+ *
+ * @param options - Optional filtering. When `readOnly` is true, forge_write is excluded.
+ */
+export declare function getAvailableTools(options?: GetToolsOptions): any[];
+/**
+ * Handle the forge_configure tool.
+ */
+export declare function handleConfigureTool(args: {
+    apiToken: string;
+}): ToolResult;
+/**
+ * Handle the forge_get_config tool.
+ */
+export declare function handleGetConfigTool(): ToolResult;
+/**
+ * Options for handleToolCall.
+ */
+export interface HandleToolCallOptions {
+    /** When true, forge_write is rejected with an error. */
+    readOnly?: boolean;
+}
+/**
+ * Handle a tool call request.
+ *
+ * Routes to the appropriate handler based on tool name:
+ * - forge_configure / forge_get_config — stdio-only config tools
+ * - forge — read-only operations (list, get, help, schema)
+ * - forge_write — write operations (create, update, delete, deploy, etc.)
+ */
+export declare function handleToolCall(name: string, args: Record<string, unknown>, options?: HandleToolCallOptions): Promise<ToolResult>;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B;;;;GAIG;AAEH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,GAAG,EAAE,CAElE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAmC1E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,UAAU,CAiBhD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,UAAU,CAAC,CA2DrB"}

package/dist/tools.d.ts

@@ -0,0 +1,47 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Read-only actions — safe operations that don't modify server state.
+ */
+export declare const READ_ACTIONS: readonly ["list", "get", "help", "schema"];
+/**
+ * Write actions — operations that modify server state.
+ * These are separated into the `forge_write` tool for safety.
+ */
+export declare const WRITE_ACTIONS: readonly ["create", "update", "delete", "deploy", "reboot", "restart", "activate", "run"];
+export type ReadAction = (typeof READ_ACTIONS)[number];
+export type WriteAction = (typeof WRITE_ACTIONS)[number];
+/**
+ * Check if an action is a write action.
+ */
+export declare function isWriteAction(action: string): action is WriteAction;
+/**
+ * Check if an action is a read action.
+ */
+export declare function isReadAction(action: string): action is ReadAction;
+/**
+ * Core tools available in both stdio and HTTP transports.
+ *
+ * Split into two tools for safety:
+ * - `forge` — read-only operations (auto-approvable by MCP clients)
+ * - `forge_write` — write operations (always requires confirmation)
+ */
+export declare const TOOLS: Tool[];
+/**
+ * Options for filtering available tools.
+ */
+export interface GetToolsOptions {
+    /** When true, only read-only tools are returned (forge_write is excluded). */
+    readOnly?: boolean;
+}
+/**
+ * Get the list of core tools, optionally filtered.
+ *
+ * In read-only mode, forge_write is excluded entirely — it won't appear
+ * in the tool listing and cannot be called.
+ */
+export declare function getTools(options?: GetToolsOptions): Tool[];
+/**
+ * Additional tools only available in stdio mode.
+ */
+export declare const STDIO_ONLY_TOOLS: Tool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAI/D;;GAEG;AACH,eAAO,MAAM,YAAY,4CAA6C,CAAC;AAEvE;;;GAGG;AACH,eAAO,MAAM,aAAa,2FAShB,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,WAAW,CAEnE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,UAAU,CAEjE;AA0OD;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,IAAI,EAAwC,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,EAAE,CAK1D;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,IAAI,EAsDlC,CAAC"}