convez.ai
MCP ServerAutomaçãoAvançado
cdubiel08

Ralph Hero - MCP Server para Automação GitHub Projects V2

cdubiel08/ralph-hero

Engenheiro de software autônomo acionado por GitHub Projects V2

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que transforma Claude em engenheiro de software autônomo, gerenciando fluxo de trabalho completo em GitHub Projects V2. Automatiza triagem de issues, pesquisa de codebase, planejamento, implementação em worktrees isoladas, criação de PRs e merge através de uma máquina de estados estruturada.

Instalação

$npx convez-ai cdubiel08/ralph-hero

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 dia
Versão
ralph-v0.3.149
Issues abertas
43
Contribuidores
3

Casos de uso

  • Automação end-to-end de desenvolvimento de features em repositórios
  • Triagem, pesquisa e planejamento autônomo de issues
  • Implementação de código em isolamento com validação humana
  • Gestão de ciclo de vida completo de tarefas com checkpoints de revisão

Veredito

Ferramenta robusta e bem estruturada para equipes que querem automação de engenharia de software em escala, com máquina de estados clara e pontos de controle humano. Requer setup inicial (token, projeto) e é mais adequada para fluxos standardizados em repositórios bem definidos.

README

A tradução para o português deste README ainda está na fila.

Ralph Hero

A Claude Code plugin that turns Claude into an autonomous software engineer. Ralph triages issues, researches codebases, writes implementation plans, codes in isolated worktrees, creates PRs, and merges — all driven by a GitHub Projects V2 board.

The naive hero picks tickets, does their best work, and moves on.

How It Works

Ralph manages GitHub issues through a structured workflow state machine:

Backlog → Research Needed → Research in Progress → Ready for Plan
       → Plan in Progress → Plan in Review → In Progress → In Review → Done

Each transition is enforced by hooks and validated by the MCP server. Issues flow through phases — triage, research, planning, review, implementation, and merge — with human checkpoints at plan review and code review.

Autonomous mode (/ralph:hero): Ralph drives an issue tree end-to-end, splitting large tickets, researching each sub-issue, creating plans, and implementing them.

Interactive mode: Use individual skills like /ralph:plan or /ralph:impl with human-in-the-loop verification at each step.

Installation

Prerequisites

  • Claude Code CLI
  • Node.js 20+
  • A GitHub Personal Access Token with repo and project scopes

Install the Plugin

claude plugins add cdubiel08/ralph-hero --plugin ralph

Configure

Add your GitHub token and project settings to .claude/settings.local.json (gitignored):

{
  "env": {
    "RALPH_HERO_GITHUB_TOKEN": "ghp_your_token_here",
    "RALPH_GH_OWNER": "your-github-username",
    "RALPH_GH_PROJECT_NUMBER": "1"
  }
}

Set Up Your Project Board

/ralph:setup

This creates a GitHub Projects V2 board with the required custom fields: Workflow State, Priority, and Estimate.

Token Expired?

gh auth refresh -s repo,project,read:org

Then restart Claude Code.

If you're using explicit RALPH_GH_REPO_TOKEN / RALPH_GH_PROJECT_TOKEN / RALPH_HERO_GITHUB_TOKEN: regenerate the PAT at https://github.com/settings/tokens, update ~/.claude/settings.json (or .claude/settings.local.json), restart Claude Code.

Skills

SkillDescription
/ralph:heroDrive an issue through the full lifecycle end-to-end (autonomous)
/ralph:hero-fableExperimental rail-free surface for Fable: outcome + boundaries + artifact contract, no prescribed phases (/ralph:hero --model fable forwards here)
/ralph:researchInvestigate an issue, create a research document, update issue state
/ralph:planCreate or review an implementation plan
/ralph:implImplement an approved plan in an isolated worktree
/ralph:reviewValidate implementation or review a plan
/ralph:caretakeTriage, hygiene, unblock, trends, split, debug, report
/ralph:catch-upSession orientation — narrative, dashboard, or status report
/ralph:formCrystallize ideas into structured GitHub issues
/ralph:setupOne-time project board setup

MCP Server

The plugin bundles an MCP server (ralph-hero-mcp-server) that provides GitHub Projects V2 tools to Claude Code via the Model Context Protocol.

Tools

The MCP server registers ~38 ralph_hero__* tools; the table below is a curated subset of the most-used ones (issue/project CRUD, relationships, dashboards, trends). Additional tools include draft-issue CRUD, decompose_feature, archive_items, create_views, sync_plan_graph, detect_stream_positions, remove_dependency, and the sre__* autoremediation set; debug tools register only when RALPH_DEBUG=true.

ToolDescription
health_checkValidate API connectivity, tokens, repo/project access, and required fields
get_projectFetch project metadata, fields, and items
setup_projectCreate or configure a project with required fields and workflow states
get_issueGet full issue details with project fields, sub-issues, and dependencies
list_issuesQuery issues with filtering, sorting, and pagination
save_issueCreate or update issues with project field values (workflow state, priority, estimate)
create_issueCreate a new issue and add it to the project
create_commentAdd a comment to an issue
create_status_updatePost a status update to the project
add_sub_issueAdd a sub-issue relationship
list_sub_issuesList sub-issues of a parent
add_dependencyAdd a blocking dependency between issues
list_dependenciesList blocking and blocked-by relationships
advance_issueMove an issue to the next workflow state with validation
batch_updateBulk-update project fields across multiple issues
pipeline_dashboardAggregated pipeline view with counts per workflow state and health indicators
project_hygieneBoard health report — stale items, orphans, field gaps
next_actionsRanked list of recommended next actions
recent_activityRead per-session activity log
capture_snapshotCapture pipeline snapshot for trend tracking
metrics_trends1d/7d/30d velocity and WIP trends

Architecture

mcp-server/              # TypeScript MCP server (published as ralph-hero-mcp-server)
ralph/                   # Claude Code plugin
├── skills/              # 9 fat verbs + experimental hero-fable surface
├── agents/              # 16 agents (8 per-phase + 8 investigators)
├── hooks/               # Lifecycle enforcement hooks
└── .claude-plugin/      # Plugin manifest + .mcp.json
plugin/
├── ralph-knowledge/     # Semantic search over thoughts/ documents
├── ralph-playwright/    # Polymorphic UI testing
└── ralph-demo/          # Sprint demo video generation

CI/CD

WorkflowTriggerDescription
ci.ymlPR to mainBuild + test; hook tests; workflow lint
release.ymlmcp-server/ changes on mainAuto-bump version, publish to npm with provenance, pin ralph/.mcp.json
release-ralph.ymlralph/ changes on mainBump ralph plugin version + tag
route-issues.ymlIssue openedRoute new issues to project board
sync-issue-state.ymlIssue state changeSync GitHub issue state with project workflow
sync-pr-merge.ymlPR mergedMove linked issues to Done
sync-project-state.ymlProject field changeSync project state changes back to issues
advance-parent.ymlSub-issue state changeAuto-advance parent when all children reach a gate state

Configuration

VariableRequiredDescription
RALPH_HERO_GITHUB_TOKENNo (defaults to gh auth token)GitHub PAT with repo + project scopes
RALPH_GH_OWNERYesGitHub owner (user or org)
RALPH_GH_PROJECT_NUMBERYesGitHub Projects V2 number
RALPH_GH_REPONoRepository name (inferred from project if omitted)
RALPH_GH_PROJECT_NUMBERSNoComma-separated project numbers for cross-project dashboard
RALPH_GH_PROJECT_OWNERNoProject owner if different from repo owner
RALPH_GH_REPO_TOKENNoSeparate repo token (falls back to main token)
RALPH_GH_PROJECT_TOKENNoSeparate project token (falls back to repo token)
RALPH_IMPL_MODELNoOverride model for impl-agent (sonnet, opus, or fable; default sonnet; BLOCKED escalation re-dispatches once at fable)
RALPH_DEBUGNoEnable JSONL debug logging + OpenTelemetry export

Set all variables in .claude/settings.local.json under the "env" key. Do not put tokens in .mcp.json.

Development

cd mcp-server
npm install
npm run build
npm test

Tests use Vitest.

Release process: Merges to main that touch mcp-server/src/** automatically bump the version, publish to npm, and pin ralph/.mcp.json. Include #minor or #major in a commit message for larger version bumps.

Security

To report a vulnerability or review our supported versions and disclosure process, see SECURITY.md.

License

MIT

Ver o original no GitHub

Bom para

Relacionados