@agilemonster/mcp-server 1.0.5 → 1.0.7

package/bin/mcp.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { runStdioServer } from '../dist/server.js';
+import { MCP_SERVER_VERSION } from '../dist/client.js';
 
 const cliCommands = new Set([
   'bootstrap',
@@ -19,7 +20,10 @@ const cliCommands = new Set([
 ]);
 
 const firstArg = process.argv[2];
-if (firstArg && cliCommands.has(firstArg)) {
+if (firstArg === '--version' || firstArg === '-v' || firstArg === 'version') {
+  console.log(MCP_SERVER_VERSION);
+  process.exit(0);
+} else if (firstArg && cliCommands.has(firstArg)) {
   // Delegate to orchestrator CLI
   await import('./orchestrator.js');
 } else {

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import { AgileMonsterProjectConfig, Board, BoardAgentConfig, Card, ContextResponse } from './types.js';
+import { AgileMonsterProjectConfig, Board, BoardAgentConfig, Card, ContextResponse, PulseResponse } from './types.js';
+export declare const MCP_SERVER_VERSION = "1.0.7";
 export declare class AgileMonsterClient {
     private apiKey;
     private baseUrl;
@@ -29,11 +30,17 @@ export declare class AgileMonsterClient {
     saveBoardAgents(boardId: string, agents: BoardAgentConfig[], projectName?: string, projectPath?: string, gitRemote?: string): Promise<{
         agents: BoardAgentConfig[];
     }>;
+    pulse(options: {
+        boardId: string;
+        provider?: string;
+        projectName?: string;
+        projectPath?: string;
+    }): Promise<PulseResponse>;
     listAssigned(provider?: string, status?: string, boardId?: string, workspaceId?: string): Promise<{
         provider: string;
         cards: Card[];
     }>;
-    claimTask(cardId: string, provider: string, runRef?: string): Promise<Card>;
+    claimTask(cardId: string, provider: string, runRef?: string, expectedBoardId?: string): Promise<Card>;
     askQuestion(cardId: string, provider: string, question: string): Promise<Card>;
     addProgress(cardId: string, provider: string, update: string, tokensUsed?: number, costUsd?: number): Promise<Card>;
     recordSpend(cardId: string, provider: string, tokens: number, costUsd: number, note?: string): Promise<Card>;

package/dist/client.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+export const MCP_SERVER_VERSION = '1.0.7';
 export class AgileMonsterClient {
     apiKey = '';
     baseUrl;
@@ -122,6 +123,7 @@ export class AgileMonsterClient {
             Authorization: `Bearer ${this.apiKey}`,
             'Content-Type': 'application/json',
             Accept: 'application/json',
+            'X-AgileMonster-MCP-Version': MCP_SERVER_VERSION,
             ...(options.headers || {}),
         };
         const res = await fetch(url, {
@@ -178,10 +180,23 @@ export class AgileMonsterClient {
                 project_name: projectName,
                 project_path: projectPath,
                 git_remote: gitRemote,
+                mcp_version: MCP_SERVER_VERSION,
                 connected: true,
             }),
         });
     }
+    async pulse(options) {
+        return this.request('/api/agent/pulse', {
+            method: 'POST',
+            body: JSON.stringify({
+                board_id: options.boardId,
+                provider: options.provider || 'any',
+                project_name: options.projectName,
+                project_path: options.projectPath,
+                mcp_version: MCP_SERVER_VERSION,
+            }),
+        });
+    }
     async listAssigned(provider = 'any', status, boardId, workspaceId) {
         const params = new URLSearchParams();
         if (provider)
@@ -195,10 +210,11 @@ export class AgileMonsterClient {
         const qs = params.toString();
         return this.request(`/api/agent/assigned${qs ? `?${qs}` : ''}`);
     }
-    async claimTask(cardId, provider, runRef) {
+    async claimTask(cardId, provider, runRef, expectedBoardId) {
+        const boardId = expectedBoardId || this.loadProjectConfig()?.board_id;
         return this.request(`/api/agent/cards/${cardId}/claim`, {
             method: 'POST',
-            body: JSON.stringify({ provider, run_ref: runRef }),
+            body: JSON.stringify({ provider, run_ref: runRef, board_id: boardId }),
         });
     }
     async askQuestion(cardId, provider, question) {

package/dist/orchestrator.js

@@ -12,6 +12,10 @@ export class AgileMonsterOrchestrator {
         const projectConfig = this.client.loadProjectConfig();
         const provider = options?.provider || projectConfig?.provider || 'any';
         const boardId = options?.boardId || projectConfig?.board_id;
+        // STRICT BOARD SCOPE GUARD: Never poll across all boards when current folder is unbound!
+        if (!boardId) {
+            return [];
+        }
         const result = await this.client.listAssigned(provider, undefined, boardId);
         return result.cards || [];
     }
@@ -34,8 +38,10 @@ export class AgileMonsterOrchestrator {
             console.log(`🤖 Default Provider: ${config.provider || 'any'}`);
         }
         else {
-            console.log(`ℹ️  No .agilemonster.json found in current directory (${cwdName}).`);
-            console.log('   Run "agilemonster-orchestrator init" to bind this repo to a board.\n');
+            console.log(`⚠️  [UNBOUND REPOSITORY] No .agilemonster.json found in "${cwdName}".`);
+            console.log('   To prevent agents from picking up tasks from the wrong board and burning tokens:');
+            console.log('   Run "npx -y @agilemonster/mcp-server bootstrap" in this folder first!\n');
+            return;
         }
         console.log('\n🔍 Checking for assigned agent tasks...');
         const tasks = await this.checkTasks();
@@ -217,13 +223,24 @@ export class AgileMonsterOrchestrator {
                     else {
                         const num = parseInt(choice, 10);
                         if (!Number.isNaN(num) && num >= 1 && num <= boards.length) {
-                            targetBoard = boards[num - 1];
-                        }
-                        else if (context.matched_board) {
-                            targetBoard = context.matched_board;
+                            const candidate = boards[num - 1];
+                            // Safety confirmation if user picks an existing board that AI said didn't match this folder
+                            if (aiMatch &&
+                                aiMatch.matched_board_id !== candidate.id &&
+                                candidate.name.toLowerCase() !== folderName.toLowerCase()) {
+                                const confirm = (await rl.question(`⚠️  Safety Check: Folder is "${folderName}" but board is "${candidate.name}". Are you sure they are the same project? [y/N]: `))
+                                    .trim()
+                                    .toLowerCase();
+                                if (confirm !== 'y' && confirm !== 'yes') {
+                                    console.log('❌ Cancelled to prevent connecting the wrong board.');
+                                    return;
+                                }
+                            }
+                            targetBoard = candidate;
                         }
                         else {
-                            targetBoard = boards[0];
+                            console.error(`❌ Invalid selection "${choice}". Aborting so we never bind the wrong board.`);
+                            return;
                         }
                     }
                 }
@@ -232,14 +249,15 @@ export class AgileMonsterOrchestrator {
                 }
             }
             else {
-                // Non-interactive fallback: use AI match if present, or create new board if none matched
-                if (context.matched_board) {
+                // Non-interactive mode: ONLY auto-bind if AI matched with high confidence OR --board was explicitly passed.
+                // NEVER auto-pick a board or create a board silently if ambiguous!
+                if (context.matched_board && aiMatch?.confidence === 'high') {
                     targetBoard = context.matched_board;
                 }
-                else if (boards.length > 0 || (context.workspaces && context.workspaces.length > 0)) {
-                    const workspaceId = boards[0]?.workspace_id || context.workspaces?.[0]?.id || '';
-                    targetBoard = await this.client.createBoard(workspaceId, suggestedNewBoardName, `Connected to repository ${folderName}`);
-                    console.log(`✨ Created new board "${targetBoard.name}" (${targetBoard.id})`);
+                else {
+                    console.error(`❌ Ambiguous board match for folder "${folderName}" in non-interactive mode.`);
+                    console.error(`   Please run interactively in your terminal or pass --board="<Board Name>" explicitly so we never connect the wrong board.`);
+                    return;
                 }
             }
         }
@@ -288,6 +306,8 @@ export class AgileMonsterOrchestrator {
             workspace_id: targetBoard.workspace_id,
             board_id: targetBoard.id,
             board_name: targetBoard.name,
+            project_name: folderName,
+            project_path: process.cwd(),
             provider: options?.provider || 'antigravity',
             review_list: 'In Review',
             done_list: 'Done',
@@ -341,7 +361,7 @@ export class AgileMonsterOrchestrator {
                 existing.mcpServers = existing.mcpServers || {};
                 existing.mcpServers.agilemonster = {
                     command: 'npx',
-                    args: ['-y', '@agilemonster/mcp-server'],
+                    args: ['-y', '@agilemonster/mcp-server@latest'],
                     env: {
                         AGILEMONSTER_API_KEY: apiKey,
                         AGILEMONSTER_API_URL: 'https://api.agilemonster.com',
@@ -368,7 +388,7 @@ export class AgileMonsterOrchestrator {
                 existing.mcpServers = existing.mcpServers || {};
                 existing.mcpServers.agilemonster = {
                     command: 'npx',
-                    args: ['-y', '@agilemonster/mcp-server'],
+                    args: ['-y', '@agilemonster/mcp-server@latest'],
                     env: {
                         AGILEMONSTER_API_KEY: apiKey,
                         AGILEMONSTER_API_URL: 'https://api.agilemonster.com',
@@ -399,7 +419,7 @@ export class AgileMonsterOrchestrator {
                     existing.mcpServers = existing.mcpServers || {};
                     existing.mcpServers.agilemonster = {
                         command: 'npx',
-                        args: ['-y', '@agilemonster/mcp-server'],
+                        args: ['-y', '@agilemonster/mcp-server@latest'],
                         env: {
                             AGILEMONSTER_API_KEY: apiKey,
                             AGILEMONSTER_API_URL: 'https://api.agilemonster.com',
@@ -430,7 +450,7 @@ export class AgileMonsterOrchestrator {
                 existing.mcpServers = existing.mcpServers || {};
                 existing.mcpServers.agilemonster = {
                     command: 'npx',
-                    args: ['-y', '@agilemonster/mcp-server'],
+                    args: ['-y', '@agilemonster/mcp-server@latest'],
                     env: {
                         AGILEMONSTER_API_KEY: apiKey,
                         AGILEMONSTER_API_URL: 'https://api.agilemonster.com',
@@ -459,7 +479,7 @@ export class AgileMonsterOrchestrator {
                     existing.mcpServers = existing.mcpServers || {};
                     existing.mcpServers.agilemonster = {
                         command: 'npx',
-                        args: ['-y', '@agilemonster/mcp-server'],
+                        args: ['-y', '@agilemonster/mcp-server@latest'],
                         env: {
                             AGILEMONSTER_API_KEY: apiKey,
                             AGILEMONSTER_API_URL: 'https://api.agilemonster.com',

package/dist/server.d.ts

@@ -34,4 +34,5 @@ export declare function createServer(client?: AgileMonsterClient): Server<{
         } | undefined;
     } | undefined;
 }>;
+export declare function startBuiltInPullPulse(server: Server, client: AgileMonsterClient, intervalMs?: number): NodeJS.Timeout;
 export declare function runStdioServer(): Promise<void>;

package/dist/server.js

@@ -3,17 +3,18 @@ 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 { spawn } from 'node:child_process';
+import { AgileMonsterClient, MCP_SERVER_VERSION } 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',
+        version: MCP_SERVER_VERSION,
     }, {
         capabilities: {
             tools: {},
             prompts: {},
-            resources: {},
+            resources: { subscribe: true, listChanged: true },
         },
     });
     // -------------------------------------------------------------------------
@@ -512,12 +513,30 @@ Please strictly follow the Agile Monster Task Lifecycle Protocol:
                     const status = args.status;
                     const boardId = args.board_id || projectConfig?.board_id;
                     const workspaceId = projectConfig?.workspace_id;
+                    if (!boardId) {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `⚠️ [BOARD SCOPE GUARD] Current project folder "${path.basename(process.cwd())}" is not bound to an Agile Monster board (.agilemonster.json is missing).\n` +
+                                        `Refusing to list tasks across all boards so you never accidentally pick up a task from the wrong project and burn tokens.\n` +
+                                        `Please run "npx -y @agilemonster/mcp-server bootstrap" in this folder or call agilemonster_get_context first to bind the right board.`,
+                                },
+                            ],
+                        };
+                    }
                     const result = await client.listAssigned(provider, status, boardId, workspaceId);
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: JSON.stringify(result, null, 2),
+                                text: JSON.stringify({
+                                    bound_board_id: boardId,
+                                    bound_board_name: projectConfig?.board_name,
+                                    bound_project_name: projectConfig?.project_name || path.basename(process.cwd()),
+                                    ...result,
+                                }, null, 2),
                             },
                         ],
                     };
@@ -526,12 +545,25 @@ Please strictly follow the Agile Monster Task Lifecycle Protocol:
                     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);
+                    const expectedBoardId = projectConfig?.board_id;
+                    if (!expectedBoardId) {
+                        return {
+                            isError: true,
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `⚠️ [BOARD SCOPE GUARD] Cannot claim card ${cardId} because this repository folder ("${path.basename(process.cwd())}") has no .agilemonster.json board binding.\n` +
+                                        `Run "npx -y @agilemonster/mcp-server bootstrap" first so we verify this folder matches the card's board.`,
+                                },
+                            ],
+                        };
+                    }
+                    const card = await client.claimTask(cardId, provider, runRef, expectedBoardId);
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `Task claimed successfully. Status is now "in_progress".\n${JSON.stringify(card, null, 2)}`,
+                                text: `Task claimed successfully on board "${card.board_name || expectedBoardId}". Status is now "in_progress".\n${JSON.stringify(card, null, 2)}`,
                             },
                         ],
                     };
@@ -673,8 +705,135 @@ Please strictly follow the Agile Monster Task Lifecycle Protocol:
     });
     return server;
 }
+function sendDesktopNotification(title, message) {
+    if (process.platform === 'darwin') {
+        try {
+            const safeTitle = title.replace(/["\\]/g, '');
+            const safeMsg = message.replace(/["\\]/g, '').slice(0, 180);
+            const child = spawn('osascript', ['-e', `display notification "${safeMsg}" with title "${safeTitle}" sound name "Glass"`], { stdio: 'ignore', detached: true });
+            child.unref();
+        }
+        catch { }
+    }
+}
+function syncIdeTaskRules(boardName, queuedCards) {
+    const cwd = process.cwd();
+    const cursorRulesDir = path.join(cwd, '.cursor', 'rules');
+    const cursorRuleFile = path.join(cursorRulesDir, 'agilemonster-queue.mdc');
+    if (queuedCards.length === 0) {
+        try {
+            if (fs.existsSync(cursorRuleFile)) {
+                fs.unlinkSync(cursorRuleFile);
+            }
+        }
+        catch { }
+        return;
+    }
+    const lines = [
+        '---',
+        'description: Active Agile Monster queued tasks assigned to this repository',
+        'globs: ',
+        'alwaysApply: true',
+        '---',
+        `# 🔔 Queued Agile Monster Tasks for Board "${boardName}"`,
+        '',
+        `There ${queuedCards.length === 1 ? 'is 1 queued task' : `are ${queuedCards.length} queued tasks`} assigned on the "${boardName}" board waiting to be claimed:`,
+        '',
+    ];
+    for (const c of queuedCards) {
+        const worker = c.agent_display_name || c.agent_provider || 'agent';
+        const model = c.agent_model && c.agent_model !== 'auto' ? ` (Preferred Model: ${c.agent_model})` : '';
+        lines.push(`- **${c.title}** (Card ID: \`${c.id}\` | Assigned to: \`${worker}\`${model})`);
+        if (c.description) {
+            lines.push(`  - Details: ${c.description.replace(/\r?\n/g, ' ').slice(0, 280)}`);
+        }
+    }
+    lines.push('');
+    lines.push('When the user starts a task or asks what is next, call `agilemonster_claim_task` with the Card ID above, implement the solution, and submit it for review with `agilemonster_submit_for_review`.');
+    try {
+        if (fs.existsSync(path.join(cwd, '.cursor'))) {
+            if (!fs.existsSync(cursorRulesDir)) {
+                fs.mkdirSync(cursorRulesDir, { recursive: true });
+            }
+            fs.writeFileSync(cursorRuleFile, lines.join('\n') + '\n', 'utf8');
+        }
+    }
+    catch { }
+}
+function triggerBackgroundSelfUpdate() {
+    try {
+        // 1. Pre-warm latest @agilemonster/mcp-server in npx cache
+        const child = spawn('npx', ['-y', '@agilemonster/mcp-server@latest', '--version'], {
+            stdio: 'ignore',
+            detached: true,
+        });
+        child.unref();
+        // 2. Ensure local .cursor/mcp.json and .mcp.json use @latest so next IDE reload uses latest
+        const cwd = process.cwd();
+        for (const rel of ['.cursor/mcp.json', '.mcp.json', '.vscode/mcp.json']) {
+            const p = path.join(cwd, rel);
+            if (fs.existsSync(p)) {
+                try {
+                    const parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+                    if (parsed?.mcpServers?.agilemonster) {
+                        parsed.mcpServers.agilemonster.args = ['-y', '@agilemonster/mcp-server@latest'];
+                        fs.writeFileSync(p, JSON.stringify(parsed, null, 2), 'utf8');
+                    }
+                }
+                catch { }
+            }
+        }
+    }
+    catch { }
+}
+export function startBuiltInPullPulse(server, client, intervalMs = 20000) {
+    const notifiedCardIds = new Set();
+    let updateTriggered = false;
+    const runPulse = async () => {
+        try {
+            const config = client.loadProjectConfig();
+            if (!config?.board_id || !client.getApiKey()) {
+                return;
+            }
+            const res = await client.pulse({
+                boardId: config.board_id,
+                provider: 'any',
+                projectName: config.project_name || path.basename(process.cwd()),
+                projectPath: config.project_path || process.cwd(),
+            });
+            const queued = res.queued_cards || [];
+            syncIdeTaskRules(config.board_name || 'Board', queued);
+            for (const card of queued) {
+                if (!notifiedCardIds.has(card.id)) {
+                    notifiedCardIds.add(card.id);
+                    const worker = card.agent_display_name || card.agent_provider || 'AI Agent';
+                    const modelTag = card.agent_model && card.agent_model !== 'auto' ? ` [${card.agent_model}]` : '';
+                    sendDesktopNotification(`Agile Monster -> ${worker}${modelTag}`, `New task queued on ${config.board_name || 'Board'}: "${card.title}"`);
+                    try {
+                        await server.sendResourceUpdated({ uri: 'agilemonster://project/context' });
+                    }
+                    catch { }
+                }
+            }
+            if ((res.version?.force_update_requested || res.version?.update_available) &&
+                !updateTriggered) {
+                updateTriggered = true;
+                triggerBackgroundSelfUpdate();
+            }
+        }
+        catch {
+            // Silent during background pulse
+        }
+    };
+    setTimeout(runPulse, 2500).unref();
+    const timer = setInterval(runPulse, intervalMs);
+    timer.unref();
+    return timer;
+}
 export async function runStdioServer() {
-    const server = createServer();
+    const client = new AgileMonsterClient();
+    const server = createServer(client);
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    startBuiltInPullPulse(server, client, 20000);
 }

package/dist/types.d.ts

@@ -2,6 +2,8 @@ export interface AgileMonsterProjectConfig {
     workspace_id?: string;
     board_id?: string;
     board_name?: string;
+    project_name?: string;
+    project_path?: string;
     provider?: string;
     review_list?: string;
     done_list?: string;
@@ -16,6 +18,9 @@ export interface Card {
     position?: number;
     due_date?: string | null;
     agent_provider?: string | null;
+    agent_id?: string | null;
+    agent_model?: string | null;
+    agent_display_name?: string | null;
     agent_status?: string | null;
     agent_run_ref?: string | null;
     max_budget_usd?: number | null;
@@ -57,9 +62,26 @@ export interface BoardAgentConfig {
     project_name?: string | null;
     project_path?: string | null;
     git_remote?: string | null;
+    mcp_version?: string | null;
     connected?: boolean;
     last_connected_at?: string | null;
 }
+export interface PulseVersionInfo {
+    client_version: string | null;
+    latest_version: string;
+    min_supported_version: string;
+    update_available: boolean;
+    update_required: boolean;
+    force_update_requested: boolean;
+    update_command: string;
+}
+export interface PulseResponse {
+    board_id: string;
+    pulsed_at: string;
+    queued_cards: Card[];
+    in_progress_cards: Card[];
+    version: PulseVersionInfo;
+}
 export interface ContextResponse {
     matched_board: Board | null;
     ai_match?: AiBoardMatch | null;

package/dist/worker.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import path from 'node:path';
 import { AgileMonsterClient } from './client.js';
 export class AgileMonsterWorker {
     client;
@@ -59,8 +60,11 @@ export class AgileMonsterWorker {
         const projectConfig = this.client.loadProjectConfig();
         const provider = options.provider || projectConfig?.provider || 'antigravity';
         const boardId = options.boardId || projectConfig?.board_id;
+        if (!boardId) {
+            throw new Error(`[Board Scope Guard] No .agilemonster.json board binding found in "${path.basename(process.cwd())}". Refusing to poll tasks without an explicit board binding.`);
+        }
         const res = await this.client.listAssigned(provider, 'queued', boardId);
-        const tasks = res.cards || [];
+        const tasks = (res.cards || []).filter((c) => !c.board_id || c.board_id === boardId);
         if (tasks.length === 0) {
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilemonster/mcp-server",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "description": "Official Model Context Protocol (MCP) server & Orchestrator for Agile Monster (Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf)",
   "main": "dist/server.js",