# SpecForge

**Turn GitHub issues into merged pull requests — autonomously.**

SpecForge is a Model Context Protocol (MCP) server that connects an LLM client (like Claude Desktop) to a fully autonomous code-fixing pipeline. Point it at a GitHub issue, and it reads the repo, plans a fix, writes the code, tests it, and opens a pull request — without a human touching the keyboard in between.

Built for the **CyOps Arena x MiniMax M3 Hackathon 2025**.

---

## How It Works

SpecForge orchestrates four stages, each handled by a specialized agent:

| Stage | Agent | What Happens |
|-------|-------|---------------|
| 1. Recon | Recon Agent | Reads repo structure, detects language, package manager, and test runner |
| 2. Plan | Planning Agent | Generates a file-level implementation plan from the issue description |
| 3. Implement | MiniMax M3 | Writes the actual code changes |
| 4. Review | Review Agent | Runs tests, self-critiques, and loops until the suite passes |
| 5. Ship | GitHub Agent | Creates a branch, commits changes, and opens a pull request |

You give it an issue URL. It gives you back a PR.

---

## Prerequisites

| Requirement | Notes |
|---|---|
| Node.js | v18 or higher |
| npm | v9 or higher |
| CyOps account | Free signup at [ai.cysic.xyz](https://ai.cysic.xyz/agent_market) |
| GitHub Personal Access Token | Needs `repo` and `pull_request` scopes |

---

## Installation

### 1. Install dependencies

```bash
cd mcp-server
npm install
npm run build
```

### 2. Configure environment variables

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

```env
# GitHub — token needs repo, pull_requests, and contents (read + write) scopes
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# CyOps Gateway URL (from your ai.cysic.xyz workspace)
CYOPS_GATEWAY_URL=https://your-instance.cysic.xyz

# CyOps API key (Settings → API Keys, inside your workspace)
CYOPS_API_KEY=cyops_xxxxxxxxxxxxxxxxxxxx
```

### 3. Set MiniMax M3 as your model in CyOps

1. Open your CyOps workspace and click **Open Gateway**
2. Go to **Settings → LLM Proxy**
3. Set each agent's model to **MiniMax M3**

This unlocks the hackathon's 80% discount on token pricing.

### 4. Connect to Claude Desktop

Open your Claude Desktop config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add SpecForge as an MCP server:

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

Restart Claude Desktop. SpecForge should now appear in your available tools.

---

## Usage

In Claude Desktop, just describe what you want fixed:

```
Use specforge to fix https://github.com/org/repo/issues/42
```

SpecForge runs the full pipeline and returns a pull request URL when finished. No further input required unless you want to check progress mid-run.

---

## Available Tools

### `specforge_run`

Kicks off the full pipeline for a given issue.

```typescript
{
  issue_url: string;           // Required — full GitHub issue URL
  strategy_profile?: string;   // Optional — CyOps strategy (default: "Default RLCR (Claude → MiniMax M3)")
  max_wait_minutes?: number;   // Optional — timeout in minutes (default: 10)
}
```

### `specforge_status`

Checks the status of an in-progress run.

```typescript
{
  run_id: string;     // CyOps run ID, returned from specforge_run
  project_id: string; // CyOps project ID, returned from specforge_run
}
```

---

## Architecture

```
specforge_run (MCP tool)
  │
  ├── parseIssueUrl()          → Parse the GitHub issue URL
  ├── fetchIssue()              → Read issue body + comments
  │
  ├── runRecon()                → Recon Agent
  │     ├── fetchRepoContext()
  │     ├── readFile() × N      → package.json, tsconfig, etc.
  │     └── detect test runner, package manager
  │
  ├── createProject()           → CyOps: create new project
  ├── generatePlan()            → CyOps: generate plan from requirement
  ├── startRun()                → CyOps: begin Implement → Review loop
  ├── pollRun()                 → CyOps: wait for completion
  │
  ├── getArtifacts()            → List changed files
  ├── readWorkspaceFile() × N   → Read each changed file
  ├── createBranch()            → GitHub: create new branch
  ├── commitFileToGitHub() × N  → GitHub: push each changed file
  └── openPullRequest()         → GitHub: open pull request
```

---

## Project Structure

```
mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point + tool handlers
│   ├── github.ts             # GitHub API client
│   ├── cyops.ts               # CyOps Gateway API client
│   └── agents/
│       ├── recon.ts          # Recon Agent — repo understanding
│       └── orchestrator.ts   # Main pipeline coordinator
├── package.json
├── tsconfig.json
└── README.md
```

---

## Hackathon

**CyOps Arena x MiniMax M3** — June 2025