kspec-mcp-server

Spec-as-a-Service MCP Server — Enables AI agents to use software development specs without exposing markdown files.

Quick Start

Add to your ~/.claude.json:

{
  "mcpServers": {
    "kspec": {
      "command": "npx",
      "args": ["-y", "kspec-mcp-server@latest"]
    }
  }
}

Restart Claude Code. Done.

What It Does

This MCP Server exposes templates, skills and workflows as structured JSON tools, resources and prompts — never as raw markdown documents.

Principles

• No Markdown Exposed: All specs are stored as structured JSON
• Strict Validation: Zod schemas ensure data integrity
• Parameterizable Templates: Specs generated dynamically via parameters
• Guided Workflows: Step sequences with structured instructions

Available Skills (Prompts)

| Prompt | Description | |--------|-------------| | /kspec:prd | Create a PRD from a feature request | | /kspec:techspec | Create a Tech Spec from an existing PRD | | /kspec:tasks | Create incremental task list from PRD + Tech Spec | | /kspec:bootstrap | Analyze project and generate Claude Code configuration | | /kspec:implement_task | Implement the next available task | | /kspec:implement_all_tasks | Execute all pending tasks | | /kspec:qa | Run Quality Assurance on a feature | | /kspec:bugfix | Fix bugs documented in bugs.md | | /kspec:adr | Generate Architecture Decision Records | | /kspec:apidoc | Generate OpenAPI 3.1 documentation | | /kspec:release | Generate changelog and release notes | | /kspec:migrate | Plan and execute dependency upgrades | | /kspec:sync | Sync .claude/ and .github/ from .agents/ | | /kspec:ideia | Brainstorm session to decompose an app idea into modules |

Available Tools

| Tool | Description | Parameters | |------|-------------|------------| | list_specs | List all available specs | — | | get_spec | Get spec details | spec_id | | list_templates | List all templates | — | | get_template | Get template details | template_id | | create_spec_from_template | Create spec from template | template_id, template_name, parameters | | validate_spec | Validate a spec | spec (JSON) | | list_skills | List all skills | — | | get_skill | Get skill details | skill_id | | list_workflows | List all workflows | — | | get_workflow | Get workflow details | workflow_id | | start_workflow | Start a workflow instance | workflow_id, initial_context | | get_workflow_status | Running workflow status | instance_id | | next_step | Advance to next step | instance_id |

Available Resources

| Resource | URI | Description | |----------|-----|-----------| | Spec Catalog | spec://catalog | All specs catalog | | Spec by ID | spec://{spec_id} | Individual spec | | Workflow Catalog | workflow://catalog | All workflows catalog | | Workflow by ID | workflow://{workflow_id} | Individual workflow | | Server Info | spec://server/info | Server information |

Development

Prerequisites

• Node.js >= 18
• npm

Setup

git clone [email protected]:K77-dev/kspec-mcp-server.git
cd kspec-mcp-server
npm install
npm run build

Scripts

npm run dev          # Start dev server (tsx)
npm run build        # Build for production
npm start            # Run production build
npm run mcp:dev      # Interactive FastMCP dashboard

Updating Embedded Skills

When SKILL.md files change in the kspec repo, re-embed them:

KSPEC_SKILLS_DIR=/path/to/kspec/.claude/skills npm run rebuild

Publishing a New Version

# Bump version
npm version patch  # or minor, major

# Publish to npmjs.com
npm publish --access public

Technologies

• FastMCP — MCP TypeScript Framework
• Zod — Schema validation
• @modelcontextprotocol/sdk — Official MCP SDK

License

MIT