@vibescope/mcp-server 0.2.8 → 0.2.9

package/dist/tools.js

@@ -26,13 +26,11 @@ Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.`
                 },
                 model: {
                     type: 'string',
-                    enum: ['opus', 'sonnet', 'haiku'],
-                    description: 'Claude model being used (for accurate cost tracking). E.g., "opus", "sonnet", "haiku".',
+                    description: 'Model being used for cost tracking. E.g., "opus", "sonnet", "haiku" for Claude, "gemini" for Gemini, "gpt-4o" for OpenAI.',
                 },
                 role: {
                     type: 'string',
-                    enum: ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'],
-                    description: 'Agent role: developer (general work, default), validator (task validation), deployer (deployments), reviewer (code review), maintainer (housekeeping)',
+                    description: 'Agent role (e.g., "developer", "validator", "deployer", "reviewer", "maintainer"). Custom roles accepted.',
                 },
                 hostname: {
                     type: 'string',
@@ -40,8 +38,7 @@ Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.`
                 },
                 agent_type: {
                     type: 'string',
-                    enum: ['claude', 'gemini', 'cursor', 'windsurf', 'other'],
-                    description: 'Agent type for onboarding. When a new agent type connects to an existing project, setup instructions are returned.',
+                    description: 'Agent type (e.g., "claude", "gemini", "cursor", "windsurf"). Custom agent types accepted.',
                 },
             },
         },
@@ -60,8 +57,7 @@ This marks your agent type as fully onboarded to the project, so you won't recei
                 },
                 agent_type: {
                     type: 'string',
-                    enum: ['claude', 'gemini', 'cursor', 'windsurf', 'other'],
-                    description: 'Agent type that completed setup',
+                    description: 'Agent type that completed setup (e.g., "claude", "gemini", "cursor"). Custom agent types accepted.',
                 },
             },
             required: ['project_id', 'agent_type'],
@@ -110,7 +106,6 @@ The Claude API response includes 'usage.input_tokens' and 'usage.output_tokens'
                 },
                 model: {
                     type: 'string',
-                    enum: ['opus', 'sonnet', 'haiku'],
                     description: 'Model used for this API call (optional, uses session model if not provided)',
                 },
             },
@@ -2904,8 +2899,7 @@ Only returns tasks where all dependencies are completed.`,
                 },
                 role: {
                     type: 'string',
-                    enum: ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'],
-                    description: 'Role to configure',
+                    description: 'Role to configure (e.g., "developer", "validator", "deployer"). Custom roles accepted.',
                 },
                 enabled: {
                     type: 'boolean',
@@ -2949,8 +2943,7 @@ Only returns tasks where all dependencies are completed.`,
             properties: {
                 role: {
                     type: 'string',
-                    enum: ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'],
-                    description: 'Role to assign to this session',
+                    description: 'Role to assign to this session (e.g., "developer", "validator", "deployer"). Custom roles accepted.',
                 },
                 role_config: {
                     type: 'object',

package/package.json

@@ -1,51 +1,51 @@
-{
-  "name": "@vibescope/mcp-server",
-  "version": "0.2.8",
-  "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"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Nonatomic/Vibescope.git",
-    "directory": "packages/mcp-server"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "docs:generate": "npx tsx scripts/generate-docs.ts --output=docs/TOOLS.md",
-    "docs:preview": "npx tsx scripts/generate-docs.ts",
-    "version:check": "npx tsx scripts/version-bump.ts --dry-run",
-    "version:bump": "npx tsx scripts/version-bump.ts",
-    "version:patch": "npx tsx scripts/version-bump.ts --patch",
-    "version:minor": "npx tsx scripts/version-bump.ts --minor",
-    "version:major": "npx tsx scripts/version-bump.ts --major",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "vibescope",
-    "ai",
-    "project-management"
-  ],
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.7.0",
-    "vitest": "^4.0.17"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2"
-  }
-}
+{
+  "name": "@vibescope/mcp-server",
+  "version": "0.2.9",
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nonatomic/Vibescope.git",
+    "directory": "packages/mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "docs:generate": "npx tsx scripts/generate-docs.ts --output=docs/TOOLS.md",
+    "docs:preview": "npx tsx scripts/generate-docs.ts",
+    "version:check": "npx tsx scripts/version-bump.ts --dry-run",
+    "version:bump": "npx tsx scripts/version-bump.ts",
+    "version:patch": "npx tsx scripts/version-bump.ts --patch",
+    "version:minor": "npx tsx scripts/version-bump.ts --minor",
+    "version:major": "npx tsx scripts/version-bump.ts --major",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vibescope",
+    "ai",
+    "project-management"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.17"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2"
+  }
+}

package/src/api-client.ts

@@ -83,10 +83,10 @@ export class VibescopeApiClient {
 		project_id?: string;
 		git_url?: string;
 		mode?: 'lite' | 'full';
-		model?: 'opus' | 'sonnet' | 'haiku';
-		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
+		model?: string; // Open-ended - any model name accepted
+		role?: string; // Open-ended - any role name accepted
 		hostname?: string; // Machine hostname for worktree tracking
-		agent_type?: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'; // Agent type for onboarding
+		agent_type?: string; // Open-ended - any agent type accepted
 	}): Promise<ApiResponse<{
 		session_started: boolean;
 		session_id?: string;
@@ -1429,7 +1429,7 @@ export class VibescopeApiClient {
 	async reportTokenUsage(sessionId: string, params: {
 		input_tokens: number;
 		output_tokens: number;
-		model?: 'opus' | 'sonnet' | 'haiku';
+		model?: string; // Open-ended - any model name accepted
 	}): Promise<ApiResponse<{
 		success: boolean;
 		reported: {
@@ -2467,7 +2467,7 @@ export class VibescopeApiClient {
 	 * Confirm that agent setup is complete for a project.
 	 * This marks the agent type as onboarded so future sessions don't receive setup instructions.
 	 */
-	async confirmAgentSetup(projectId: string, agentType: 'claude' | 'gemini' | 'cursor' | 'windsurf' | 'other'): Promise<ApiResponse<{
+	async confirmAgentSetup(projectId: string, agentType: string): Promise<ApiResponse<{
 		success: boolean;
 		project_id: string;
 		agent_type: string;

package/src/handlers/roles.test.ts

@@ -166,13 +166,15 @@ describe('setSessionRole', () => {
 		});
 	});
 
-	it('should return error for invalid role', async () => {
+	it('should accept custom roles (open-ended)', async () => {
 		const ctx = createMockContext();
 
-		const result = await setSessionRole({ role: 'invalid_role' }, ctx);
+		const result = await setSessionRole({ role: 'custom_role' }, ctx);
 
+		// Roles are now open-ended - any role name is accepted
 		expect(result.result).toMatchObject({
-			error: expect.stringContaining('Invalid role: invalid_role'),
+			success: true,
+			role: 'custom_role',
 		});
 	});
 

package/src/handlers/roles.ts

@@ -116,14 +116,7 @@ export const setSessionRole: Handler = async (args, ctx) => {
 		};
 	}
 
-	const validRoles: AgentRole[] = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
-	if (!validRoles.includes(role)) {
-		return {
-			result: {
-				error: `Invalid role: ${role}. Must be one of: ${validRoles.join(', ')}`,
-			},
-		};
-	}
+	// Role is now open-ended - any role name accepted
 
 	// Update local session state
 	updateSession({ currentRole: role });

package/src/handlers/session.ts

@@ -14,29 +14,28 @@ import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
 import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
+import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
 
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
 
 const VALID_MODES = ['lite', 'full'] as const;
-const VALID_MODELS = ['opus', 'sonnet', 'haiku'] as const;
-const VALID_ROLES = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'] as const;
-const VALID_AGENT_TYPES = ['claude', 'gemini', 'cursor', 'windsurf', 'other'] as const;
+// Model, role, and agent_type are now open-ended - any string is accepted
 
 type SessionMode = typeof VALID_MODES[number];
-type SessionModel = typeof VALID_MODELS[number];
-type SessionRole = typeof VALID_ROLES[number];
-type AgentType = typeof VALID_AGENT_TYPES[number];
+type SessionModel = string; // Open-ended - any model name accepted
+type SessionRole = string; // Open-ended - any role name accepted
+type AgentType = string; // Open-ended - any agent type accepted
 
 // Argument schemas for type-safe parsing
 const startWorkSessionSchema = {
 	project_id: { type: 'string' as const },
 	git_url: { type: 'string' as const },
 	mode: { type: 'string' as const, default: 'lite', validate: createEnumValidator(VALID_MODES) },
-	model: { type: 'string' as const, validate: createEnumValidator(VALID_MODELS) },
-	role: { type: 'string' as const, default: 'developer', validate: createEnumValidator(VALID_ROLES) },
+	model: { type: 'string' as const }, // Open-ended - any model name accepted
+	role: { type: 'string' as const, default: 'developer' }, // Open-ended - any role name accepted
 	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
-	agent_type: { type: 'string' as const, validate: createEnumValidator(VALID_AGENT_TYPES) }, // Agent type for onboarding
+	agent_type: { type: 'string' as const }, // Open-ended - any agent type accepted
 };
 
 const heartbeatSchema = {
@@ -62,10 +61,8 @@ export const startWorkSession: Handler = async (args, ctx) => {
 	const { session, updateSession } = ctx;
 
 	// Reset token tracking for new session with model info
+	// Model is now open-ended - use as-is (normalize Claude model names for consistency)
 	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-	const validModel = normalizedModel && VALID_MODELS.includes(normalizedModel as SessionModel)
-		? normalizedModel
-		: null;
 
 	updateSession({
 		tokenUsage: {
@@ -73,7 +70,7 @@ export const startWorkSession: Handler = async (args, ctx) => {
 			totalTokens: 0,
 			byTool: {},
 			byModel: {},
-			currentModel: validModel,
+			currentModel: normalizedModel,
 		},
 	});
 
@@ -396,31 +393,26 @@ export const getHelp: Handler = async (args, _ctx) => {
 	const apiClient = getApiClient();
 	const response = await apiClient.getHelpTopic(topic);
 
-	if (!response.ok) {
-		// If database fetch fails, return error
-		return {
-			result: {
-				error: response.error || `Failed to fetch help topic: ${topic}`,
-			},
-		};
+	// Try database content first
+	if (response.ok && response.data?.content) {
+		return { result: { topic, content: response.data.content } };
 	}
 
-	if (!response.data) {
-		// Topic not found - fetch available topics
-		const topicsResponse = await apiClient.getHelpTopics();
-		const available = topicsResponse.ok && topicsResponse.data
-			? topicsResponse.data.map(t => t.slug)
-			: ['getting_started', 'tasks', 'validation', 'deployment', 'git', 'blockers', 'milestones', 'fallback', 'session', 'tokens', 'sprints', 'topics'];
-
-		return {
-			result: {
-				error: `Unknown topic: ${topic}`,
-				available,
-			},
-		};
+	// Fall back to local content if database is empty or unavailable
+	const fallback = getFallbackHelpContent(topic);
+	if (fallback) {
+		return { result: { topic, content: fallback.content } };
 	}
 
-	return { result: { topic, content: response.data.content } };
+	// Topic not found in either source - show available topics
+	const available = getAvailableHelpTopics();
+
+	return {
+		result: {
+			error: `Unknown topic: ${topic}`,
+			available,
+		},
+	};
 };
 
 // Model pricing rates (USD per 1M tokens) by pricing tier
@@ -572,12 +564,12 @@ export const getTokenUsage: Handler = async (_args, ctx) => {
 const reportTokenUsageSchema = {
 	input_tokens: { type: 'number' as const, required: true as const },
 	output_tokens: { type: 'number' as const, required: true as const },
-	model: { type: 'string' as const, validate: createEnumValidator(VALID_MODELS) },
+	model: { type: 'string' as const }, // Open-ended - any model name accepted
 };
 
 const confirmAgentSetupSchema = {
 	project_id: { type: 'string' as const, required: true as const },
-	agent_type: { type: 'string' as const, required: true as const, validate: createEnumValidator(VALID_AGENT_TYPES) },
+	agent_type: { type: 'string' as const, required: true as const }, // Open-ended - any agent type accepted
 };
 
 /**
@@ -704,7 +696,7 @@ export const confirmAgentSetup: Handler = async (args, _ctx) => {
 	}
 
 	const apiClient = getApiClient();
-	const response = await apiClient.confirmAgentSetup(project_id, agent_type as AgentType);
+	const response = await apiClient.confirmAgentSetup(project_id, agent_type);
 
 	if (!response.ok) {
 		return {

package/src/handlers/validation.ts

@@ -8,6 +8,7 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
+import { error, success } from './types.js';
 import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
@@ -34,10 +35,16 @@ export const getTasksAwaitingValidation: Handler = async (args, _ctx) => {
 	const response = await apiClient.getTasksAwaitingValidation(project_id);
 
 	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to fetch tasks awaiting validation' }, isError: true };
+		return error(response.error || 'Failed to fetch tasks awaiting validation');
 	}
 
-	return { result: response.data };
+	// Check for application-level errors (200 OK but error in body)
+	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+		return error(errMsg);
+	}
+
+	return success(response.data);
 };
 
 export const claimValidation: Handler = async (args, ctx) => {
@@ -50,10 +57,16 @@ export const claimValidation: Handler = async (args, ctx) => {
 	const response = await apiClient.claimValidation(task_id, currentSessionId || undefined);
 
 	if (!response.ok) {
-		return { result: { error: response.error || 'Failed to claim task for validation' }, isError: true };
+		return error(response.error || 'Failed to claim task for validation');
+	}
+
+	// Check for application-level errors (200 OK but error in body)
+	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+		return error(errMsg);
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 export const validateTask: Handler = async (args, ctx) => {
@@ -72,19 +85,22 @@ export const validateTask: Handler = async (args, ctx) => {
 	if (!response.ok) {
 		// Handle PR required error specially
 		if (response.error === 'pr_required') {
-			return {
-				result: {
-					error: 'pr_required',
-					message: response.data?.message || 'A Pull Request is required before validation approval. Create a PR and add it via add_task_reference.',
-					workflow: response.data?.workflow,
-					action_required: 'Create a PR for this task and add it via add_task_reference(task_id, pr_url, label: "Pull Request")',
-				},
-			};
+			return error('pr_required', {
+				message: response.data?.message || 'A Pull Request is required before validation approval. Create a PR and add it via add_task_reference.',
+				workflow: response.data?.workflow,
+				action_required: 'Create a PR for this task and add it via add_task_reference(task_id, pr_url, label: "Pull Request")',
+			});
 		}
-		return { result: { error: response.error || 'Failed to validate task' }, isError: true };
+		return error(response.error || 'Failed to validate task');
+	}
+
+	// Check for application-level errors (200 OK but error in body)
+	if (response.data && typeof response.data === 'object' && 'error' in response.data) {
+		const errMsg = typeof response.data.error === 'string' ? response.data.error : 'Unknown error';
+		return error(errMsg);
 	}
 
-	return { result: response.data };
+	return success(response.data);
 };
 
 /**

package/src/index.ts

@@ -87,8 +87,8 @@ const handlerRegistry = buildHandlerRegistry();
 
 const KNOWLEDGE_BASE: Record<string, string> = {
 	getting_started: `# Getting Started
-1. Call start_work_session(git_url, model: "opus"|"sonnet"|"haiku") to initialize
-   - IMPORTANT: Pass your model for accurate cost tracking
+1. Call start_work_session(git_url, model: "your-model-name") to initialize
+   - IMPORTANT: Pass your model for accurate cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
    - Check your system prompt for "You are powered by the model named..." to find it
 2. Response includes next_task - start working on it immediately
 3. Use update_task to mark in_progress and track progress
@@ -153,7 +153,7 @@ When no tasks available, get_next_task suggests activities:
 
 	session: `# Session Management
 - start_work_session(git_url, model) initializes and returns next_task
-- ALWAYS pass model parameter ("opus", "sonnet", "haiku") for cost tracking
+- ALWAYS pass model parameter for cost tracking (e.g., "opus", "sonnet", "gemini", "gpt-4o")
 - Use mode:'lite' (default) or mode:'full' for complete context
 - heartbeat every 30-60 seconds maintains active status
 - end_work_session releases claimed tasks and returns summary