Gitworthy MCP server

Gitworthy

The decision layer before a coding agent starts work.

Gitworthy helps coding agents scout, rank, and preflight software work before they spend cycles implementing it. It finds the strongest candidates, checks whether the work is already handled or blocked, and returns evidence-backed ACT, VERIFY, or SKIP decisions for each target.

MCP setup · CLI · Agent workflow · Verdicts · Troubleshooting · Case studies · Roadmap · Contributing

Why Gitworthy

Coding agents make implementation cheap. Choosing the wrong task is still expensive.

An issue can look open while:

• a fix already exists on an unlinked branch;
• another contributor has an active pull request;
• the change landed on main but has not been released;
• the repository requires assignment before accepting work;
• a duplicate or abandoned implementation already contains the answer.

Gitworthy performs that preflight before a human or agent spends the next unit of work.

How agents use Gitworthy

The agent owns the loop. Gitworthy is the MCP decision engine it calls to scout and validate work.

Contribution goal, repository, or organization
                      │
                      ▼
         Cursor / ChatGPT / Hermes / agent
                      │
                 Gitworthy MCP
                      │
                      ▼
        policy → scan → rank → preflight
                      │
             ┌────────┼────────┐
             ▼        ▼        ▼
            ACT     VERIFY    SKIP
          queue it   inspect   drop it
             │
             ▼
     optional `portfolio`
     (mode + dispatch, not a new verdict)
             │
             ▼
       Ranked candidate shortlist
             │
             ▼
         Select a candidate
             │
             ▼
   recheck → reproduce → implement → review

There are two distinct lanes:

• Scout lane: discover, filter, rank, preflight, and return a shortlist.
• Execute lane: select, record intent, recheck fresh state, reproduce, implement, review, and submit through the repository's allowed contribution path.

ACT means “worth considering,” not “start coding blindly.” Scout results go stale, so Gitworthy should be run again when an agent actually claims or begins a target.

See docs/AGENT_WORKFLOW.md for the complete agent policy, tool-selection guide, and scout-to-execute handoff.

Use it with Cursor, ChatGPT, Hermes, or any MCP client

Local stdio (desktop / agent VM)

{
  "mcpServers": {
    "gitworthy": {
      "command": "npx",
      "args": ["-y", "gitworthy@latest", "mcp"],
      "env": {
        "GITHUB_TOKEN": "github_pat_..."
      }
    }
  }
}

Streamable HTTP (Cloud Agents / mobile / iPad)

Run or deploy the same engine over HTTP and point the client at a URL:

export GITWORTHY_MCP_TOKEN="$(openssl rand -hex 32)"
export GITHUB_TOKEN="github_pat_..."
npx -y gitworthy@latest mcp --http --host 127.0.0.1 --port 8787

Shortened. The full README is on GitHub.