ralph-hero-mcp-server 2.5.191 → 2.5.193

package/README.md

@@ -0,0 +1,64 @@
+# ralph-hero-mcp-server
+
+MCP server for GitHub Projects V2 — the workflow-automation engine behind the [Ralph](https://github.com/cdubiel08/ralph-hero) Claude Code plugin.
+
+## What it is
+
+`ralph-hero-mcp-server` exposes [GitHub Projects V2](https://docs.github.com/en/issues/planning-and-tracking-with-projects) as a set of [Model Context Protocol](https://modelcontextprotocol.io/) tools, so an agent (Claude Code) can read and drive an issue through a workflow state machine — `Backlog → Research Needed → … → In Review → Done` — entirely through typed tool calls instead of shelling out to `gh`.
+
+It is bundled and consumed by the `ralph` Claude Code plugin (the skills call these tools), but it is a standalone stdio MCP server and can be wired into any MCP client.
+
+## Install
+
+The server is published to npm and is normally run via `npx` from an MCP client config (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ralph-github": {
+      "command": "npx",
+      "args": ["-y", "ralph-hero-mcp-server"]
+    }
+  }
+}
+```
+
+All tools are namespaced with the `ralph_hero__` prefix (e.g. `ralph_hero__get_issue`, `ralph_hero__save_issue`, `ralph_hero__next_actions`).
+
+## Configuration
+
+Configuration flows through the parent process's environment (the `.mcp.json` has **no** `env` block — do not put tokens there).
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `RALPH_GH_OWNER` | Yes | GitHub owner (user or org). |
+| `RALPH_GH_PROJECT_NUMBER` | Yes | GitHub Projects V2 number. |
+| `RALPH_GH_REPO` | No | Repository name (inferred from the project if omitted). |
+| `RALPH_HERO_GITHUB_TOKEN` | No | GitHub PAT with `repo` + `project` scopes. **Falls back to `gh auth token`** when unset — so with `gh auth login -s repo,project,read:org` you usually need no token in any config. |
+| `RALPH_GH_PROJECT_OWNER` | No | Project owner, if different from the repo owner (split-owner setups). |
+
+## Tool architecture
+
+Each tool module exports a `registerXyzTools()` function that registers tools onto the MCP server. All tools use the `ralph_hero__` prefix and return via `toolSuccess()` / `toolError()`. Modules cover issues (`get_issue`, `save_issue`, `list_issues`), projects, relationships (`add_sub_issue`, `add_dependency`, `advance_issue`), dashboards (`pipeline_dashboard`, `next_actions`), trends, and more.
+
+For the full module/tool inventory and internals (GitHub client dual-endpoint design, caching, the workflow state machine), see [the repo's CLAUDE.md § "MCP Server Internals"](https://github.com/cdubiel08/ralph-hero/blob/main/CLAUDE.md#mcp-server-internals).
+
+## Build & test
+
+```bash
+npm install
+npm run build   # TypeScript -> dist/ (tsc)
+npm test        # vitest
+```
+
+The server is ESM (`"type": "module"`, `"module": "NodeNext"`) — internal imports use `.js` extensions. TypeScript strict mode is the primary quality gate (no linter).
+
+## Links
+
+- Repository: <https://github.com/cdubiel08/ralph-hero>
+- Plugin + workflow docs: <https://github.com/cdubiel08/ralph-hero/blob/main/README.md>
+- Issues: <https://github.com/cdubiel08/ralph-hero/issues>
+
+## License
+
+See the [repository](https://github.com/cdubiel08/ralph-hero).

package/dist/lib/dashboard-fetch.js

@@ -51,7 +51,7 @@ export function toDashboardItems(raw, projectNumber, projectTitle) {
             estimate: getFieldValue(r, "Estimate"),
             assignees: r.content.assignees?.nodes?.map((a) => a.login) ?? [],
             subIssueCount: r.content.subIssues?.totalCount ?? 0,
-            blockedBy: r.content.trackedIssues?.nodes?.map((n) => ({
+            blockedBy: r.content.blockedBy?.nodes?.map((n) => ({
                 number: n.number,
                 workflowState: n.state === "CLOSED" ? "Done" : null,
             })) ?? [],
@@ -93,7 +93,7 @@ export const DASHBOARD_ITEMS_QUERY = `query($projectId: ID!, $cursor: String, $f
               assignees(first: 5) { nodes { login } }
               repository { nameWithOwner name }
               subIssues { totalCount }
-              trackedIssues(first: 10) { nodes { number state } }
+              blockedBy(first: 20) { nodes { number state } }
               trackedInIssues(first: 3) { nodes { number state closedAt } }
             }
             ... on PullRequest {

package/dist/lib/directions.js

@@ -541,6 +541,12 @@ export function rankDirections(items, openPRs, config) {
             if (item.workflowState !== "Backlog" && item.workflowState !== null) {
                 continue;
             }
+            // Defense-in-depth: skip blocked items in the fallback loop so a
+            // dependency-blocked Backlog issue never enters scored even when the
+            // primary filter (step 2 below) would catch it anyway.
+            if (hasOpenBlockers(item)) {
+                continue;
+            }
             const { score, kind, tags, signals } = scoreIssue(item, items, config);
             scored.push({
                 item,

package/dist/lib/workflow-states.js

@@ -131,4 +131,22 @@ export const WORKFLOW_STATE_TO_STATUS = {
     "Canceled": "Done",
     "Human Needed": "Todo",
 };
+/**
+ * Reverse-inference map (GH-1471): when a save_issue call closes the GitHub
+ * issue but provides no explicit workflowState, infer the matching terminal
+ * board state. Keyed by `CLOSED:${stateReason ?? ""}` to mirror the lookup in
+ * issue-tools.ts. This is the symmetric inverse of the forward auto-close path.
+ *
+ * - CLOSED:COMPLETED   → Done     (issue closed as completed)
+ * - CLOSED:NOT_PLANNED → Canceled (issue closed as not planned)
+ * - CLOSED:            → Done     (close with no stateReason defaults to Done)
+ *
+ * An explicit workflowState always wins — the caller only consults this map
+ * when args.workflowState is undefined.
+ */
+export const ISSUE_STATE_TO_TERMINAL_WORKFLOW = {
+    "CLOSED:COMPLETED": "Done",
+    "CLOSED:NOT_PLANNED": "Canceled",
+    "CLOSED:": "Done",
+};
 //# sourceMappingURL=workflow-states.js.map

package/dist/tools/issue-tools.js

@@ -8,7 +8,7 @@ import { z } from "zod";
 import { paginateConnection } from "../lib/pagination.js";
 import { detectGroup } from "../lib/group-detection.js";
 import { detectPipelinePosition, OVERSIZED_ESTIMATES, } from "../lib/pipeline-detection.js";
-import { isValidState, isParentGateState, VALID_STATES, LOCK_STATES, TERMINAL_STATES, WORKFLOW_STATE_TO_STATUS, } from "../lib/workflow-states.js";
+import { isValidState, isParentGateState, VALID_STATES, LOCK_STATES, TERMINAL_STATES, WORKFLOW_STATE_TO_STATUS, ISSUE_STATE_TO_TERMINAL_WORKFLOW, } from "../lib/workflow-states.js";
 import { buildBatchMutationQuery } from "./batch-tools.js";
 import { resolveState } from "../lib/state-resolution.js";
 import { parseDateMath } from "../lib/date-math.js";
@@ -808,6 +808,7 @@ export function registerIssueTools(server, client, fieldCache) {
         "and project field values (workflow state, estimate, priority, iteration) in a single call. " +
         "Supports semantic intents (__LOCK__, __COMPLETE__, etc.) for workflowState. " +
         "Auto-closes the GitHub issue when workflowState resolves to a terminal state (Done, Canceled) unless issueState is explicitly set. " +
+        "Reverse inference: when issueState closes the issue (CLOSED→Done, CLOSED_NOT_PLANNED→Canceled) and no workflowState is provided, the board is advanced to the matching terminal state automatically. Explicit workflowState always wins. " +
         "Set estimate, priority, or iteration to null to clear the field. Use @current/@next tokens for iteration. " +
         "Returns: number, url, changes.", {
         owner: z.string().optional().describe("GitHub owner. Defaults to GITHUB_OWNER env var"),
@@ -887,6 +888,20 @@ export function registerIssueTools(server, client, fieldCache) {
                 stateReason = resolvedWorkflowState === "Canceled" ? "NOT_PLANNED" : "COMPLETED";
                 changes.autoClose = true;
             }
+            // Reverse inference: if issueState closes the issue and no explicit workflowState,
+            // default the board to the matching terminal workflow state (Done or Canceled).
+            // This is the symmetric inverse of the forward auto-close path above.
+            // Explicit workflowState always wins — this only fires when args.workflowState is absent.
+            let inferredFromClose = false;
+            if (args.workflowState === undefined && targetState === "CLOSED") {
+                const key = `CLOSED:${stateReason ?? ""}`;
+                const inferred = ISSUE_STATE_TO_TERMINAL_WORKFLOW[key];
+                if (inferred) {
+                    resolvedWorkflowState = inferred;
+                    inferredFromClose = true;
+                    changes.workflowStateInferred = inferred;
+                }
+            }
             // 3. Issue state mutations (close/reopen) - use dedicated mutations
             const hasMetadataFields = args.title !== undefined || args.body !== undefined ||
                 args.labels !== undefined || args.assignees !== undefined;
@@ -982,7 +997,8 @@ export function registerIssueTools(server, client, fieldCache) {
                 }
             }
             // 4. Project-field mutations (aliased batch for workflow state + status sync + estimate + priority)
-            if (hasProjectFields) {
+            // Also fires when workflowState was inferred from issueState (reverse-close inference).
+            if (hasProjectFields || inferredFromClose) {
                 const { projectNumber, projectOwner } = resolveFullConfig(client, args);
                 await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
                 const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number, projectNumber);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.191",
+  "version": "2.5.193",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",