@vibescope/mcp-server 0.4.4 → 0.4.5

package/src/handlers/chat.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { sendProjectMessage, getProjectMessages, autoPostActivity } from './chat.js';
+import { ValidationError } from '../validators.js';
+import { createMockContext } from './__test-utils__.js';
+
+// vi.mock is hoisted above imports by Vitest — this intercepts the api-client module
+const mockSendProjectMessage = vi.fn();
+const mockGetProjectMessages = vi.fn();
+
+vi.mock('../api-client.js', () => ({
+	getApiClient: () => ({
+		sendProjectMessage: mockSendProjectMessage,
+		getProjectMessages: mockGetProjectMessages,
+	}),
+	initApiClient: vi.fn(),
+	VibescopeApiClient: vi.fn(),
+}));
+
+const VALID_PROJECT_ID = '123e4567-e89b-12d3-a456-426614174000';
+
+// ============================================================================
+// sendProjectMessage Tests
+// ============================================================================
+
+describe('sendProjectMessage', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockSendProjectMessage.mockResolvedValue({ ok: true, data: {} });
+		mockGetProjectMessages.mockResolvedValue({ ok: true, data: { messages: [], count: 0 } });
+	});
+
+	it('should throw for missing project_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			sendProjectMessage({ message: 'Hello' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw for invalid project_id UUID', async () => {
+		const ctx = createMockContext();
+		await expect(
+			sendProjectMessage({ project_id: 'not-a-uuid', message: 'Hello' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw for missing message', async () => {
+		const ctx = createMockContext();
+		await expect(
+			sendProjectMessage({ project_id: VALID_PROJECT_ID }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should send message successfully', async () => {
+		mockSendProjectMessage.mockResolvedValue({
+			ok: true,
+			data: { success: true, message_id: 'msg-1', sent_at: '2026-02-22T12:00:00Z' },
+		});
+		const ctx = createMockContext({ sessionId: 'session-abc' });
+
+		const result = await sendProjectMessage(
+			{ project_id: VALID_PROJECT_ID, message: 'Deployment complete' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true, message_id: 'msg-1' });
+		expect(mockSendProjectMessage).toHaveBeenCalledWith(
+			VALID_PROJECT_ID,
+			'Deployment complete',
+			'session-abc'
+		);
+	});
+
+	it('should return error when API fails', async () => {
+		mockSendProjectMessage.mockResolvedValue({
+			ok: false,
+			error: 'Project not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await sendProjectMessage(
+			{ project_id: VALID_PROJECT_ID, message: 'Hi' },
+			ctx
+		);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({ error: 'Project not found' });
+	});
+});
+
+// ============================================================================
+// getProjectMessages Tests
+// ============================================================================
+
+describe('getProjectMessages', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockSendProjectMessage.mockResolvedValue({ ok: true, data: {} });
+		mockGetProjectMessages.mockResolvedValue({ ok: true, data: { messages: [], count: 0 } });
+	});
+
+	it('should throw for missing project_id', async () => {
+		const ctx = createMockContext();
+		await expect(
+			getProjectMessages({}, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should fetch messages successfully', async () => {
+		const mockMessages = [
+			{ id: 'msg-1', sender_type: 'agent', sender_name: 'Garath', content: 'Started session', created_at: '2026-02-22T12:00:00Z' },
+		];
+		mockGetProjectMessages.mockResolvedValue({
+			ok: true,
+			data: { messages: mockMessages, count: 1 },
+		});
+		const ctx = createMockContext();
+
+		const result = await getProjectMessages({ project_id: VALID_PROJECT_ID }, ctx);
+
+		expect(result.result).toMatchObject({ messages: mockMessages, count: 1 });
+		expect(mockGetProjectMessages).toHaveBeenCalledWith(VALID_PROJECT_ID, undefined);
+	});
+
+	it('should pass limit when provided', async () => {
+		const ctx = createMockContext();
+
+		await getProjectMessages({ project_id: VALID_PROJECT_ID, limit: 5 }, ctx);
+
+		expect(mockGetProjectMessages).toHaveBeenCalledWith(VALID_PROJECT_ID, 5);
+	});
+
+	it('should return error when API fails', async () => {
+		mockGetProjectMessages.mockResolvedValue({ ok: false, error: 'Unauthorized' });
+		const ctx = createMockContext();
+
+		const result = await getProjectMessages({ project_id: VALID_PROJECT_ID }, ctx);
+
+		expect(result.isError).toBe(true);
+	});
+});
+
+// ============================================================================
+// autoPostActivity Tests
+// ============================================================================
+
+describe('autoPostActivity', () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockSendProjectMessage.mockResolvedValue({ ok: true, data: {} });
+	});
+
+	it('should call sendProjectMessage with correct args', async () => {
+		await autoPostActivity(VALID_PROJECT_ID, 'Agent started work', 'session-123');
+
+		expect(mockSendProjectMessage).toHaveBeenCalledWith(
+			VALID_PROJECT_ID,
+			'Agent started work',
+			'session-123'
+		);
+	});
+
+	it('should silently ignore errors (never throws)', async () => {
+		mockSendProjectMessage.mockRejectedValue(new Error('Network error'));
+
+		// Should not throw
+		await expect(
+			autoPostActivity(VALID_PROJECT_ID, 'message', 'session-123')
+		).resolves.toBeUndefined();
+	});
+
+	it('should do nothing when projectId is empty', async () => {
+		await autoPostActivity('', 'message', 'session-123');
+		expect(mockSendProjectMessage).not.toHaveBeenCalled();
+	});
+
+	it('should work without sessionId', async () => {
+		await autoPostActivity(VALID_PROJECT_ID, 'no session message');
+
+		expect(mockSendProjectMessage).toHaveBeenCalledWith(
+			VALID_PROJECT_ID,
+			'no session message',
+			undefined
+		);
+	});
+});

package/src/handlers/chat.ts

@@ -0,0 +1,69 @@
+/**
+ * Chat handlers
+ *
+ * Handlers for project chat tools:
+ * - send_project_message: Post a message to the project chat
+ * - get_project_messages: Read recent messages from project chat
+ *
+ * Also exports autoPostActivity — a fire-and-forget helper used by other
+ * handlers to log agent boot progress and key events to the chat window.
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { parseArgs, uuidValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+const sendProjectMessageSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	message: { type: 'string' as const, required: true as const },
+};
+
+const getProjectMessagesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	limit: { type: 'number' as const },
+};
+
+export const sendProjectMessage: Handler = async (args, ctx) => {
+	const { project_id, message } = parseArgs(args, sendProjectMessageSchema);
+	const api = getApiClient();
+	const response = await api.sendProjectMessage(project_id, message, ctx.session.currentSessionId || undefined);
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to send message' }, isError: true };
+	}
+	return { result: response.data };
+};
+
+export const getProjectMessages: Handler = async (args, _ctx) => {
+	const { project_id, limit } = parseArgs(args, getProjectMessagesSchema);
+	const api = getApiClient();
+	const response = await api.getProjectMessages(project_id, limit);
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to fetch messages' }, isError: true };
+	}
+	return { result: response.data };
+};
+
+/**
+ * Auto-post an agent activity message to the project chat.
+ *
+ * Fire-and-forget: errors are silently swallowed so auto-posting never
+ * interrupts or breaks the main tool response.
+ */
+export async function autoPostActivity(
+	projectId: string,
+	message: string,
+	sessionId?: string | null
+): Promise<void> {
+	if (!projectId) return;
+	try {
+		const api = getApiClient();
+		await api.sendProjectMessage(projectId, message, sessionId ?? undefined);
+	} catch {
+		// Silently ignore — activity logging must never break main functionality
+	}
+}
+
+export const chatHandlers: HandlerRegistry = {
+	send_project_message: sendProjectMessage,
+	get_project_messages: getProjectMessages,
+};

package/src/handlers/deployment.ts

@@ -12,6 +12,8 @@
  * - add_deployment_requirement
  * - complete_deployment_requirement
  * - get_deployment_requirements
+ * - get_deployment_requirements_stats
+ * - reorder_deployment_requirements
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
@@ -334,6 +336,32 @@ export const getDeploymentRequirementsStats: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
+// ============================================================================
+// Reorder Deployment Requirements
+// ============================================================================
+
+const reorderDeploymentRequirementsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	stage: { type: 'string' as const, required: true as const, validate: createEnumValidator(REQUIREMENT_STAGES) },
+	requirement_ids: { type: 'object' as const, required: true as const },
+};
+
+export const reorderDeploymentRequirements: Handler = async (args, ctx) => {
+	const { project_id, stage, requirement_ids } = parseArgs(args, reorderDeploymentRequirementsSchema);
+
+	const apiClient = getApiClient();
+	const response = await apiClient.reorderDeploymentRequirements(project_id, {
+		stage,
+		requirement_ids: requirement_ids as unknown as string[],
+	});
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to reorder deployment requirements' }, isError: true };
+	}
+
+	return { result: response.data };
+};
+
 // ============================================================================
 // Scheduled Deployments
 // ============================================================================
@@ -531,6 +559,7 @@ export const deploymentHandlers: HandlerRegistry = {
 	complete_deployment_requirement: completeDeploymentRequirement,
 	get_deployment_requirements: getDeploymentRequirements,
 	get_deployment_requirements_stats: getDeploymentRequirementsStats,
+	reorder_deployment_requirements: reorderDeploymentRequirements,
 	// Scheduled deployments
 	schedule_deployment: scheduleDeployment,
 	get_scheduled_deployments: getScheduledDeployments,

package/src/handlers/discovery.ts

@@ -167,6 +167,7 @@ export const TOOL_CATEGORIES: Record<string, { description: string; tools: Array
 			{ name: 'complete_deployment_requirement', brief: 'Mark step done' },
 			{ name: 'get_deployment_requirements', brief: 'List pre-deploy steps' },
 			{ name: 'get_deployment_requirements_stats', brief: 'Get requirements statistics' },
+			{ name: 'reorder_deployment_requirements', brief: 'Reorder steps within a stage' },
 			{ name: 'schedule_deployment', brief: 'Schedule future deployment' },
 			{ name: 'get_scheduled_deployments', brief: 'List scheduled deployments' },
 			{ name: 'update_scheduled_deployment', brief: 'Update schedule config' },

package/src/handlers/index.ts

@@ -30,6 +30,7 @@ export * from './roles.js';
 export * from './connectors.js';
 export * from './cloud-agents.js';
 export * from './version.js';
+export * from './chat.js';
 
 import type { HandlerRegistry } from './types.js';
 import { milestoneHandlers } from './milestones.js';
@@ -56,6 +57,7 @@ import { roleHandlers } from './roles.js';
 import { connectorHandlers } from './connectors.js';
 import { cloudAgentHandlers } from './cloud-agents.js';
 import { versionHandlers } from './version.js';
+import { chatHandlers } from './chat.js';
 
 /**
  * Build the complete handler registry from all modules
@@ -86,5 +88,6 @@ export function buildHandlerRegistry(): HandlerRegistry {
 		...connectorHandlers,
 		...cloudAgentHandlers,
 		...versionHandlers,
+		...chatHandlers,
 	};
 }

package/src/handlers/session.ts

@@ -17,6 +17,7 @@ import { getApiClient } from '../api-client.js';
 import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
 import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
 import { normalizeGitUrl } from '../utils.js';
+import { autoPostActivity } from './chat.js';
 
 /**
  * Simple hash for content change detection.
@@ -569,6 +570,17 @@ export const startWorkSession: Handler = async (args, ctx) => {
 			: 'signal_idle() — no tasks available and fallback activities are disabled.';
 	}
 
+	// Auto-post boot activity to project chat
+	if (data.project?.id) {
+		const persona = data.persona || 'Agent';
+		const nextTaskInfo = data.next_task ? ` Next task: **${data.next_task.title}**` : '';
+		void autoPostActivity(
+			data.project.id,
+			`🤖 **${persona}** started a work session.${nextTaskInfo}`,
+			data.session_id
+		);
+	}
+
 	return { result };
 };
 

package/src/handlers/tasks.ts

@@ -36,6 +36,7 @@ import {
 } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 import { capPagination, PAGINATION_LIMITS } from '../utils.js';
+import { autoPostActivity } from './chat.js';
 
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
@@ -591,6 +592,17 @@ export const completeTask: Handler = async (args, ctx) => {
 		};
 	}
 
+	// Auto-post completion activity to project chat
+	if (ctx.session.currentProjectId) {
+		const persona = ctx.session.currentPersona || 'Agent';
+		const summaryText = summary ? `: ${summary}` : '';
+		void autoPostActivity(
+			ctx.session.currentProjectId,
+			`✅ **${persona}** completed a task${summaryText}`,
+			ctx.session.currentSessionId || undefined
+		);
+	}
+
 	return { result };
 };
 

package/src/handlers/tool-docs.ts

@@ -1081,6 +1081,14 @@ Get pending deployment requirements.
 - stage (optional): preparation, deployment, verification, or all
 - status (optional): pending, completed, converted_to_task, or all (default: pending)`,
 
+	reorder_deployment_requirements: `# reorder_deployment_requirements
+Reorder deployment requirements within a stage.
+
+**Parameters:**
+- project_id (required): Project UUID
+- stage (required): preparation, deployment, or verification
+- requirement_ids (required): Array of requirement UUIDs in desired order`,
+
 	// Knowledge base
 	query_knowledge_base: `# query_knowledge_base
 Query aggregated project knowledge in a single call. Reduces token usage by combining multiple data sources.

package/src/tools/deployment.ts

@@ -265,6 +265,19 @@ export const deploymentTools: Tool[] = [
 			required: ['project_id'],
 		},
 	},
+	{
+		name: 'reorder_deployment_requirements',
+		description: `Reorder deployment requirements within a stage. Pass the requirement IDs in the desired order.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project_id: { type: 'string', description: 'Project UUID' },
+				stage: { type: 'string', enum: ['preparation', 'deployment', 'verification'], description: 'Deployment stage' },
+				requirement_ids: { type: 'array', items: { type: 'string' }, description: 'Ordered array of requirement UUIDs' },
+			},
+			required: ['project_id', 'stage', 'requirement_ids'],
+		},
+	},
 	{
 		name: 'schedule_deployment',
 		description: `Schedule a deployment for a specific time. Supports one-time and recurring schedules with auto-trigger or manual trigger modes.`,