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
GitHub Personal Access Token	Needs repo and pull_request scopes

---

Installation

1. Install dependencies

cd mcp-server
npm install
npm run build

2. Configure environment variables

cp .env.example .env

Edit .env with your credentials:

# 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:

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

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

{
  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