# @komexa/kickoff-mcp

[Português](README.md) | **English**

> **Structure copilot for vibe coders.**
> Turns ideas into trackable projects. Guides the kickoff, generates full documentation, breaks requirements into tasks, and tracks coverage — all offline, integrated into your AI agent.

Works with **Claude Code**, **Cursor**, **Windsurf**, **Aider**, and any MCP-compatible IDE.

---

## Why use it

Vibe coding is fast — but without structure, projects turn into a snowball of untracked features. `kickoff-mcp` solves that:

| Problem | Solution |
|---------|----------|
| "I've lost track of the project" | `get_project_brief` — full summary in 300 tokens |
| "I don't know what to implement next" | `next_task` — highest-priority task with context, schema, and flow |
| "New feature with no record" | `add_feature` — automatic REQ-ID, docs updated |
| "I don't know what's done" | `validate_coverage` — coverage per REQ-ID, % by priority |
| "Form doesn't match the database" | `validate_integrity` — detects missing fields across UI↔API↔DB |
| "I want to see progress" | React dashboard at `localhost:4242` |

---

## Installation

```bash
npm install -g @komexa/kickoff-mcp
```

### Configure as an MCP server

Add to your agent's config file (`.mcp.json`, `claude_desktop_config.json`, etc.):

```json
{
  "mcpServers": {
    "kickoff-mcp": {
      "command": "npx",
      "args": ["-y", "@komexa/kickoff-mcp"]
    }
  }
}
```

### Initialize in an existing project

```bash
cd /path/to/project
npx @komexa/kickoff-mcp init
```

Creates `.mcp.json` with the server configured and `CLAUDE.md` with project context.

---

## Quick start

```
1. npx @komexa/kickoff-mcp init     ← sets up the project
2. Open Claude Code (or your IDE)
3. Say: "start kickoff"             ← guided interview begins
4. Docs generated automatically
5. next_task → implement → complete_task → repeat
```

---

## MCP Tools

### `get_project_brief`
Compact project summary (~300 tokens). **Use at the start of every session** to orient the agent without spending context reading docs manually.

Returns: name, stack, coverage %, next pending task, last validation date, environment facts.

---

### `kickoff_project`
Guided interview in 4 blocks that generates **15+ documents** in the project root:

| Block | What it captures |
|-------|-----------------|
| **Identity** | Name, type, description, problem, solution |
| **Stack** | Technologies per layer with rationale |
| **Features** | Functionalities, acceptance criteria, priority (must/should/could), phase (mvp/post) |
| **Data model** | Entities, SQL schema, relationships |

**Generated documents:**

```
project/
├── REQUIREMENTS.md          ← source of truth (REQ-IDs)
├── CLAUDE.md                ← instructions for Claude Code
├── docs/
│   ├── PRD.md               ← Product Requirements Document
│   ├── SAD.md               ← Software Architecture Document
│   ├── ERD.md               ← Entity Relationship Diagram
│   ├── FLOWS.md             ← Flow diagrams per feature
│   ├── RUNBOOK.md           ← Setup, commands, env vars
│   ├── LEGAL.md             ← License and privacy
│   └── PROCESS.md           ← Development process
├── .agents/
│   ├── rules/
│   │   ├── project-context.md
│   │   ├── requirements-guide.md
│   │   ├── coding-standards.md    ← doc comments in the project's language
│   │   └── task-workflow.md
│   └── skills/
│       ├── add-feature.md
│       ├── validate-coverage.md
│       └── create-skill.md
└── .kickoff/
    ├── db.sqlite            ← SQLite index (auto-rebuilding cache)
    ├── LEARNINGS.md         ← top 15 errors→solutions memorized
    └── .gitignore
```

If the project already has `REQUIREMENTS.md`, it offers to **update**, **regenerate**, or **restart** — without overwriting existing work.

---

### `add_feature`
Registers a new feature with a unique REQ-ID, updates `REQUIREMENTS.md` and affected docs.

```
Parameters:
  description  — feature description
  priority     — must | should | could
  phase        — mvp | post
```

Also **alerts on untracked features**: files without `// REQ-XXX` appear as "untracked" during validation.

---

### `validate_coverage`
Scans the codebase and classifies each REQ-ID:

| Status | Meaning |
|--------|---------|
| ✅ **covered** | REQ-ID found in code with acceptance criteria met |
| ⚠️ **partial** | Implementation exists, some criteria missing |
| ❌ **pending** | No traceable implementation |

Detects `// REQ-XXX` at the top of files. With Ollama, performs **semantic scanning** — infers the REQ even without a comment.

Saves the report to `VALIDATION_REPORT.md` with a timestamp and detailed table.

---

### `validate_integrity`
Detects **missing fields across layers** (UI ↔ API ↔ DB) via AST analysis.

Supports:
- **TypeScript / JavaScript** — interfaces, types, Zod schemas, controllers, React forms
- **C#** — classes, properties, Entity Framework models, DTOs, controllers

```
Example: field `email` exists in the React form but not in the POST endpoint → alert generated
```

---

### `task_manager`

Full task management with the automated cycle `next_task → implement → complete_task`.

#### Available actions

| Action | What it does |
|--------|-------------|
| `next_task` | Selects the most urgent task, marks it `in_progress`, returns full context |
| `complete_task` | Validates coverage, creates git commit, marks task/subtasks/milestone as done |
| `breakdown_req` | Breaks a REQ-ID into TDD subtasks + auto-creates milestone |
| `create_task` | Creates a manual task linked to a REQ-ID |
| `list_tasks` | Kanban by status (todo / in_progress / done / blocked) |
| `update_task` | Updates status, estimated hours, assignee |
| `create_milestone` | Creates a manual milestone with a deadline |
| `stats` | Statistics: tasks, hours, progress per REQ, milestones |

#### TDD order (auto breakdown)

Tasks are generated and executed in this order for each REQ-ID:

```
1. Schema/Types       → interfaces, types, SQL schema
2. Backend + Tests    → tests first, then implementation
3. Frontend           → UI consuming the tested backend
4. validate_integrity → confirms data flows between layers
```

#### Context returned by `next_task`

- SQL schema of relevant entities (from ERD)
- Feature flow diagram (from FLOWS)
- Acceptance criteria (from REQUIREMENTS)
- Subtask checklist
- Milestone and deadline
- Detailed implementation plan (if Ollama available)

#### Gantt / Sprint Timeline

`start_date` field on tasks + `hours_per_day` config. Dashboard shows Gantt with day/week zoom, status-colored bars, and overdue tasks in red.

---

### `dev_context`
Persistent memory of environment and errors. **Available as both an MCP tool and CLI.**

| Action | What it does |
|--------|-------------|
| `get` | Lists saved environment facts (platform, shell, node, paths, etc.) |
| `set` | Saves an environment fact as key→value |
| `remember` | Memorizes an error→solution pair with a confidence score |
| `find` | Searches solutions by pattern (semantic with Ollama, text without) |
| `translate` | Accesses full error→solution history in SQLite |
| `sync` | Promotes top 15 solutions from SQLite to `.kickoff/LEARNINGS.md` |

`init` auto-detects: platform, shell, Node.js version, Python, package manager.

Sensitive data (tokens, IPs, personal paths) is sanitized before persisting.

Solutions are suggested with a **confidence score** (`success_count / total`) — minimum threshold of 0.5.

---

### `query_project_brain`
**Full-text search (FTS5)** on requirements by keywords.

- `unicode61` tokenizer with `remove_diacritics` → native multilingual support
- Returns: `req_id`, title, priority, and acceptance criteria for the N most relevant results
- Synchronized via triggers with the `requirements` table

---

### `review_code`
Semantic code analysis via Ollama (qwen2.5-coder recommended).

Detects bugs, missing fields, unannotated REQ-IDs. Silent fallback if Ollama is unavailable.

---

### `progress_report`
Progress and coverage report.

```
Modes:
  summary  — % by priority (must/should/could) + milestones
  full     — complete table with status per REQ-ID
```

---

## CLI

```bash
# Setup
kickoff-mcp init [dir]                          # Configure project (.mcp.json + CLAUDE.md + .agents/)
kickoff-mcp regenerate [dir]                    # Regenerate .agents/ without re-running kickoff
kickoff-mcp rebuild-index [dir]                 # Rebuild SQLite from .md files

# Validation
kickoff-mcp validate [dir]                      # Validate requirements coverage
kickoff-mcp validate-integrity [entity]         # Validate layer integrity (UI/API/DB)

# Reports and dashboard
kickoff-mcp report [summary|full]               # Progress report
kickoff-mcp dashboard [dir]                     # Open dashboard at localhost:4242

# Automation
kickoff-mcp watch [cooldown-ms]                 # Daemon auto-validates on save (default: 2s)
kickoff-mcp add-feature <desc> [prio] [phase]   # Register feature (must/should/could, mvp/post)

# Environment memory
kickoff-mcp dev-context get                     # List environment facts
kickoff-mcp dev-context set <key> <value>       # Save a fact
kickoff-mcp dev-context remember <error> <sol>  # Memorize solution for an error
kickoff-mcp dev-context find <pattern>          # Search solutions (semantic with Ollama)
kickoff-mcp dev-context sync                    # Update LEARNINGS.md

# Advanced
kickoff-mcp review <file> [focus]               # Code review via Ollama
kickoff-mcp info                                # System status (version, SQLite, Ollama)
```

---

## Dashboard

```bash
kickoff-mcp dashboard
# Visit: http://localhost:4242
```

| Tab | Content |
|-----|---------|
| **Overview** | Coverage by priority, global metrics, REQ detail drawer |
| **Tasks** | Kanban (todo/in_progress/done/blocked), expandable subtasks, Gantt sprint timeline |
| **Workflows** | MCP pipeline, validation history, milestones timeline |
| **Schema** | Entities, fields by layer (UI/API/DB), detected integrity issues |

Updates in real time via **SSE (Server-Sent Events)** — `.md` changes reflect without a page refresh.

---

## Ollama (optional)

Enables task enrichment, code review, and semantic search. Silent fallback to static mode if unavailable.

### Setup

```bash
# 1. Install Ollama
curl -fsSL https://ollama.com/install.sh | sh   # macOS/Linux
# Windows: https://ollama.com/download

# 2. Embeddings model (semantic search)
ollama pull nomic-embed-text    # 274 MB — default
ollama pull bge-small           # 67 MB  — balanced
ollama pull all-minilm          # 23 MB  — lightweight

# 3. Generation model (tasks + code review)
ollama pull gemma4:e4b          # default
ollama pull qwen2.5-coder:7b    # recommended for code review
```

### Environment variables

```bash
# .env at project root (add to .gitignore)
KICKOFF_OLLAMA_URL=http://127.0.0.1:11434
KICKOFF_OLLAMA_MODEL=nomic-embed-text       # embeddings
KICKOFF_OLLAMA_GEN_MODEL=gemma4:e4b         # generation
```

### Difference with and without Ollama

| Without Ollama | With Ollama |
|----------------|-------------|
| Static context (schema + flow + criteria) | + Detailed implementation plan (files, routes, validations) |
| Text search (`LIKE`) on memorized solutions | Semantic search by embedding similarity |
| Regex-only validation (`// REQ-XXX`) | + Semantic scan — infers REQ even without comment |
| No code review | Review with bug analysis, improvements, missing REQ-IDs |

---

## REQ-ID Traceability

Add `// REQ-XXX` at the top of every file you create or modify:

```typescript
// REQ-042
export function initProject(dir: string) { ... }
```

`validate_coverage` uses these comments as anchors. With Ollama, semantic scanning complements regex detection.

---

## Multi-agent support

`kickoff-mcp init` generates rules and skills in `.agents/` compatible with any agent that reads markdown:

- **Claude Code** → `CLAUDE.md` + `.agents/rules/`
- **Cursor** → `.agents/rules/` + `.agents/skills/`
- **Windsurf** → `.agents/rules/`
- **Aider** → `.agents/rules/`

Generated rules include the **doc comment standard for the project's language** (JSDoc for TS/JS, `/// <summary>` for C#, docstrings for Python, GoDoc for Go, etc.).

---

## Architecture

```
Claude Code / Cursor / Windsurf
  │  stdio (MCP protocol)
  ▼
@komexa/kickoff-mcp (src/index.ts)
  ├── tools/kickoff.ts              ← guided interview + generates 15+ docs
  ├── tools/add-feature.ts          ← registers feature, updates .md
  ├── tools/validate.ts             ← scans codebase vs REQ-IDs
  ├── tools/validate-integrity.ts   ← detects gaps UI↔API↔DB via AST
  ├── tools/task-manager.ts         ← tasks, subtasks, milestones, TDD cycle
  ├── tools/report.ts               ← coverage report
  ├── tools/dev-context.ts          ← environment and error memory
  ├── tools/query-brain.ts          ← FTS5 search on requirements
  ├── tools/project-brief.ts        ← compact summary for session start
  └── tools/review-code.ts          ← semantic review via Ollama
  │
  ├── core/doc-generator.ts         ← Handlebars → .md (15+ templates)
  ├── core/sqlite-index.ts          ← SQLite index (.kickoff/db.sqlite)
  ├── core/coverage.ts              ← covered/partial/pending classification
  ├── core/ollama-enricher.ts       ← task enrichment (static + LLM)
  ├── core/file-watcher.ts          ← auto-validate on save daemon
  ├── core/fs-reader.ts             ← reads .md and codebase
  └── core/context-injector.ts      ← injects project context into prompts
  │
  dashboard/server.ts               ← HTTP localhost:4242 + SSE
  dashboard/ui/                     ← Vite + React (overview, tasks, workflows, schema)
```

### Architectural decisions

| ADR | Decision |
|-----|----------|
| 001 | `.md` files are source of truth; SQLite is an auto-rebuilding cache |
| 002 | MCP uses stdio transport — compatible with Claude Code, Cursor, Windsurf |
| 003 | Dashboard runs as a separate process — MCP is never blocked by HTTP |
| 004 | Vite builds React to static files; MCP serves the built output |

---

## Development

```bash
git clone https://github.com/komexa/kickoff-mcp.git
cd kickoff-mcp

npm install
npm run dev          # watch mode (MCP + UI in parallel)
npm run build        # full build (TypeScript + Vite)
npm run build:mcp    # compile MCP server only
npm run build:ui     # build dashboard only
npm test             # run tests
npm run lint         # ESLint + TypeScript check

npx . init           # test CLI locally
npx . dashboard      # test dashboard locally
```

---

## License

MIT — see [LICENSE](./LICENSE).

---

Built by **[Komexa Studio](https://komexa.com)**.
