GenSpec MCP Server

A Model Context Protocol (MCP) server that converts user stories into structured documentation including README, ROADMAP, and SYSTEM-ARCHITECTURE documents through a guided approval workflow.

GenSpec MCP Server streamlines the documentation creation process by taking user stories as input and generating three key documentation artifacts:

- README.md- Project overview and setup instructions
- ROADMAP.md- Development roadmap and milestones
- SYSTEM-ARCHITECTURE.md- Technical architecture documentation

The server uses a continuation workflow where each phase can be approved or edited before proceeding to the next phase, ensuring high-quality documentation output.

- MCP Integration- Works seamlessly with Claude Desktop, VS Code with MCP extension, and Cursor
- Template-Based Generation- Uses predefined templates for consistent documentation structure
- Approval Workflow- Generate → Present → Approve/Edit cycle for each document
- Phase Dependencies- ROADMAP requires README, SYSTEM-ARCHITECTURE requires both
- Multiple Entry Points- Start from any phase or run the complete workflow
- Resource Access- Exposes templates via MCP resource protocol

- Node.js 18.0.0 or higher
- npm or yarn package manager

git clone <repository-url> cd genspec-mcp npm install npm run build

Add to your Claude Desktop configuration file:

macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "genspec": { "command": "npx", "args": ["genspec-mcp"] } } }

- Install the MCP extension for VS Code
- Add to your VS Code settings or MCP configuration:

{ "mcp.servers": { "genspec": { "command": "npx", "args": ["genspec-mcp"] } } }

{ "mcpServers": { "genspec": { "command": "npx", "args": ["genspec-mcp"] } } }

The GenSpec MCP server provides several ways to start the documentation generation workflow:

- start_genspec- Run full workflow: README → ROADMAP → SYSTEM-ARCHITECTURE
- generate_readme- Generate README, then continue through ROADMAP → SYSTEM-ARCHITECTURE
- generate_roadmap- Generate ROADMAP, then continue through SYSTEM-ARCHITECTURE
- generate_architecture- Generate only SYSTEM-ARCHITECTURE

- /start-genspec- Invokes start_genspec tool
- /start-readme- Invokes generate_readme tool
- /start-roadmap- Invokes generate_roadmap tool
- /start-arch- Invokes generate_architecture tool

The server accepts user stories in three priority order:
- Inline text- Pass user stories directly asuserStoryparameter
- URI reference- ProvideuserStoryUrifor the client to fetch via MCP ReadResource
- Local file- Falls back toUSER-STORIES.mdin the current directory

Use the /start-genspec prompt or start_genspec tool

- Generated document is presented for review
- Respond with approval terms: "approve", "approved", "ok", "okay", "yes", "y", "lgtm"
- Or provide edit feedback to regenerate

- After approval, the workflow continues to the next phase
- Each phase follows the same generate → present → approve/edit cycle

genspec-mcp/ ├── dist/ # Compiled JavaScript files ├── src/ # TypeScript source files │ ├── index.ts # MCP server entry point │ ├── server.ts # GenSpecServer implementation │ ├── types.ts # Type definitions and constants │ └── utils/ # Utility modules (Track B, C, D) ├── templates/ # Generation templates │ ├── 1-generate-readme.md │ ├── 2-generate-roadmap.md │ └── 3-generate-system-architecture.md ├── _ai/docs/ # Generated documentation output ├── package.json # Package configuration ├── tsconfig.json # TypeScript configuration └── README.md # This file

All generated documents are saved to the_ai/docs/directory:

- _ai/docs/README.md- Generated project README
- _ai/docs/ROADMAP.md- Generated development roadmap
- _ai/docs/SYSTEM-ARCHITECTURE.md- Generated system architecture

Issue: MCP server not detected by client

- Solution: Ensure the server is properly installed and the configuration file syntax is correct
- Check: Restart your MCP client after configuration changes

Issue: "ERR_MISSING_USER_STORIES" error

- Solution: Provide user stories via one of the three supported methods (inline, URI, or local file)
- Check: Ensure USER-STORIES.md exists if using the local file fallback

Issue: "ERR_MISSING_PREREQUISITES" error

- Solution: Generate prerequisite phases first (README before ROADMAP, README and ROADMAP before SYSTEM-ARCHITECTURE)
- Check: Use continuation workflow tools that include prerequisites

- Solution: Verify that templates/ directory exists and contains the required template files
- Check: Ensure the package was installed correctly with all files

Issue: Permission errors writing to _ai/docs/

- Solution: Ensure the current directory is writable and _ai/docs/ directory can be created
- Check: Run from a directory where you have write permissions

Enable debug logging by setting the DEBUG environment variable:

- Check theMCP specificationfor protocol details
- Review template files in the templates/ directory for generation logic
- File issues or feature requests in the project repository

Paid remote MCP for CLI tool MCP, structured receipts, usage logs, and audit-ready evidence for agent and CI workflows.