@igor-olikh/openspec-mcp-server 2.1.3 → 2.1.5

package/dist/cache.js

@@ -0,0 +1,78 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/** Build a composite cache key to avoid collisions between changes and specs with the same name */
+export function cacheKey(type, name) {
+    return `${type}:${name}`;
+}
+/** Look up a cache entry by name, with optional type filter. If type is omitted, prefers changes over specs. */
+export function lookupEntry(cache, name, type) {
+    if (type) {
+        return cache.entries.get(cacheKey(type, name));
+    }
+    // Default: prefer change, fall back to spec
+    return cache.entries.get(cacheKey('change', name)) ?? cache.entries.get(cacheKey('spec', name));
+}
+export function buildCache(projectPath) {
+    const cache = {
+        entries: new Map(),
+        lastRefresh: Date.now()
+    };
+    refreshCache(cache, projectPath);
+    return cache;
+}
+export function refreshCache(cache, projectPath) {
+    cache.entries.clear();
+    cache.lastRefresh = Date.now();
+    const openspecDir = path.join(projectPath, 'openspec');
+    if (!fs.existsSync(openspecDir)) {
+        return;
+    }
+    const dirsToScan = [
+        { type: 'change', dirName: 'changes' },
+        { type: 'spec', dirName: 'specs' }
+    ];
+    for (const { type, dirName } of dirsToScan) {
+        const dir = path.join(openspecDir, dirName);
+        if (!fs.existsSync(dir))
+            continue;
+        try {
+            const subdirs = fs.readdirSync(dir, { withFileTypes: true })
+                .filter(dirent => dirent.isDirectory())
+                .map(dirent => dirent.name);
+            for (const name of subdirs) {
+                const entryPath = path.join(dir, name);
+                try {
+                    const files = fs.readdirSync(entryPath, { withFileTypes: true })
+                        .filter(dirent => dirent.isFile())
+                        .map(dirent => dirent.name);
+                    cache.entries.set(cacheKey(type, name), {
+                        name,
+                        type,
+                        path: entryPath,
+                        files
+                    });
+                }
+                catch (err) {
+                    // Ignore unreadable dirs
+                }
+            }
+        }
+        catch (err) {
+            // Ignore unreadable dirs
+        }
+    }
+}
+export function readSpecFile(cache, projectPath, name, fileType, type) {
+    const entry = lookupEntry(cache, name, type);
+    if (!entry)
+        return null;
+    if (!entry.files.includes(fileType))
+        return null;
+    const filePath = path.join(entry.path, fileType);
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return null;
+    }
+}

package/dist/server.js

@@ -2,8 +2,10 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { getTools, handleToolCall } from './tools.js';
+import { buildCache } from './cache.js';
 export class OpenSpecMCPServer {
     server;
+    cache = null;
     projectPath = process.cwd();
     constructor() {
         this.server = new Server({
@@ -62,7 +64,7 @@ Follow this workflow exactly:
         });
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
-                const result = await handleToolCall(request.params.name, request.params.arguments || {}, this.projectPath);
+                const result = await handleToolCall(request.params.name, request.params.arguments || {}, this.projectPath, this.cache);
                 return {
                     content: [
                         {
@@ -82,6 +84,7 @@ Follow this workflow exactly:
     }
     async initialize(projectPath) {
         this.projectPath = projectPath;
+        this.cache = buildCache(projectPath);
         // Connect to stdio transport
         const transport = new StdioServerTransport();
         transport.onclose = async () => {

package/dist/tools.js

@@ -1,5 +1,6 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { readSpecFile, refreshCache, lookupEntry } from './cache.js';
 const execAsync = promisify(exec);
 const OPENSPEC_CMD = 'npx --yes @fission-ai/openspec';
 export function getTools() {
@@ -109,10 +110,40 @@ export function getTools() {
                 },
                 required: ['artifact']
             }
+        },
+        {
+            name: 'openspec_read_file',
+            description: 'Read any OpenSpec artifact directly. Much faster than show — use this when you need file contents.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Change or spec name (e.g. "add-dark-mode")' },
+                    fileType: {
+                        type: 'string',
+                        description: 'File to read',
+                        enum: ['proposal.md', 'design.md', 'tasks.md', '.openspec.yaml']
+                    },
+                    type: {
+                        type: 'string',
+                        description: 'Item type to disambiguate if a change and spec share the same name. If omitted, prefers changes.',
+                        enum: ['change', 'spec']
+                    }
+                },
+                required: ['name', 'fileType']
+            }
+        },
+        {
+            name: 'openspec_refresh_cache',
+            description: 'Force refresh the cached directory listing. Use if you suspect changes were made outside OpenSpec tools.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+                required: []
+            }
         }
     ];
 }
-export async function handleToolCall(name, args, cwd) {
+export async function handleToolCall(name, args, cwd, cache) {
     const runOpenSpec = async (callArgs) => {
         const cmd = `${OPENSPEC_CMD} ${callArgs.join(' ')}`;
         try {
@@ -130,12 +161,27 @@ export async function handleToolCall(name, args, cwd) {
     };
     switch (name) {
         case 'openspec_init': {
-            return await runOpenSpec(['init', '--no-interactive']);
+            const res = await runOpenSpec(['init', '--no-interactive']);
+            refreshCache(cache, cwd);
+            return res;
         }
         case 'openspec_update': {
-            return await runOpenSpec(['update']);
+            const res = await runOpenSpec(['update']);
+            refreshCache(cache, cwd);
+            return res;
         }
         case 'openspec_list': {
+            if (args.json !== false && cache && cache.entries.size > 0) {
+                const typeFilter = args.specs ? 'spec' : 'change';
+                const items = Array.from(cache.entries.values())
+                    .filter(e => e.type === typeFilter)
+                    .map(e => ({ name: e.name, type: e.type, files: e.files }));
+                return {
+                    success: true,
+                    stdout: JSON.stringify({ [args.specs ? 'specs' : 'changes']: items }, null, 2),
+                    message: 'Served from cache'
+                };
+            }
             const cmdArgs = ['list'];
             if (args.specs)
                 cmdArgs.push('--specs');
@@ -167,13 +213,17 @@ export async function handleToolCall(name, args, cwd) {
             const cmdArgs = ['archive', `"${args.changeName}"`, '--yes'];
             if (args.skipSpecs)
                 cmdArgs.push('--skip-specs');
-            return await runOpenSpec(cmdArgs);
+            const res = await runOpenSpec(cmdArgs);
+            refreshCache(cache, cwd);
+            return res;
         }
         case 'openspec_new_change': {
             const cmdArgs = ['new', 'change', `"${args.name}"`];
             if (args.description)
                 cmdArgs.push('--description', `"${args.description}"`);
-            return await runOpenSpec(cmdArgs);
+            const res = await runOpenSpec(cmdArgs);
+            refreshCache(cache, cwd);
+            return res;
         }
         case 'openspec_status': {
             const cmdArgs = ['status'];
@@ -191,6 +241,21 @@ export async function handleToolCall(name, args, cwd) {
                 cmdArgs.push('--json');
             return await runOpenSpec(cmdArgs);
         }
+        case 'openspec_read_file': {
+            const entry = lookupEntry(cache, args.name, args.type);
+            if (!entry) {
+                return { success: false, message: `No change or spec named '${args.name}' found. Run openspec_list to see available items.` };
+            }
+            const content = readSpecFile(cache, cwd, args.name, args.fileType, args.type);
+            if (content === null) {
+                return { success: false, message: `File '${args.fileType}' does not exist for '${args.name}'. Available files: ${entry.files.join(', ')}` };
+            }
+            return { success: true, stdout: content, message: `Read ${args.fileType} from ${entry.type}:${args.name}` };
+        }
+        case 'openspec_refresh_cache': {
+            refreshCache(cache, cwd);
+            return { success: true, message: 'Cache refreshed successfully.' };
+        }
         default:
             return { success: false, message: `Unknown tool: ${name}` };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igor-olikh/openspec-mcp-server",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "An MCP server that connects OpenSpec to AI assistants like Codex, Claude, and Cursor.",
   "main": "dist/index.js",
   "type": "module",