@becklabs/beck-mcp-server 1.0.0

package/dist/tools/index.js

@@ -0,0 +1,739 @@
+import * as taskTools from "./tasks.js";
+import * as documentTools from "./documents.js";
+/**
+ * Define all MCP tools available to Claude Code
+ */
+export const TOOLS = [
+    {
+        name: "whoami",
+        description: "Return the identity behind this API token (name, email, user id). Use to know who comments and progress updates will be attributed to.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "list_workspaces",
+        description: "List Beck workspaces this token can see. Tokens are org-scoped — this is not a default workspace. If the human named one, use only that id. If more than one and none named, ask. create_workspace only if they asked for a new one.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "create_workspace",
+        description: "Create a workspace in the current org or personal account. Default: only when the human asked for a new workspace. If they named an existing one, bind to that instead. An empty bound workspace gets a prd document, not a second workspace. The human's prompt overrides this default.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Workspace name",
+                },
+                description: {
+                    type: "string",
+                    description: "Optional description",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "list_tasks",
+        description: "List tasks in a workspace. Can filter by status, epic, or show icebox items.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "The workspace ID to list tasks from",
+                },
+                status: {
+                    type: "string",
+                    enum: ["not_started", "started", "ready_for_review", "completed"],
+                    description: "Filter by task status",
+                },
+                epicId: {
+                    type: "string",
+                    description: "Filter by epic ID",
+                },
+                isIcebox: {
+                    type: "boolean",
+                    description: "If true, list icebox items instead of backlog",
+                },
+                assigneeId: {
+                    type: "string",
+                    description: "Filter by assignee user ID",
+                },
+            },
+            required: ["workspaceId"],
+        },
+    },
+    {
+        name: "get_task",
+        description: "Get full details of a task including description, acceptance criteria, and comments.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to retrieve",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "start_task",
+        description: "Start working on a task. This assigns the task to you and changes status to 'started'. Use this before beginning implementation work.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to start",
+                },
+                comment: {
+                    type: "string",
+                    description: "Optional comment to add when starting (e.g., your implementation approach)",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "finish_task",
+        description: "Submit a task for review. Changes status to 'ready_for_review'. Use this after completing implementation work. accept_task / reject_task are the next step — default is to leave review to the human unless they asked you to review.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to finish",
+                },
+                comment: {
+                    type: "string",
+                    description: "Optional completion comment summarizing what was done",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "accept_task",
+        description: "Accept a ready_for_review task (marks completed). Default: only when the human asked you to review or accept. Do not accept your own work unless they said to. The human's prompt overrides this default.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to accept",
+                },
+                comment: {
+                    type: "string",
+                    description: "Optional acceptance comment",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "reject_task",
+        description: "Reject a ready_for_review task back to started. reason is required and is stored on the activity feed. Default: only when the human asked you to review or reject. The human's prompt overrides this default.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to reject",
+                },
+                reason: {
+                    type: "string",
+                    description: "Why the task is being sent back",
+                },
+            },
+            required: ["taskId", "reason"],
+        },
+    },
+    {
+        name: "list_comments",
+        description: "List all comments on a task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "add_comment",
+        description: "Add a comment to a task. Use this to document progress, ask questions, or provide updates.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to comment on",
+                },
+                content: {
+                    type: "string",
+                    description: "The comment text (supports markdown)",
+                },
+            },
+            required: ["taskId", "content"],
+        },
+    },
+    {
+        name: "update_task",
+        description: "Update task details (title, type, points, tags, epic, description, blocked status, acceptance criteria, relevant files). Status cannot be set here — use start_task, finish_task, accept_task, or reject_task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to update",
+                },
+                title: {
+                    type: "string",
+                    description: "New title",
+                },
+                type: {
+                    type: "string",
+                    enum: ["feature", "bug", "chore"],
+                    description: "Task type",
+                },
+                points: {
+                    type: "number",
+                    description: "Story points (1, 2, 3, 5, or 8)",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Replacement tag list",
+                },
+                epicId: {
+                    type: "string",
+                    description: "Move the task to this epic",
+                },
+                description: {
+                    type: "string",
+                    description: "New description (markdown)",
+                },
+                isBlocked: {
+                    type: "boolean",
+                    description: "Whether the task is blocked",
+                },
+                blockedReason: {
+                    type: "string",
+                    description: "Reason for being blocked (required if isBlocked is true)",
+                },
+                acceptanceCriteria: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            text: { type: "string" },
+                            completed: { type: "boolean" },
+                        },
+                        required: ["text", "completed"],
+                    },
+                    description: "Updated acceptance criteria with completion status",
+                },
+                relevantFiles: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            path: { type: "string", description: "Relative path from project root (e.g., 'src/api/auth.ts')" },
+                            purpose: { type: "string", description: "Why this file is relevant (e.g., 'main implementation', 'test file')" },
+                        },
+                        required: ["path"],
+                    },
+                    description: "Files relevant to this task. Paths must be relative to project root.",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "set_relevant_files",
+        description: "Set the relevant files for a task. Use this to record which files are important for the task, so future work sessions know where to look. Paths must be relative to project root.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to update",
+                },
+                files: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            path: { type: "string", description: "Relative path from project root (e.g., 'src/api/auth.ts')" },
+                            purpose: { type: "string", description: "Why this file is relevant (e.g., 'main implementation', 'test file')" },
+                        },
+                        required: ["path"],
+                    },
+                    description: "Files relevant to this task",
+                },
+            },
+            required: ["taskId", "files"],
+        },
+    },
+    {
+        name: "get_task_context",
+        description: "Get rich context for a task including epic spec, related tasks, comments, and activity. Use this when starting work on a task to understand the full context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to get context for",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "log_progress",
+        description: "Log a structured progress update for a task. Use this to document what you attempted, what succeeded, what failed, and any blockers or questions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID to log progress for",
+                },
+                whatAttempted: {
+                    type: "string",
+                    description: "What was attempted (required)",
+                },
+                whatSucceeded: {
+                    type: "string",
+                    description: "What worked or was accomplished",
+                },
+                whatFailed: {
+                    type: "string",
+                    description: "What didn't work and why",
+                },
+                questions: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Questions for the team",
+                },
+                blockers: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Issues blocking progress (will mark task as blocked if provided)",
+                },
+            },
+            required: ["taskId", "whatAttempted"],
+        },
+    },
+    {
+        name: "list_progress",
+        description: "List structured progress updates for a task.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskId: {
+                    type: "string",
+                    description: "The task ID",
+                },
+            },
+            required: ["taskId"],
+        },
+    },
+    {
+        name: "recommend_task",
+        description: "Get recommendations for what task to work on next. Returns tasks prioritized by: 1) Your in-progress work, 2) Tasks assigned to you, 3) High-priority unassigned tasks.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "The workspace ID to get recommendations for",
+                },
+                epicId: {
+                    type: "string",
+                    description: "Optional: filter recommendations to tasks in a specific epic",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of recommendations to return (default 5, max 20)",
+                },
+            },
+            required: ["workspaceId"],
+        },
+    },
+    {
+        name: "list_documents",
+        description: "List planning documents in a workspace. Documents are the living PRD/notes corpus.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace ID" },
+            },
+            required: ["workspaceId"],
+        },
+    },
+    {
+        name: "read_document",
+        description: "Read a workspace document by path (e.g. prd or research/notes).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                path: { type: "string", description: "Document path such as prd" },
+            },
+            required: ["workspaceId", "path"],
+        },
+    },
+    {
+        name: "create_document",
+        description: "Create a markdown document in a workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                path: { type: "string" },
+                title: { type: "string" },
+                body: { type: "string", description: "Markdown body" },
+            },
+            required: ["workspaceId", "path"],
+        },
+    },
+    {
+        name: "write_document",
+        description: "Update a document. etag is required (If-Match from a prior read_document). Writes without an etag are rejected so concurrent edits cannot silently overwrite.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                path: { type: "string" },
+                title: { type: "string" },
+                body: { type: "string" },
+                etag: { type: "string", description: "Required If-Match etag from a prior read" },
+            },
+            required: ["workspaceId", "path", "etag"],
+        },
+    },
+    {
+        name: "delete_document",
+        description: "Delete a document. etag is required (If-Match from a prior read_document) so concurrent deletes cannot race a newer edit.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                path: { type: "string" },
+                etag: { type: "string", description: "Required If-Match etag from a prior read" },
+            },
+            required: ["workspaceId", "path", "etag"],
+        },
+    },
+    {
+        name: "list_document_versions",
+        description: "List saved versions of a document (id, time, actor, etag). Use restore_document to roll back.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                path: { type: "string" },
+            },
+            required: ["workspaceId", "path"],
+        },
+    },
+    {
+        name: "restore_document",
+        description: "Restore a document to a previous version. etag is the current document etag (If-Match), not the version's etag.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                path: { type: "string" },
+                versionId: { type: "string", description: "Version id from list_document_versions" },
+                etag: { type: "string", description: "Current document etag from read_document" },
+            },
+            required: ["workspaceId", "path", "versionId", "etag"],
+        },
+    },
+    {
+        name: "list_epics",
+        description: "List epics in a workspace (title, status, task counts, last plan, GitHub).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+            },
+            required: ["workspaceId"],
+        },
+    },
+    {
+        name: "get_epic",
+        description: "Get an epic: working spec, last-plan provenance, imported tasks, GitHub link, and latest suggested breakdown. Use after plan_it or when you need the spec without a task id.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                epicId: { type: "string", description: "The epic ID" },
+            },
+            required: ["epicId"],
+        },
+    },
+    {
+        name: "plan_it",
+        description: "Snapshot selected documents into one or more epics and run AI task breakdown. Does not import tasks until a human reviews them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string" },
+                paths: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Document paths to snapshot",
+                },
+                documentIds: { type: "array", items: { type: "string" } },
+                epicIds: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Existing epics to update. Omit to create a new epic.",
+                },
+                title: { type: "string", description: "Title for a new epic" },
+                runBreakdown: { type: "boolean" },
+            },
+            required: ["workspaceId"],
+        },
+    },
+    {
+        name: "link_epic_github",
+        description: "Link a GitHub branch or PR to an epic. Use this after creating a branch or opening a PR for an epic's work.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                epicId: {
+                    type: "string",
+                    description: "The epic ID to link",
+                },
+                branch: {
+                    type: "string",
+                    description: "Branch name (e.g., 'feature/user-auth')",
+                },
+                prUrl: {
+                    type: "string",
+                    description: "Full GitHub PR URL (e.g., 'https://github.com/owner/repo/pull/123')",
+                },
+            },
+            required: ["epicId"],
+        },
+    },
+    {
+        name: "get_epic_github",
+        description: "Get the GitHub branch and PR URL linked to an epic.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                epicId: {
+                    type: "string",
+                    description: "The epic ID",
+                },
+            },
+            required: ["epicId"],
+        },
+    },
+];
+/**
+ * Handle a tool call and return the result
+ */
+export async function handleToolCall(client, name, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+args) {
+    try {
+        let result;
+        switch (name) {
+            case "whoami":
+                result = await taskTools.whoami(client);
+                break;
+            case "list_workspaces":
+                result = await taskTools.listWorkspaces(client);
+                break;
+            case "create_workspace":
+                result = await taskTools.createWorkspace(client, {
+                    name: args.name,
+                    description: args.description,
+                });
+                break;
+            case "list_tasks":
+                result = await taskTools.listTasks(client, args.workspaceId, {
+                    status: args.status,
+                    epicId: args.epicId,
+                    isIcebox: args.isIcebox,
+                    assigneeId: args.assigneeId,
+                });
+                break;
+            case "get_task":
+                result = await taskTools.getTask(client, args.taskId);
+                break;
+            case "start_task":
+                result = await taskTools.startTask(client, args.taskId, args.comment);
+                break;
+            case "finish_task":
+                result = await taskTools.finishTask(client, args.taskId, args.comment);
+                break;
+            case "accept_task":
+                result = await taskTools.acceptTask(client, args.taskId, args.comment);
+                break;
+            case "reject_task":
+                if (!args.reason) {
+                    throw new Error("reason is required to reject a task.");
+                }
+                result = await taskTools.rejectTask(client, args.taskId, args.reason);
+                break;
+            case "list_comments":
+                result = await taskTools.listComments(client, args.taskId);
+                break;
+            case "add_comment":
+                result = await taskTools.addComment(client, args.taskId, args.content);
+                break;
+            case "update_task":
+                result = await taskTools.updateTask(client, args.taskId, {
+                    title: args.title,
+                    description: args.description,
+                    type: args.type,
+                    points: args.points,
+                    tags: args.tags,
+                    epicId: args.epicId,
+                    isBlocked: args.isBlocked,
+                    blockedReason: args.blockedReason,
+                    acceptanceCriteria: args.acceptanceCriteria,
+                    relevantFiles: args.relevantFiles,
+                });
+                break;
+            case "set_relevant_files":
+                result = await taskTools.setRelevantFiles(client, args.taskId, args.files);
+                break;
+            case "get_task_context":
+                result = await taskTools.getTaskContext(client, args.taskId);
+                break;
+            case "log_progress":
+                result = await taskTools.logProgress(client, args.taskId, {
+                    whatAttempted: args.whatAttempted,
+                    whatSucceeded: args.whatSucceeded,
+                    whatFailed: args.whatFailed,
+                    questions: args.questions,
+                    blockers: args.blockers,
+                });
+                break;
+            case "list_progress":
+                result = await taskTools.listProgress(client, args.taskId);
+                break;
+            case "recommend_task":
+                result = await taskTools.recommendTask(client, args.workspaceId, {
+                    epicId: args.epicId,
+                    limit: args.limit,
+                });
+                break;
+            case "list_documents":
+                result = await documentTools.listDocuments(client, args.workspaceId);
+                break;
+            case "read_document":
+                result = await documentTools.readDocument(client, args.workspaceId, args.path);
+                break;
+            case "create_document":
+                result = await documentTools.createDocument(client, args.workspaceId, {
+                    path: args.path,
+                    title: args.title,
+                    body: args.body,
+                });
+                break;
+            case "write_document":
+                if (!args.etag) {
+                    throw new Error("etag is required to write a document. Read the document first and pass its etag.");
+                }
+                result = await documentTools.writeDocument(client, args.workspaceId, args.path, {
+                    title: args.title,
+                    body: args.body,
+                    etag: args.etag,
+                });
+                break;
+            case "delete_document":
+                if (!args.etag) {
+                    throw new Error("etag is required to delete a document. Read the document first and pass its etag.");
+                }
+                result = await documentTools.deleteDocument(client, args.workspaceId, args.path, args.etag);
+                break;
+            case "list_document_versions":
+                result = await documentTools.listDocumentVersions(client, args.workspaceId, args.path);
+                break;
+            case "restore_document":
+                if (!args.etag) {
+                    throw new Error("etag is required to restore a document. Read the document first and pass its etag.");
+                }
+                result = await documentTools.restoreDocument(client, args.workspaceId, args.path, {
+                    versionId: args.versionId,
+                    etag: args.etag,
+                });
+                break;
+            case "list_epics":
+                result = await documentTools.listEpics(client, args.workspaceId);
+                break;
+            case "get_epic":
+                result = await documentTools.getEpic(client, args.epicId);
+                break;
+            case "plan_it":
+                result = await documentTools.planIt(client, args.workspaceId, {
+                    paths: args.paths,
+                    documentIds: args.documentIds,
+                    epicIds: args.epicIds,
+                    title: args.title,
+                    runBreakdown: args.runBreakdown,
+                });
+                break;
+            case "link_epic_github":
+                result = await taskTools.linkEpicGithub(client, args.epicId, {
+                    branch: args.branch,
+                    prUrl: args.prUrl,
+                });
+                break;
+            case "get_epic_github":
+                result = await taskTools.getEpicGithub(client, args.epicId);
+                break;
+            default:
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown tool: ${name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map