Skip to content

Commit 08f5315

Browse files
amittellamittell
committed
Merge PR rizethereum#2: Add MCP Server Implementation
2 parents 22043e8 + 594cf49 commit 08f5315

12 files changed

Lines changed: 3637 additions & 2 deletions

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules/
2+
*.log
3+
.DS_Store
4+
.env
5+
.env.local
6+
.vscode/
7+
.idea/

‎.npmignore‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
src/
2+
tsconfig.json
3+
*.test.ts
4+
.git/
5+
.github/
6+
examples/
7+
commands/
8+
CLAUDE.md
9+
requirements/
10+
node_modules/
11+
.DS_Store
12+
*.log

‎CLAUDE.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the Claude Requirements Gathering System - a structured workflow for collecting and documenting software requirements through AI-guided interviews. The system provides both slash commands and an MCP server implementation, using a two-phase questioning approach (discovery + expert) with automated context gathering to generate comprehensive requirements documentation.
8+
9+
## Repository Structure
10+
11+
```
12+
claude-code-requirements-builder/
13+
├── src/ # MCP server source code
14+
│ └── index.ts # Main MCP server implementation
15+
├── dist/ # Built JavaScript files
16+
├── commands/ # Claude slash command definitions
17+
│ ├── requirements-start.md # Begin new requirement gathering
18+
│ ├── requirements-status.md # Check progress (alias: current)
19+
│ ├── requirements-current.md # View active requirement details
20+
│ ├── requirements-end.md # Finalize requirement session
21+
│ ├── requirements-list.md # List all requirements
22+
│ └── requirements-remind.md # Remind AI of workflow rules
23+
├── requirements/ # Generated requirement documents
24+
│ ├── .current-requirement # Tracks active requirement
25+
│ ├── index.md # Summary of all requirements
26+
│ └── YYYY-MM-DD-HHMM-[name]/ # Individual requirement folders
27+
├── examples/ # Sample requirement outputs
28+
├── package.json # npm package configuration
29+
└── tsconfig.json # TypeScript configuration
30+
```
31+
32+
## Dual Implementation Architecture
33+
34+
This system provides two ways to access the same functionality:
35+
36+
### MCP Server (`src/index.ts`)
37+
- **Node.js TypeScript implementation** using the official MCP SDK
38+
- **6 registered tools** that mirror the slash commands:
39+
- `requirements-start` - Begin new requirement gathering
40+
- `requirements-status` - Check progress and session state
41+
- `requirements-current` - View active requirement details
42+
- `requirements-end` - Complete/incomplete/delete session
43+
- `requirements-list` - Multi-requirement overview with status
44+
- `requirements-remind` - Workflow rules and best practices reminder
45+
- **File-based state management** using the same structure as slash commands
46+
- **npx distribution** for easy installation and updates
47+
48+
### Slash Commands (`commands/` directory)
49+
Each command in `commands/` defines a specific workflow step:
50+
51+
- **requirements-start.md**: 5-phase workflow (setup → discovery → context → expert → documentation)
52+
- **requirements-status.md**: Progress tracking and session resumption
53+
- **requirements-end.md**: Finalization with options (complete/incomplete/delete)
54+
- **requirements-list.md**: Multi-requirement overview with status display
55+
56+
## Key Workflow Patterns
57+
58+
### Phase-Based Progression
59+
1. **Setup**: Create timestamped folder, extract slug from request
60+
2. **Discovery**: 5 yes/no questions about problem space
61+
3. **Context**: Autonomous code analysis and file reading
62+
4. **Expert**: 5 detailed yes/no questions with codebase knowledge
63+
5. **Documentation**: Generate comprehensive requirements spec
64+
65+
### Question Format Standards
66+
- Only yes/no questions with intelligent defaults
67+
- One question at a time (never batch)
68+
- Write ALL questions to file BEFORE asking any
69+
- Include "Default if unknown" reasoning for each question
70+
- Use actual file paths and component names in expert phase
71+
72+
### File Naming Conventions
73+
- Requirement folders: `YYYY-MM-DD-HHMM-[feature-slug]`
74+
- Sequential files: `00-initial-request.md` through `06-requirements-spec.md`
75+
- Metadata tracking: `metadata.json` with phase/progress state
76+
77+
### State Management
78+
- `.current-requirement` file tracks active session
79+
- `metadata.json` structure includes phase, progress counters, analyzed files
80+
- Status transitions: discovery → context → detail → complete
81+
82+
## Development Notes
83+
84+
This repository provides dual implementation approaches:
85+
86+
### MCP Server Development
87+
- **TypeScript** with Node.js runtime
88+
- **MCP SDK** for protocol compliance
89+
- **Build system** with `npm run build`
90+
- **npx distribution** for easy installation
91+
- **State management** via JSON metadata files
92+
93+
### Slash Commands
94+
- **Documentation-based** system reading markdown files in `commands/`
95+
- **No build system** required for slash commands
96+
- **File-based workflow** definitions
97+
98+
## Usage Patterns
99+
100+
The system is designed for product managers and developers to gather requirements through:
101+
- Simple yes/no responses (supports "idk" for defaults)
102+
- Codebase-aware questioning after AI analysis
103+
- Progressive refinement from high-level to implementation-specific
104+
- Comprehensive documentation with file paths and implementation hints
105+
106+
### MCP Server Usage
107+
Users can install via `npx claude-code-requirements` and access all functionality through MCP tools in Claude Desktop or other MCP-compatible clients.
108+
109+
### Slash Command Usage
110+
For users preferring the original slash command interface, the `commands/` directory provides the same workflow through Claude Code's built-in command system.
111+
112+
When working with this repository, maintain consistency between both implementations and ensure the workflow preserves its structured, phase-based approach while keeping questions simple and defaults intelligent.

‎README.md‎

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Claude Requirements Gathering System
22

3-
An intelligent requirements gathering system for Claude Code that progressively builds context through automated discovery, asks simple yes/no questions, and generates comprehensive requirements documentation.
3+
An intelligent requirements gathering system that combines slash commands and MCP server for Claude Code. It progressively builds context through automated discovery, asks simple yes/no questions, and generates comprehensive requirements documentation.
44

55
## 🎯 Overview
66

@@ -10,9 +10,42 @@ This system transforms the requirements gathering process by:
1010
- **Two-Phase Questioning**: 5 high-level questions for context, then 5 expert questions after code analysis
1111
- **Automated Documentation**: Generates comprehensive specs with specific file paths and patterns
1212
- **Product Manager Friendly**: No code knowledge required to answer questions
13+
- **MCP Server Support**: Available as both slash commands and MCP tools
1314

1415
## 🚀 Quick Start
1516

17+
### Option 1: Using MCP Server (Recommended)
18+
19+
**Install via npm:**
20+
```bash
21+
# Test it works
22+
npx claude-code-requirements
23+
24+
# Add to Claude Desktop config
25+
```
26+
27+
Add to your `claude_desktop_config.json`:
28+
```json
29+
{
30+
"mcpServers": {
31+
"claude-code-requirements": {
32+
"command": "npx",
33+
"args": ["claude-code-requirements"]
34+
}
35+
}
36+
}
37+
```
38+
39+
Then use the MCP tools:
40+
- `requirements-start` - Begin gathering requirements
41+
- `requirements-status` - Check progress
42+
- `requirements-current` - View active requirement
43+
- `requirements-end` - Complete/cancel session
44+
- `requirements-list` - List all requirements
45+
- `requirements-remind` - Get workflow reminder
46+
47+
### Option 2: Using Slash Commands
48+
1649
```bash
1750
# Start gathering requirements for a new feature
1851
/requirements-start add user profile picture upload
@@ -205,9 +238,35 @@ Every question includes an intelligent default based on:
205238

206239
## 🔧 Installation
207240

241+
### MCP Server Installation (Recommended)
242+
243+
Install the MCP server via npm:
244+
245+
```bash
246+
# Test it works
247+
npx claude-code-requirements
248+
249+
# Or install globally
250+
npm install -g claude-code-requirements
251+
```
252+
253+
Add to your Claude Desktop configuration:
254+
```json
255+
{
256+
"mcpServers": {
257+
"claude-code-requirements": {
258+
"command": "npx",
259+
"args": ["claude-code-requirements"]
260+
}
261+
}
262+
}
263+
```
264+
265+
### Slash Commands Installation
266+
208267
1. Clone this repository:
209268
```bash
210-
git clone https://github.com/rizethereum/claude-code-requirements-builder.git
269+
git clone https://github.com/ulasbilgen/claude-code-requirements-builder.git
211270
```
212271

213272
2. Copy the commands to your project:

‎dist/index.d.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#!/usr/bin/env node
2+
export {};
3+
//# sourceMappingURL=index.d.ts.map

‎dist/index.d.ts.map‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)