gsd-pi 2.51.0-dev.ae8f7cb → 2.52.0-dev.585e355

package/packages/mcp-server/README.md

@@ -0,0 +1,202 @@
+# @gsd/mcp-server
+
+MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP-compatible clients.
+
+Start GSD auto-mode sessions, poll progress, resolve blockers, and retrieve results — all through the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## Installation
+
+```bash
+npm install @gsd/mcp-server
+```
+
+Or with the monorepo workspace:
+
+```bash
+# Already available as a workspace package
+npx gsd-mcp-server
+```
+
+## Configuration
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "gsd": {
+      "command": "npx",
+      "args": ["gsd-mcp-server"],
+      "env": {
+        "GSD_CLI_PATH": "/path/to/gsd"
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "gsd": {
+      "command": "gsd-mcp-server"
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "gsd": {
+      "command": "npx",
+      "args": ["gsd-mcp-server"],
+      "env": {
+        "GSD_CLI_PATH": "/path/to/gsd"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `gsd_execute`
+
+Start a GSD auto-mode session for a project directory.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `projectDir` | `string` | ✅ | Absolute path to the project directory |
+| `command` | `string` | | Command to send (default: `"/gsd auto"`) |
+| `model` | `string` | | Model ID override |
+| `bare` | `boolean` | | Run in bare mode (skip user config) |
+
+**Returns:** `{ sessionId, status: "started" }`
+
+### `gsd_status`
+
+Poll the current status of a running GSD session.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | `string` | ✅ | Session ID from `gsd_execute` |
+
+**Returns:**
+
+```json
+{
+  "status": "running",
+  "progress": { "eventCount": 42, "toolCalls": 15 },
+  "recentEvents": [ ... ],
+  "pendingBlocker": null,
+  "cost": { "totalCost": 0.12, "tokens": { "input": 5000, "output": 2000, "cacheRead": 1000, "cacheWrite": 500 } },
+  "durationMs": 45000
+}
+```
+
+### `gsd_result`
+
+Get the accumulated result of a session. Works for both running (partial) and completed sessions.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | `string` | ✅ | Session ID from `gsd_execute` |
+
+**Returns:**
+
+```json
+{
+  "sessionId": "abc-123",
+  "projectDir": "/path/to/project",
+  "status": "completed",
+  "durationMs": 120000,
+  "cost": { ... },
+  "recentEvents": [ ... ],
+  "pendingBlocker": null,
+  "error": null
+}
+```
+
+### `gsd_cancel`
+
+Cancel a running session. Aborts the current operation and stops the agent process.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | `string` | ✅ | Session ID from `gsd_execute` |
+
+**Returns:** `{ cancelled: true }`
+
+### `gsd_query`
+
+Query GSD project state from the filesystem without an active session. Returns STATE.md, PROJECT.md, requirements, and milestone listing.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `projectDir` | `string` | ✅ | Absolute path to the project directory |
+| `query` | `string` | ✅ | What to query (e.g. `"status"`, `"milestones"`) |
+
+**Returns:**
+
+```json
+{
+  "projectDir": "/path/to/project",
+  "state": "...",
+  "project": "...",
+  "requirements": "...",
+  "milestones": [
+    { "id": "M001", "hasRoadmap": true, "hasSummary": false }
+  ]
+}
+```
+
+### `gsd_resolve_blocker`
+
+Resolve a pending blocker in a session by sending a response to the blocked UI request.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | `string` | ✅ | Session ID from `gsd_execute` |
+| `response` | `string` | ✅ | Response to send for the pending blocker |
+
+**Returns:** `{ resolved: true }`
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GSD_CLI_PATH` | Absolute path to the GSD CLI binary. If not set, the server resolves `gsd` via `which`. |
+
+## Architecture
+
+```
+┌─────────────────┐     stdio      ┌──────────────────┐
+│  MCP Client     │ ◄────────────► │  @gsd/mcp-server │
+│  (Claude Code,  │    JSON-RPC    │                  │
+│   Cursor, etc.) │                │  SessionManager  │
+└─────────────────┘                │       │          │
+                                   │       ▼          │
+                                   │  @gsd/rpc-client │
+                                   │       │          │
+                                   │       ▼          │
+                                   │  GSD CLI (child  │
+                                   │  process via RPC)│
+                                   └──────────────────┘
+```
+
+- **@gsd/mcp-server** — MCP protocol adapter. Translates MCP tool calls into SessionManager operations.
+- **SessionManager** — Manages RpcClient lifecycle. One session per project directory. Tracks events in a ring buffer (last 50), detects blockers, accumulates cost.
+- **@gsd/rpc-client** — Low-level RPC client that spawns and communicates with the GSD CLI process via JSON-RPC over stdio.
+
+## License
+
+MIT

package/packages/mcp-server/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@gsd/mcp-server",
+  "version": "2.51.0",
+  "description": "MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP clients",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "gsd-mcp-server": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/mcp-server.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@gsd/rpc-client": "*",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist"
+  ]
+}

package/packages/mcp-server/src/cli.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * @gsd/mcp-server CLI — stdio transport entry point.
+ *
+ * Connects the MCP server to stdin/stdout for use by Claude Code,
+ * Cursor, and other MCP-compatible clients.
+ */
+
+import { SessionManager } from './session-manager.js';
+import { createMcpServer } from './server.js';
+
+const MCP_PKG = '@modelcontextprotocol/sdk';
+
+async function main(): Promise<void> {
+  const sessionManager = new SessionManager();
+
+  // Create the configured MCP server with all 6 tools
+  const { server } = await createMcpServer(sessionManager);
+
+  // Dynamic import for StdioServerTransport (same TS subpath workaround)
+  const { StdioServerTransport } = await import(`${MCP_PKG}/server/stdio.js`);
+  const transport = new StdioServerTransport();
+
+  // Cleanup handler — stop all sessions before exiting
+  let cleaningUp = false;
+  async function cleanup(): Promise<void> {
+    if (cleaningUp) return;
+    cleaningUp = true;
+    process.stderr.write('[gsd-mcp-server] Shutting down...\n');
+    try {
+      await sessionManager.cleanup();
+    } catch {
+      // swallow cleanup errors
+    }
+    try {
+      await server.close();
+    } catch {
+      // swallow close errors
+    }
+    process.exit(0);
+  }
+
+  process.on('SIGTERM', () => void cleanup());
+  process.on('SIGINT', () => void cleanup());
+
+  // Handle stdin end — MCP client disconnected
+  process.stdin.on('end', () => void cleanup());
+
+  // Connect and start serving
+  try {
+    await server.connect(transport);
+    process.stderr.write('[gsd-mcp-server] MCP server started on stdio\n');
+  } catch (err) {
+    process.stderr.write(
+      `[gsd-mcp-server] Fatal: failed to start — ${err instanceof Error ? err.message : String(err)}\n`
+    );
+    await sessionManager.cleanup();
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `[gsd-mcp-server] Fatal: ${err instanceof Error ? err.message : String(err)}\n`
+  );
+  process.exit(1);
+});

package/packages/mcp-server/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @gsd/mcp-server — MCP server for GSD orchestration.
+ */
+
+export { SessionManager } from './session-manager.js';
+export { createMcpServer } from './server.js';
+export type {
+  SessionStatus,
+  ManagedSession,
+  ExecuteOptions,
+  PendingBlocker,
+  CostAccumulator,
+} from './types.js';
+export { MAX_EVENTS, INIT_TIMEOUT_MS } from './types.js';