@xferops/forge-mcp 2.0.0

package/dist/index.js

@@ -0,0 +1,739 @@
+#!/usr/bin/env node
+/**
+ * Forge MCP Server
+ *
+ * MCP (Model Context Protocol) server for interacting with the Forge API.
+ * Forge is XferOps' project management system (formerly Flower/Kanban).
+ *
+ * Works with: Claude Code, OpenAI Codex, OpenClaw/mcporter, and any MCP consumer.
+ *
+ * @see https://forge.xferops.dev/docs for API documentation
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Configuration
+// Accepts FORGE_* (preferred) or FLOWER_* (legacy, backward compat)
+// ─────────────────────────────────────────────────────────────────────────────
+const FORGE_URL = process.env.FORGE_URL ||
+    process.env.FLOWER_URL ||
+    process.env.KANBAN_URL ||
+    "https://forge.xferops.dev";
+const FORGE_TOKEN = process.env.FORGE_TOKEN ||
+    process.env.FLOWER_TOKEN ||
+    process.env.KANBAN_TOKEN ||
+    "";
+if (!FORGE_TOKEN) {
+    console.error("⚠️  Warning: FORGE_TOKEN environment variable not set");
+    console.error("   Get your token at: https://forge.xferops.dev/settings");
+}
+async function apiCall(path, options = {}) {
+    const url = `${FORGE_URL}${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${FORGE_TOKEN}`,
+            ...options.headers,
+        },
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        const apiError = data;
+        const message = apiError.details
+            ? apiError.details.map((d) => `${d.field}: ${d.message}`).join(", ")
+            : apiError.error || `HTTP ${res.status}`;
+        throw new Error(message);
+    }
+    return data;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Implementations - Health
+// ─────────────────────────────────────────────────────────────────────────────
+async function healthCheck() {
+    const data = await apiCall("/api/health");
+    return { ...data, url: FORGE_URL };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Implementations - Teams
+// ─────────────────────────────────────────────────────────────────────────────
+async function listTeams() {
+    return apiCall("/api/teams");
+}
+async function createTeam(name) {
+    return apiCall("/api/teams", {
+        method: "POST",
+        body: JSON.stringify({ name }),
+    });
+}
+async function listTeamMembers(teamId) {
+    return apiCall(`/api/teams/${teamId}/members`);
+}
+async function addTeamMember(teamId, email, role) {
+    return apiCall(`/api/teams/${teamId}/members`, {
+        method: "POST",
+        body: JSON.stringify({ email, role: role || "MEMBER" }),
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Implementations - Projects
+// ─────────────────────────────────────────────────────────────────────────────
+async function listProjects(teamId) {
+    return apiCall(`/api/teams/${teamId}/projects`);
+}
+async function getProject(projectId) {
+    return apiCall(`/api/projects/${projectId}`);
+}
+async function createProject(teamId, name, prefix) {
+    return apiCall(`/api/teams/${teamId}/projects`, {
+        method: "POST",
+        body: JSON.stringify({ name, prefix }),
+    });
+}
+async function updateProject(projectId, updates) {
+    return apiCall(`/api/projects/${projectId}`, {
+        method: "PATCH",
+        body: JSON.stringify(updates),
+    });
+}
+async function deleteProject(projectId) {
+    await apiCall(`/api/projects/${projectId}`, { method: "DELETE" });
+    return { success: true };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Implementations - Columns
+// ─────────────────────────────────────────────────────────────────────────────
+async function createColumn(projectId, name) {
+    return apiCall("/api/columns", {
+        method: "POST",
+        body: JSON.stringify({ projectId, name }),
+    });
+}
+async function updateColumn(columnId, updates) {
+    return apiCall(`/api/columns/${columnId}`, {
+        method: "PATCH",
+        body: JSON.stringify(updates),
+    });
+}
+async function deleteColumn(columnId, moveTasksTo) {
+    const url = moveTasksTo
+        ? `/api/columns/${columnId}?moveTasksTo=${moveTasksTo}`
+        : `/api/columns/${columnId}`;
+    await apiCall(url, { method: "DELETE" });
+    return { success: true };
+}
+async function reorderColumns(projectId, columnIds) {
+    await apiCall("/api/columns/reorder", {
+        method: "POST",
+        body: JSON.stringify({ projectId, columnIds }),
+    });
+    return { success: true };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Implementations - Tasks
+// ─────────────────────────────────────────────────────────────────────────────
+async function getTask(taskId) {
+    return apiCall(`/api/tasks/${taskId}`);
+}
+async function listTasks(projectId) {
+    const project = await apiCall(`/api/projects/${projectId}`);
+    const tasks = [];
+    for (const column of project.columns || []) {
+        if (column.tasks) {
+            tasks.push(...column.tasks);
+        }
+    }
+    return tasks;
+}
+async function searchTasks(query, projectId) {
+    const params = new URLSearchParams({ q: query });
+    if (projectId)
+        params.append("projectId", projectId);
+    const result = await apiCall(`/api/tasks/search?${params}`);
+    return result.tasks;
+}
+async function createTask(params) {
+    return apiCall("/api/tasks", {
+        method: "POST",
+        body: JSON.stringify(params),
+    });
+}
+async function updateTask(taskId, updates) {
+    return apiCall(`/api/tasks/${taskId}`, {
+        method: "PATCH",
+        body: JSON.stringify(updates),
+    });
+}
+async function moveTask(taskId, columnId) {
+    return apiCall(`/api/tasks/${taskId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ columnId }),
+    });
+}
+async function deleteTask(taskId) {
+    await apiCall(`/api/tasks/${taskId}`, { method: "DELETE" });
+    return { success: true };
+}
+async function reorderTask(taskId, columnId, position) {
+    await apiCall("/api/tasks/reorder", {
+        method: "POST",
+        body: JSON.stringify({ taskId, columnId, position }),
+    });
+    return { success: true };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Implementations - Comments
+// ─────────────────────────────────────────────────────────────────────────────
+async function listComments(taskId) {
+    return apiCall(`/api/comments?taskId=${taskId}`);
+}
+async function createComment(taskId, content) {
+    return apiCall("/api/comments", {
+        method: "POST",
+        body: JSON.stringify({ taskId, content }),
+    });
+}
+async function updateComment(commentId, content) {
+    return apiCall(`/api/comments/${commentId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ content }),
+    });
+}
+async function deleteComment(commentId) {
+    await apiCall(`/api/comments/${commentId}`, { method: "DELETE" });
+    return { success: true };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP Server Setup
+// ─────────────────────────────────────────────────────────────────────────────
+const server = new Server({
+    name: "forge-mcp",
+    version: "2.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Definitions
+// ─────────────────────────────────────────────────────────────────────────────
+const tools = [
+    // Health
+    {
+        name: "forge_health_check",
+        description: "Check if the Forge API is healthy and reachable. Returns the API status and configured URL.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    // Teams
+    {
+        name: "forge_list_teams",
+        description: "List all teams you belong to. Returns team IDs needed for other operations.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "forge_create_team",
+        description: "Create a new team. You become the owner.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Team name (e.g., 'Engineering', 'Product')",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "forge_list_team_members",
+        description: "List all members of a team with their roles. Useful for finding user IDs for task assignment.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                teamId: { type: "string", description: "Team ID" },
+            },
+            required: ["teamId"],
+        },
+    },
+    {
+        name: "forge_add_team_member",
+        description: "Add a user to a team by their email address.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                teamId: { type: "string", description: "Team ID" },
+                email: {
+                    type: "string",
+                    description: "Email address of the user to add",
+                },
+                role: {
+                    type: "string",
+                    enum: ["ADMIN", "MEMBER"],
+                    description: "Role to assign (default: MEMBER)",
+                },
+            },
+            required: ["teamId", "email"],
+        },
+    },
+    // Projects
+    {
+        name: "forge_list_projects",
+        description: "List all projects in a team.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                teamId: { type: "string", description: "Team ID" },
+            },
+            required: ["teamId"],
+        },
+    },
+    {
+        name: "forge_get_project",
+        description: "Get full project details including all columns and tasks. This is the main way to see the board state.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID" },
+            },
+            required: ["projectId"],
+        },
+    },
+    {
+        name: "forge_create_project",
+        description: "Create a new project (board) in a team.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                teamId: { type: "string", description: "Team ID" },
+                name: {
+                    type: "string",
+                    description: "Project name (e.g., 'Q1 Sprint', 'Product Roadmap')",
+                },
+                prefix: {
+                    type: "string",
+                    description: "Optional ticket prefix (e.g., 'PROD' for PROD-123 style tickets)",
+                },
+            },
+            required: ["teamId", "name"],
+        },
+    },
+    {
+        name: "forge_update_project",
+        description: "Update project name or ticket prefix.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID" },
+                name: { type: "string", description: "New project name" },
+                prefix: { type: "string", description: "New ticket prefix" },
+            },
+            required: ["projectId"],
+        },
+    },
+    {
+        name: "forge_delete_project",
+        description: "Delete a project and all its columns/tasks. This cannot be undone!",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID to delete" },
+            },
+            required: ["projectId"],
+        },
+    },
+    // Columns
+    {
+        name: "forge_create_column",
+        description: "Create a new column in a project board (e.g., 'Backlog', 'In Progress', 'Done').",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID" },
+                name: { type: "string", description: "Column name" },
+            },
+            required: ["projectId", "name"],
+        },
+    },
+    {
+        name: "forge_update_column",
+        description: "Rename a column.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                columnId: { type: "string", description: "Column ID" },
+                name: { type: "string", description: "New column name" },
+            },
+            required: ["columnId", "name"],
+        },
+    },
+    {
+        name: "forge_delete_column",
+        description: "Delete a column. If the column has tasks, you must specify where to move them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                columnId: { type: "string", description: "Column ID to delete" },
+                moveTasksTo: {
+                    type: "string",
+                    description: "Column ID to move existing tasks to (required if column has tasks)",
+                },
+            },
+            required: ["columnId"],
+        },
+    },
+    {
+        name: "forge_reorder_columns",
+        description: "Reorder columns in a project by providing the column IDs in the desired order.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID" },
+                columnIds: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Array of column IDs in the desired order",
+                },
+            },
+            required: ["projectId", "columnIds"],
+        },
+    },
+    // Tasks
+    {
+        name: "forge_get_task",
+        description: "Get a single task by ID with all its details.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string", description: "Task ID" },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "forge_list_tasks",
+        description: "List all tasks in a project (from all columns).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID" },
+            },
+            required: ["projectId"],
+        },
+    },
+    {
+        name: "forge_search_tasks",
+        description: "Search tasks by title, description, or ticket ID (e.g., '#123' or 'PROJ-123').",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query" },
+                projectId: {
+                    type: "string",
+                    description: "Optional: limit search to a specific project",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "forge_create_task",
+        description: "Create a new task in a project column.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Project ID" },
+                columnId: {
+                    type: "string",
+                    description: "Column ID to place the task in",
+                },
+                title: { type: "string", description: "Task title" },
+                description: {
+                    type: "string",
+                    description: "Task description (supports markdown)",
+                },
+                type: {
+                    type: "string",
+                    enum: ["TASK", "BUG", "STORY"],
+                    description: "Task type (default: TASK)",
+                },
+                priority: {
+                    type: "string",
+                    enum: ["LOW", "MEDIUM", "HIGH", "URGENT"],
+                    description: "Priority level (default: MEDIUM)",
+                },
+                assigneeId: {
+                    type: "string",
+                    description: "User ID to assign the task to",
+                },
+            },
+            required: ["projectId", "columnId", "title"],
+        },
+    },
+    {
+        name: "forge_update_task",
+        description: "Update a task. Use columnId to move it to a different column.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string", description: "Task ID" },
+                title: { type: "string", description: "New title" },
+                description: { type: "string", description: "New description" },
+                columnId: { type: "string", description: "Move to this column ID" },
+                assigneeId: {
+                    type: "string",
+                    description: "Assign to this user ID (use null to unassign)",
+                },
+                priority: {
+                    type: "string",
+                    enum: ["LOW", "MEDIUM", "HIGH", "URGENT"],
+                    description: "New priority",
+                },
+                type: {
+                    type: "string",
+                    enum: ["TASK", "BUG", "STORY"],
+                    description: "New type",
+                },
+                prUrl: { type: "string", description: "Link to a Pull Request" },
+                prNumber: { type: "number", description: "PR number" },
+                prRepo: {
+                    type: "string",
+                    description: "PR repository (e.g., 'XferOps/nexus')",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "forge_move_task",
+        description: "Move a task to a different column. Convenience wrapper around forge_update_task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string", description: "Task ID to move" },
+                columnId: { type: "string", description: "Target column ID" },
+            },
+            required: ["taskId", "columnId"],
+        },
+    },
+    {
+        name: "forge_delete_task",
+        description: "Delete a task and all its comments. This cannot be undone!",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string", description: "Task ID to delete" },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "forge_reorder_task",
+        description: "Move a task to a specific position within a column (for drag-and-drop reordering).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string", description: "Task ID to move" },
+                columnId: { type: "string", description: "Target column ID" },
+                position: {
+                    type: "number",
+                    description: "Target position (0-indexed)",
+                },
+            },
+            required: ["taskId", "columnId", "position"],
+        },
+    },
+    // Comments
+    {
+        name: "forge_list_comments",
+        description: "List all comments on a task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string", description: "Task ID" },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "forge_create_comment",
+        description: "Add a comment to a task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: { type: "string", description: "Task ID" },
+                content: {
+                    type: "string",
+                    description: "Comment content (supports markdown)",
+                },
+            },
+            required: ["taskId", "content"],
+        },
+    },
+    {
+        name: "forge_update_comment",
+        description: "Update a comment you authored.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                commentId: { type: "string", description: "Comment ID" },
+                content: { type: "string", description: "New comment content" },
+            },
+            required: ["commentId", "content"],
+        },
+    },
+    {
+        name: "forge_delete_comment",
+        description: "Delete a comment you authored.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                commentId: { type: "string", description: "Comment ID" },
+            },
+            required: ["commentId"],
+        },
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool Call Handler
+// ─────────────────────────────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            // Health
+            case "forge_health_check":
+                result = await healthCheck();
+                break;
+            // Teams
+            case "forge_list_teams":
+                result = await listTeams();
+                break;
+            case "forge_create_team":
+                result = await createTeam(args?.name);
+                break;
+            case "forge_list_team_members":
+                result = await listTeamMembers(args?.teamId);
+                break;
+            case "forge_add_team_member":
+                result = await addTeamMember(args?.teamId, args?.email, args?.role);
+                break;
+            // Projects
+            case "forge_list_projects":
+                result = await listProjects(args?.teamId);
+                break;
+            case "forge_get_project":
+                result = await getProject(args?.projectId);
+                break;
+            case "forge_create_project":
+                result = await createProject(args?.teamId, args?.name, args?.prefix);
+                break;
+            case "forge_update_project":
+                result = await updateProject(args?.projectId, {
+                    name: args?.name,
+                    prefix: args?.prefix,
+                });
+                break;
+            case "forge_delete_project":
+                result = await deleteProject(args?.projectId);
+                break;
+            // Columns
+            case "forge_create_column":
+                result = await createColumn(args?.projectId, args?.name);
+                break;
+            case "forge_update_column":
+                result = await updateColumn(args?.columnId, {
+                    name: args?.name,
+                });
+                break;
+            case "forge_delete_column":
+                result = await deleteColumn(args?.columnId, args?.moveTasksTo);
+                break;
+            case "forge_reorder_columns":
+                result = await reorderColumns(args?.projectId, args?.columnIds);
+                break;
+            // Tasks
+            case "forge_get_task":
+                result = await getTask(args?.taskId);
+                break;
+            case "forge_list_tasks":
+                result = await listTasks(args?.projectId);
+                break;
+            case "forge_search_tasks":
+                result = await searchTasks(args?.query, args?.projectId);
+                break;
+            case "forge_create_task":
+                result = await createTask({
+                    projectId: args?.projectId,
+                    columnId: args?.columnId,
+                    title: args?.title,
+                    description: args?.description,
+                    type: args?.type,
+                    priority: args?.priority,
+                    assigneeId: args?.assigneeId,
+                });
+                break;
+            case "forge_update_task":
+                result = await updateTask(args?.taskId, {
+                    title: args?.title,
+                    description: args?.description,
+                    columnId: args?.columnId,
+                    assigneeId: args?.assigneeId,
+                    priority: args?.priority,
+                    type: args?.type,
+                    prUrl: args?.prUrl,
+                    prNumber: args?.prNumber,
+                    prRepo: args?.prRepo,
+                });
+                break;
+            case "forge_move_task":
+                result = await moveTask(args?.taskId, args?.columnId);
+                break;
+            case "forge_delete_task":
+                result = await deleteTask(args?.taskId);
+                break;
+            case "forge_reorder_task":
+                result = await reorderTask(args?.taskId, args?.columnId, args?.position);
+                break;
+            // Comments
+            case "forge_list_comments":
+                result = await listComments(args?.taskId);
+                break;
+            case "forge_create_comment":
+                result = await createComment(args?.taskId, args?.content);
+                break;
+            case "forge_update_comment":
+                result = await updateComment(args?.commentId, args?.content);
+                break;
+            case "forge_delete_comment":
+                result = await deleteComment(args?.commentId);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Start Server
+// ─────────────────────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("⚒️  Forge MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Failed to start Forge MCP server:", error);
+    process.exit(1);
+});