@vibescope/mcp-server 0.3.13 → 0.3.15

package/dist/api-client/validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Validation API Methods
+ *
+ * Handles task validation workflow for code review and approval.
+ */
+import type { ApiResponse, ProxyFn } from './types.js';
+export interface TaskAwaitingValidation {
+    id: string;
+    title: string;
+    completed_at?: string;
+    completed_by_session_id?: string;
+}
+export interface ValidationMethods {
+    getTasksAwaitingValidation(projectId: string): Promise<ApiResponse<{
+        tasks: TaskAwaitingValidation[];
+    }>>;
+    claimValidation(taskId: string, sessionId?: string): Promise<ApiResponse<{
+        success: boolean;
+        task_id: string;
+    }>>;
+    validateTask(taskId: string, params: {
+        approved: boolean;
+        validation_notes?: string;
+        skip_pr_check?: boolean;
+        pr_checks_passing?: boolean;
+        create_fix_task?: boolean;
+    }, sessionId?: string): Promise<ApiResponse<{
+        success: boolean;
+        approved: boolean;
+        task_id: string;
+        message?: string;
+        workflow?: string;
+    }>>;
+}
+export declare function createValidationMethods(proxy: ProxyFn): ValidationMethods;

package/dist/api-client/validation.js

@@ -0,0 +1,23 @@
+/**
+ * Validation API Methods
+ *
+ * Handles task validation workflow for code review and approval.
+ */
+export function createValidationMethods(proxy) {
+    return {
+        async getTasksAwaitingValidation(projectId) {
+            return proxy('get_tasks_awaiting_validation', { project_id: projectId });
+        },
+        async claimValidation(taskId, sessionId) {
+            return proxy('claim_validation', { task_id: taskId }, sessionId ? {
+                session_id: sessionId
+            } : undefined);
+        },
+        async validateTask(taskId, params, sessionId) {
+            return proxy('validate_task', {
+                task_id: taskId,
+                ...params
+            }, sessionId ? { session_id: sessionId } : undefined);
+        }
+    };
+}

package/dist/api-client.js

@@ -4,7 +4,11 @@
  * HTTP client for communicating with the Vibescope API.
  * All database operations are handled server-side through these endpoints.
  */
+import crypto from 'crypto';
 const DEFAULT_API_URL = 'https://vibescope.dev';
+// Stable instance ID for this process — persists across start_work_session calls
+// so the API can recognise reconnections after context clears
+const PROCESS_INSTANCE_ID = crypto.randomUUID();
 // Retry configuration defaults
 const DEFAULT_RETRY_STATUS_CODES = [429, 503, 504];
 const DEFAULT_MAX_RETRIES = 3;
@@ -133,7 +137,10 @@ export class VibescopeApiClient {
     }
     // Session endpoints
     async startSession(params) {
-        return this.request('POST', '/api/mcp/sessions/start', params);
+        return this.request('POST', '/api/mcp/sessions/start', {
+            ...params,
+            instance_id: PROCESS_INSTANCE_ID,
+        });
     }
     async heartbeat(sessionId, options) {
         return this.request('POST', '/api/mcp/sessions/heartbeat', {

package/dist/handlers/cloud-agents.js

@@ -27,12 +27,8 @@ const listCloudAgentsSchema = {
  * Clean up stale cloud agents that failed to start or lost connection.
  * Only operates on agents in the specified project (security scoped).
  */
-export const cleanupStaleCloudAgents = async (args, ctx) => {
+export const cleanupStaleCloudAgents = async (args, _ctx) => {
     const { project_id, stale_minutes, include_running, dry_run } = parseArgs(args, cleanupStaleAgentsSchema);
-    // Ensure user has an active session with this project (security check)
-    if (ctx.session.currentProjectId && ctx.session.currentProjectId !== project_id) {
-        return error('Cannot cleanup agents for a different project than your current session');
-    }
     const apiClient = getApiClient();
     // Call the cleanup endpoint via fetch (since it's a new endpoint not in the client)
     const response = await apiClient.proxy('cleanup_stale_cloud_agents', {
@@ -41,7 +37,7 @@ export const cleanupStaleCloudAgents = async (args, ctx) => {
         includeRunning: include_running,
         dryRun: dry_run,
     });
-    if (!response.ok) {
+    if (!response.ok || !response.data) {
         return error(response.error || 'Failed to cleanup stale agents');
     }
     const data = response.data;
@@ -63,18 +59,14 @@ export const cleanupStaleCloudAgents = async (args, ctx) => {
 /**
  * List cloud agents for a project with optional status filter.
  */
-export const listCloudAgents = async (args, ctx) => {
+export const listCloudAgents = async (args, _ctx) => {
     const { project_id, status } = parseArgs(args, listCloudAgentsSchema);
-    // Ensure user has an active session with this project (security check)
-    if (ctx.session.currentProjectId && ctx.session.currentProjectId !== project_id) {
-        return error('Cannot list agents for a different project than your current session');
-    }
     const apiClient = getApiClient();
     const response = await apiClient.proxy('list_cloud_agents', {
         project_id,
         status: status === 'all' ? undefined : status,
     });
-    if (!response.ok) {
+    if (!response.ok || !response.data) {
         return error(response.error || 'Failed to list cloud agents');
     }
     return success({

package/dist/handlers/discovery.js

@@ -319,6 +319,7 @@ export const TOOL_CATEGORIES = {
     cloud_agents: {
         description: 'Cloud agent management and cleanup',
         tools: [
+            { name: 'update_agent_status', brief: 'Update agent dashboard status message' },
             { name: 'cleanup_stale_cloud_agents', brief: 'Clean up stale cloud agents' },
             { name: 'list_cloud_agents', brief: 'List cloud agents for project' },
         ],

package/dist/handlers/findings.js

@@ -13,7 +13,7 @@ import { parseArgs, uuidValidator, createEnumValidator } from '../validators.js'
 import { getApiClient } from '../api-client.js';
 const VALID_FINDING_CATEGORIES = ['performance', 'security', 'code_quality', 'accessibility', 'documentation', 'architecture', 'testing', 'other'];
 const VALID_FINDING_SEVERITIES = ['info', 'low', 'medium', 'high', 'critical'];
-const VALID_FINDING_STATUSES = ['open', 'addressed', 'dismissed', 'wontfix'];
+const VALID_FINDING_STATUSES = ['open', 'in_development', 'implemented', 'addressed', 'dismissed', 'wontfix'];
 // Argument schemas for type-safe parsing
 const addFindingSchema = {
     project_id: { type: 'string', required: true, validate: uuidValidator },

package/dist/handlers/ideas.js

@@ -12,7 +12,7 @@
  */
 import { parseArgs, uuidValidator, priorityValidator, minutesValidator, createEnumValidator, } from '../validators.js';
 import { getApiClient } from '../api-client.js';
-const VALID_IDEA_STATUSES = ['raw', 'exploring', 'planned', 'in_development', 'shipped'];
+const VALID_IDEA_STATUSES = ['raw', 'exploring', 'planned', 'in_development', 'implemented', 'shipped'];
 // Argument schemas for type-safe parsing
 const addIdeaSchema = {
     project_id: { type: 'string', required: true, validate: uuidValidator },

package/dist/handlers/session.js

@@ -292,6 +292,7 @@ export const startWorkSession = async (args, ctx) => {
     }
     agentRules.push('COMPLETE TASKS: Always call complete_task() after creating a PR. This is mandatory.');
     agentRules.push('REVIEW REQUIRED: All tasks must be reviewed by another agent before merging.');
+    agentRules.push('STATUS UPDATES: Call update_agent_status(status_message: "Working on: TASK_TITLE") whenever you start a new task, and update_task(task_id, status: "in_progress") to claim it.');
     result.AGENT_RULES = agentRules;
     // Add next action at end - pending requests take priority over validation, then regular tasks
     if (hasUrgentQuestions) {

package/dist/handlers/tool-docs.js

@@ -980,4 +980,348 @@ Query aggregated project knowledge in a single call. Reduces token usage by comb
 **Token savings:** Replaces multiple tool calls (get_findings, get_decisions, get_blockers, etc.) with one call.
 
 **Example:** query_knowledge_base(project_id, categories: ["findings", "decisions"], limit: 10)`,
+    // Session tools (additional)
+    report_token_usage: `# report_token_usage
+Report actual token usage from Claude API responses.
+
+**Parameters:**
+- session_id (optional): Session UUID (uses current session if not provided)
+- input_tokens (required): Number of input tokens
+- output_tokens (required): Number of output tokens
+- model (optional): Model used (e.g., "claude-3-opus")
+
+**Returns:** Updated token usage summary`,
+    signal_idle: `# signal_idle
+Signal that the agent is idle and available for work.
+
+**Parameters:**
+- session_id (optional): Session UUID (uses current session if not provided)
+
+**Returns:** Idle status confirmation, may include suggested activities`,
+    confirm_agent_setup: `# confirm_agent_setup
+Confirm that agent setup is complete after following setup instructions.
+
+**Parameters:**
+- project_id (required): Project UUID
+- agent_type (required): Type of agent (e.g., "claude", "gemini")
+
+**Returns:** Setup confirmation status`,
+    // Project tools (additional)
+    get_project_summary: `# get_project_summary
+Get unified project statistics overview in a single call.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Task counts, blocker counts, finding counts, decision counts, and more`,
+    // Blocker tools (additional)
+    get_blocker: `# get_blocker
+Get a single blocker by ID.
+
+**Parameters:**
+- blocker_id (required): Blocker UUID
+
+**Returns:** Blocker details including description, status, resolution`,
+    get_blockers_stats: `# get_blockers_stats
+Get aggregate blocker statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Open/resolved counts, breakdown by age`,
+    // Decision tools (additional)
+    get_decision: `# get_decision
+Get a single decision by ID.
+
+**Parameters:**
+- decision_id (required): Decision UUID
+
+**Returns:** Decision details including title, description, rationale`,
+    get_decisions_stats: `# get_decisions_stats
+Get aggregate decision statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Total count, recent decisions count`,
+    // Idea tools (additional)
+    get_idea: `# get_idea
+Get a single idea by ID.
+
+**Parameters:**
+- idea_id (required): Idea UUID
+
+**Returns:** Idea details including title, description, status`,
+    // Finding tools (additional)
+    get_finding: `# get_finding
+Get a single finding by ID.
+
+**Parameters:**
+- finding_id (required): Finding UUID
+
+**Returns:** Finding details including title, category, severity, status`,
+    get_findings_stats: `# get_findings_stats
+Get aggregate finding statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Counts by category, severity, and status`,
+    // Deployment tools (additional)
+    get_deployment_requirements_stats: `# get_deployment_requirements_stats
+Get aggregate deployment requirement statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Counts by stage and status`,
+    // Worktree tools
+    get_stale_worktrees: `# get_stale_worktrees
+Find orphaned worktrees that need cleanup.
+
+**Parameters:**
+- project_id (required): Project UUID
+- hostname (optional): Filter to worktrees created on this machine
+
+**Returns:** List of stale worktrees with task info and cleanup commands`,
+    clear_worktree_path: `# clear_worktree_path
+Clear worktree path from a task after cleanup.
+
+**Parameters:**
+- task_id (required): Task UUID
+
+**Note:** Call this AFTER running git worktree remove`,
+    // Role tools
+    get_role_settings: `# get_role_settings
+Get project role settings and configuration.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Role configuration including allowed roles, default role`,
+    update_role_settings: `# update_role_settings
+Configure project role behavior.
+
+**Parameters:**
+- project_id (required): Project UUID
+- default_role (optional): Default role for new sessions
+- allowed_roles (optional): Array of allowed role names
+
+**Returns:** Updated role settings`,
+    set_session_role: `# set_session_role
+Set the role for the current session.
+
+**Parameters:**
+- session_id (optional): Session UUID (uses current session)
+- role (required): Role name (e.g., "developer", "validator", "deployer")
+
+**Returns:** Updated session with new role`,
+    get_agents_by_role: `# get_agents_by_role
+List active agents grouped by role.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Agents organized by role`,
+    // File checkout/lock tools
+    checkout_file: `# checkout_file
+Lock a file for editing to prevent conflicts with other agents.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to the file to lock
+- reason (optional): Why you need to edit this file
+
+**Returns:** Checkout confirmation with expiry time`,
+    checkin_file: `# checkin_file
+Release a file lock after editing.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to the file to release
+
+**Returns:** Checkin confirmation`,
+    get_file_checkouts: `# get_file_checkouts
+List current file locks.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (optional): Filter to specific file
+
+**Returns:** List of active file checkouts`,
+    get_file_checkouts_stats: `# get_file_checkouts_stats
+Get file checkout statistics.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Active checkout count, breakdown by agent`,
+    abandon_checkout: `# abandon_checkout
+Force-release a file lock (use with caution).
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to the file to release
+
+**Note:** Only use when the original agent is unreachable`,
+    is_file_available: `# is_file_available
+Check if a file is available for checkout.
+
+**Parameters:**
+- project_id (required): Project UUID
+- file_path (required): Path to check
+
+**Returns:** Availability status, current holder if locked`,
+    // Connector tools
+    get_connectors: `# get_connectors
+List project connectors (integrations).
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Array of configured connectors`,
+    get_connector: `# get_connector
+Get connector details.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+
+**Returns:** Connector configuration and status`,
+    add_connector: `# add_connector
+Create a new external integration connector.
+
+**Parameters:**
+- project_id (required): Project UUID
+- type (required): Connector type (webhook, slack, discord, etc.)
+- name (required): Display name
+- config (required): Type-specific configuration
+
+**Returns:** Created connector details`,
+    update_connector: `# update_connector
+Update connector configuration.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+- name (optional): New display name
+- config (optional): Updated configuration
+- enabled (optional): Enable/disable connector
+
+**Returns:** Updated connector details`,
+    delete_connector: `# delete_connector
+Remove a connector.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+
+**Returns:** Deletion confirmation`,
+    test_connector: `# test_connector
+Send a test event to verify connector configuration.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+
+**Returns:** Test result with success/failure details`,
+    get_connector_events: `# get_connector_events
+Get event history for a connector.
+
+**Parameters:**
+- connector_id (required): Connector UUID
+- limit (optional): Max events to return (default: 50)
+
+**Returns:** Array of sent events with status`,
+    // Cloud agent tools
+    update_agent_status: `# update_agent_status
+Update your status message on the dashboard. Call this after start_work_session and whenever you start a new task.
+
+**Parameters:**
+- status_message (required): Status text shown on dashboard (e.g. "Working on: Task title")
+- agent_name (required): Your agent name
+- project_id (required): Project UUID
+
+**Example:** update_agent_status(status_message: "Working on: Progress Report Modal", agent_name: "Leon", project_id: "...")`,
+    cleanup_stale_cloud_agents: `# cleanup_stale_cloud_agents
+Clean up stale cloud agents that failed to start or lost connection.
+
+**Parameters:**
+- project_id (required): Project UUID
+- stale_minutes (optional): Minutes of inactivity before considered stale (default: 5)
+- include_running (optional): Include running agents in cleanup (default: false)
+- dry_run (optional): Preview what would be cleaned without actually cleaning (default: false)
+
+**Returns:**
+- cleaned: Number of agents cleaned up
+- failed: Number of cleanup failures
+- agents: Array of affected agents with status
+
+**Example:** cleanup_stale_cloud_agents(project_id, stale_minutes: 10, dry_run: true)`,
+    list_cloud_agents: `# list_cloud_agents
+List cloud agents for a project with optional status filter.
+
+**Parameters:**
+- project_id (required): Project UUID
+- status (optional): Filter by status - starting, running, stopped, failed, or all (default: all)
+
+**Returns:**
+- agents: Array of agents with id, name, status, created_at, last_heartbeat, public_ip, ecs_task_id
+- count: Total number of agents returned
+
+**Example:** list_cloud_agents(project_id, status: "running")`,
+    // Chat tools
+    send_project_message: `# send_project_message
+Send a message to the project chat channel for agent and user communication.
+
+**Parameters:**
+- project_id (required): Project UUID
+- message (required): Message content to send
+- author_name (optional): Name of the message sender (defaults to session persona)
+
+**Returns:**
+- message_id: UUID of the sent message
+- timestamp: When the message was sent
+
+**Example:** send_project_message(project_id: "123e4567-e89b-12d3-a456-426614174000", message: "Deployment completed successfully")`,
+    get_project_messages: `# get_project_messages
+Read recent project chat messages to stay informed about project communication.
+
+**Parameters:**
+- project_id (required): Project UUID
+- limit (optional): Number of recent messages to retrieve (default: 20, max: 100)
+- since (optional): ISO timestamp to get messages after this time
+
+**Returns:**
+- messages: Array of messages with id, author_name, message, timestamp
+- count: Number of messages returned
+
+**Example:** get_project_messages(project_id: "123e4567-e89b-12d3-a456-426614174000", limit: 10)`,
+    // Version management tools  
+    check_mcp_version: `# check_mcp_version
+Check for available MCP server updates and version information.
+
+**Parameters:**
+- check_remote (optional): Whether to check remote registry for updates (default: true)
+
+**Returns:**
+- current_version: Currently running MCP server version
+- latest_version: Latest available version (if check_remote is true)
+- update_available: Boolean indicating if an update is available
+- release_notes: Summary of changes in latest version (if available)
+
+**Example:** check_mcp_version(check_remote: true)`,
+    update_mcp_server: `# update_mcp_server
+Self-update the MCP server to the latest available version.
+
+**Parameters:**
+- version (optional): Specific version to update to (defaults to latest)
+- restart_after_update (optional): Whether to restart after update (default: true)
+- backup_config (optional): Whether to backup current config (default: true)
+
+**Returns:**
+- success: Boolean indicating if update succeeded
+- old_version: Previous version before update
+- new_version: Version after update
+- restart_required: Whether manual restart is needed
+
+**Example:** update_mcp_server()
+
+**Note:** This operation may temporarily disconnect active sessions during restart.`,
 };

package/docs/TOOLS.md

@@ -2,7 +2,7 @@
 
 > Auto-generated from tool definitions. Do not edit manually.
 >
-> Generated: 2026-02-18
+> Generated: 2026-02-21
 >
 > Total tools: 159
 
@@ -33,7 +33,7 @@
 - [roles](#roles) - Agent role management (4 tools)
 - [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)
+- [cloud_agents](#cloud-agents) - Cloud agent management and cleanup (3 tools)
 - [chat](#chat) - Project-wide chat channel for agent and user communication (2 tools)
 - [version](#version) - MCP server version management and updates (2 tools)
 
@@ -2416,6 +2416,34 @@ Get event history for a connector or project. Shows delivery status and errors.
 
 *Cloud agent management and cleanup*
 
+### 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) |
+
+---
+
 ### cleanup_stale_cloud_agents
 
 Clean up stale cloud agents that failed to start or lost connection.
@@ -2515,35 +2543,3 @@ Update the Vibescope MCP server to the latest version. Runs npm install to fetch
 | `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,6 +1,6 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",

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);
+		}
+	};
+}