@agilemonster/mcp-server 0.0.0-stage → 1.0.1

package/dist/server.js

@@ -0,0 +1,680 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import { AgileMonsterClient } from './client.js';
+import { AGENT_GUIDELINES_MARKDOWN } from './guidelines.js';
+export function createServer(client = new AgileMonsterClient()) {
+    const server = new Server({
+        name: 'agilemonster-mcp-server',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+            prompts: {},
+            resources: {},
+        },
+    });
+    // -------------------------------------------------------------------------
+    // 1. Prompts for Autonomous Agents
+    // -------------------------------------------------------------------------
+    const prompts = [
+        {
+            name: 'agilemonster_agent_protocol',
+            description: 'Official operational guidelines and lifecycle protocol for AI agents working on Agile Monster boards.',
+            arguments: [],
+        },
+        {
+            name: 'agilemonster_work_on_task',
+            description: 'Workflow prompt for an AI agent to claim, investigate, implement, test, and submit an Agile Monster task for review.',
+            arguments: [
+                {
+                    name: 'card_id',
+                    description: 'The UUID of the Agile Monster card to work on.',
+                    required: true,
+                },
+                {
+                    name: 'task_title',
+                    description: 'Optional task title for context.',
+                    required: false,
+                },
+            ],
+        },
+    ];
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return { prompts };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        if (name === 'agilemonster_agent_protocol') {
+            return {
+                description: 'Agile Monster Task Lifecycle Protocol for AI Agents',
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: AGENT_GUIDELINES_MARKDOWN,
+                        },
+                    },
+                ],
+            };
+        }
+        if (name === 'agilemonster_work_on_task') {
+            const cardId = args?.card_id || 'UNKNOWN_CARD_ID';
+            const taskTitle = args?.task_title ? `"${args.task_title}"` : 'assigned task';
+            return {
+                description: `Operational task workflow for card ${cardId}`,
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `You are an autonomous AI coding assistant working on the Agile Monster card ${taskTitle} (ID: ${cardId}).
+
+Please strictly follow the Agile Monster Task Lifecycle Protocol:
+1. **Claim the Task**: Call agilemonster_claim_task({ card_id: "${cardId}" }) to mark it "in_progress".
+2. **Context & Exploration**: Read relevant files, check git history, and understand requirements.
+3. **Handle Ambiguity**: If anything is unclear, call agilemonster_ask_question({ card_id: "${cardId}", question: "..." }) to set status to "waiting_for_input" and wait for the user.
+4. **Log Progress**: If you complete a major milestone, call agilemonster_add_progress({ card_id: "${cardId}", update: "..." }).
+5. **Implement & Test**: Write clean code and verify with automated unit/integration tests or build commands.
+6. **Submit for Human Review**: NEVER mark this task as Done directly. Call agilemonster_submit_for_review({ card_id: "${cardId}", summary: "...", verification_steps: "..." }) to reassign to the user for testing.
+7. **Suggest Follow-Ups**: Call agilemonster_create_followup_tasks({ card_id: "${cardId}", tasks: [...] }) to propose staging/production deployment or further testing.`,
+                        },
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    });
+    // -------------------------------------------------------------------------
+    // 2. Resources for Autonomous Agents
+    // -------------------------------------------------------------------------
+    const resources = [
+        {
+            uri: 'agilemonster://guidelines/agents',
+            name: 'Agile Monster Agent Operational Protocol',
+            description: 'Standard lifecycle and operating procedures for AI agents using Agile Monster.',
+            mimeType: 'text/markdown',
+        },
+        {
+            uri: 'agilemonster://project/context',
+            name: 'Current Repository Board Context',
+            description: 'Active Agile Monster board ID, columns, and assigned tasks for this repository.',
+            mimeType: 'application/json',
+        },
+    ];
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return { resources };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        if (uri === 'agilemonster://guidelines/agents') {
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'text/markdown',
+                        text: AGENT_GUIDELINES_MARKDOWN,
+                    },
+                ],
+            };
+        }
+        if (uri === 'agilemonster://project/context') {
+            const projectConfig = client.loadProjectConfig();
+            const projectName = projectConfig?.board_name || path.basename(process.cwd());
+            const boardId = projectConfig?.board_id;
+            const context = await client.getContext(projectName, boardId);
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            config_source: projectConfig ? '.agilemonster.json' : 'auto_matched',
+                            project_config: projectConfig,
+                            ...context,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        throw new Error(`Resource not found: ${uri}`);
+    });
+    // -------------------------------------------------------------------------
+    // 3. Tools for Autonomous Agents
+    // -------------------------------------------------------------------------
+    const tools = [
+        {
+            name: 'agilemonster_get_context',
+            description: 'Inspect Agile Monster board and project context for this repository. Automatically reads .agilemonster.json if present or finds matching board.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_name: {
+                        type: 'string',
+                        description: 'Optional project or repository name to match against board names.',
+                    },
+                    board_id: {
+                        type: 'string',
+                        description: 'Optional explicit board ID.',
+                    },
+                },
+            },
+        },
+        {
+            name: 'agilemonster_init_project',
+            description: 'Bind the current repository to an Agile Monster workspace and board by creating a .agilemonster.json file and generating AGENTS.md.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workspace_id: {
+                        type: 'string',
+                        description: 'The Agile Monster workspace UUID.',
+                    },
+                    board_id: {
+                        type: 'string',
+                        description: 'The Agile Monster board UUID.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Default agent provider for this repo (e.g. antigravity, cursor, claude_code, hermes).',
+                    },
+                    review_list: {
+                        type: 'string',
+                        description: 'Optional name of list to move cards to upon review (default: "Review" or "Testing").',
+                    },
+                },
+                required: ['workspace_id', 'board_id'],
+            },
+        },
+        {
+            name: 'agilemonster_list_my_tasks',
+            description: 'List tasks assigned to the AI agent on Agile Monster boards (queued, in_progress, waiting_for_input, review).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name (e.g. antigravity, cursor, claude_code, codex, hermes, windsurf). Defaults to repo config or "any".',
+                    },
+                    status: {
+                        type: 'string',
+                        description: 'Filter by status: "queued", "in_progress", "waiting_for_input", "review", or "all".',
+                    },
+                    board_id: {
+                        type: 'string',
+                        description: 'Optional filter by board ID (defaults to repo config if present).',
+                    },
+                },
+            },
+        },
+        {
+            name: 'agilemonster_claim_task',
+            description: 'Claim a task assigned to this agent to begin working on it. Marks card as "in_progress" in Agile Monster.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID to claim.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name (e.g. antigravity, cursor, claude_code, hermes).',
+                    },
+                    run_ref: {
+                        type: 'string',
+                        description: 'Optional execution/session reference ID.',
+                    },
+                },
+                required: ['card_id', 'provider'],
+            },
+        },
+        {
+            name: 'agilemonster_ask_question',
+            description: 'Ask the user a clarifying question about the task. Posts a tagged comment on the card and updates status to "waiting_for_input".',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name.',
+                    },
+                    question: {
+                        type: 'string',
+                        description: 'The question for the user.',
+                    },
+                },
+                required: ['card_id', 'provider', 'question'],
+            },
+        },
+        {
+            name: 'agilemonster_add_progress',
+            description: 'Post a progress update or implementation notes to the Agile Monster task activity/comments.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name.',
+                    },
+                    update: {
+                        type: 'string',
+                        description: 'Summary of progress made so far.',
+                    },
+                    tokens_used: {
+                        type: 'number',
+                        description: 'Optional count of LLM tokens consumed in this step.',
+                    },
+                    cost_usd: {
+                        type: 'number',
+                        description: 'Optional USD cost consumed in this step (e.g. 0.0150).',
+                    },
+                },
+                required: ['card_id', 'provider', 'update'],
+            },
+        },
+        {
+            name: 'agilemonster_record_spend',
+            description: 'Record LLM token and cost consumption on a card to enforce circuit breakers against runaway billing.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name.',
+                    },
+                    tokens: {
+                        type: 'number',
+                        description: 'Number of tokens consumed.',
+                    },
+                    cost_usd: {
+                        type: 'number',
+                        description: 'Estimated USD cost.',
+                    },
+                    note: {
+                        type: 'string',
+                        description: 'Optional note describing what the spend was used for.',
+                    },
+                },
+                required: ['card_id', 'provider', 'tokens', 'cost_usd'],
+            },
+        },
+        {
+            name: 'agilemonster_set_budget',
+            description: 'Configure spend and token circuit-breaker limits for an Agile Monster task to protect against infinite loops.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID.',
+                    },
+                    max_budget_usd: {
+                        type: 'number',
+                        description: 'Maximum dollar budget allowed for this task (e.g. 5.00).',
+                    },
+                    max_tokens: {
+                        type: 'number',
+                        description: 'Maximum token budget allowed for this task (e.g. 150000).',
+                    },
+                },
+                required: ['card_id'],
+            },
+        },
+        {
+            name: 'agilemonster_submit_for_review',
+            description: 'Handoff task to human: moves card to Testing/QA/Review column, reassigns the card to the human who requested it, sets status to "review", and posts step-by-step verification instructions.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name.',
+                    },
+                    summary: {
+                        type: 'string',
+                        description: 'Summary of the work completed and files changed.',
+                    },
+                    verification_steps: {
+                        type: 'string',
+                        description: 'Step-by-step instructions for the user to test and verify the changes.',
+                    },
+                    target_list: {
+                        type: 'string',
+                        description: 'Optional name or ID of the testing/review column (e.g. "Testing", "QA", "In Review"). Auto-detected if omitted.',
+                    },
+                    target_list_id: {
+                        type: 'string',
+                        description: 'Optional ID of the review/testing column (legacy alias).',
+                    },
+                    assign_to_user_id: {
+                        type: 'string',
+                        description: 'Optional user UUID to assign to. Defaults to the human who created/requested the task.',
+                    },
+                },
+                required: ['card_id', 'provider', 'summary'],
+            },
+        },
+        {
+            name: 'agilemonster_create_followup_tasks',
+            description: 'Suggest and create follow-up tasks on the board (e.g., "Deploy to Test", "Deploy to Production", "Write integration tests").',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The parent card UUID.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name.',
+                    },
+                    tasks: {
+                        type: 'array',
+                        description: 'List of follow-up tasks to create.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                title: { type: 'string', description: 'Title of the follow-up task' },
+                                description: { type: 'string', description: 'Details or instructions' },
+                                list_id: { type: 'string', description: 'Target column list ID' },
+                                agent_provider: { type: 'string', description: 'Optional agent worker to pre-assign' },
+                            },
+                            required: ['title'],
+                        },
+                    },
+                },
+                required: ['card_id', 'provider', 'tasks'],
+            },
+        },
+        {
+            name: 'agilemonster_block_task',
+            description: 'Block a task and reassign back to human user with a reason (e.g. missing credentials, ambiguous requirements, or upstream blockers). Sets status to blocked / waiting_for_input.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID to block.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name (e.g. antigravity, cursor, claude_code, windsurf).',
+                    },
+                    comment: {
+                        type: 'string',
+                        description: 'Detailed explanation of why the task is blocked and what is needed from the user to proceed.',
+                    },
+                },
+                required: ['card_id'],
+            },
+        },
+        {
+            name: 'agilemonster_complete_task',
+            description: 'Mark task as complete and advance to the board Done list after testing and verification pass. Adds structured completion comment detailing deployment status (automated CI/CD run or user-controlled trigger instructions).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    card_id: {
+                        type: 'string',
+                        description: 'The card UUID to mark as completed.',
+                    },
+                    provider: {
+                        type: 'string',
+                        description: 'Agent provider name (e.g. antigravity, cursor, claude_code, windsurf).',
+                    },
+                    comment: {
+                        type: 'string',
+                        description: 'Detailed completion notes including test results and deployment details (auto-deployed CI/CD run ID/commit or manual trigger instructions).',
+                    },
+                },
+                required: ['card_id'],
+            },
+        },
+    ];
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        const projectConfig = client.loadProjectConfig();
+        try {
+            switch (name) {
+                case 'agilemonster_get_context': {
+                    const projectName = args.project_name ||
+                        projectConfig?.board_name ||
+                        path.basename(process.cwd());
+                    const boardId = args.board_id || projectConfig?.board_id;
+                    const context = await client.getContext(projectName, boardId);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    config_source: projectConfig ? '.agilemonster.json' : 'auto_matched',
+                                    project_config: projectConfig,
+                                    ...context,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_init_project': {
+                    const workspaceId = args.workspace_id;
+                    const boardId = args.board_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const reviewList = args.review_list || projectConfig?.review_list;
+                    const savedPath = client.saveProjectConfig({
+                        workspace_id: workspaceId,
+                        board_id: boardId,
+                        provider,
+                        review_list: reviewList,
+                    });
+                    // Ensure AGENTS.md exists in the project root
+                    const agentsMdPath = path.resolve(process.cwd(), 'AGENTS.md');
+                    let agentsMdCreated = false;
+                    if (!fs.existsSync(agentsMdPath)) {
+                        fs.writeFileSync(agentsMdPath, AGENT_GUIDELINES_MARKDOWN, 'utf-8');
+                        agentsMdCreated = true;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Successfully initialized Agile Monster project config at ${savedPath}:\n` +
+                                    JSON.stringify({ workspace_id: workspaceId, board_id: boardId, provider }, null, 2) +
+                                    (agentsMdCreated ? `\n• Generated AGENTS.md with AI agent operational protocols.` : `\n• AGENTS.md already present.`),
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_list_my_tasks': {
+                    const provider = args.provider || projectConfig?.provider || 'any';
+                    const status = args.status;
+                    const boardId = args.board_id || projectConfig?.board_id;
+                    const workspaceId = projectConfig?.workspace_id;
+                    const result = await client.listAssigned(provider, status, boardId, workspaceId);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(result, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_claim_task': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const runRef = args.run_ref;
+                    const card = await client.claimTask(cardId, provider, runRef);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Task claimed successfully. Status is now "in_progress".\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_ask_question': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const question = args.question;
+                    const card = await client.askQuestion(cardId, provider, question);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Question posted on task ${cardId}. Status set to "waiting_for_input".\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_add_progress': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const update = args.update;
+                    const tokensUsed = args.tokens_used;
+                    const costUsd = args.cost_usd;
+                    const card = await client.addProgress(cardId, provider, update, tokensUsed, costUsd);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Progress update posted to task ${cardId}.\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_record_spend': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const tokens = args.tokens || 0;
+                    const costUsd = args.cost_usd || 0;
+                    const note = args.note;
+                    const card = await client.recordSpend(cardId, provider, tokens, costUsd, note);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `LLM Spend recorded for task ${cardId}: +${tokens} tokens, +$${costUsd}.\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_set_budget': {
+                    const cardId = args.card_id;
+                    const maxBudgetUsd = args.max_budget_usd !== undefined ? args.max_budget_usd : null;
+                    const maxTokens = args.max_tokens !== undefined ? args.max_tokens : null;
+                    const card = await client.setBudget(cardId, maxBudgetUsd, maxTokens);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Circuit-breaker budget configured for task ${cardId}.\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_submit_for_review': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const summary = args.summary;
+                    const verificationSteps = args.verification_steps;
+                    const targetList = args.target_list || args.target_list_id || undefined;
+                    const assignToUserId = args.assign_to_user_id;
+                    const card = await client.submitReview(cardId, provider, summary, verificationSteps, targetList, assignToUserId);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Task ${cardId} moved to testing/review and reassigned back to human requester for confirmation.\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_create_followup_tasks': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const tasks = args.tasks;
+                    const result = await client.createFollowupTasks(cardId, provider, tasks);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Created ${result.tasks.length} follow-up task(s) on the board:\n${JSON.stringify(result.tasks, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_block_task': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const comment = args.comment;
+                    const card = await client.blockTask(cardId, provider, comment);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Task ${cardId} marked as blocked and reassigned back to human teammate.\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                case 'agilemonster_complete_task': {
+                    const cardId = args.card_id;
+                    const provider = args.provider || projectConfig?.provider || 'antigravity';
+                    const comment = args.comment;
+                    const card = await client.completeTask(cardId, provider, comment);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Task ${cardId} marked as Done and completed successfully.\n${JSON.stringify(card, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error executing ${name}: ${error?.message || String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    return server;
+}
+export async function runStdioServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}