# dev-flow-mcp

MCP Server for development workflow automation. Supports iOS (Swift) and Android (Kotlin) projects.

## Features

- **Auto-detect** project type (iOS / Android)
- **Git workflow** status detection (branch, PR, phase)
- **Code quality** checks (SwiftLint, SwiftFormat, ktlint, detekt)
- **Phase guidance** with platform-specific commands
- **Smart caching** - Per-tool caching with appropriate TTLs
- **Token-optimized** - Minimal output formats (10-100 tokens per call)
- **Prompts & Resources** - Proactive suggestions and subscribable status
- **Standards compliance** - Conventional Commits & Git Flow

## Installation

### 1. Install dependencies

```bash
cd dev-flow-mcp
npm install
npm run build
```

### 2. Configure Claude Code

Add to your Claude Code MCP settings (`~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "dev-flow": {
      "command": "node",
      "args": ["/path/to/dev-flow-mcp/dist/index.js"]
    }
  }
}
```

### 3. Restart Claude Code

## Tools

### `dev_status` [~30 tokens]

Ultra-compact status for quick checks.

```
Output: PHASE|✅0|next
Example: DEVELOPING|❌3|fix
```

**Use by default** for quick workflow checks.

### `dev_flow` [~100 tokens]

Structured status with more details.

```
Input:
- verbose (optional): Add phase-specific guidance (+50 tokens)

Output: Project(TYPE)|branch|PHASE|✅errors/warnings
Example: MyApp(IOS)|feature/TASK-123|DEVELOPING|❌3/12
```

### `dev_fix` [~20 tokens]

Get fix commands.

```
Output: command1 && command2
Example: swiftformat . && swiftlint --fix
```

### `dev_check` [~10 tokens]

CI-ready check.

```
Output: ✅ or ❌count
Example: ❌5
```

### `dev_next` [~15 tokens]

Get recommended next command following Conventional Commits & Git Flow.

```
Output: Suggested command for current phase
Example: git add . && git commit -m "feat(scope): add feature description"
```

## Prompts

Claude can proactively use these prompts:

- `dev_workflow_check` - Check workflow before committing
- `dev_auto_fix` - Auto-fix code quality issues
- `dev_next_step` - Get next recommended action

## Resources

Subscribable project information:

- `dev://status` - Real-time workflow status
- `dev://config` - Project configuration and tools

## Supported Platforms

### iOS

| Tool | Purpose |
|------|---------|
| SwiftLint | Code linting |
| SwiftFormat | Code formatting |
| xcodebuild | Build |
| CocoaPods | Dependencies |

### Android

| Tool | Purpose |
|------|---------|
| ktlint | Code linting & formatting |
| detekt | Static analysis |
| Gradle | Build & tasks |

## Workflow Phases

| Phase | Description |
|-------|-------------|
| `IDLE` | On master, ready for new task |
| `STARTING` | Need to create feature branch |
| `DEVELOPING` | On feature branch, has changes |
| `READY_TO_PUSH` | Has unpushed commits |
| `WAITING_QA` | Pushed, waiting for QA |
| `PR_OPEN` | PR created, under review |
| `PR_MERGED` | PR merged |
| `READY_TO_RELEASE` | Ready to create release tag |

## Token Optimization

| Tool | Before | After | Savings |
|------|--------|-------|---------|
| `dev_status` | ~100 | ~30 | 70% |
| `dev_flow` | ~300 | ~100 | 67% |
| `dev_fix` | ~50 | ~20 | 60% |
| `dev_check` | ~30 | ~10 | 67% |

**Caching Strategy:**
- Project info: 60s TTL (rarely changes)
- Git status: 5s TTL (changes often)
- Quality checks: 10s TTL (moderate)

**Per-tool caching** prevents redundant executions when multiple tools are called.

## Automation Capabilities

### Prompts
Claude can proactively suggest MCP tools based on context:

- **Before committing**: Claude suggests `dev_workflow_check` prompt
- **Code quality issues**: Claude suggests `dev_auto_fix` prompt
- **Workflow guidance**: Claude suggests `dev_next_step` prompt

### Resources
Claude can subscribe to project status:

- **dev://status**: Live workflow phase and quality status
- **dev://config**: Project type, available tools, configuration

### Smart Suggestions
All commands follow industry standards:

- **Conventional Commits**: `feat(scope):`, `fix:`, `docs:`, etc.
- **Git Flow**: `feature/*`, `release/*`, `hotfix/*` branches
- **PR Standards**: Structured titles and descriptions with testing checklists

## Example Output

**dev_status:**
```
DEVELOPING|❌3|fix
```

**dev_flow:**
```
MyApp(IOS)|feature/TASK-945|DEVELOPING|❌3/12
```

**dev_next:**
```
swiftformat . && swiftlint --fix
```

**dev_check:**
```
❌3
```

## Development

```bash
# Run in development mode
npm run dev

# Build
npm run build

# Lint
npm run lint
```

## License

MIT