ralph-hero-mcp-server 2.4.11 → 2.4.13

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerDashboardTools } from "./tools/dashboard-tools.js";
 import { registerBatchTools } from "./tools/batch-tools.js";
 import { registerProjectManagementTools } from "./tools/project-management-tools.js";
 import { registerHygieneTools } from "./tools/hygiene-tools.js";
+import { registerRoutingTools } from "./tools/routing-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -248,6 +249,8 @@ async function main() {
     registerProjectManagementTools(server, client, fieldCache);
     // Hygiene reporting tools
     registerHygieneTools(server, client, fieldCache);
+    // Routing config management tools
+    registerRoutingTools(server, client, fieldCache);
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/lib/routing-types.js

@@ -0,0 +1,163 @@
+/**
+ * Routing rules config schema and TypeScript types.
+ *
+ * Defines the structure for `.ralph-routing.yml` config files used by
+ * the issue routing engine. Zod schemas provide runtime validation;
+ * TypeScript types are derived via z.infer<> for compile-time safety.
+ *
+ * Consumers:
+ * - #167 matching engine: imports MatchCriteria, RoutingRule types
+ * - #168 config loader: imports RoutingConfigSchema for YAML validation
+ * - #178 CRUD tool: imports schemas + types for inline validation
+ */
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Match Criteria
+// ---------------------------------------------------------------------------
+/**
+ * Defines conditions for matching an issue to a routing rule.
+ *
+ * At least one criterion must be specified. Multiple criteria are AND'd:
+ * all specified conditions must match for the rule to apply.
+ *
+ * Example YAML:
+ *   match:
+ *     repo: "cdubiel08/ralph-hero"
+ *     labels:
+ *       any: ["enhancement", "bug"]
+ */
+export const MatchCriteriaSchema = z
+    .object({
+    repo: z
+        .string()
+        .optional()
+        .describe("Repository glob pattern (e.g., 'my-org/*', 'owner/repo')"),
+    labels: z
+        .object({
+        any: z
+            .array(z.string())
+            .optional()
+            .describe("Match if issue has ANY of these labels"),
+        all: z
+            .array(z.string())
+            .optional()
+            .describe("Match if issue has ALL of these labels"),
+    })
+        .optional()
+        .describe("Label matching criteria"),
+    issueType: z
+        .enum(["issue", "pull_request", "draft_issue"])
+        .optional()
+        .describe("Match by item type"),
+    negate: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Invert match result — true means 'NOT matching'"),
+})
+    .refine((d) => d.repo || d.labels || d.issueType, {
+    message: "At least one match criterion must be specified (repo, labels, or issueType)",
+});
+// ---------------------------------------------------------------------------
+// Routing Action
+// ---------------------------------------------------------------------------
+/**
+ * Defines what happens when a rule matches.
+ *
+ * At least one action must be specified. Multiple actions execute together.
+ *
+ * Example YAML:
+ *   action:
+ *     projectNumber: 3
+ *     workflowState: "Backlog"
+ *     labels: ["triaged"]
+ */
+export const RoutingActionSchema = z
+    .object({
+    projectNumber: z
+        .number()
+        .optional()
+        .describe("Add issue to this project (shorthand for single project)"),
+    projectNumbers: z
+        .array(z.number())
+        .optional()
+        .describe("Add issue to multiple projects"),
+    workflowState: z
+        .string()
+        .optional()
+        .describe("Set workflow state after routing"),
+    labels: z
+        .array(z.string())
+        .optional()
+        .describe("Add these labels to the issue"),
+})
+    .refine((d) => d.projectNumber || d.projectNumbers || d.workflowState || d.labels, {
+    message: "At least one action must be specified (projectNumber, projectNumbers, workflowState, or labels)",
+});
+// ---------------------------------------------------------------------------
+// Routing Rule
+// ---------------------------------------------------------------------------
+/**
+ * A single routing rule: match criteria + action.
+ *
+ * Example YAML:
+ *   - name: "Route MCP server issues"
+ *     match:
+ *       repo: "cdubiel08/ralph-hero"
+ *     action:
+ *       projectNumber: 3
+ */
+export const RoutingRuleSchema = z.object({
+    name: z
+        .string()
+        .optional()
+        .describe("Human-readable rule name for debugging and audit trail"),
+    match: MatchCriteriaSchema,
+    action: RoutingActionSchema,
+    enabled: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Toggle rule on/off without removing it"),
+});
+// ---------------------------------------------------------------------------
+// Routing Config
+// ---------------------------------------------------------------------------
+/**
+ * Top-level routing configuration.
+ *
+ * Example YAML:
+ *   version: 1
+ *   stopOnFirstMatch: true
+ *   rules:
+ *     - name: "Route bugs"
+ *       match:
+ *         labels:
+ *           any: ["bug"]
+ *       action:
+ *         projectNumber: 3
+ */
+export const RoutingConfigSchema = z.object({
+    version: z
+        .literal(1)
+        .describe("Schema version for forward compatibility"),
+    stopOnFirstMatch: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Stop evaluating rules after first match (default: true)"),
+    rules: z
+        .array(RoutingRuleSchema)
+        .describe("Ordered list of routing rules — evaluated top to bottom"),
+});
+// ---------------------------------------------------------------------------
+// Convenience Functions
+// ---------------------------------------------------------------------------
+/**
+ * Validate and parse a routing config object (e.g., from YAML parse output).
+ * Throws ZodError with detailed messages on validation failure.
+ */
+export function validateRoutingConfig(data) {
+    return RoutingConfigSchema.parse(data);
+}
+//# sourceMappingURL=routing-types.js.map

package/dist/tools/routing-tools.js

@@ -0,0 +1,84 @@
+/**
+ * MCP tool for managing routing rules in .ralph-routing.yml.
+ *
+ * Provides a single `ralph_hero__configure_routing` tool with four
+ * CRUD operations: list_rules, add_rule, update_rule, remove_rule.
+ */
+import fs from "node:fs/promises";
+import { parse, stringify } from "yaml";
+import { z } from "zod";
+import { toolSuccess, toolError } from "../types.js";
+// ---------------------------------------------------------------------------
+// Register routing tools
+// ---------------------------------------------------------------------------
+export function registerRoutingTools(server, _client, _fieldCache) {
+    server.tool("ralph_hero__configure_routing", "Manage routing rules in .ralph-routing.yml. CRUD operations: list, add, update, remove rules. Config path: configPath arg > RALPH_ROUTING_CONFIG env var > .ralph-routing.yml. Returns: updated rule list and configPath.", {
+        operation: z
+            .enum(["list_rules", "add_rule", "update_rule", "remove_rule"])
+            .describe("CRUD operation to perform"),
+        configPath: z
+            .string()
+            .optional()
+            .describe("Path to routing config file. Defaults to RALPH_ROUTING_CONFIG env var or .ralph-routing.yml"),
+        rule: z
+            .object({
+            match: z.object({
+                labels: z.array(z.string()).optional(),
+                repo: z.string().optional(),
+            }),
+            action: z.object({
+                workflowState: z.string().optional(),
+                projectNumber: z.number().optional(),
+            }),
+        })
+            .optional()
+            .describe("Rule definition (required for add_rule, update_rule)"),
+        ruleIndex: z
+            .number()
+            .optional()
+            .describe("Zero-based rule index (required for update_rule, remove_rule)"),
+    }, async (args) => {
+        const configPath = args.configPath ??
+            process.env.RALPH_ROUTING_CONFIG ??
+            ".ralph-routing.yml";
+        try {
+            const raw = await fs.readFile(configPath, "utf-8").catch(() => "");
+            const config = raw
+                ? parse(raw)
+                : { rules: [] };
+            if (!config.rules)
+                config.rules = [];
+            switch (args.operation) {
+                case "list_rules":
+                    return toolSuccess({ rules: config.rules, configPath });
+                case "add_rule":
+                    if (!args.rule)
+                        return toolError("rule is required for add_rule operation");
+                    config.rules = [...config.rules, args.rule];
+                    await fs.writeFile(configPath, stringify(config, { lineWidth: 0 }));
+                    return toolSuccess({ rules: config.rules, configPath });
+                case "update_rule":
+                    if (args.ruleIndex == null || !args.rule)
+                        return toolError("ruleIndex and rule are required for update_rule operation");
+                    if (args.ruleIndex < 0 || args.ruleIndex >= config.rules.length)
+                        return toolError(`Rule index ${args.ruleIndex} out of range (0-${config.rules.length - 1})`);
+                    config.rules[args.ruleIndex] = args.rule;
+                    await fs.writeFile(configPath, stringify(config, { lineWidth: 0 }));
+                    return toolSuccess({ rules: config.rules, configPath });
+                case "remove_rule":
+                    if (args.ruleIndex == null)
+                        return toolError("ruleIndex is required for remove_rule operation");
+                    if (args.ruleIndex < 0 || args.ruleIndex >= config.rules.length)
+                        return toolError(`Rule index ${args.ruleIndex} out of range (0-${config.rules.length - 1})`);
+                    config.rules = config.rules.filter((_, i) => i !== args.ruleIndex);
+                    await fs.writeFile(configPath, stringify(config, { lineWidth: 0 }));
+                    return toolSuccess({ rules: config.rules, configPath });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to configure routing: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=routing-tools.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.4.11",
+  "version": "2.4.13",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,7 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@octokit/graphql": "^9.0.3",
     "@octokit/plugin-paginate-graphql": "^6.0.0",
+    "yaml": "^2.7.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {