@studiometa/forge-mcp 0.1.0 → 0.2.1

package/README.md

@@ -7,10 +7,11 @@ MCP (Model Context Protocol) server for [Laravel Forge](https://forge.laravel.co
 
 ## Features
 
-- Single unified `forge` tool — minimal token overhead
+- **Two tools with clear safety split** — `forge` (read) and `forge_write` (write)
+- MCP clients auto-approve `forge` reads, always prompt for `forge_write` writes
 - Resource/action routing from centralized constants
 - Built-in help system — `action=help` for any resource
-- Stdio transport for local use
+- Stdio and Streamable HTTP transports
 - Configuration tools for interactive token setup
 
 ## Installation
@@ -42,37 +43,75 @@ Add to your Claude Desktop config:
 
 Alternatively, omit the `env` block and ask Claude to configure credentials using the `forge_configure` tool.
 
-## The `forge` Tool
+### Read-Only Mode
 
-A single unified tool with `resource` + `action` routing:
+To guarantee no write operations are possible at the server level:
+
+```json
+{
+  "mcpServers": {
+    "forge": {
+      "command": "forge-mcp",
+      "args": ["--read-only"],
+      "env": {
+        "FORGE_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Or via environment variable: `FORGE_READ_ONLY=true`.
+
+When enabled, the `forge_write` tool is not registered at all — only `forge`, `forge_configure`, and `forge_get_config` are available.
+
+## Tools
+
+### `forge` — Read Operations
+
+Safe, read-only queries. Annotated `readOnlyHint: true` so MCP clients can auto-approve.
+
+**Actions**: `list`, `get`, `help`, `schema`
 
 ```json
 { "resource": "servers", "action": "list" }
 { "resource": "servers", "action": "get", "id": "123" }
 { "resource": "sites", "action": "list", "server_id": "123" }
-{ "resource": "deployments", "action": "deploy", "server_id": "123", "site_id": "456" }
 { "resource": "servers", "action": "help" }
 ```
 
+### `forge_write` — Write Operations
+
+Mutating operations. Annotated `destructiveHint: true` so MCP clients always prompt for confirmation.
+
+**Actions**: `create`, `update`, `delete`, `deploy`, `reboot`, `restart`, `activate`, `run`
+
+```json
+{ "resource": "deployments", "action": "deploy", "server_id": "123", "site_id": "456" }
+// deploy blocks until complete, returning: status, deployment log, elapsed time
+{ "resource": "servers", "action": "reboot", "id": "123" }
+{ "resource": "daemons", "action": "create", "server_id": "123", "command": "php artisan queue:work" }
+```
+
 ### Resources & Actions
 
-| Resource        | Actions                             | Required Fields            |
-| --------------- | ----------------------------------- | -------------------------- |
-| servers         | list, get, create, delete, reboot   | id (for get/delete/reboot) |
-| sites           | list, get, create, delete           | server_id                  |
-| deployments     | list, deploy, get, update           | server_id, site_id         |
-| env             | get, update                         | server_id, site_id         |
-| nginx           | get, update                         | server_id, site_id         |
-| certificates    | list, get, create, delete, activate | server_id, site_id         |
-| databases       | list, get, create, delete           | server_id                  |
-| daemons         | list, get, create, delete, restart  | server_id                  |
-| firewall-rules  | list, get, create, delete           | server_id                  |
-| ssh-keys        | list, get, create, delete           | server_id                  |
-| security-rules  | list, get, create, delete           | server_id, site_id         |
-| redirect-rules  | list, get, create, delete           | server_id, site_id         |
-| monitors        | list, get, create, delete           | server_id                  |
-| nginx-templates | list, get, create, update, delete   | server_id                  |
-| recipes         | list, get, create, delete, run      | id (for get/delete/run)    |
+| Resource        | Read Actions | Write Actions            | Required Fields            |
+| --------------- | ------------ | ------------------------ | -------------------------- |
+| servers         | list, get    | create, delete, reboot   | id (for get/delete/reboot) |
+| sites           | list, get    | create, delete           | server_id                  |
+| deployments     | list         | deploy, update           | server_id, site_id         |
+| env             | get          | update                   | server_id, site_id         |
+| nginx           | get          | update                   | server_id, site_id         |
+| certificates    | list, get    | create, delete, activate | server_id, site_id         |
+| databases       | list, get    | create, delete           | server_id                  |
+| daemons         | list, get    | create, delete, restart  | server_id                  |
+| firewall-rules  | list, get    | create, delete           | server_id                  |
+| ssh-keys        | list, get    | create, delete           | server_id                  |
+| security-rules  | list, get    | create, delete           | server_id, site_id         |
+| redirect-rules  | list, get    | create, delete           | server_id, site_id         |
+| monitors        | list, get    | create, delete           | server_id                  |
+| nginx-templates | list, get    | create, update, delete   | server_id                  |
+| recipes         | list, get    | create, delete, run      | id (for get/delete/run)    |
 
 ### Discovery
 
@@ -90,6 +129,17 @@ Use `action: "help"` with any resource:
 | `forge_configure`  | Save API token to local config     |
 | `forge_get_config` | Show current config (token masked) |
 
+## Audit Logging
+
+All write operations (`forge_write` tool calls) are automatically logged for traceability:
+
+- **Default path**: `~/.config/forge-tools/audit.log`
+- **Override**: Set `FORGE_AUDIT_LOG` environment variable
+- **Format**: JSON lines (via pino) with timestamp, resource, action, sanitized args, and status
+- **Safety**: Logging never interrupts operations — silent on failure
+
+The CLI also logs write commands to the same audit log.
+
 ## Getting Your API Token
 
 1. Log into [Laravel Forge](https://forge.laravel.com)

package/dist/flags-LFbdErsZ.js

@@ -0,0 +1,23 @@
+/**
+* CLI flag parsers shared between stdio and HTTP entry points.
+*
+* Extracted to a separate module so that both `index.ts` (stdio) and
+* `server.ts` (HTTP) can import it without creating a shared dependency
+* that triggers Vite code-splitting — which would break the `isMainModule`
+* guard in `index.ts`.
+*
+* See: https://github.com/studiometa/forge-tools/issues/63
+*/
+/**
+* Parse read-only flag from process.argv and environment.
+*
+* Supports:
+* - `--read-only` CLI flag
+* - `FORGE_READ_ONLY=true` environment variable
+*/
+function parseReadOnlyFlag() {
+	return process.argv.includes("--read-only") || process.env.FORGE_READ_ONLY === "true";
+}
+export { parseReadOnlyFlag as t };
+
+//# sourceMappingURL=flags-LFbdErsZ.js.map

package/dist/flags-LFbdErsZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-LFbdErsZ.js","names":[],"sources":["../src/flags.ts"],"sourcesContent":["/**\n * CLI flag parsers shared between stdio and HTTP entry points.\n *\n * Extracted to a separate module so that both `index.ts` (stdio) and\n * `server.ts` (HTTP) can import it without creating a shared dependency\n * that triggers Vite code-splitting — which would break the `isMainModule`\n * guard in `index.ts`.\n *\n * See: https://github.com/studiometa/forge-tools/issues/63\n */\n\n/**\n * Parse read-only flag from process.argv and environment.\n *\n * Supports:\n * - `--read-only` CLI flag\n * - `FORGE_READ_ONLY=true` environment variable\n */\nexport function parseReadOnlyFlag(): boolean {\n  return process.argv.includes(\"--read-only\") || process.env.FORGE_READ_ONLY === \"true\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAkBA,SAAgB,oBAA6B;AAC3C,QAAO,QAAQ,KAAK,SAAS,cAAc,IAAI,QAAQ,IAAI,oBAAoB"}

package/dist/flags.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI flag parsers shared between stdio and HTTP entry points.
+ *
+ * Extracted to a separate module so that both `index.ts` (stdio) and
+ * `server.ts` (HTTP) can import it without creating a shared dependency
+ * that triggers Vite code-splitting — which would break the `isMainModule`
+ * guard in `index.ts`.
+ *
+ * See: https://github.com/studiometa/forge-tools/issues/63
+ */
+/**
+ * Parse read-only flag from process.argv and environment.
+ *
+ * Supports:
+ * - `--read-only` CLI flag
+ * - `FORGE_READ_ONLY=true` environment variable
+ */
+export declare function parseReadOnlyFlag(): boolean;
+//# sourceMappingURL=flags.d.ts.map

package/dist/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C"}

package/dist/formatters.d.ts

@@ -45,9 +45,17 @@ export declare function formatDatabaseUser(user: ForgeDatabaseUser): string;
  */
 export declare function formatDeploymentList(deployments: ForgeDeployment[]): string;
 /**
- * Format a deployment action result (deploy/update-script).
- */
-export declare function formatDeployAction(siteId: string, serverId: string): string;
+ * Format a deployment action result.
+ *
+ * When a `DeployResult` is provided the output includes status, elapsed time,
+ * and the deployment log.  When called with just IDs (legacy) it falls back to
+ * the simple confirmation message so existing tests keep passing.
+ */
+export declare function formatDeployAction(siteId: string, serverId: string, result?: {
+    status: "success" | "failed";
+    log: string;
+    elapsed_ms: number;
+}): string;
 /**
  * Format deployment script content.
  */

package/dist/formatters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"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"}

package/dist/handlers/index.d.ts

@@ -2,8 +2,9 @@
  * Tool execution handlers for Forge MCP server.
  * Shared between stdio and HTTP transports.
  *
- * Single consolidated tool for minimal token overhead:
- * - forge: resource + action based API
+ * Two tools with clear separation:
+ * - forge: read-only operations (list, get, help, schema)
+ * - forge_write: write operations (create, update, delete, deploy, reboot, etc.)
  */
 import type { ToolResult } from "./types.ts";
 export type { ToolResult } from "./types.ts";
@@ -11,8 +12,9 @@ export type { ToolResult } from "./types.ts";
  * Execute a tool call with provided credentials.
  *
  * This is the main entry point shared between stdio and HTTP transports.
+ * Validates that the action matches the tool (read vs write).
  */
-export declare function executeToolWithCredentials(_name: string, args: Record<string, unknown>, credentials: {
+export declare function executeToolWithCredentials(name: string, args: Record<string, unknown>, credentials: {
     apiToken: string;
 }): Promise<ToolResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/handlers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAA8B,UAAU,EAAE,MAAM,YAAY,CAAC;AA6BzE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAiE7C;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChC,OAAO,CAAC,UAAU,CAAC,CAyDrB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAA8B,UAAU,EAAE,MAAM,YAAY,CAAC;AA8BzE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAwE7C;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChC,OAAO,CAAC,UAAU,CAAC,CAyFrB"}

package/dist/handlers/types.d.ts

@@ -1,12 +1,17 @@
 import type { ExecutorContext } from "@studiometa/forge-core";
 /**
  * Result from MCP tool handlers.
+ *
+ * - `content` — human-readable text (always present)
+ * - `structuredContent` — machine-readable data matching the tool's `outputSchema`
+ * - `isError` — true when the result represents an error
  */
 export interface ToolResult {
     content: Array<{
         type: "text";
         text: string;
     }>;
+    structuredContent?: Record<string, unknown>;
     isError?: boolean;
 }
 /**

package/dist/handlers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/handlers/utils.d.ts

@@ -1,8 +1,11 @@
 import type { ToolResult } from "./types.ts";
 import { UserInputError } from "../errors.ts";
 /**
- * Create a successful JSON result.
- * Accepts a string or an object (which will be JSON-serialized).
+ * Create a successful result with both human-readable text and structured content.
+ *
+ * - When `data` is a string, `structuredContent` wraps it as `{ result: data }`.
+ * - When `data` is an object/array, `structuredContent` is `{ result: data }` and
+ *   the text representation is the JSON-serialized form.
  */
 export declare function jsonResult(data: string | Record<string, unknown> | unknown): ToolResult;
 /**
@@ -13,7 +16,7 @@ export declare function jsonResult(data: string | Record<string, unknown> | unkn
  */
 export declare function sanitizeId(value: string): boolean;
 /**
- * Create an error result.
+ * Create an error result with structured error content.
  */
 export declare function errorResult(message: string): ToolResult;
 /**

package/dist/handlers/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/handlers/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,UAAU,CAKvF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAKvD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAWhG"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/handlers/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,UAAU,CAMvF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAMvD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAehG"}

package/dist/{http-BJUKoZdb.js → http-w0DliUHY.js}

@@ -1,4 +1,4 @@
-import { a as INSTRUCTIONS, i as executeToolWithCredentials, r as TOOLS, t as VERSION } from "./version-Cw8OGt4r.js";
+import { a as INSTRUCTIONS, i as getTools, n as executeToolWithCredentials, t as VERSION } from "./version-BmEJceWJ.js";
 import { parseAuthHeader } from "./auth.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -110,7 +110,9 @@ var SessionManager = class {
 * Unlike stdio, HTTP mode does NOT include forge_configure/forge_get_config
 * because credentials come from the Authorization header per-request.
 */
-function createMcpServer() {
+function createMcpServer(options) {
+	const readOnly = options?.readOnly ?? false;
+	const tools = getTools({ readOnly });
 	const server = new Server({
 		name: "forge-mcp",
 		version: VERSION
@@ -119,7 +121,7 @@ function createMcpServer() {
 		instructions: INSTRUCTIONS
 	});
 	server.setRequestHandler(ListToolsRequestSchema, async () => {
-		return { tools: TOOLS };
+		return { tools };
 	});
 	server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 		const { name, arguments: args } = request.params;
@@ -130,9 +132,24 @@ function createMcpServer() {
 				type: "text",
 				text: "Error: Authentication required. No token found in request."
 			}],
+			structuredContent: {
+				success: false,
+				error: "Authentication required. No token found in request."
+			},
 			isError: true
 		};
 		/* v8 ignore stop */
+		if (readOnly && name === "forge_write") 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
+		};
 		try {
 			return await executeToolWithCredentials(
 				name,
@@ -141,12 +158,18 @@ function createMcpServer() {
 				{ apiToken: token }
 			);
 		} catch (error) {
+			/* v8 ignore start */
+			const message = error instanceof Error ? error.message : String(error);
 			/* v8 ignore stop */
 			return {
 				content: [{
 					type: "text",
-					text: `Error: ${error instanceof Error ? error.message : String(error)}`
+					text: `Error: ${message}`
 				}],
+				structuredContent: {
+					success: false,
+					error: message
+				},
 				isError: true
 			};
 		}
@@ -163,8 +186,9 @@ function createMcpServer() {
 * @param req - Node.js IncomingMessage
 * @param res - Node.js ServerResponse
 * @param sessions - Session manager instance (injected)
+* @param options - Server options (read-only mode, etc.)
 */
-async function handleMcpRequest(req, res, sessions) {
+async function handleMcpRequest(req, res, sessions, options) {
 	const authHeader = req.headers.authorization;
 	const credentials = parseAuthHeader(authHeader);
 	if (!credentials) {
@@ -204,7 +228,7 @@ async function handleMcpRequest(req, res, sessions) {
 		return;
 	}
 	const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
-	const server = createMcpServer();
+	const server = createMcpServer(options);
 	await server.connect(transport);
 	transport.onclose = () => {
 		const sid = transport.sessionId;
@@ -225,9 +249,9 @@ async function handleMcpRequest(req, res, sessions) {
 * Create a request handler bound to a SessionManager instance.
 * Convenience factory for server.ts.
 */
-function createMcpRequestHandler(sessions) {
+function createMcpRequestHandler(sessions, options) {
 	/* v8 ignore start */
-	return (req, res) => handleMcpRequest(req, res, sessions);
+	return (req, res) => handleMcpRequest(req, res, sessions, options);
 	/* v8 ignore stop */
 }
 /**
@@ -250,4 +274,4 @@ function createHealthApp() {
 }
 export { SessionManager as a, handleMcpRequest as i, createMcpRequestHandler as n, createMcpServer as r, createHealthApp as t };
 
-//# sourceMappingURL=http-BJUKoZdb.js.map
+//# sourceMappingURL=http-w0DliUHY.js.map

package/dist/http-w0DliUHY.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-w0DliUHY.js","names":[],"sources":["../src/sessions.ts","../src/http.ts"],"sourcesContent":["/**\n * Session manager for multi-tenant Streamable HTTP transport.\n *\n * Each MCP client session gets its own transport + server pair.\n * Sessions are identified by UUID and tracked in a Map.\n *\n * Supports automatic TTL-based cleanup of idle sessions to prevent\n * memory leaks from abandoned clients.\n */\n\nimport type { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport type { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\n\n/**\n * A managed session: transport + MCP server pair.\n */\nexport interface ManagedSession {\n  transport: StreamableHTTPServerTransport;\n  server: Server;\n  createdAt: number;\n  lastActiveAt: number;\n}\n\nexport interface SessionManagerOptions {\n  /**\n   * Maximum idle time in milliseconds before a session is reaped.\n   * Default: 30 minutes. Set to 0 to disable automatic cleanup.\n   */\n  ttl?: number;\n\n  /**\n   * How often to check for expired sessions, in milliseconds.\n   * Default: 60 seconds.\n   */\n  sweepInterval?: number;\n}\n\nconst DEFAULT_TTL = 30 * 60 * 1000; // 30 minutes\nconst DEFAULT_SWEEP_INTERVAL = 60 * 1000; // 60 seconds\n\nexport class SessionManager {\n  private sessions = new Map<string, ManagedSession>();\n  private sweepTimer: ReturnType<typeof setInterval> | undefined;\n  private readonly ttl: number;\n\n  constructor(options?: SessionManagerOptions) {\n    this.ttl = options?.ttl ?? DEFAULT_TTL;\n\n    if (this.ttl > 0) {\n      const interval = options?.sweepInterval ?? DEFAULT_SWEEP_INTERVAL;\n      this.sweepTimer = setInterval(() => {\n        this.sweep();\n      }, interval);\n      // Don't keep the process alive just for the sweep timer\n      this.sweepTimer.unref();\n    }\n  }\n\n  /**\n   * Register a session after its ID has been assigned by the transport.\n   */\n  register(transport: StreamableHTTPServerTransport, server: Server): void {\n    const sessionId = transport.sessionId;\n    if (sessionId) {\n      const now = Date.now();\n      this.sessions.set(sessionId, {\n        transport,\n        server,\n        createdAt: now,\n        lastActiveAt: now,\n      });\n    }\n  }\n\n  /**\n   * Look up a session by its ID and refresh its activity timestamp.\n   */\n  get(sessionId: string): ManagedSession | undefined {\n    const session = this.sessions.get(sessionId);\n    if (session) {\n      session.lastActiveAt = Date.now();\n    }\n    return session;\n  }\n\n  /**\n   * Remove a session and close its transport + server.\n   */\n  async remove(sessionId: string): Promise<void> {\n    const session = this.sessions.get(sessionId);\n    if (session) {\n      this.sessions.delete(sessionId);\n      await session.transport.close();\n      await session.server.close();\n    }\n  }\n\n  /**\n   * Get the number of active sessions.\n   */\n  get size(): number {\n    return this.sessions.size;\n  }\n\n  /**\n   * Sweep expired sessions. Called automatically by the sweep timer.\n   * Returns the number of sessions reaped.\n   */\n  sweep(): number {\n    if (this.ttl <= 0) return 0;\n\n    const now = Date.now();\n    const expired: string[] = [];\n\n    for (const [id, session] of this.sessions) {\n      if (now - session.lastActiveAt > this.ttl) {\n        expired.push(id);\n      }\n    }\n\n    for (const id of expired) {\n      // Fire-and-forget cleanup — don't block the sweep\n      /* v8 ignore start */\n      this.remove(id).catch(() => {});\n      /* v8 ignore stop */\n    }\n\n    return expired.length;\n  }\n\n  /**\n   * Close all sessions, stop the sweep timer, and clean up.\n   */\n  async closeAll(): Promise<void> {\n    if (this.sweepTimer) {\n      clearInterval(this.sweepTimer);\n      this.sweepTimer = undefined;\n    }\n\n    const promises: Promise<void>[] = [];\n    for (const [, session] of this.sessions) {\n      promises.push(session.transport.close());\n      promises.push(session.server.close());\n    }\n    await Promise.all(promises);\n    this.sessions.clear();\n  }\n}\n","/**\n * Streamable HTTP transport for Forge MCP Server\n *\n * Implements the official MCP Streamable HTTP transport specification (2025-03-26)\n * using the SDK's StreamableHTTPServerTransport.\n *\n * Architecture:\n * - Stateful mode with per-session transport+server pairs (multi-tenant)\n * - Auth via Bearer token → authInfo.token → handler extra.authInfo\n * - Session manager (injected) maps session IDs to transport+server instances\n * - Health/status endpoints handled by h3, MCP endpoint by the SDK transport\n */\n\nimport { randomUUID } from \"node:crypto\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\n\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { CallToolRequestSchema, ListToolsRequestSchema } from \"@modelcontextprotocol/sdk/types.js\";\nimport { createApp, defineEventHandler, type H3 } from \"h3\";\n\nimport { parseAuthHeader } from \"./auth.ts\";\nimport { executeToolWithCredentials } from \"./handlers/index.ts\";\nimport { INSTRUCTIONS } from \"./instructions.ts\";\nimport { SessionManager } from \"./sessions.ts\";\nimport { getTools } from \"./tools.ts\";\nimport { VERSION } from \"./version.ts\";\n\nexport { SessionManager } from \"./sessions.ts\";\n\n/**\n * Options for the HTTP MCP server.\n */\nexport interface HttpServerOptions {\n  /** When true, forge_write tool is not registered and write operations are rejected. */\n  readOnly?: boolean;\n}\n\n/**\n * Create a configured MCP Server instance for HTTP transport.\n *\n * Unlike stdio, HTTP mode does NOT include forge_configure/forge_get_config\n * because credentials come from the Authorization header per-request.\n */\nexport function createMcpServer(options?: HttpServerOptions): Server {\n  const readOnly = options?.readOnly ?? false;\n  const tools = getTools({ readOnly });\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 };\n  });\n\n  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {\n    const { name, arguments: args } = request.params;\n    const token = extra.authInfo?.token;\n\n    /* v8 ignore start */\n    if (!token) {\n      return {\n        content: [\n          {\n            type: \"text\" as const,\n            text: \"Error: Authentication required. No token found in request.\",\n          },\n        ],\n        structuredContent: {\n          success: false,\n          error: \"Authentication required. No token found in request.\",\n        },\n        isError: true,\n      };\n    }\n    /* v8 ignore stop */\n\n    // Reject write operations in read-only mode\n    if (readOnly && name === \"forge_write\") {\n      return {\n        content: [\n          {\n            type: \"text\" as const,\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    try {\n      const result = await executeToolWithCredentials(\n        name,\n        /* v8 ignore next */ (args as Record<string, unknown>) ?? {},\n        { apiToken: token },\n      );\n      return result as unknown as Record<string, unknown>;\n    } catch (error) {\n      /* v8 ignore start */\n      const message = error instanceof Error ? error.message : String(error);\n      /* v8 ignore stop */\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 * Handle an MCP request using the Streamable HTTP transport.\n *\n * Routes requests based on whether they have a session ID:\n * - No session ID + initialize request → create new session\n * - Has session ID → route to existing session's transport\n *\n * @param req - Node.js IncomingMessage\n * @param res - Node.js ServerResponse\n * @param sessions - Session manager instance (injected)\n * @param options - Server options (read-only mode, etc.)\n */\nexport async function handleMcpRequest(\n  req: IncomingMessage,\n  res: ServerResponse,\n  sessions: SessionManager,\n  options?: HttpServerOptions,\n): Promise<void> {\n  // Extract and validate auth\n  const authHeader = req.headers.authorization;\n  const credentials = parseAuthHeader(authHeader);\n\n  if (!credentials) {\n    res.writeHead(401, { \"Content-Type\": \"application/json\" });\n    res.end(\n      JSON.stringify({\n        jsonrpc: \"2.0\",\n        error: {\n          code: -32001,\n          message: \"Authentication required. Provide a Bearer token with your Forge API token.\",\n        },\n        id: null,\n      }),\n    );\n    return;\n  }\n\n  // Inject auth info for the SDK transport\n  const authenticatedReq = req as IncomingMessage & {\n    auth?: { token: string; clientId: string; scopes: string[] };\n  };\n  authenticatedReq.auth = {\n    token: credentials.apiToken,\n    clientId: \"forge-http-client\",\n    scopes: [],\n  };\n\n  const sessionId = req.headers[\"mcp-session-id\"] as string | undefined;\n\n  if (sessionId) {\n    // Existing session — route to its transport\n    const session = sessions.get(sessionId);\n    if (!session) {\n      res.writeHead(404, { \"Content-Type\": \"application/json\" });\n      res.end(\n        JSON.stringify({\n          jsonrpc: \"2.0\",\n          error: {\n            code: -32000,\n            message: \"Session not found. The session may have expired or been terminated.\",\n          },\n          id: null,\n        }),\n      );\n      return;\n    }\n\n    await session.transport.handleRequest(authenticatedReq, res);\n    return;\n  }\n\n  // No session ID — this should be an initialize request.\n  // Create a new transport + server pair.\n  const transport = new StreamableHTTPServerTransport({\n    sessionIdGenerator: () => randomUUID(),\n  });\n\n  const server = createMcpServer(options);\n  await server.connect(transport);\n\n  // Set up cleanup on close\n  transport.onclose = () => {\n    const sid = transport.sessionId;\n    /* v8 ignore start */\n    if (sid) {\n      sessions.remove(sid).catch(() => {\n        // Ignore cleanup errors\n      });\n    }\n    /* v8 ignore stop */\n  };\n\n  // Handle the request (this will set transport.sessionId during initialize)\n  await transport.handleRequest(authenticatedReq, res);\n\n  // After handling, register the session if the transport got a session ID\n  /* v8 ignore start */\n  if (transport.sessionId) {\n    sessions.register(transport, server);\n  } else {\n    // No session was created (e.g., invalid request) — clean up\n    await transport.close();\n    await server.close();\n  }\n  /* v8 ignore stop */\n}\n\n/**\n * Create a request handler bound to a SessionManager instance.\n * Convenience factory for server.ts.\n */\nexport function createMcpRequestHandler(\n  sessions: SessionManager,\n  options?: HttpServerOptions,\n): (req: IncomingMessage, res: ServerResponse) => Promise<void> {\n  /* v8 ignore start */\n  return (req, res) => handleMcpRequest(req, res, sessions, options);\n  /* v8 ignore stop */\n}\n\n/**\n * Create h3 app for health check and service info endpoints.\n * The MCP endpoint is handled separately by handleMcpRequest.\n */\nexport function createHealthApp(): H3 {\n  const app = createApp();\n\n  app.get(\n    \"/\",\n    defineEventHandler(() => {\n      return { status: \"ok\", service: \"forge-mcp\", version: VERSION };\n    }),\n  );\n\n  app.get(\n    \"/health\",\n    defineEventHandler(() => {\n      return { status: \"ok\" };\n    }),\n  );\n\n  return app;\n}\n"],"mappings":"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"}

package/dist/http.d.ts

@@ -15,13 +15,20 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { type H3 } from "h3";
 import { SessionManager } from "./sessions.ts";
 export { SessionManager } from "./sessions.ts";
+/**
+ * Options for the HTTP MCP server.
+ */
+export interface HttpServerOptions {
+    /** When true, forge_write tool is not registered and write operations are rejected. */
+    readOnly?: boolean;
+}
 /**
  * Create a configured MCP Server instance for HTTP transport.
  *
  * Unlike stdio, HTTP mode does NOT include forge_configure/forge_get_config
  * because credentials come from the Authorization header per-request.
  */
-export declare function createMcpServer(): Server;
+export declare function createMcpServer(options?: HttpServerOptions): Server;
 /**
  * Handle an MCP request using the Streamable HTTP transport.
  *
@@ -32,13 +39,14 @@ export declare function createMcpServer(): Server;
  * @param req - Node.js IncomingMessage
  * @param res - Node.js ServerResponse
  * @param sessions - Session manager instance (injected)
+ * @param options - Server options (read-only mode, etc.)
  */
-export declare function handleMcpRequest(req: IncomingMessage, res: ServerResponse, sessions: SessionManager): Promise<void>;
+export declare function handleMcpRequest(req: IncomingMessage, res: ServerResponse, sessions: SessionManager, options?: HttpServerOptions): Promise<void>;
 /**
  * Create a request handler bound to a SessionManager instance.
  * Convenience factory for server.ts.
  */
-export declare function createMcpRequestHandler(sessions: SessionManager): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export declare function createMcpRequestHandler(sessions: SessionManager, options?: HttpServerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 /**
  * Create h3 app for health check and service info endpoints.
  * The MCP endpoint is handled separately by handleMcpRequest.

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,EAAiC,KAAK,EAAE,EAAE,MAAM,IAAI,CAAC;AAK5D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAI/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAuDxC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAwFf;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,GACvB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAI9D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,EAAE,CAkBpC"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,EAAiC,KAAK,EAAE,EAAE,MAAM,IAAI,CAAC;AAK5D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAI/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAgFnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAwFf;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAI9D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,EAAE,CAkBpC"}

package/dist/http.js

@@ -1,3 +1,3 @@
-import "./version-Cw8OGt4r.js";
-import { a as SessionManager, i as handleMcpRequest, n as createMcpRequestHandler, r as createMcpServer, t as createHealthApp } from "./http-BJUKoZdb.js";
+import "./version-BmEJceWJ.js";
+import { a as SessionManager, i as handleMcpRequest, n as createMcpRequestHandler, r as createMcpServer, t as createHealthApp } from "./http-w0DliUHY.js";
 export { SessionManager, createHealthApp, createMcpRequestHandler, createMcpServer, handleMcpRequest };

package/dist/index.d.ts

@@ -7,24 +7,35 @@
  *
  * 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";
+export { parseReadOnlyFlag } from "./flags.ts";
+/**
+ * Options for the stdio MCP server.
+ */
+export interface StdioServerOptions {
+    /** When true, forge_write tool is not registered and write operations are rejected. */
+    readOnly?: boolean;
+}
 /**
  * Create and configure the MCP server.
  */
-export declare function createStdioServer(): Server;
+export declare function createStdioServer(options?: StdioServerOptions): Server;
 /**
  * Start the stdio server.
  */
-export declare function startStdioServer(): Promise<void>;
+export declare function startStdioServer(options?: StdioServerOptions): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAkC1C;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAUnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;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"}