@vibescope/mcp-server 0.4.0 → 0.4.2

package/src/handlers/tool-docs.ts

@@ -1106,4 +1106,386 @@ 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/src/handlers/version.ts

@@ -0,0 +1,63 @@
+/**
+ * Version management handlers
+ */
+
+import { execSync } from 'child_process';
+import type { HandlerRegistry } from './types.js';
+import { success, error } from './types.js';
+import { checkVersion, getLocalVersion } from '../version.js';
+
+const PACKAGE_NAME = '@vibescope/mcp-server';
+
+export const versionHandlers: HandlerRegistry = {
+	check_mcp_version: async (_args, _ctx) => {
+		const info = await checkVersion();
+
+		if (info.error) {
+			return success({
+				current_version: info.current,
+				latest_version: info.latest,
+				update_available: false,
+				warning: info.error,
+			});
+		}
+
+		return success({
+			current_version: info.current,
+			latest_version: info.latest,
+			update_available: info.updateAvailable,
+			message: info.updateAvailable
+				? `Update available! v${info.current} → v${info.latest}. Ask the user if they would like to update using the update_mcp_server tool.`
+				: `Vibescope MCP server is up to date (v${info.current}).`,
+		});
+	},
+
+	update_mcp_server: async (args, _ctx) => {
+		const useGlobal = args.global !== false; // default true
+		const flag = useGlobal ? '-g ' : '';
+		const command = `npm install ${flag}${PACKAGE_NAME}@latest`;
+
+		try {
+			const output = execSync(command, {
+				encoding: 'utf-8',
+				timeout: 60000,
+				stdio: ['pipe', 'pipe', 'pipe'],
+			});
+
+			// Check the new version
+			const newVersion = getLocalVersion();
+
+			return success({
+				updated: true,
+				command_run: command,
+				output: output.trim(),
+				new_version: newVersion,
+				message:
+					'Update complete. The MCP server must be restarted to use the new version. Please ask the user to restart their editor/MCP client, or reconnect the MCP server.',
+			});
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			return error(`Failed to update: ${message}. The user may need to run manually: ${command}`);
+		}
+	},
+};

package/src/index.ts

@@ -43,6 +43,7 @@ import {
 	setCurrentModel,
 	type TokenUsage,
 } from './token-tracking.js';
+import { getUpdateWarning } from './version.js';
 
 // ============================================================================
 // Agent Instance Tracking
@@ -654,6 +655,13 @@ async function main() {
 		process.exit(1);
 	}
 
+	// Check for updates (non-blocking, with timeout)
+	const updateWarning = await getUpdateWarning();
+
+	const serverInstructions = updateWarning
+		? `${updateWarning}\n\nVibescope MCP server - AI project tracking and coordination tools.`
+		: 'Vibescope MCP server - AI project tracking and coordination tools.';
+
 	const server = new Server(
 		{
 			name: 'vibescope',
@@ -663,6 +671,7 @@ async function main() {
 			capabilities: {
 				tools: {},
 			},
+			instructions: serverInstructions,
 		}
 	);
 

package/src/templates/agent-guidelines.ts

@@ -6,7 +6,11 @@
  * 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
 
@@ -183,6 +187,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}
 `;
 
 /**

package/src/templates/help-content.ts

@@ -217,14 +217,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/src/tools/chat.ts

@@ -0,0 +1,46 @@
+/**
+ * Project chat tools:
+ * - send_project_message
+ * - get_project_messages
+ */
+
+import type { Tool } from './types.js';
+
+export const chatTools: Tool[] = [
+	{
+		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/src/tools/cloud-agents.ts

@@ -66,5 +66,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/src/tools/index.ts

@@ -33,6 +33,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
@@ -62,6 +64,8 @@ export const tools: Tool[] = [
 	...gitIssueTools,
 	...connectorTools,
 	...cloudAgentTools,
+	...versionTools,
+	...chatTools,
 ];
 
 /**
@@ -100,6 +104,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),
 } as const;
 
 // Re-export domain tools for selective imports
@@ -128,4 +133,5 @@ export {
 	gitIssueTools,
 	connectorTools,
 	cloudAgentTools,
+	versionTools,
 };

package/src/tools/project.ts

@@ -64,7 +64,7 @@ export const projectTools: Tool[] = [
 				},
 				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/src/tools/tasks.ts

@@ -299,6 +299,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'],
 		},
@@ -329,6 +333,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/src/tools/version.ts

@@ -0,0 +1,34 @@
+/**
+ * Version management tool definitions
+ */
+
+import type { Tool } from './types.js';
+
+export const versionTools: Tool[] = [
+	{
+		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' as const,
+			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' as const,
+			properties: {
+				global: {
+					type: 'boolean',
+					description:
+						'If true, update the global installation (npm install -g). If false, update locally. Default: true.',
+				},
+			},
+			required: [],
+		},
+	},
+];