@vibescope/mcp-server 0.4.0 → 0.4.2

package/dist/templates/agent-guidelines.js

@@ -5,7 +5,10 @@
  * in every project using Vibescope for agent tracking. These guidelines ensure
  * agents follow proper workflows and maintain visibility.
  */
-export const AGENT_GUIDELINES_TEMPLATE = `# Vibescope Agent Guidelines
+export const VIBESCOPE_SECTION_START = '<!-- vibescope:start -->';
+export const VIBESCOPE_SECTION_END = '<!-- vibescope:end -->';
+export const AGENT_GUIDELINES_TEMPLATE = `${VIBESCOPE_SECTION_START}
+# Vibescope Agent Guidelines
 
 ## Quick Start
 
@@ -182,6 +185,7 @@ claude mcp add vibescope npx @vibescope/mcp-server@latest \\
 1. Copy \`.mcp.json.example\` to \`.mcp.json\`
 2. Get \`VIBESCOPE_API_KEY\` from https://vibescope.dev/dashboard/settings
 3. Restart Claude Code
+${VIBESCOPE_SECTION_END}
 `;
 /**
  * Get the agent guidelines template

package/dist/templates/help-content.js

@@ -214,14 +214,14 @@ add_finding(
   title: "Fix exists but awaits deployment",
   category: "other",
   severity: "info",
-  description: "The fix for [issue] was implemented in PR #XXX but hasn't been deployed yet.",
+  description: "The fix for [issue] was implemented in PR #{pr_number} but hasn't been deployed yet.",
   related_task_id: task_id
 )
 \`\`\`
 
 2. **Complete the task** (investigation is done):
 \`\`\`
-complete_task(task_id, summary: "Fix already exists in codebase (PR #XXX). Needs deployment to production.")
+complete_task(task_id, summary: "Fix already exists in codebase (PR #{pr_number}). Needs deployment to production.")
 \`\`\`
 
 3. **Request deployment** if not already pending:

package/dist/tools/chat.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Project chat tools:
+ * - send_project_message
+ * - get_project_messages
+ */
+import type { Tool } from './types.js';
+export declare const chatTools: Tool[];

package/dist/tools/chat.js

@@ -0,0 +1,43 @@
+/**
+ * Project chat tools:
+ * - send_project_message
+ * - get_project_messages
+ */
+export const chatTools = [
+    {
+        name: 'send_project_message',
+        description: 'Send a message to the project chat channel. All agents and the project owner can see messages here. Use this to communicate status updates, ask questions, report blockers, or coordinate with other agents.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                message: {
+                    type: 'string',
+                    description: 'Message content (supports markdown)',
+                },
+            },
+            required: ['project_id', 'message'],
+        },
+    },
+    {
+        name: 'get_project_messages',
+        description: 'Read recent messages from the project chat channel. Use this to check if the user or other agents have posted anything.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Number of recent messages to fetch (default: 20, max: 100)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+];

package/dist/tools/cloud-agents.js

@@ -63,5 +63,36 @@ Use this to check the state of cloud agents before/after cleanup.`,
             },
             required: ['project_id']
         }
+    },
+    {
+        name: 'update_agent_status',
+        description: `Report what you're currently doing. This updates the status message shown on the dashboard.
+
+Call this at key milestones during boot and work:
+- "Installing dependencies..."
+- "Running start_work_session..."
+- "Working on: <task title>"
+- "Running tests..."
+- "Committing changes..."
+
+Keep messages short (under 80 chars). The dashboard shows this in real-time.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status_message: {
+                    type: 'string',
+                    description: 'Short status message to display on dashboard (max 80 chars)'
+                },
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID (optional if session has project context)'
+                },
+                agent_name: {
+                    type: 'string',
+                    description: 'Agent name (used to find the spawned_agents record)'
+                }
+            },
+            required: ['status_message']
+        }
     }
 ];

package/dist/tools/index.d.ts

@@ -30,6 +30,7 @@ import { sprintTools } from './sprints.js';
 import { gitIssueTools } from './git-issues.js';
 import { connectorTools } from './connectors.js';
 import { cloudAgentTools } from './cloud-agents.js';
+import { versionTools } from './version.js';
 /**
  * All MCP tool definitions combined
  */
@@ -67,5 +68,6 @@ export declare const toolCategories: {
     readonly gitIssues: string[];
     readonly connectors: string[];
     readonly cloudAgents: string[];
+    readonly version: string[];
 };
-export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, };
+export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, versionTools, };

package/dist/tools/index.js

@@ -29,6 +29,8 @@ import { sprintTools } from './sprints.js';
 import { gitIssueTools } from './git-issues.js';
 import { connectorTools } from './connectors.js';
 import { cloudAgentTools } from './cloud-agents.js';
+import { versionTools } from './version.js';
+import { chatTools } from './chat.js';
 /**
  * All MCP tool definitions combined
  */
@@ -57,6 +59,8 @@ export const tools = [
     ...gitIssueTools,
     ...connectorTools,
     ...cloudAgentTools,
+    ...versionTools,
+    ...chatTools,
 ];
 /**
  * Build the complete tool list from all domain modules
@@ -93,6 +97,7 @@ export const toolCategories = {
     gitIssues: gitIssueTools.map((t) => t.name),
     connectors: connectorTools.map((t) => t.name),
     cloudAgents: cloudAgentTools.map((t) => t.name),
+    version: versionTools.map((t) => t.name),
 };
 // Re-export domain tools for selective imports
-export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, };
+export { sessionTools, costTools, discoveryTools, worktreeTools, projectTools, taskTools, progressTools, blockerTools, decisionTools, ideaTools, findingTools, validationTools, deploymentTools, fallbackTools, requestTools, milestoneTools, bodiesOfWorkTools, organizationTools, fileCheckoutTools, roleTools, sprintTools, gitIssueTools, connectorTools, cloudAgentTools, versionTools, };

package/dist/tools/project.js

@@ -61,7 +61,7 @@ export const projectTools = [
                 },
                 goal: {
                     type: 'string',
-                    description: 'What does "done" look like for this project?',
+                    description: 'High-level project goal or purpose (e.g. "A multiplayer card game platform")',
                 },
                 git_url: {
                     type: 'string',

package/dist/tools/tasks.js

@@ -296,6 +296,10 @@ For projects without git branching (trunk-based or none), use skip_worktree_requ
                     type: 'boolean',
                     description: 'Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false',
                 },
+                session_id: {
+                    type: 'string',
+                    description: 'Session ID from start_work_session. Required for cloud agents using mcporter (session context is not preserved between calls). Links the task to your agent on the dashboard.',
+                },
             },
             required: ['task_id'],
         },
@@ -326,6 +330,10 @@ The auto_continue: true flag in the response means you are expected to continue
                     type: 'string',
                     description: 'Brief summary of what was done. This is stored on the task as completion_summary and displayed when reviewing completed tasks.',
                 },
+                session_id: {
+                    type: 'string',
+                    description: 'Session ID from start_work_session. Required for cloud agents using mcporter.',
+                },
             },
             required: ['task_id'],
         },

package/dist/tools/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Version management tool definitions
+ */
+import type { Tool } from './types.js';
+export declare const versionTools: Tool[];

package/dist/tools/version.js

@@ -0,0 +1,28 @@
+/**
+ * Version management tool definitions
+ */
+export const versionTools = [
+    {
+        name: 'check_mcp_version',
+        description: 'Check if the Vibescope MCP server is up to date. Compares the locally installed version against the latest published version on npm. Call this when starting a session or when the server instructions indicate an update is available.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'update_mcp_server',
+        description: 'Update the Vibescope MCP server to the latest version. Runs npm install to fetch the latest version. After updating, the server must be restarted (the agent should ask the user to restart their MCP client/editor). Only call this when the user agrees to update.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                global: {
+                    type: 'boolean',
+                    description: 'If true, update the global installation (npm install -g). If false, update locally. Default: true.',
+                },
+            },
+            required: [],
+        },
+    },
+];

package/dist/version.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Version checking utilities
+ *
+ * Compares the locally installed version against the latest published
+ * version on npm to detect available updates.
+ */
+export interface VersionInfo {
+    current: string;
+    latest: string | null;
+    updateAvailable: boolean;
+    error?: string;
+}
+/**
+ * Get the current locally installed version from package.json
+ */
+export declare function getLocalVersion(): string;
+/**
+ * Fetch the latest published version from npm registry
+ */
+export declare function getLatestVersion(): Promise<string | null>;
+/**
+ * Check if an update is available
+ */
+export declare function checkVersion(): Promise<VersionInfo>;
+/**
+ * Get the update warning message for server instructions, or null if up to date
+ */
+export declare function getUpdateWarning(): Promise<string | null>;

package/dist/version.js

@@ -0,0 +1,91 @@
+/**
+ * Version checking utilities
+ *
+ * Compares the locally installed version against the latest published
+ * version on npm to detect available updates.
+ */
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@vibescope/mcp-server';
+const PACKAGE_NAME = '@vibescope/mcp-server';
+/**
+ * Get the current locally installed version from package.json
+ */
+export function getLocalVersion() {
+    try {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = resolve(__dirname, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Fetch the latest published version from npm registry
+ */
+export async function getLatestVersion() {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const response = await fetch(`${NPM_REGISTRY_URL}/latest`, {
+            signal: controller.signal,
+            headers: { 'Accept': 'application/json' },
+        });
+        clearTimeout(timeout);
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare semver strings. Returns true if latest > current.
+ */
+function isNewer(current, latest) {
+    const parse = (v) => v.split('.').map(Number);
+    const c = parse(current);
+    const l = parse(latest);
+    for (let i = 0; i < 3; i++) {
+        if ((l[i] ?? 0) > (c[i] ?? 0))
+            return true;
+        if ((l[i] ?? 0) < (c[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Check if an update is available
+ */
+export async function checkVersion() {
+    const current = getLocalVersion();
+    const latest = await getLatestVersion();
+    if (!latest) {
+        return {
+            current,
+            latest: null,
+            updateAvailable: false,
+            error: 'Could not reach npm registry to check for updates',
+        };
+    }
+    return {
+        current,
+        latest,
+        updateAvailable: isNewer(current, latest),
+    };
+}
+/**
+ * Get the update warning message for server instructions, or null if up to date
+ */
+export async function getUpdateWarning() {
+    const info = await checkVersion();
+    if (info.updateAvailable && info.latest) {
+        return `⚠️ UPDATE AVAILABLE: Vibescope MCP server v${info.current} is outdated. Latest version is v${info.latest}. Before starting work, inform the user that an update is available and recommend running the \`check_mcp_version\` tool, or ask them to update with: npm install -g ${PACKAGE_NAME}@latest (or npx @vibescope/mcp-server@latest for auto-update on next run).`;
+    }
+    return null;
+}

package/docs/TOOLS.md

@@ -2,9 +2,9 @@
 
 > Auto-generated from tool definitions. Do not edit manually.
 >
-> Generated: 2026-02-06
+> Generated: 2026-02-19
 >
-> Total tools: 154
+> Total tools: 159
 
 ## Table of Contents
 
@@ -34,6 +34,8 @@
 - [file_locks](#file-locks) - File checkout/locking for multi-agent (6 tools)
 - [connectors](#connectors) - External integration connectors (7 tools)
 - [cloud_agents](#cloud-agents) - Cloud agent management and cleanup (2 tools)
+- [chat](#chat) - Project-wide chat channel for agent and user communication (2 tools)
+- [version](#version) - MCP server version management and updates (2 tools)
 
 ## session
 
@@ -207,7 +209,7 @@ Create a new project to track in Vibescope.
 |-----------|------|----------|-------------|
 | `name` | `string` | Yes | Project display name |
 | `description` | `string` | No | Brief project description |
-| `goal` | `string` | No | What does "done" look like for this project? |
+| `goal` | `string` | No | High-level project goal or purpose (e.g. "A multiplayer card game platform") |
 | `git_url` | `string` | No | Git repository URL (if available) |
 | `tech_stack` | `string[]` | No | Technologies used (e.g., ["TypeScript", "React", "PostgreSQL"]) |
 
@@ -414,6 +416,7 @@ For projects without git branching (trunk-based or none), use skip_worktree_requ
 | `worktree_hostname` | `string` | No | Machine hostname where worktree was created (os.hostname()). Required with worktree_path to enable machine-aware cleanup. |
 | `model_capability` | `"haiku" | "sonnet" | "opus"` | No | Recommended model capability: haiku (simple tasks), sonnet (standard), opus (complex reasoning) |
 | `skip_worktree_requirement` | `boolean` | No | Skip git_branch requirement for projects without branching workflows (trunk-based or none). Default: false |
+| `session_id` | `string` | No | Session ID from start_work_session. Required for cloud agents using mcporter (session context is not preserved between calls). Links the task to your agent on the dashboard. |
 
 ---
 
@@ -445,6 +448,7 @@ The auto_continue: true flag in the response means you are expected to continue
 |-----------|------|----------|-------------|
 | `task_id` | `string` | Yes | Task UUID |
 | `summary` | `string` | No | Brief summary of what was done. This is stored on the task as completion_summary and displayed when reviewing completed tasks. |
+| `session_id` | `string` | No | Session ID from start_work_session. Required for cloud agents using mcporter. |
 
 ---
 
@@ -2457,3 +2461,89 @@ Use this to check the state of cloud agents before/after cleanup.
 | `status` | `"starting" | "running" | "stopped" | "failed" | "all"` | No | Filter by status (default: all) |
 
 ---
+
+## chat
+
+*Project-wide chat channel for agent and user communication*
+
+### send_project_message
+
+Send a message to the project chat channel. All agents and the project owner can see messages here. Use this to communicate status updates, ask questions, report blockers, or coordinate with other agents.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `message` | `string` | Yes | Message content (supports markdown) |
+
+---
+
+### get_project_messages
+
+Read recent messages from the project chat channel. Use this to check if the user or other agents have posted anything.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project_id` | `string` | Yes | Project UUID |
+| `limit` | `number` | No | Number of recent messages to fetch (default: 20, max: 100) |
+
+---
+
+## version
+
+*MCP server version management and updates*
+
+### check_mcp_version
+
+Check if the Vibescope MCP server is up to date. Compares the locally installed version against the latest published version on npm. Call this when starting a session or when the server instructions indicate an update is available.
+
+**Parameters:** None
+
+---
+
+### update_mcp_server
+
+Update the Vibescope MCP server to the latest version. Runs npm install to fetch the latest version. After updating, the server must be restarted (the agent should ask the user to restart their MCP client/editor). Only call this when the user agrees to update.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `global` | `boolean` | No | If true, update the global installation (npm install -g). If false, update locally. Default: true. |
+
+---
+
+## Uncategorized
+
+*Tools not yet assigned to a category*
+
+### update_agent_status
+
+Report what you're currently doing. This updates the status message shown on the dashboard.
+
+Call this at key milestones during boot and work:
+
+- "Installing dependencies..."
+
+- "Running start_work_session..."
+
+- "Working on: <task title>"
+
+- "Running tests..."
+
+- "Committing changes..."
+
+Keep messages short (under 80 chars). The dashboard shows this in real-time.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `status_message` | `string` | Yes | Short status message to display on dashboard (max 80 chars) |
+| `project_id` | `string` | No | Project UUID (optional if session has project context) |
+| `agent_name` | `string` | No | Agent name (used to find the spawned_agents record) |
+
+---

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
     "vibescope-mcp": "dist/index.js",
-    "vibescope-cli": "dist/cli.js"
+    "vibescope-cli": "dist/cli.js",
+    "vibescope": "dist/cli-init.js",
+    "vibescope-init": "dist/cli-init.js"
   },
   "repository": {
     "type": "git",

package/src/api-client/fallback.ts

@@ -0,0 +1,52 @@
+/**
+ * Fallback Activity API Methods
+ *
+ * Handles background activities when agents are idle with no pending tasks.
+ */
+
+import type { ApiResponse, ProxyFn } from './types.js';
+
+export interface FallbackActivityResult {
+	success: boolean;
+	activity: string;
+	message: string;
+	git_workflow?: {
+		workflow: string;
+		base_branch: string;
+		worktree_recommended: boolean;
+		note: string;
+	};
+	worktree_setup?: {
+		message: string;
+		commands: string[];
+		worktree_path: string;
+		branch_name: string;
+		cleanup_command: string;
+		report_worktree: string;
+	};
+	next_step?: string;
+}
+
+export interface FallbackMethods {
+	startFallbackActivity(projectId: string, activity: string, sessionId?: string): Promise<ApiResponse<FallbackActivityResult>>;
+
+	stopFallbackActivity(projectId: string, summary?: string, sessionId?: string): Promise<ApiResponse<{ success: boolean }>>;
+}
+
+export function createFallbackMethods(proxy: ProxyFn): FallbackMethods {
+	return {
+		async startFallbackActivity(projectId, activity, sessionId) {
+			return proxy('start_fallback_activity', {
+				project_id: projectId,
+				activity
+			}, sessionId ? { session_id: sessionId } : undefined);
+		},
+
+		async stopFallbackActivity(projectId, summary, sessionId) {
+			return proxy('stop_fallback_activity', {
+				project_id: projectId,
+				summary
+			}, sessionId ? { session_id: sessionId } : undefined);
+		}
+	};
+}

package/src/api-client/findings.ts

@@ -0,0 +1,100 @@
+/**
+ * Findings API Methods
+ *
+ * Handles security findings, code quality issues, and audit findings.
+ */
+
+import type { ApiResponse, ProxyFn } from './types.js';
+
+export interface Finding {
+	id: string;
+	title: string;
+	description?: string;
+	category: string;
+	severity: string;
+	status: string;
+	file_path?: string;
+	line_number?: number;
+	resolution_note?: string;
+	created_at: string;
+}
+
+export interface FindingsStats {
+	total: number;
+	by_status: Record<string, number>;
+	by_severity: Record<string, number>;
+	by_category: Record<string, number>;
+}
+
+export interface FindingsMethods {
+	getFindings(projectId: string, params?: {
+		category?: string;
+		severity?: string;
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+		summary_only?: boolean;
+	}): Promise<ApiResponse<{ findings: Finding[]; total_count?: number; has_more?: boolean }>>;
+
+	getFinding(findingId: string): Promise<ApiResponse<{ finding: Finding }>>;
+
+	getFindingsStats(projectId: string): Promise<ApiResponse<FindingsStats>>;
+
+	addFinding(projectId: string, params: {
+		title: string;
+		description?: string;
+		category?: string;
+		severity?: string;
+		file_path?: string;
+		line_number?: number;
+		related_task_id?: string;
+	}, sessionId?: string): Promise<ApiResponse<{ success: boolean; finding_id: string }>>;
+
+	updateFinding(findingId: string, updates: {
+		title?: string;
+		description?: string;
+		severity?: string;
+		status?: string;
+		resolution_note?: string;
+	}): Promise<ApiResponse<{ success: boolean; finding_id: string }>>;
+
+	deleteFinding(findingId: string): Promise<ApiResponse<{ success: boolean }>>;
+}
+
+export function createFindingsMethods(proxy: ProxyFn): FindingsMethods {
+	return {
+		async getFindings(projectId, params) {
+			return proxy('get_findings', {
+				project_id: projectId,
+				...params
+			});
+		},
+
+		async getFinding(findingId) {
+			return proxy('get_finding', { finding_id: findingId });
+		},
+
+		async getFindingsStats(projectId) {
+			return proxy('get_findings_stats', { project_id: projectId });
+		},
+
+		async addFinding(projectId, params, sessionId) {
+			return proxy('add_finding', {
+				project_id: projectId,
+				...params
+			}, sessionId ? { session_id: sessionId } : undefined);
+		},
+
+		async updateFinding(findingId, updates) {
+			return proxy('update_finding', {
+				finding_id: findingId,
+				...updates
+			});
+		},
+
+		async deleteFinding(findingId) {
+			return proxy('delete_finding', { finding_id: findingId });
+		}
+	};
+}