Implement OpenSpec as an MCP Server for Universal AI Assistant Integration

[luoxiner]

Hello, everyone.
I propose implementing OpenSpec as a Model Context Protocol (MCP) server. This would enable any MCP-compatible AI assistant (Claude, GitHub Copilot, Amazon Q, etc.) to directly interact with OpenSpec's change proposals, specifications, and project context—making spec-driven development workflows available across the entire AI assistant ecosystem beyond just command-line tools.We propose implementing OpenSpec as a Model Context Protocol (MCP) server. This would enable any MCP-compatible AI assistant (Claude, GitHub Copilot, Amazon Q, etc.) to directly interact with OpenSpec's change proposals, specifications, and project context—making spec-driven development workflows available across the entire AI assistant ecosystem beyond just command-line tools.

[luoxiner]

Motivation

OpenSpec currently supports spec-driven development through integrations with specific AI tools (Claude Code, Cursor, Cline, Codex, etc.) via slash commands and custom workflows. However, the Model Context Protocol (MCP) provides a platform-agnostic standard that could dramatically expand OpenSpec's accessibility:

1. Universal Assistant Support: Enable OpenSpec integration for any MCP-compatible AI tool, including Claude via Claude.ai, new emerging AI assistants, and enterprise identity providers integrating MCP servers.

2. Ecosystem-Agnostic Access: Rather than implementing OpenSpec integrations tool-by-tool, an MCP server becomes the single source of truth that works everywhere MCP is supported.

3. Enhanced Cross-Tool Workflows: Teams using mixed AI tooling (Claude Code in IDE, Claude.ai in browser, Amazon Q in terminal) could share and collaborate on the same OpenSpec project context seamlessly.

4. Better Developer Experience: Developers get OpenSpec capabilities in environments where custom slash commands aren't available—like Claude.ai web interface, GitHub Copilot Chat in VS Code, or any emerging MCP-compatible platform.

5. Reduced Maintenance Burden: One MCP server implementation replaces the need for tool-specific integrations, making OpenSpec more sustainable and easier to maintain as new AI tools emerge.

6. Enterprise Integration: Organizations can integrate OpenSpec into their MCP-compatible infrastructure (private MCP servers, enterprise AI platforms) without waiting for each tool to implement custom support.

What OpenSpec Brings to MCP

OpenSpec provides a lightweight, pragmatic workflow for spec-driven development with these core capabilities:

• Proposal → Apply → Archive Workflow: A three-phase change management system that keeps specs and implementations in sync
• Unified Spec Management: Maintains source-of-truth specs in openspec/specs/ while proposals live in openspec/changes/
• Multi-Tool Agnostic: Already works with 15+ AI coding assistants through AGENTS.md convention and slash commands
• Lightweight YAML Specs: Scenario-based specifications that are both human-readable and AI-understandable

Technical Proposal

MCP Server: OpenSpec Context Protocol

We propose an MCP server that exposes OpenSpec project structure and workflows as MCP resources and tools:

Resources

Expose OpenSpec project state as queryable resources:

• openspec://project - Project metadata from openspec/project.md
• openspec://specs/{domain} - Current specifications by domain
• openspec://changes/{change-id} - Active change proposals and their details
• openspec://changes/{change-id}/tasks - Implementation task lists
• openspec://archive/{change-id} - Archived changes for historical reference
• openspec://agents - AI assistant configuration from AGENTS.md

Tools

Provide spec-driven workflow operations:

• list-specs - List all specifications and domains
• list-changes - List active, archived, or filtered changes
• get-change - Retrieve full change details (proposal, tasks, design, deltas)
• validate-change - Run OpenSpec validation on a change
• get-project-context - Retrieve project conventions and tech stack
• show-delta - Display spec delta showing ADDED/MODIFIED/REMOVED requirements
• compare-specs - Show diff between current spec and proposed changes

Prompts

Provide pre-written guidance for spec-driven workflows:

• draft-proposal - Guidance for creating change proposals
• review-proposal - Checklist for proposal review and iteration
• implement-tasks - Implementation workflow from task list
• archive-change - Post-completion change archival workflow

Implementation Architecture

MCP Client (Claude, GitHub Copilot, Amazon Q, etc.)
    ↓
MCP Server (OpenSpec-MCP)
    ├─ Resource Manager (reads openspec/ directory)
    ├─ Validator (runs openspec validate logic)
    ├─ Project Context Loader (parses specs, AGENTS.md)
    └─ FileSystem Interface (local project access)

[pexa-dnugent]

Love the idea, and certainly practical in a locally running stdio server, although to be honest, I don't see that much of a benefit over letting the agent do its thing within the project. Agents are generally really good at sorting out what needs doing and where to find things. And you really do need the OpenSpec documents in the project repository.

For any sort of remote server (http, SSE, websockets) this may be a little less straight-forward, having to remotely manage documents. You see, an mcp has no direct way to manipulate files on a client/local filesystem – at least it has to assume it cannot do so.

So, kudos for the idea, but having been down this road before, I can also see hurdles.

[conrad621]

Can this project be regarded as a feasible solution?
https://github.com/Pimzino/spec-workflow-mcp

[TabishB]

There are definitely some benefits of having MCP -> Mainly around interoperability.

My view here is in line with gh cli vs Github MCP. The Github MCP does everything the gh cli can do but comes at the cost of extra uneeded context being loaded in every session. I've been relucatant to add in MCP because this would add context bloat for developers even when they aren't using OpenSpec.

Anthropic themselves see this as a big problem which they've documented in this post here: https://www.anthropic.com/engineering/code-execution-with-mcp

I haven't had a chance to try the new updated way that MCP works and maybe it can make sense with some of those fixes there. (Unsure if every coding agent has adopted this approach yet though)

Let me know if there's any strong arguments for MCP over just providing the agent a cli they can use.

[luoxiner]

Can this project be regarded as a feasible solution? https://github.com/Pimzino/spec-workflow-mcp

Awesome project! That's exactly what I need.

[luoxiner]

There are definitely some benefits of having MCP -> Mainly around interoperability.

My view here is in line with gh cli vs Github MCP. The Github MCP does everything the gh cli can do but comes at the cost of extra uneeded context being loaded in every session. I've been relucatant to add in MCP because this would add context bloat for developers even when they aren't using OpenSpec.

Anthropic themselves see this as a big problem which they've documented in this post here: https://www.anthropic.com/engineering/code-execution-with-mcp

I haven't had a chance to try the new updated way that MCP works and maybe it can make sense with some of those fixes there. (Unsure if every coding agent has adopted this approach yet though)

Let me know if there's any strong arguments for MCP over just providing the agent a cli they can use.

+1. CLI is very useful for both agents and humans, and can be integrated into shell scripts for batch data processing.

[JonnyDB]

Well, I got bored and has some cursor credits to burn. Here you go #379