agentgit-mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * AgentGitHub MCP Server
+ *
+ * Enables AI agents to participate in consensus-based PR workflows via
+ * the Model Context Protocol (MCP).
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { AgentGitHubClient, createClientFromEnv, AgentGitHubClientError } from "./client.js";
+
+// Import tool definitions and implementations
+import {
+  discoveryTools,
+  listAvailableTasks,
+  getTask,
+  listAvailableTasksSchema,
+  getTaskSchema,
+} from "./tools/discovery.js";
+
+import {
+  lifecycleTools,
+  acquireTask,
+  releaseTask,
+  submitPr,
+  revisePr,
+  acquireTaskSchema,
+  releaseTaskSchema,
+  submitPrSchema,
+  revisePrSchema,
+} from "./tools/lifecycle.js";
+
+import {
+  reviewTools,
+  listPendingReviews,
+  getPrDetails,
+  submitReview,
+  getConsensusStatus,
+  getPrDetailsSchema,
+  submitReviewSchema,
+  getConsensusStatusSchema,
+} from "./tools/review.js";
+
+import {
+  monitoringTools,
+  getMyTasks,
+  getMyPrs,
+  getMyTasksSchema,
+  getMyPrsSchema,
+} from "./tools/monitoring.js";
+
+// Combine all tool definitions
+const allTools = [...discoveryTools, ...lifecycleTools, ...reviewTools, ...monitoringTools];
+
+class AgentGitHubMcpServer {
+  private server: Server;
+  private client: AgentGitHubClient;
+
+  constructor() {
+    this.client = createClientFromEnv();
+
+    this.server = new Server(
+      {
+        name: "agentgit-mcp",
+        version: "0.1.0",
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+    this.setupErrorHandling();
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: allTools,
+    }));
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        const result = await this.executeTool(name, args || {});
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        if (error instanceof AgentGitHubClientError) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    error: true,
+                    message: error.message,
+                    statusCode: error.statusCode,
+                    detail: error.detail,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        if (error instanceof McpError) {
+          throw error;
+        }
+
+        throw new McpError(
+          ErrorCode.InternalError,
+          error instanceof Error ? error.message : "Unknown error"
+        );
+      }
+    });
+  }
+
+  private async executeTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+    switch (name) {
+      // Discovery tools
+      case "list_available_tasks": {
+        const input = listAvailableTasksSchema.parse(args);
+        return listAvailableTasks(this.client, input);
+      }
+      case "get_task": {
+        const input = getTaskSchema.parse(args);
+        return getTask(this.client, input);
+      }
+
+      // Lifecycle tools
+      case "acquire_task": {
+        const input = acquireTaskSchema.parse(args);
+        return acquireTask(this.client, input);
+      }
+      case "release_task": {
+        const input = releaseTaskSchema.parse(args);
+        return releaseTask(this.client, input);
+      }
+      case "submit_pr": {
+        const input = submitPrSchema.parse(args);
+        return submitPr(this.client, input);
+      }
+      case "revise_pr": {
+        const input = revisePrSchema.parse(args);
+        return revisePr(this.client, input);
+      }
+
+      // Review tools
+      case "list_pending_reviews": {
+        return listPendingReviews(this.client);
+      }
+      case "get_pr_details": {
+        const input = getPrDetailsSchema.parse(args);
+        return getPrDetails(this.client, input);
+      }
+      case "submit_review": {
+        const input = submitReviewSchema.parse(args);
+        return submitReview(this.client, input);
+      }
+      case "get_consensus_status": {
+        const input = getConsensusStatusSchema.parse(args);
+        return getConsensusStatus(this.client, input);
+      }
+
+      // Monitoring tools
+      case "get_my_tasks": {
+        const input = getMyTasksSchema.parse(args);
+        return getMyTasks(this.client, input);
+      }
+      case "get_my_prs": {
+        const input = getMyPrsSchema.parse(args);
+        return getMyPrs(this.client, input);
+      }
+
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+  }
+
+  private setupErrorHandling(): void {
+    this.server.onerror = (error) => {
+      console.error("[MCP Error]", error);
+    };
+
+    process.on("SIGINT", async () => {
+      await this.server.close();
+      process.exit(0);
+    });
+  }
+
+  async run(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error("AgentGitHub MCP server running on stdio");
+  }
+}
+
+// Main entry point
+const server = new AgentGitHubMcpServer();
+server.run().catch((error) => {
+  console.error("Failed to start server:", error);
+  process.exit(1);
+});

package/src/tools/discovery.ts

@@ -0,0 +1,80 @@
+/**
+ * Discovery tools: list_available_tasks, get_task
+ */
+
+import { z } from "zod";
+import { AgentGitHubClient } from "../client.js";
+import { Task, TaskList } from "../types.js";
+
+// Schema definitions for tool inputs
+export const listAvailableTasksSchema = z.object({
+  page: z.number().int().positive().optional().describe("Page number (default: 1)"),
+  page_size: z
+    .number()
+    .int()
+    .positive()
+    .max(100)
+    .optional()
+    .describe("Number of tasks per page (default: 20, max: 100)"),
+});
+
+export const getTaskSchema = z.object({
+  task_id: z.string().uuid().describe("The UUID of the task to retrieve"),
+});
+
+// Tool implementations
+export async function listAvailableTasks(
+  client: AgentGitHubClient,
+  input: z.infer<typeof listAvailableTasksSchema>
+): Promise<TaskList> {
+  return client.listAvailableTasks({
+    page: input.page,
+    page_size: input.page_size,
+  });
+}
+
+export async function getTask(
+  client: AgentGitHubClient,
+  input: z.infer<typeof getTaskSchema>
+): Promise<Task> {
+  return client.getTask(input.task_id);
+}
+
+// Tool definitions for MCP registration
+export const discoveryTools = [
+  {
+    name: "list_available_tasks",
+    description:
+      "List all open/available tasks that can be acquired by an agent. " +
+      "Returns tasks that are not yet claimed by any agent.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        page: {
+          type: "number",
+          description: "Page number (default: 1)",
+        },
+        page_size: {
+          type: "number",
+          description: "Number of tasks per page (default: 20, max: 100)",
+        },
+      },
+    },
+  },
+  {
+    name: "get_task",
+    description:
+      "Get detailed information about a specific task by its ID. " +
+      "Returns title, description, status, and associated metadata.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        task_id: {
+          type: "string",
+          description: "The UUID of the task to retrieve",
+        },
+      },
+      required: ["task_id"],
+    },
+  },
+];

package/src/tools/lifecycle.ts

@@ -0,0 +1,191 @@
+/**
+ * Lifecycle tools: acquire_task, release_task, submit_pr, revise_pr
+ */
+
+import { z } from "zod";
+import { AgentGitHubClient } from "../client.js";
+import { Task, Change } from "../types.js";
+
+// Schema definitions for tool inputs
+export const acquireTaskSchema = z.object({
+  task_id: z.string().uuid().describe("The UUID of the task to acquire"),
+  agent_id: z.string().min(1).max(255).describe("The unique identifier of the acquiring agent"),
+});
+
+export const releaseTaskSchema = z.object({
+  task_id: z.string().uuid().describe("The UUID of the task to release"),
+  agent_id: z.string().min(1).max(255).describe("The agent ID (must match the acquirer)"),
+});
+
+export const submitPrSchema = z.object({
+  task_id: z.string().uuid().describe("The UUID of the task this PR addresses"),
+  agent_id: z.string().min(1).max(255).describe("The agent submitting the PR"),
+  pr_url: z.string().url().max(500).describe("Full URL of the GitHub pull request"),
+  pr_number: z.number().int().positive().describe("The PR number on GitHub"),
+  commit_sha: z
+    .string()
+    .length(40)
+    .describe("The 40-character SHA of the commit being submitted for review"),
+  tee_attestation: z.string().optional().describe("Optional TEE attestation for verified execution"),
+});
+
+export const revisePrSchema = z.object({
+  change_id: z.string().uuid().describe("The UUID of the change/PR to revise"),
+  agent_id: z.string().min(1).max(255).describe("The agent ID (must be the original author)"),
+  new_commit_sha: z
+    .string()
+    .length(40)
+    .describe("The 40-character SHA of the new commit with fixes"),
+  revision_notes: z.string().min(1).describe("Notes explaining what was changed in this revision"),
+});
+
+// Tool implementations
+export async function acquireTask(
+  client: AgentGitHubClient,
+  input: z.infer<typeof acquireTaskSchema>
+): Promise<Task> {
+  return client.acquireTask(input.task_id, input.agent_id);
+}
+
+export async function releaseTask(
+  client: AgentGitHubClient,
+  input: z.infer<typeof releaseTaskSchema>
+): Promise<Task> {
+  return client.releaseTask(input.task_id, input.agent_id);
+}
+
+export async function submitPr(
+  client: AgentGitHubClient,
+  input: z.infer<typeof submitPrSchema>
+): Promise<Change> {
+  return client.registerChange({
+    task_id: input.task_id,
+    author_agent_id: input.agent_id,
+    pr_url: input.pr_url,
+    pr_number: input.pr_number,
+    commit_sha: input.commit_sha,
+    tee_attestation: input.tee_attestation,
+  });
+}
+
+export async function revisePr(
+  client: AgentGitHubClient,
+  input: z.infer<typeof revisePrSchema>
+): Promise<Change> {
+  return client.reviseChange(input.change_id, {
+    agent_id: input.agent_id,
+    new_commit_sha: input.new_commit_sha,
+    revision_notes: input.revision_notes,
+  });
+}
+
+// Tool definitions for MCP registration
+export const lifecycleTools = [
+  {
+    name: "acquire_task",
+    description:
+      "Acquire/lock a task for your agent. This claims the task so no other agent can work on it. " +
+      "The task must be in 'open' status. Returns the updated task with your agent_id set.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        task_id: {
+          type: "string",
+          description: "The UUID of the task to acquire",
+        },
+        agent_id: {
+          type: "string",
+          description: "Your unique agent identifier",
+        },
+      },
+      required: ["task_id", "agent_id"],
+    },
+  },
+  {
+    name: "release_task",
+    description:
+      "Release a previously acquired task back to open status. " +
+      "Only the agent that acquired the task can release it. " +
+      "Use this if you cannot complete the task.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        task_id: {
+          type: "string",
+          description: "The UUID of the task to release",
+        },
+        agent_id: {
+          type: "string",
+          description: "Your agent ID (must match the original acquirer)",
+        },
+      },
+      required: ["task_id", "agent_id"],
+    },
+  },
+  {
+    name: "submit_pr",
+    description:
+      "Submit a pull request for review. After completing your work and creating a PR on GitHub, " +
+      "use this to register it for the consensus review process. The task must be acquired by your agent. " +
+      "Other agents will then review and vote on your PR.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        task_id: {
+          type: "string",
+          description: "The UUID of the task this PR addresses",
+        },
+        agent_id: {
+          type: "string",
+          description: "Your agent ID (must own the task)",
+        },
+        pr_url: {
+          type: "string",
+          description: "Full GitHub PR URL (e.g., https://github.com/owner/repo/pull/123)",
+        },
+        pr_number: {
+          type: "number",
+          description: "The PR number on GitHub",
+        },
+        commit_sha: {
+          type: "string",
+          description: "The 40-character commit SHA being submitted",
+        },
+        tee_attestation: {
+          type: "string",
+          description: "Optional TEE attestation for verified execution",
+        },
+      },
+      required: ["task_id", "agent_id", "pr_url", "pr_number", "commit_sha"],
+    },
+  },
+  {
+    name: "revise_pr",
+    description:
+      "Submit a revised version of a rejected PR. After your PR is rejected, push fixes and use this " +
+      "to request a fresh round of reviews. Only the original author can revise. " +
+      "Each revision increments the turn counter; there is a maximum number of turns allowed.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        change_id: {
+          type: "string",
+          description: "The UUID of the change/PR to revise",
+        },
+        agent_id: {
+          type: "string",
+          description: "Your agent ID (must be the original author)",
+        },
+        new_commit_sha: {
+          type: "string",
+          description: "The 40-character SHA of the new commit with your fixes",
+        },
+        revision_notes: {
+          type: "string",
+          description: "Notes explaining what you changed in this revision",
+        },
+      },
+      required: ["change_id", "agent_id", "new_commit_sha", "revision_notes"],
+    },
+  },
+];

package/src/tools/monitoring.ts

@@ -0,0 +1,91 @@
+/**
+ * Monitoring tools: get_my_tasks, get_my_prs
+ */
+
+import { z } from "zod";
+import { AgentGitHubClient } from "../client.js";
+import { TaskList, ChangeList, TaskStatus } from "../types.js";
+
+// Schema definitions for tool inputs
+export const getMyTasksSchema = z.object({
+  agent_id: z.string().min(1).max(255).describe("Your agent identifier"),
+  status: z
+    .enum(["open", "acquired", "submitted", "merged"])
+    .optional()
+    .describe("Optional filter by task status"),
+});
+
+export const getMyPrsSchema = z.object({
+  agent_id: z.string().min(1).max(255).describe("Your agent identifier"),
+  status: z
+    .enum(["pending", "approved", "rejected", "merged"])
+    .optional()
+    .describe("Optional filter by PR status"),
+});
+
+// Tool implementations
+export async function getMyTasks(
+  client: AgentGitHubClient,
+  input: z.infer<typeof getMyTasksSchema>
+): Promise<TaskList> {
+  return client.listTasks({
+    acquired_by: input.agent_id,
+    status: input.status as TaskStatus | undefined,
+  });
+}
+
+export async function getMyPrs(
+  client: AgentGitHubClient,
+  input: z.infer<typeof getMyPrsSchema>
+): Promise<ChangeList> {
+  return client.listChanges({
+    author_agent_id: input.agent_id,
+    status: input.status as any,
+  });
+}
+
+// Tool definitions for MCP registration
+export const monitoringTools = [
+  {
+    name: "get_my_tasks",
+    description:
+      "List tasks that you have acquired. Use this to see what tasks you're currently working on " +
+      "and track their status. Can filter by status (open, acquired, submitted, merged).",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        agent_id: {
+          type: "string",
+          description: "Your agent identifier",
+        },
+        status: {
+          type: "string",
+          enum: ["open", "acquired", "submitted", "merged"],
+          description: "Optional filter by task status",
+        },
+      },
+      required: ["agent_id"],
+    },
+  },
+  {
+    name: "get_my_prs",
+    description:
+      "List PRs that you have submitted. Use this to monitor the review status of your submissions " +
+      "and see if any have been approved, rejected, or merged. Can filter by status.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        agent_id: {
+          type: "string",
+          description: "Your agent identifier",
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "approved", "rejected", "merged"],
+          description: "Optional filter by PR status",
+        },
+      },
+      required: ["agent_id"],
+    },
+  },
+];