ralph-hero-mcp-server 1.3.2 → 1.3.3

package/dist/index.js

@@ -17,6 +17,7 @@ import { registerIssueTools } from "./tools/issue-tools.js";
 import { registerRelationshipTools } from "./tools/relationship-tools.js";
 import { registerDashboardTools } from "./tools/dashboard-tools.js";
 import { registerBatchTools } from "./tools/batch-tools.js";
+import { registerProjectManagementTools } from "./tools/project-management-tools.js";
 /**
  * Initialize the GitHub client from environment variables.
  */
@@ -242,6 +243,8 @@ async function main() {
     registerDashboardTools(server, client, fieldCache);
     // Phase 5: Batch operations
     registerBatchTools(server, client, fieldCache);
+    // Project management tools (archive, remove, add, link repo, clear field)
+    registerProjectManagementTools(server, client, fieldCache);
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/lib/helpers.js

@@ -6,6 +6,7 @@
  * implementations to their original versions.
  */
 import { resolveProjectOwner } from "../types.js";
+import { WORKFLOW_STATE_TO_STATUS } from "./workflow-states.js";
 // ---------------------------------------------------------------------------
 // Helper: Fetch project data for field cache population
 // ---------------------------------------------------------------------------
@@ -197,4 +198,28 @@ export function resolveFullConfig(client, args) {
     }
     return { owner, repo, projectNumber, projectOwner };
 }
+// ---------------------------------------------------------------------------
+// Helper: Sync default Status field after Workflow State change
+// ---------------------------------------------------------------------------
+/**
+ * Sync the default Status field to match a Workflow State change.
+ * Best-effort: logs warning on failure but does not throw.
+ */
+export async function syncStatusField(client, fieldCache, projectItemId, workflowState) {
+    const targetStatus = WORKFLOW_STATE_TO_STATUS[workflowState];
+    if (!targetStatus)
+        return;
+    const statusFieldId = fieldCache.getFieldId("Status");
+    if (!statusFieldId)
+        return;
+    const statusOptionId = fieldCache.resolveOptionId("Status", targetStatus);
+    if (!statusOptionId)
+        return;
+    try {
+        await updateProjectItemField(client, fieldCache, projectItemId, "Status", targetStatus);
+    }
+    catch {
+        // Best-effort sync - don't fail the primary operation
+    }
+}
 //# sourceMappingURL=helpers.js.map

package/dist/lib/workflow-states.js

@@ -79,4 +79,26 @@ export function isEarlierState(a, b) {
 export function isValidState(state) {
     return VALID_STATES.includes(state);
 }
+/**
+ * Maps Ralph Workflow States to GitHub's default Status field values.
+ * Used for one-way sync: Workflow State changes -> Status field updates.
+ *
+ * Rationale:
+ * - Todo = work not yet actively started (queued states)
+ * - In Progress = work actively being processed (lock states + review)
+ * - Done = terminal/escalated states (no automated progression)
+ */
+export const WORKFLOW_STATE_TO_STATUS = {
+    "Backlog": "Todo",
+    "Research Needed": "Todo",
+    "Ready for Plan": "Todo",
+    "Plan in Review": "Todo",
+    "Research in Progress": "In Progress",
+    "Plan in Progress": "In Progress",
+    "In Progress": "In Progress",
+    "In Review": "In Progress",
+    "Done": "Done",
+    "Canceled": "Done",
+    "Human Needed": "Done",
+};
 //# sourceMappingURL=workflow-states.js.map

package/dist/tools/batch-tools.js

@@ -6,7 +6,7 @@
  * instead of one per issue).
  */
 import { z } from "zod";
-import { isEarlierState } from "../lib/workflow-states.js";
+import { isEarlierState, WORKFLOW_STATE_TO_STATUS } from "../lib/workflow-states.js";
 import { toolSuccess, toolError } from "../types.js";
 import { ensureFieldCache, resolveFullConfig, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
@@ -267,6 +267,27 @@ export function registerBatchTools(server, client, fieldCache) {
                             field: op.field,
                             value: op.value,
                         });
+                        // For workflow_state operations, also sync the default Status field
+                        if (op.field === "workflow_state") {
+                            const targetStatus = WORKFLOW_STATE_TO_STATUS[op.value];
+                            if (targetStatus) {
+                                const statusFieldId = fieldCache.getFieldId("Status");
+                                const statusOptionId = statusFieldId
+                                    ? fieldCache.resolveOptionId("Status", targetStatus)
+                                    : undefined;
+                                if (statusFieldId && statusOptionId) {
+                                    updates.push({
+                                        alias: `s${num}_${opIdx}`,
+                                        itemId: issue.projectItemId,
+                                        fieldId: statusFieldId,
+                                        optionId: statusOptionId,
+                                        issueNumber: num,
+                                        field: "status_sync",
+                                        value: targetStatus,
+                                    });
+                                }
+                            }
+                        }
                     }
                 }
                 // Chunk mutations if needed

package/dist/tools/issue-tools.js

@@ -11,7 +11,7 @@ import { detectPipelinePosition, } from "../lib/pipeline-detection.js";
 import { isValidState, VALID_STATES, LOCK_STATES, } from "../lib/workflow-states.js";
 import { resolveState } from "../lib/state-resolution.js";
 import { toolSuccess, toolError } from "../types.js";
-import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, } from "../lib/helpers.js";
+import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, resolveFullConfig, syncStatusField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
 // Register issue tools
 // ---------------------------------------------------------------------------
@@ -607,6 +607,8 @@ export function registerIssueTools(server, client, fieldCache) {
             const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number);
             // Update the field with the resolved state
             await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", resolvedState);
+            // Sync default Status field (best-effort, one-way)
+            await syncStatusField(client, fieldCache, projectItemId, resolvedState);
             const result = {
                 number: args.number,
                 previousState: previousState || "(unknown)",

package/dist/tools/project-management-tools.js

@@ -0,0 +1,248 @@
+/**
+ * MCP tools for GitHub Projects V2 management operations.
+ *
+ * Provides tools for archiving/unarchiving items, removing items from projects,
+ * adding existing issues to projects, linking repositories, and clearing field values.
+ */
+import { z } from "zod";
+import { toolSuccess, toolError } from "../types.js";
+import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, resolveFullConfig, } from "../lib/helpers.js";
+// ---------------------------------------------------------------------------
+// Register project management tools
+// ---------------------------------------------------------------------------
+export function registerProjectManagementTools(server, client, fieldCache) {
+    // -------------------------------------------------------------------------
+    // ralph_hero__archive_item
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__archive_item", "Archive or unarchive a project item. Archived items are hidden from default views but not deleted. Returns: number, archived, projectItemId.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        number: z.number().describe("Issue number"),
+        unarchive: z.boolean().optional().default(false)
+            .describe("If true, unarchive instead of archive (default: false)"),
+    }, async (args) => {
+        try {
+            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number);
+            if (args.unarchive) {
+                await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!) {
+              unarchiveProjectV2Item(input: {
+                projectId: $projectId,
+                itemId: $itemId
+              }) {
+                item { id }
+              }
+            }`, { projectId, itemId: projectItemId });
+            }
+            else {
+                await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!) {
+              archiveProjectV2Item(input: {
+                projectId: $projectId,
+                itemId: $itemId
+              }) {
+                item { id }
+              }
+            }`, { projectId, itemId: projectItemId });
+            }
+            return toolSuccess({
+                number: args.number,
+                archived: !args.unarchive,
+                projectItemId,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to ${args.unarchive ? "unarchive" : "archive"} item: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__remove_from_project
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__remove_from_project", "Remove an issue from the project. This deletes the project item (not the issue itself). Returns: number, removed.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        number: z.number().describe("Issue number"),
+    }, async (args) => {
+        try {
+            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number);
+            await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!) {
+            deleteProjectV2Item(input: {
+              projectId: $projectId,
+              itemId: $itemId
+            }) {
+              deletedItemId
+            }
+          }`, { projectId, itemId: projectItemId });
+            // Invalidate cached project item ID since it no longer exists
+            client.getCache().invalidate(`project-item-id:${owner}/${repo}#${args.number}`);
+            return toolSuccess({
+                number: args.number,
+                removed: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to remove from project: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__add_to_project
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__add_to_project", "Add an existing issue to the project. The issue must already exist in the repository. Returns: number, projectItemId, added.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        number: z.number().describe("Issue number"),
+    }, async (args) => {
+        try {
+            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const issueNodeId = await resolveIssueNodeId(client, owner, repo, args.number);
+            const result = await client.projectMutate(`mutation($projectId: ID!, $contentId: ID!) {
+            addProjectV2ItemById(input: {
+              projectId: $projectId,
+              contentId: $contentId
+            }) {
+              item { id }
+            }
+          }`, { projectId, contentId: issueNodeId });
+            const projectItemId = result.addProjectV2ItemById.item.id;
+            // Cache the new project item ID
+            client.getCache().set(`project-item-id:${owner}/${repo}#${args.number}`, projectItemId, 30 * 60 * 1000);
+            return toolSuccess({
+                number: args.number,
+                projectItemId,
+                added: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to add to project: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__link_repository
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__link_repository", "Link or unlink a repository to/from the project. Linked repositories enable auto-add workflows and issue filtering. Returns: repository, linked.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repoToLink: z.string()
+            .describe("Repository to link, as 'owner/name' or just 'name' (uses default owner)"),
+        unlink: z.boolean().optional().default(false)
+            .describe("If true, unlink instead of link (default: false)"),
+    }, async (args) => {
+        try {
+            const { projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            // Parse repoToLink: "owner/name" or just "name" (using default owner)
+            let repoOwner;
+            let repoName;
+            if (args.repoToLink.includes("/")) {
+                const parts = args.repoToLink.split("/");
+                repoOwner = parts[0];
+                repoName = parts[1];
+            }
+            else {
+                repoOwner = client.config.owner || projectOwner;
+                repoName = args.repoToLink;
+            }
+            // Resolve repository node ID
+            const repoResult = await client.query(`query($repoOwner: String!, $repoName: String!) {
+            repository(owner: $repoOwner, name: $repoName) { id }
+          }`, { repoOwner, repoName }, { cache: true, cacheTtlMs: 60 * 60 * 1000 });
+            const repoId = repoResult.repository?.id;
+            if (!repoId) {
+                return toolError(`Repository ${repoOwner}/${repoName} not found`);
+            }
+            if (args.unlink) {
+                await client.projectMutate(`mutation($projectId: ID!, $repositoryId: ID!) {
+              unlinkProjectV2FromRepository(input: {
+                projectId: $projectId,
+                repositoryId: $repositoryId
+              }) {
+                repository { id }
+              }
+            }`, { projectId, repositoryId: repoId });
+            }
+            else {
+                await client.projectMutate(`mutation($projectId: ID!, $repositoryId: ID!) {
+              linkProjectV2ToRepository(input: {
+                projectId: $projectId,
+                repositoryId: $repositoryId
+              }) {
+                repository { id }
+              }
+            }`, { projectId, repositoryId: repoId });
+            }
+            return toolSuccess({
+                repository: `${repoOwner}/${repoName}`,
+                linked: !args.unlink,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to ${args.unlink ? "unlink" : "link"} repository: ${message}`);
+        }
+    });
+    // -------------------------------------------------------------------------
+    // ralph_hero__clear_field
+    // -------------------------------------------------------------------------
+    server.tool("ralph_hero__clear_field", "Clear a field value on a project item. Works for any single-select field (Workflow State, Estimate, Priority, Status, etc.). Returns: number, field, cleared.", {
+        owner: z.string().optional().describe("GitHub owner. Defaults to env var"),
+        repo: z.string().optional().describe("Repository name. Defaults to env var"),
+        number: z.number().describe("Issue number"),
+        field: z.string().describe("Field name to clear (e.g., 'Estimate', 'Priority', 'Workflow State')"),
+    }, async (args) => {
+        try {
+            const { owner, repo, projectNumber, projectOwner } = resolveFullConfig(client, args);
+            await ensureFieldCache(client, fieldCache, projectOwner, projectNumber);
+            const projectId = fieldCache.getProjectId();
+            if (!projectId) {
+                return toolError("Could not resolve project ID");
+            }
+            const fieldId = fieldCache.getFieldId(args.field);
+            if (!fieldId) {
+                const validFields = fieldCache.getFieldNames();
+                return toolError(`Field "${args.field}" not found in project. ` +
+                    `Valid fields: ${validFields.join(", ")}`);
+            }
+            const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, args.number);
+            await client.projectMutate(`mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!) {
+            clearProjectV2ItemFieldValue(input: {
+              projectId: $projectId,
+              itemId: $itemId,
+              fieldId: $fieldId
+            }) {
+              projectV2Item { id }
+            }
+          }`, { projectId, itemId: projectItemId, fieldId });
+            return toolSuccess({
+                number: args.number,
+                field: args.field,
+                cleared: true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return toolError(`Failed to clear field: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=project-management-tools.js.map

package/dist/tools/relationship-tools.js

@@ -11,7 +11,7 @@ import { z } from "zod";
 import { detectGroup } from "../lib/group-detection.js";
 import { isValidState, isEarlierState, VALID_STATES, } from "../lib/workflow-states.js";
 import { toolSuccess, toolError, resolveProjectOwner } from "../types.js";
-import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, } from "../lib/helpers.js";
+import { ensureFieldCache, resolveIssueNodeId, resolveProjectItemId, updateProjectItemField, getCurrentFieldValue, resolveConfig, syncStatusField, } from "../lib/helpers.js";
 // ---------------------------------------------------------------------------
 // Register relationship tools
 // ---------------------------------------------------------------------------
@@ -411,6 +411,8 @@ export function registerRelationshipTools(server, client, fieldCache) {
                     // Advance the child
                     const projectItemId = await resolveProjectItemId(client, fieldCache, owner, repo, child.number);
                     await updateProjectItemField(client, fieldCache, projectItemId, "Workflow State", args.targetState);
+                    // Sync default Status field (best-effort, one-way)
+                    await syncStatusField(client, fieldCache, projectItemId, args.targetState);
                     advanced.push({
                         number: child.number,
                         fromState: currentState,

package/package.json

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