@igor-olikh/openspec-mcp-server 1.0.4 → 1.1.0

package/README.md

@@ -116,3 +116,14 @@ 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)
+
+---
+
+## Upcoming Features (Planned via OpenSpec)
+This server is actively evolving! The following features are currently being designed utilizing OpenSpec and will be implemented soon:
+
+- ⏳ **Built-in MCP Prompts**: A pre-made "cheat sheet" standard prompt (e.g., `openspec_kickoff`) that automatically injects massive hidden rules into your AI, steering it to behave perfectly when generating structured features.
+- ⏳ **Structured JSON Outputs**: Replacing raw, colorful terminal output with parsed JavaScript objects, preventing the AI from misreading states and reducing hallucinations.
+- ⏳ **Direct File Readers**: Highly targeted tools (e.g., `openspec_read_active_proposal`) allowing the AI to skip hunting around your directory structure to read active designs.
+- ⏳ **Smart Error Handling**: Coaching the LLM when OpenSpec validations fail (e.g. intercepting terminal errors to output: *"Hey, you forgot the 'Tasks' header in design.md"*).
+

package/openspec/changes/add-direct-file-readers/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02

package/openspec/changes/add-direct-file-readers/design.md

@@ -0,0 +1,8 @@
+# Design: Direct File Readers
+
+## Architecture
+- We will resolve the active change path dynamically inside NodeJS and use standard filesystem `fs` tools to read it out completely.
+
+## Technical Details
+- Read `.openspec` internal pointers or execute a silent status check to find out which feature is active.
+- Target `openspec/changes/{feature_name}/proposal|design.md`.

package/openspec/changes/add-direct-file-readers/proposal.md

@@ -0,0 +1,12 @@
+# Proposal: Direct File Reading Tools
+
+## What we are going to do
+We are going to add specific, highly targeted tools to the MCP server like `openspec_read_active_proposal` and `openspec_read_active_design`. 
+
+## Why we need this
+Currently, if the AI wants to read the active proposal, it has to first figure out what the active change is, guess the directory structure (`openspec/changes/feature/proposal.md`), and use a generic system file reader to fetch it. This wastes tokens, takes multiple chat turns, and invites errors. By giving the AI a direct tool, it gets exactly the context it needs in a single action.
+
+## How we will do it
+1. Intercept the standard `openspec status` to dynamically read which feature branch is currently marked as "active".
+2. Add a new tool called `openspec_read_active_spec` in `src/tools.ts`.
+3. When the AI calls this tool, we use Node's `fs.readFileSync` to grab the content of the `proposal.md` or `design.md` for that active feature, and return the raw text back to the AI.

package/openspec/changes/add-direct-file-readers/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+- [ ] Add `openspec_read_active_proposal` configuration array logic.
+- [ ] Add `openspec_read_active_design` configuration.
+- [ ] Write the targeted wrapper `fs.readFileSync` hook in `src/tools.ts`.

package/openspec/changes/add-json-output/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02

package/openspec/changes/add-json-output/design.md

@@ -0,0 +1,8 @@
+# Design: Structured JSON Outputs
+
+## Architecture
+- The MCP server needs to receive clean data so it doesn't just pipe ANSI colored terminal strings to the AI.
+
+## Technical Details
+- Modify `execAsync` execution calls.
+- If OpenSpec CLI supports JSON natively, inject the CLI flag. Otherwise, clean standard stdout to extract objects.

package/openspec/changes/add-json-output/proposal.md

@@ -0,0 +1,12 @@
+# Proposal: Structured JSON Outputs
+
+## What we are going to do
+We are going to change our tool wrappers (`openspec_list`, `openspec_status`, etc.) to request structured JSON output from the underlying OpenSpec CLI, rather than taking the raw colorful terminal text.
+
+## Why we need this
+When the AI (like Codex) asks for the status of a project, handing it raw terminal text (which often includes weird color codes or spacing) makes it harder for the AI to understand. AI models reason exponentially better when they are fed clean, predictable JSON objects representing the exact status of files and tasks. This minimizes hallucinations and mistakes.
+
+## How we will do it
+1. Modify `src/tools.ts` to append a `--json` or `--format=json` flag when calling `execAsync` for the Fission-AI OpenSpec package.
+2. Parse that JSON output natively in our server (`JSON.parse(stdout)`).
+3. Format and return it cleanly to the MCP protocol response. If OpenSpec doesn't yet support `--json`, we will write a tiny parser script to clean the terminal text into a structured response.

package/openspec/changes/add-json-output/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+- [ ] Inspect underlying OpenSpec CLI for JSON output flags.
+- [ ] Update tool handlers in `src/tools.ts`.
+- [ ] Upgrade MCP response format to structure the textual JSON payload properly.

package/openspec/changes/add-mcp-prompts/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02

package/openspec/changes/add-mcp-prompts/design.md

@@ -0,0 +1,8 @@
+# Design: Built-in MCP Prompts
+
+## Architecture
+- Use `@modelcontextprotocol/sdk` to hook into `server.setRequestHandler(ListPromptsRequestSchema, ...)` and `server.setRequestHandler(GetPromptRequestSchema, ...)`.
+- Define an `openspec_kickoff` prompt definition containing the rules of engagement.
+
+## Technical Details
+- The prompt context must be robust enough to instruct the LLM on exactly which tools to call first (e.g. `openspec_init` if missing, then `openspec_list`).

package/openspec/changes/add-mcp-prompts/proposal.md

@@ -0,0 +1,13 @@
+# Proposal: Built-in MCP Prompts
+
+## What we are going to do
+We want to add a feature called "MCP Prompts" directly into the server. This gives the AI a pre-made "cheat sheet" standard prompt (like `openspec_kickoff`) that provides a massive set of hidden rules on how it should behave when using OpenSpec.
+
+## Why we need this
+Right now, every time you chat with Codex or Claude, you have to manually tell it: "Please use OpenSpec, remember to create a proposal first, don't write code until the design is done." 
+If you forget to say that, the AI might act wildly. With MCP Prompts, the AI is instantly injected with all the necessary system instructions and guardrails automatically when you click the prompt.
+
+## How we will do it
+1. Use the `@modelcontextprotocol/sdk` to define a `ListPromptsRequest` and `GetPromptRequest` handler in our `src/server.ts`.
+2. Write a deeply robust instructional prompt text (the "cheat sheet").
+3. Expose it so that Codex users can see it as a clickable Quick Action in their chat UI.

package/openspec/changes/add-mcp-prompts/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+- [ ] Implement `ListPromptsRequestSchema` in `src/server.ts`.
+- [ ] Implement `GetPromptRequestSchema` returning the massive text instruction string.
+- [ ] Test in Codex UI using the Quick Action.

package/openspec/changes/add-smart-error-handling/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-02

package/openspec/changes/add-smart-error-handling/design.md

@@ -0,0 +1,8 @@
+# Design: Smart Error Handling
+
+## Architecture
+- By intercepting terminal crash errors natively in TS, we output standard JSON-RPC text responses to the LLM masking the raw crash.
+
+## Technical Details
+- Parse `stderr`.
+- If regex matches validation failure regarding markdown structure, rewrite the error.

package/openspec/changes/add-smart-error-handling/proposal.md

@@ -0,0 +1,12 @@
+# Proposal: Smart Error Handling
+
+## What we are going to do
+We want to dramatically improve the feedback the AI gets when it runs an invalid command. If `openspec_validate` fails, rather than just returning "Command Failed: exit code 1", we will intercept the exact error and give the AI a helpful, coaching reply.
+
+## Why we need this
+If the AI incorrectly writes a spec (e.g. it forgets to include the "Tasks" header in the design file), OpenSpec validation turns red and fails. The AI sometimes gets confused by raw CLI errors. If we coach the AI ("Hey AI, your validation failed specifically because you forgot the 'Tasks' header in design.md"), it can immediately fix it without human intervention! This creates a self-healing AI loop.
+
+## How we will do it
+1. In `src/tools.ts`, inside the `catch (error)` block for `execAsync`, we will read `error.stderr` instead of just crashing.
+2. We will analyze the `stderr` string. If it contains "missing section", we map it to a friendly message.
+3. We will return this friendly, parsed diagnostic string natively through the standard MCP response payload back to the assistant.

package/openspec/changes/add-smart-error-handling/tasks.md

@@ -0,0 +1,5 @@
+# Tasks
+
+- [ ] Open `src/tools.ts`.
+- [ ] Expand the `catch` argument block around the primary execution.
+- [ ] Programmatically map string heuristics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igor-olikh/openspec-mcp-server",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "An MCP server that connects OpenSpec to AI assistants like Codex, Claude, and Cursor.",
   "main": "dist/index.js",
   "type": "module",
@@ -29,6 +29,7 @@
     "dev": "tsx src/index.ts"
   },
   "dependencies": {
+    "@igor-olikh/openspec-mcp-server": "^1.0.4",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "zod": "^3.23.8"
   },