Aurea Orchestrator MCP

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

Quick Start

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:

{
  "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 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

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