# Aurea Orchestrator MCP

Production-ready MCP server for enforcing git/PR/Jira workflows with atomic, composable tools.

## Quick Start

```bash
npm install
cp .aurearc.example.json .aurearc.json
cp .env.example .env
npm run build && npm start
```

### Add to your MCP host

Add to your Claude Code or Cursor MCP configuration:

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

### Required Configuration

- `.aurearc.json` - Project rules (branch naming, ticket patterns, protected branches)
- `GITHUB_TOKEN` - GitHub personal access token (required)
- `JIRA_*` - Jira credentials (optional, only if using Jira tools)

Owner/repo are auto-detected from `git remote origin`.

## Available Tools

### Git Operations (`aurea.git.*`)

- `create_branch` - Create branch with enforced naming and duplicate detection
- `commit` - Conventional commits in English with ticket references
- `review_changes` - Diff summary with hotspots (package.json, migrations, etc.)
- `push` - Push with protected branch guardrails

### Pull Requests (`aurea.pr.*`)

- `compose` - Generate standardized PR title and body
- `create` - Create PR with auto-detection of owner/repo
- `open` - **ONE-CALL**: compose + push + create

### Jira Operations (`aurea.jira.*`)

- `get_ticket` - Fetch ticket details (summary, status, assignee)
- `create_ticket` - Create new Jira ticket
- `transition` - Move ticket to different status
- `ensure_ticket` - Legacy: validate or create (prefer get_ticket + create_ticket)

## Conventions

**Branches**: `feature/NT-1234-short-title` or `hotfix/NT-5678-fix-bug`

**Commits**: `feat(scope): message [NT-1234]` (English, imperative mood)

**PRs**: Auto-generated with template (summary, risks, checklist)

## Architecture

```
┌─────────────────────────────┐
│  HOST (Claude Code/Cursor)  │
│  - Reads user prompts       │
│  - Orchestrates workflow    │
│  - Asks for approval        │
└──────────┬──────────────────┘
           │ calls tools
           ↓
┌─────────────────────────────┐
│    Aurea MCP (this pkg)     │
│  - Atomic git operations    │
│  - PR creation with template│
│  - Jira integration         │
│  - Naming enforcement       │
│  - Safety guardrails        │
└─────────────────────────────┘
```

**The MCP provides tools. The HOST orchestrates.**

## Usage Example

```
User: "Implement webhook retry for NT-1234"
    ↓
Host (using Aurea tools):
  1. aurea.jira.get_ticket({ ticket: "NT-1234" })
     ✓ "Add webhook retry mechanism"
  2. aurea.git.create_branch({ type: "feature", ticket: "NT-1234", title: "webhook retry" })
     ✓ feature/NT-1234-webhook-retry
  3. [Implements code]
  4. aurea.git.commit({ ticket, message: "add retry logic" })
  5. aurea.git.commit({ ticket, message: "add tests" })
  6. aurea.git.review_changes()
  7. [Asks user approval]
  8. aurea.git.push()
  9. aurea.pr.open({ type, ticket, title, summary })
 10. aurea.jira.transition({ ticket, status: "In Code Review" })
     ✓ PR: https://github.com/org/repo/pull/123
```

## Configuration

See [docs/WORKFLOW_EXAMPLE.md](./docs/WORKFLOW_EXAMPLE.md) for:
- Claude Code slash command setup
- Cursor `.cursorrules` configuration
- Complete workflow examples
- Best practices

## Key Features

✅ **Production-ready**: Comprehensive error handling, retry logic, token sanitization
✅ **Type-safe**: Full TypeScript with Zod validation
✅ **Atomic tools**: Composable operations for flexible workflows
✅ **Safety guardrails**: Protected branch checks, working tree validation
✅ **Auto-detection**: Owner/repo from git remote, upstream branch handling
✅ **Structured logging**: Clear visibility into operations
✅ **Duplicate detection**: Warns about existing branches for same ticket

## Development

```bash
npm run dev          # Run in dev mode
npm run build        # Build TypeScript
npm run check        # Type checking
npm run lint         # Lint code
npm run format       # Format with Prettier
```

## License

MIT