@igor-olikh/openspec-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# OpenSpec MCP Server (AI Assistant Plugin)
+
+Welcome! This is a simple bridge (plugin) that connects **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** to your favorite AI coding assistant (like **Codex**, **Claude Desktop**, or **Cursor**).
+
+## What is this and why do I need it?
+When you want your AI to build a new feature, you usually just type it into the chat. But as projects grow, the AI can forget things, get confused, or write messy code.
+
+**OpenSpec** is a system that solves this. It forces the AI to create a clear "specification" (a plan) before it writes any code. It organizes your plan into neat folders (`proposal`, `design`, `tasks`) so you can review it.
+
+However, your AI doesn't automatically know how to use OpenSpec. **That is what this server does!** It gives your AI the "tools" it needs to automatically create these folders, list tasks, and mark them as complete as it writes code for you.
+
+---
+
+## How to Connect Your AI
+
+To use this, you need to tell your AI assistant where this server is located. The setup simply depends on which AI assistant you use.
+
+### Option 1: Connecting to Codex (Recommended)
+
+Codex has a built-in user interface to easily add these plugins. 
+You can add it quickly by running this terminal command:
+
+```bash
+codex mcp add openspec-server node /Users/igorolikh/Documents/projects/private/openspec-mcp-server/dist/index.js
+```
+
+**Or, manually through the Codex User Interface:**
+1. Open the **"Connect to a custom MCP"** box in Codex.
+2. **Name**: `openspec` 
+3. **Mode**: Leave as `STDIO`
+4. **Command to launch**: `node`
+5. **Arguments**: Click `+ Add argument` and paste exactly:
+   `/Users/igorolikh/Documents/projects/private/openspec-mcp-server/dist/index.js`
+6. **Working directory**: Leave this blank! (This allows Codex to dynamically use OpenSpec inside whichever project you currently have open).
+7. Save it!
+
+### Option 2: Connecting to Claude Desktop App
+
+If you prefer using the Claude Desktop application:
+1. Open your Claude configuration file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json` on Mac).
+2. Add the `openspec` server to it:
+
+```json
+{
+  "mcpServers": {
+    "openspec": {
+      "command": "node",
+      "args": [
+        "/Users/igorolikh/Documents/projects/private/openspec-mcp-server/dist/index.js"
+      ]
+    }
+  }
+}
+```
+3. Save the file and restart Claude Desktop.
+
+---
+
+## How do I use it?
+
+Once connected, you don't need to do anything technical. You just talk to your AI like normal, but ask it to use OpenSpec!
+
+**Example Chat Prompts:**
+* *"Hey Codex, I want to add a dark mode feature to this application. Please use OpenSpec to propose and validate it."*
+* *"What is the OpenSpec status of our current project?"*
+* *"List all the OpenSpec changes we are currently working on."*
+
+The AI will automatically use the tools below to handle the rest!
+
+---
+
+## For Developers (Under the Hood)
+
+This server exposes the official `@fission-ai/openspec` CLI commands as Model Context Protocol (MCP) JSON-RPC tools.
+
+**Available AI Tools:**
+- `openspec_init`: Starts OpenSpec in a project.
+- `openspec_new_change`: Creates a folder for a new feature proposal.
+- `openspec_status`: Checks how much of the feature is done.
+- `openspec_validate`: Checks if the code matches the plan.
+- `openspec_archive`: Marks the feature as 100% completed.
+- `openspec_list`: Shows all current tasks.
+- `openspec_show`: Reads a specific task.
+- `openspec_update`: Updates OpenSpec rules.
+- `openspec_instructions`: Reads AI instructions for building parts of the plan.
+
+### Development Setup
+If you want to modify this server's code:
+1. `npm install` (Installs dependencies)
+2. `npm run build` (Compiles the code)
+3. `npm run start` (Runs the server to test standard input/output)

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { OpenSpecMCPServer } from './server.js';
+import path from 'path';
+async function main() {
+    const args = process.argv.slice(2);
+    const projectPath = args[0] || process.cwd();
+    const resolvedPath = path.resolve(projectPath);
+    console.error(`Starting OpenSpec MCP Server for project: ${resolvedPath}`);
+    const server = new OpenSpecMCPServer();
+    await server.initialize(resolvedPath);
+    // Handle graceful shutdown
+    const shutdown = async () => {
+        await server.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,73 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { getTools, handleToolCall } from './tools.js';
+export class OpenSpecMCPServer {
+    server;
+    projectPath = process.cwd();
+    constructor() {
+        this.server = new Server({
+            name: 'openspec-mcp-server',
+            version: '1.0.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            // Provide dynamic tools or static ones
+            return {
+                tools: getTools(),
+            };
+        });
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                const result = await handleToolCall(request.params.name, request.params.arguments || {}, this.projectPath);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: result.message || 'Tool executed successfully',
+                        },
+                        ...(result.stdout ? [{ type: 'text', text: `Output:\n${result.stdout}` }] : []),
+                        ...(result.stderr ? [{ type: 'text', text: `Error Output:\n${result.stderr}` }] : [])
+                    ],
+                    isError: !result.success
+                };
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InternalError, error.message);
+            }
+        });
+    }
+    async initialize(projectPath) {
+        this.projectPath = projectPath;
+        // Connect to stdio transport
+        const transport = new StdioServerTransport();
+        transport.onclose = async () => {
+            await this.stop();
+            process.exit(0);
+        };
+        await this.server.connect(transport);
+        process.stdin.on('end', async () => {
+            await this.stop();
+            process.exit(0);
+        });
+        process.stdin.on('error', async (error) => {
+            console.error('stdin error:', error);
+            await this.stop();
+            process.exit(1);
+        });
+    }
+    async stop() {
+        try {
+            await this.server.close();
+        }
+        catch (error) {
+            console.error('Error closing server:', error);
+        }
+    }
+}

package/dist/tools.js

@@ -0,0 +1,197 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+const OPENSPEC_CMD = 'npx --yes @fission-ai/openspec';
+export function getTools() {
+    return [
+        {
+            name: 'openspec_init',
+            description: 'Initialize OpenSpec in your project',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+                required: []
+            }
+        },
+        {
+            name: 'openspec_update',
+            description: 'Update OpenSpec instruction files',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+                required: []
+            }
+        },
+        {
+            name: 'openspec_list',
+            description: 'List items (changes or specs). Returns a JSON array when --json is used.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    specs: { type: 'boolean', description: 'List specs instead of changes' },
+                    json: { type: 'boolean', description: 'Output as JSON', default: true }
+                },
+                required: []
+            }
+        },
+        {
+            name: 'openspec_show',
+            description: 'Show a change or spec. Use type to specify if it is ambiguous.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    itemName: { type: 'string', description: 'Name of the item to show' },
+                    type: { type: 'string', description: 'Item type: "change" or "spec"' },
+                    json: { type: 'boolean', description: 'Output as JSON', default: true }
+                },
+                required: ['itemName']
+            }
+        },
+        {
+            name: 'openspec_validate',
+            description: 'Validate a change proposal or spec',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    itemName: { type: 'string', description: 'Name of the change to validate (optional)' },
+                    all: { type: 'boolean', description: 'Validate all changes and specs' },
+                    strict: { type: 'boolean', description: 'Enable strict validation mode' },
+                    json: { type: 'boolean', description: 'Output as JSON' }
+                },
+                required: []
+            }
+        },
+        {
+            name: 'openspec_archive',
+            description: 'Archive a completed change and update main specs',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    changeName: { type: 'string', description: 'Name of the change to archive' },
+                    skipSpecs: { type: 'boolean', description: 'Skip spec updates' }
+                },
+                required: ['changeName']
+            }
+        },
+        {
+            name: 'openspec_new_change',
+            description: 'Create a new change directory',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Name of the change' },
+                    description: { type: 'string', description: 'Description to add to README.md' }
+                },
+                required: ['name']
+            }
+        },
+        {
+            name: 'openspec_status',
+            description: 'Display artifact completion status for a change',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    changeName: { type: 'string', description: 'Change name to show status for' },
+                    json: { type: 'boolean', description: 'Output as JSON', default: true }
+                },
+                required: []
+            }
+        },
+        {
+            name: 'openspec_instructions',
+            description: 'Output enriched instructions for an artifact or apply',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    artifact: { type: 'string', description: 'Artifact name (e.g. design.md, tasks.md) or "apply"' },
+                    changeName: { type: 'string', description: 'Change name' },
+                    json: { type: 'boolean', description: 'Output as JSON' }
+                },
+                required: ['artifact']
+            }
+        }
+    ];
+}
+export async function handleToolCall(name, args, cwd) {
+    const runOpenSpec = async (callArgs) => {
+        const cmd = `${OPENSPEC_CMD} ${callArgs.join(' ')}`;
+        try {
+            const { stdout, stderr } = await execAsync(cmd, { cwd });
+            return { success: true, stdout, stderr, message: `Ran: ${cmd}` };
+        }
+        catch (error) {
+            return {
+                success: false,
+                stdout: error.stdout,
+                stderr: error.stderr,
+                message: `Command failed: ${error.message}`
+            };
+        }
+    };
+    switch (name) {
+        case 'openspec_init': {
+            return await runOpenSpec(['init', '--no-interactive']);
+        }
+        case 'openspec_update': {
+            return await runOpenSpec(['update']);
+        }
+        case 'openspec_list': {
+            const cmdArgs = ['list'];
+            if (args.specs)
+                cmdArgs.push('--specs');
+            if (args.json !== false)
+                cmdArgs.push('--json');
+            return await runOpenSpec(cmdArgs);
+        }
+        case 'openspec_show': {
+            const cmdArgs = ['show', `"${args.itemName}"`];
+            if (args.type)
+                cmdArgs.push('--type', args.type);
+            if (args.json !== false)
+                cmdArgs.push('--json');
+            return await runOpenSpec(cmdArgs);
+        }
+        case 'openspec_validate': {
+            const cmdArgs = ['validate'];
+            if (args.itemName)
+                cmdArgs.push(`"${args.itemName}"`);
+            if (args.all)
+                cmdArgs.push('--all');
+            if (args.strict)
+                cmdArgs.push('--strict');
+            if (args.json !== false)
+                cmdArgs.push('--json');
+            return await runOpenSpec(cmdArgs);
+        }
+        case 'openspec_archive': {
+            const cmdArgs = ['archive', `"${args.changeName}"`, '--yes'];
+            if (args.skipSpecs)
+                cmdArgs.push('--skip-specs');
+            return await runOpenSpec(cmdArgs);
+        }
+        case 'openspec_new_change': {
+            const cmdArgs = ['new', 'change', `"${args.name}"`];
+            if (args.description)
+                cmdArgs.push('--description', `"${args.description}"`);
+            return await runOpenSpec(cmdArgs);
+        }
+        case 'openspec_status': {
+            const cmdArgs = ['status'];
+            if (args.changeName)
+                cmdArgs.push('--change', `"${args.changeName}"`);
+            if (args.json !== false)
+                cmdArgs.push('--json');
+            return await runOpenSpec(cmdArgs);
+        }
+        case 'openspec_instructions': {
+            const cmdArgs = ['instructions', `"${args.artifact}"`];
+            if (args.changeName)
+                cmdArgs.push('--change', `"${args.changeName}"`);
+            if (args.json !== false)
+                cmdArgs.push('--json');
+            return await runOpenSpec(cmdArgs);
+        }
+        default:
+            return { success: false, message: `Unknown tool: ${name}` };
+    }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@igor-olikh/openspec-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for OpenSpec",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "openspec-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}