@agent-collab/mcp-server 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+export type CollaborationClientEnv = {
+    COLLABORATION_API_BASE_URL?: string;
+    MCP_API_TOKEN?: string;
+    COLLABORATION_CLIENT?: string;
+    COLLABORATION_TASK_ID?: string;
+};
+export type JsonObject = Record<string, unknown>;
+export type GetCollaborationContextInput = {
+    projectSlug?: string;
+    taskId?: string;
+};
+export type GetProjectConflictsInput = {
+    projectSlug?: string;
+};
+export type ClaimPathsInput = {
+    taskId: string;
+    agentSessionId?: string;
+    ownerMemberId?: string;
+    claims: Array<{
+        path: string;
+        claimType: "file" | "directory" | "module" | "service";
+    }>;
+};
+export type RegisterSessionInput = {
+    taskId?: string;
+    client: "codex-app" | "codex-cli" | "ide-agent";
+};
+export type HeartbeatInput = {
+    agentSessionId: string;
+    status?: "online" | "idle" | "offline";
+};
+export type ReportProgressInput = {
+    taskId: string;
+    agentSessionId?: string;
+    kind: "started" | "progress" | "finding" | "submitted" | "blocked";
+    message: string;
+};
+export type SubmitWorkInput = {
+    taskId: string;
+    title: string;
+    kind: "branch" | "patch" | "pull_request";
+    reference: string;
+};
+export type CollaborationClient = {
+    getCollaborationContext: (input: GetCollaborationContextInput) => Promise<unknown>;
+    getProjectConflicts: (input: GetProjectConflictsInput) => Promise<unknown>;
+    registerSession: (input: RegisterSessionInput) => Promise<unknown>;
+    heartbeat: (input: HeartbeatInput) => Promise<unknown>;
+    claimPaths: (input: ClaimPathsInput) => Promise<unknown>;
+    reportProgress: (input: ReportProgressInput) => Promise<unknown>;
+    submitWork: (input: SubmitWorkInput) => Promise<unknown>;
+};
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export declare class CollaborationApiError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+export declare const createCollaborationClient: (env?: CollaborationClientEnv, fetchImpl?: FetchLike) => CollaborationClient;

package/dist/client.js

@@ -0,0 +1,138 @@
+export class CollaborationApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "CollaborationApiError";
+    }
+}
+export const createCollaborationClient = (env = process.env, fetchImpl = fetch) => {
+    let sessionPromise = null;
+    const get = (path, query) => requestJson(env, fetchImpl, path, {
+        method: "GET",
+        query
+    });
+    const post = (path, body) => requestJson(env, fetchImpl, path, {
+        method: "POST",
+        body
+    });
+    const register = async (input) => {
+        const response = await post("/api/collaboration/register-session", input);
+        const session = readRegisteredSession(response);
+        if (session) {
+            sessionPromise = Promise.resolve(session);
+        }
+        return response;
+    };
+    const ensureSession = (taskId) => {
+        sessionPromise ??= register({
+            taskId: taskId ?? env.COLLABORATION_TASK_ID,
+            client: collaborationClientName(env.COLLABORATION_CLIENT)
+        }).then((response) => {
+            const session = readRegisteredSession(response);
+            if (!session) {
+                throw new CollaborationApiError("register-session response did not include session id and member id");
+            }
+            return session;
+        });
+        return sessionPromise;
+    };
+    return {
+        getCollaborationContext: (input) => get("/api/collaboration/context", {
+            projectSlug: input.projectSlug,
+            taskId: input.taskId
+        }),
+        getProjectConflicts: (input) => get("/api/collaboration/conflicts", {
+            projectSlug: input.projectSlug
+        }),
+        registerSession: register,
+        heartbeat: (input) => post("/api/collaboration/heartbeat", input),
+        claimPaths: async (input) => {
+            const session = input.agentSessionId && input.ownerMemberId
+                ? null
+                : await ensureSession(input.taskId);
+            return post("/api/collaboration/claim-paths", {
+                ...input,
+                agentSessionId: input.agentSessionId ?? session?.id,
+                ownerMemberId: input.ownerMemberId ?? session?.memberId
+            });
+        },
+        reportProgress: async (input) => {
+            const session = input.agentSessionId ? null : await ensureSession(input.taskId);
+            return post("/api/collaboration/progress", {
+                ...input,
+                agentSessionId: input.agentSessionId ?? session?.id
+            });
+        },
+        submitWork: (input) => post("/api/collaboration/submit-work", input)
+    };
+};
+const collaborationClientName = (value) => {
+    if (value === "codex-cli" || value === "ide-agent") {
+        return value;
+    }
+    return "codex-app";
+};
+const readRegisteredSession = (value) => {
+    const response = value;
+    const id = response.session?.id;
+    const memberId = response.session?.memberId;
+    if (typeof id === "string" && typeof memberId === "string") {
+        return {
+            id,
+            memberId
+        };
+    }
+    return null;
+};
+const requestJson = async (env, fetchImpl, path, request) => {
+    const baseUrl = requiredEnv(env.COLLABORATION_API_BASE_URL, "COLLABORATION_API_BASE_URL");
+    const token = requiredEnv(env.MCP_API_TOKEN, "MCP_API_TOKEN");
+    const url = buildUrl(baseUrl, path, request.query);
+    const response = await fetchImpl(url, {
+        method: request.method,
+        headers: {
+            authorization: `Bearer ${token}`,
+            ...(request.body ? { "content-type": "application/json" } : {})
+        },
+        ...(request.body ? { body: JSON.stringify(request.body) } : {})
+    });
+    const json = await readJson(response);
+    if (!response.ok) {
+        const apiError = json;
+        const code = apiError.error?.code ?? "unknown_error";
+        const message = apiError.error?.message ?? response.statusText;
+        throw new CollaborationApiError(`Collaboration API request failed: ${response.status} ${code} - ${message}`, response.status, code);
+    }
+    return json;
+};
+const requiredEnv = (value, name) => {
+    if (!value) {
+        throw new CollaborationApiError(`${name} is required`);
+    }
+    return value;
+};
+const buildUrl = (baseUrl, path, query) => {
+    const url = new URL(path, withTrailingSlash(baseUrl));
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value) {
+            url.searchParams.set(key, value);
+        }
+    }
+    return url.toString();
+};
+const withTrailingSlash = (value) => (value.endsWith("/") ? value : `${value}/`);
+const readJson = async (response) => {
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CollaborationApiError(`Collaboration API returned non-JSON response with status ${response.status}`, response.status);
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+import { createCollaborationClient } from "./client.js";
+const server = new McpServer({
+    name: "agent-collaboration-mcp-server",
+    version: "0.1.0"
+});
+const client = createCollaborationClient();
+const jsonContent = (payload) => ({
+    content: [
+        {
+            type: "text",
+            text: JSON.stringify(payload, null, 2)
+        }
+    ]
+});
+server.registerTool("get_collaboration_context", {
+    title: "Get Collaboration Context",
+    description: "Read project, task, knowledge, plan, path claim, and submission context.",
+    inputSchema: {
+        projectSlug: z.string().optional().describe("Project slug. Defaults to server configuration."),
+        taskId: z.string().optional().describe("Task id. Defaults to the latest active task.")
+    }
+}, async (input) => jsonContent(await client.getCollaborationContext(input)));
+server.registerTool("get_project_conflicts", {
+    title: "Get Project Conflicts",
+    description: "Read active path claims and computed overlap conflicts for a project.",
+    inputSchema: {
+        projectSlug: z.string().optional().describe("Project slug. Defaults to server configuration.")
+    }
+}, async (input) => jsonContent(await client.getProjectConflicts(input)));
+server.registerTool("register_session", {
+    title: "Register Session",
+    description: "Register the current agent session for a project token.",
+    inputSchema: {
+        taskId: z.string().optional().describe("Optional task id. Defaults to the latest active task."),
+        client: z.enum(["codex-app", "codex-cli", "ide-agent"])
+    }
+}, async (input) => jsonContent(await client.registerSession(input)));
+server.registerTool("heartbeat", {
+    title: "Heartbeat",
+    description: "Update lastSeenAt and status for a registered agent session.",
+    inputSchema: {
+        agentSessionId: z.string().describe("Agent session id returned by register_session."),
+        status: z.enum(["online", "idle", "offline"]).optional()
+    }
+}, async (input) => jsonContent(await client.heartbeat(input)));
+server.registerTool("claim_paths", {
+    title: "Claim Paths",
+    description: "Declare files, directories, modules, or services an agent is actively editing.",
+    inputSchema: {
+        taskId: z.string().describe("Task id for the current work."),
+        agentSessionId: z.string().optional().describe("Agent session id. Defaults to auto-registered session."),
+        ownerMemberId: z.string().optional().describe("Member id. Defaults to the project token owner."),
+        claims: z
+            .array(z.object({
+            path: z.string().describe("Repository path or logical module/service name."),
+            claimType: z.enum(["file", "directory", "module", "service"])
+        }))
+            .min(1)
+    }
+}, async (input) => jsonContent(await client.claimPaths(input)));
+server.registerTool("report_progress", {
+    title: "Report Progress",
+    description: "Report started, progress, finding, submitted, or blocked status for a task.",
+    inputSchema: {
+        taskId: z.string().describe("Task id for the current work."),
+        agentSessionId: z.string().optional().describe("Agent session id. Defaults to auto-registered session."),
+        kind: z.enum(["started", "progress", "finding", "submitted", "blocked"]),
+        message: z.string().describe("Short progress update shown on the dashboard.")
+    }
+}, async (input) => jsonContent(await client.reportProgress(input)));
+server.registerTool("submit_work", {
+    title: "Submit Work",
+    description: "Submit a branch, patch, or pull request reference into the merge queue.",
+    inputSchema: {
+        taskId: z.string().describe("Task id for the completed work."),
+        title: z.string().describe("Human-readable submission title."),
+        kind: z.enum(["branch", "patch", "pull_request"]),
+        reference: z.string().describe("Branch name, patch reference, or pull request URL.")
+    }
+}, async (input) => jsonContent(await client.submitWork(input)));
+const main = async () => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Agent Collaboration MCP server running on stdio");
+};
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@agent-collab/mcp-server",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agent-collab-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/index.ts",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  }
+}