ralph-hero-mcp-server 2.5.190 → 2.5.192

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/index.js

@@ -31,7 +31,6 @@ import { registerDecomposeTools } from "./tools/decompose-tools.js";
 import { registerViewTools } from "./tools/view-tools.js";
 import { registerPlanGraphTools } from "./tools/plan-graph-tools.js";
 import { registerActivityTools } from "./tools/activity-tools.js";
-import { registerDelegationTools } from "./tools/delegation-tools.js";
 import { registerTrendsTools } from "./tools/trends-tools.js";
 import { registerSreTools } from "./tools/sre-tools.js";
 /**
@@ -447,8 +446,6 @@ async function main() {
     registerPlanGraphTools(server, client);
     // Activity log reader (recent_activity tool — pure filesystem, no GitHub client)
     registerActivityTools(server);
-    // Delegation telemetry reader (delegation_stats tool — pure filesystem, no GitHub client)
-    registerDelegationTools(server);
     // Trends tools (capture_snapshot — JSONL persistence under ~/.ralph-hero/snapshots/)
     registerTrendsTools(server, client, fieldCache);
     // SRE operation tools (kubectl autoremediation — typed argv, no-shell invariant)

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/repo-registry.js

@@ -52,7 +52,7 @@ export const RepoDefaultsSchema = z.object({
  *     tech: [typescript, node]
  *     defaults:
  *       labels: [backend]
- *     paths: [plugin/ralph-hero/mcp-server]
+ *     paths: [mcp-server]
  */
 export const RepoEntrySchema = z.object({
     owner: z

package/package.json

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

package/dist/lib/delegation-log.js

@@ -1,199 +0,0 @@
-/**
- * Pure read library for the local ralph-delegate JSONL audit log.
- *
- * The log lives at `~/.ralph-hero/delegate.log` (overridable via
- * `RALPH_DELEGATE_LOG_PATH`). One JSON object per line, append-only,
- * written by `plugin/ralph-hero/scripts/ralph-delegate.sh`. This library
- * only reads — it never writes.
- *
- * Schema versioning: F1 (issue #1185) does NOT emit an explicit
- * `schemaVersion` field on each line. F5 treats lines containing the
- * required fields `{ts, task, status, ms}` as **implicit v1**. A future
- * issue MAY add an explicit `schemaVersion >= 2` — when that happens, the
- * shape-check should be expanded to honor it. TODO: revisit when the
- * producer side emits `schemaVersion`.
- *
- * Determinism: pure functions. Filesystem reads are the only side effect.
- * Missing log file resolves to a zero-state result with no throw, matching
- * the activity.ts precedent (the steady state for opt-out users).
- */
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-// ---------------------------------------------------------------------------
-// Test hook + default path resolution
-// ---------------------------------------------------------------------------
-/**
- * Optional override used only by tests. Production code never sets this.
- * Mirrors `__setSnapshotRoot` in `snapshots.ts`.
- */
-let delegateLogPathOverride = null;
-/** Test hook: override the default log path. Pass `null` to restore. */
-export function __setDelegateLogPath(path) {
-    delegateLogPathOverride = path;
-}
-/**
- * Resolve the default log path: env var override, then `~/.ralph-hero/delegate.log`.
- * Expands a leading `~/` (mirrors `ralph-delegate.sh:208-211`).
- */
-export function defaultDelegationLogPath() {
-    if (delegateLogPathOverride !== null)
-        return delegateLogPathOverride;
-    const fromEnv = process.env.RALPH_DELEGATE_LOG_PATH;
-    if (fromEnv && fromEnv.length > 0) {
-        return expandHome(fromEnv);
-    }
-    return path.join(os.homedir(), ".ralph-hero", "delegate.log");
-}
-function expandHome(p) {
-    if (p.startsWith("~/")) {
-        return path.join(os.homedir(), p.slice(2));
-    }
-    return p;
-}
-// ---------------------------------------------------------------------------
-// Reader
-// ---------------------------------------------------------------------------
-/**
- * Read the delegation audit log. Returns a zero-state result with
- * `fileExists: false` when the file is missing — never throws on ENOENT.
- * Lines that fail JSON.parse OR lack required fields are skipped and
- * counted in `skippedLines`; each skip emits a `console.warn` with a
- * truncated prefix of the offending line.
- */
-export async function readDelegationLog(config) {
-    const logPath = config.logPath;
-    let content;
-    try {
-        content = await fs.readFile(logPath, "utf8");
-    }
-    catch (e) {
-        if (e &&
-            typeof e === "object" &&
-            "code" in e &&
-            e.code === "ENOENT") {
-            return { events: [], skippedLines: 0, fileExists: false, logPath };
-        }
-        throw e;
-    }
-    const events = [];
-    let skipped = 0;
-    for (const raw of content.split("\n")) {
-        const line = raw.trim();
-        if (line.length === 0)
-            continue;
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-        }
-        catch {
-            skipped++;
-            console.warn(`[delegation-log] Skipping malformed line in ${logPath}: ${line.slice(0, 80)}`);
-            continue;
-        }
-        if (!isDelegationEventShape(parsed)) {
-            skipped++;
-            console.warn(`[delegation-log] Skipping line with missing required fields in ${logPath}: ${line.slice(0, 80)}`);
-            continue;
-        }
-        events.push(parsed);
-    }
-    return { events, skippedLines: skipped, fileExists: true, logPath };
-}
-/**
- * Implicit-v1 shape check: presence of `{ts, task, status, ms}` with
- * correct primitive types. A future explicit `schemaVersion >= 2` may
- * extend this gate.
- */
-function isDelegationEventShape(v) {
-    if (!v || typeof v !== "object")
-        return false;
-    const o = v;
-    return (typeof o.ts === "string" &&
-        typeof o.task === "string" &&
-        typeof o.status === "string" &&
-        typeof o.ms === "number");
-}
-// ---------------------------------------------------------------------------
-// Aggregator
-// ---------------------------------------------------------------------------
-/**
- * Aggregate parsed events into per-task + totals. Pure function — does
- * no I/O. Percentiles use the nearest-rank method against successful
- * (status=ok) calls only.
- */
-export function aggregateDelegationStats(events) {
-    const byTask = {};
-    const okMsByTask = {};
-    let totalCalls = 0;
-    let totalFallbacks = 0;
-    let totalBytesIn = 0;
-    let totalBytesOut = 0;
-    for (const ev of events) {
-        const task = ev.task;
-        if (!byTask[task]) {
-            byTask[task] = {
-                calls: 0,
-                fallbacks: 0,
-                p50Ms: null,
-                p99Ms: null,
-                bytesIn: 0,
-                bytesOut: 0,
-                tokens: null,
-            };
-            okMsByTask[task] = [];
-        }
-        byTask[task].calls += 1;
-        totalCalls += 1;
-        if (isFallbackStatus(ev.status)) {
-            byTask[task].fallbacks += 1;
-            totalFallbacks += 1;
-        }
-        const bIn = typeof ev.bytes_in === "number" ? ev.bytes_in : 0;
-        const bOut = typeof ev.bytes_out === "number" ? ev.bytes_out : 0;
-        byTask[task].bytesIn += bIn;
-        byTask[task].bytesOut += bOut;
-        totalBytesIn += bIn;
-        totalBytesOut += bOut;
-        if (ev.status === "ok") {
-            okMsByTask[task].push(ev.ms);
-        }
-    }
-    // Compute percentiles
-    for (const task of Object.keys(byTask)) {
-        const samples = okMsByTask[task];
-        byTask[task].p50Ms = percentile(samples, 0.5);
-        byTask[task].p99Ms = percentile(samples, 0.99);
-    }
-    return {
-        totals: {
-            calls: totalCalls,
-            fallbacks: totalFallbacks,
-            bytesIn: totalBytesIn,
-            bytesOut: totalBytesOut,
-        },
-        byTask,
-    };
-}
-/**
- * A fallback is any non-`ok`, non-`dry_run` status: timeout, unreachable,
- * parse_error, http_*. `dry_run` is operator-driven and not a real
- * delegation failure, so it does not count.
- */
-function isFallbackStatus(status) {
-    return status !== "ok" && status !== "dry_run";
-}
-/**
- * Nearest-rank percentile: `sorted[ceil(q * n) - 1]`. Returns `null`
- * when the sample is empty.
- */
-function percentile(samples, q) {
-    if (samples.length === 0)
-        return null;
-    const sorted = [...samples].sort((a, b) => a - b);
-    const rank = Math.ceil(q * sorted.length);
-    // Guard the edge case q=0 (would index -1)
-    const idx = Math.max(0, rank - 1);
-    return sorted[idx];
-}
-//# sourceMappingURL=delegation-log.js.map

package/dist/tools/delegation-tools.js

@@ -1,44 +0,0 @@
-/**
- * Registers the `ralph_hero__delegation_stats` MCP tool. Pure read-only
- * surface over the JSONL audit log written by `ralph-delegate.sh` (F1).
- *
- * Follows the same registration convention as `activity-tools.ts`: no
- * GitHub client argument, defaults pulled from env var with a homedir
- * fallback, returns `toolSuccess` on missing-file (zero-state) so callers
- * can render a dashboard without an error path.
- */
-import { z } from "zod";
-import { readDelegationLog, aggregateDelegationStats, defaultDelegationLogPath, } from "../lib/delegation-log.js";
-import { toolSuccess, toolError } from "../types.js";
-const TOKENS_REASON = "F1 audit-log does not capture token usage; bytes used as a proxy";
-export function registerDelegationTools(server) {
-    server.tool("ralph_hero__delegation_stats", "Read-only telemetry over the local ralph-delegate JSONL audit log. Returns per-task call counts, fallback counts (non-ok/non-dry_run), p50/p99 latency from successful calls, and bytes_in/bytes_out aggregates. Reads RALPH_DELEGATE_LOG_PATH (default ~/.ralph-hero/delegate.log). Missing log file returns a zero-state result, never errors.", {
-        logPath: z
-            .string()
-            .optional()
-            .describe("Optional override for the JSONL log path. Defaults to RALPH_DELEGATE_LOG_PATH or ~/.ralph-hero/delegate.log."),
-    }, async (params) => {
-        try {
-            const resolvedPath = params.logPath ?? defaultDelegationLogPath();
-            const read = await readDelegationLog({ logPath: resolvedPath });
-            const stats = aggregateDelegationStats(read.events);
-            return toolSuccess({
-                logPath: read.logPath,
-                fileExists: read.fileExists,
-                totals: {
-                    calls: stats.totals.calls,
-                    fallbacks: stats.totals.fallbacks,
-                    bytesIn: stats.totals.bytesIn,
-                    bytesOut: stats.totals.bytesOut,
-                    skippedLines: read.skippedLines,
-                },
-                byTask: stats.byTask,
-                tokensReason: TOKENS_REASON,
-            });
-        }
-        catch (err) {
-            return toolError(err instanceof Error ? err.message : String(err));
-        }
-    });
-}
-//# sourceMappingURL=delegation-tools.js.map