@vibescope/mcp-server 0.3.0 → 0.3.3

package/dist/tools/project.js

@@ -0,0 +1,199 @@
+/**
+ * Project Tool Definitions
+ *
+ * Tools for project management:
+ * - get_project_context
+ * - get_git_workflow
+ * - create_project
+ * - update_project
+ * - update_project_readme
+ * - get_project_summary
+ */
+export const projectTools = [
+    {
+        name: 'get_project_context',
+        description: 'Get full project context: goals, instructions, tasks, blockers, decisions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID. If not provided, will list all projects.',
+                },
+                git_url: {
+                    type: 'string',
+                    description: 'Git repository URL. Used to find project if project_id not provided.',
+                },
+            },
+        },
+    },
+    {
+        name: 'get_git_workflow',
+        description: 'Get git workflow config and branching instructions for the project.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                task_id: {
+                    type: 'string',
+                    description: 'Optional task ID to include branch naming suggestion',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'create_project',
+        description: 'Create a new project to track in Vibescope.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Project display name',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Brief project description',
+                },
+                goal: {
+                    type: 'string',
+                    description: 'What does "done" look like for this project?',
+                },
+                git_url: {
+                    type: 'string',
+                    description: 'Git repository URL (if available)',
+                },
+                tech_stack: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Technologies used (e.g., ["TypeScript", "React", "PostgreSQL"])',
+                },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'update_project',
+        description: 'Update project details (name, description, goal, settings).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                name: { type: 'string', description: 'Project name' },
+                description: { type: 'string', description: 'Project description' },
+                goal: { type: 'string', description: 'Project goal or objective' },
+                git_url: { type: 'string', description: 'Git repository URL' },
+                tech_stack: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'List of technologies used in the project',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'paused', 'completed', 'archived'],
+                    description: 'Project status',
+                },
+                git_workflow: {
+                    type: 'string',
+                    enum: ['none', 'trunk-based', 'github-flow', 'git-flow'],
+                    description: 'Git workflow: none (no branching), trunk-based (commit to main), github-flow (feature branches + PR), git-flow (develop/release branches)',
+                },
+                git_main_branch: {
+                    type: 'string',
+                    description: 'Main branch name (default: main)',
+                },
+                git_develop_branch: {
+                    type: 'string',
+                    description: 'Development branch name (used with git-flow)',
+                },
+                git_auto_branch: {
+                    type: 'boolean',
+                    description: 'Automatically create feature branches for new tasks',
+                },
+                git_auto_tag: {
+                    type: 'boolean',
+                    description: 'Automatically tag deployments on main branch',
+                },
+                deployment_instructions: {
+                    type: 'string',
+                    description: 'Instructions for how to deploy (e.g., "Push to main for Vercel auto-deploy", "Run fly deploy")',
+                },
+                git_delete_branch_on_merge: {
+                    type: 'boolean',
+                    description: 'Delete feature branch after PR merge (default: true)',
+                },
+                require_pr_for_validation: {
+                    type: 'boolean',
+                    description: 'Require PR exists before task validation can be approved (default: true for github-flow/git-flow)',
+                },
+                auto_merge_on_approval: {
+                    type: 'boolean',
+                    description: 'Automatically merge PR when validator approves (default: true)',
+                },
+                validation_required: {
+                    type: 'boolean',
+                    description: 'Completed tasks require validation before being considered done (default: true)',
+                },
+                default_task_priority: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 5,
+                    description: 'Default priority for new tasks when not specified (1=highest, 5=lowest, default: 3)',
+                },
+                require_time_estimates: {
+                    type: 'boolean',
+                    description: 'Require estimated_minutes when creating tasks (default: false)',
+                },
+                fallback_activities_enabled: {
+                    type: 'boolean',
+                    description: 'Allow agents to perform background activities when no tasks available (default: true)',
+                },
+                preferred_fallback_activities: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of preferred fallback activities (e.g., ["code_review", "security_review"]). Null means all allowed.',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'update_project_readme',
+        description: 'Sync README content to the dashboard.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                readme_content: {
+                    type: 'string',
+                    description: 'README content in markdown format',
+                },
+            },
+            required: ['project_id', 'readme_content'],
+        },
+    },
+    {
+        name: 'get_project_summary',
+        description: 'Get a unified project overview with aggregated stats. Token-efficient way to get task counts, blockers, findings, active agents, and more in a single call.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+];

package/dist/tools/requests.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Request Tool Definitions
+ *
+ * Tools for handling user requests:
+ * - get_pending_requests
+ * - acknowledge_request
+ * - answer_question
+ */
+import type { Tool } from './types.js';
+export declare const requestTools: Tool[];

package/dist/tools/requests.js

@@ -0,0 +1,65 @@
+/**
+ * Request Tool Definitions
+ *
+ * Tools for handling user requests:
+ * - get_pending_requests
+ * - acknowledge_request
+ * - answer_question
+ */
+export const requestTools = [
+    {
+        name: 'get_pending_requests',
+        description: `Get unacknowledged user requests for this agent/project.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max number of requests to return (default 50, max 200)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of requests to skip for pagination (default 0)',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'acknowledge_request',
+        description: `Mark a user request as handled.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                request_id: {
+                    type: 'string',
+                    description: 'Request UUID to acknowledge',
+                },
+            },
+            required: ['request_id'],
+        },
+    },
+    {
+        name: 'answer_question',
+        description: `Answer a question from the user. Use this when the user has asked a question via the dashboard.
+The answer will be displayed to the user and the question marked as answered.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                request_id: {
+                    type: 'string',
+                    description: 'Request UUID of the question to answer',
+                },
+                answer: {
+                    type: 'string',
+                    description: 'Your answer to the user\'s question',
+                },
+            },
+            required: ['request_id', 'answer'],
+        },
+    },
+];

package/dist/tools/roles.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Role Tool Definitions
+ *
+ * Tools for managing agent roles:
+ * - get_role_settings
+ * - update_role_settings
+ * - set_session_role
+ * - get_agents_by_role
+ */
+import type { Tool } from './types.js';
+export declare const roleTools: Tool[];

package/dist/tools/roles.js

@@ -0,0 +1,109 @@
+/**
+ * Role Tool Definitions
+ *
+ * Tools for managing agent roles:
+ * - get_role_settings
+ * - update_role_settings
+ * - set_session_role
+ * - get_agents_by_role
+ */
+export const roleTools = [
+    {
+        name: 'get_role_settings',
+        description: 'Get role configuration for a project. Shows available roles and their settings.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+    {
+        name: 'update_role_settings',
+        description: 'Update role settings for a project. Configure which roles are enabled and their behavior.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                role: {
+                    type: 'string',
+                    description: 'Role to configure (e.g., "developer", "validator", "deployer"). Custom roles accepted.',
+                },
+                enabled: {
+                    type: 'boolean',
+                    description: 'Enable or disable this role',
+                },
+                display_name: {
+                    type: 'string',
+                    description: 'Custom display name for this role',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Description of what this role does',
+                },
+                priority_filter: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Only show tasks with these priorities (1-5)',
+                },
+                fallback_activities: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Preferred fallback activities for this role',
+                },
+                auto_assign_validation: {
+                    type: 'boolean',
+                    description: 'Auto-assign validation tasks to agents with this role',
+                },
+                auto_assign_deployment: {
+                    type: 'boolean',
+                    description: 'Auto-assign deployment tasks to agents with this role',
+                },
+            },
+            required: ['project_id', 'role'],
+        },
+    },
+    {
+        name: 'set_session_role',
+        description: 'Set the role for your current session. Changes task filtering and fallback activity suggestions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                role: {
+                    type: 'string',
+                    description: 'Role to assign to this session (e.g., "developer", "validator", "deployer"). Custom roles accepted.',
+                },
+                role_config: {
+                    type: 'object',
+                    description: 'Custom configuration for specialist role (optional)',
+                },
+            },
+            required: ['role'],
+        },
+    },
+    {
+        name: 'get_agents_by_role',
+        description: 'Get active agents grouped by their assigned roles. See who is working on what.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                counts_only: {
+                    type: 'boolean',
+                    description: 'When true (default), returns only counts per role to save tokens. Set to false for full agent details.',
+                },
+            },
+            required: ['project_id'],
+        },
+    },
+];

package/dist/tools/session.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Session Tool Definitions
+ *
+ * Tools for managing agent work sessions:
+ * - start_work_session
+ * - confirm_agent_setup
+ * - get_help
+ * - get_token_usage
+ * - report_token_usage
+ * - heartbeat
+ * - end_work_session
+ * - signal_idle
+ */
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const sessionTools: Tool[];

package/dist/tools/session.js

@@ -0,0 +1,178 @@
+/**
+ * Session Tool Definitions
+ *
+ * Tools for managing agent work sessions:
+ * - start_work_session
+ * - confirm_agent_setup
+ * - get_help
+ * - get_token_usage
+ * - report_token_usage
+ * - heartbeat
+ * - end_work_session
+ * - signal_idle
+ */
+export const sessionTools = [
+    {
+        name: 'start_work_session',
+        description: `CALL THIS FIRST when beginning work on a project.
+Returns session info, persona, role, and next_task. Start the next_task IMMEDIATELY without asking the user.
+
+IMPORTANT: If the user gives you direct work that isn't tracked as a task (e.g., "add feature X", "fix bug Y"), you MUST call add_task() first to create a task before starting work. This ensures all work is tracked and visible on the dashboard.
+
+Use mode:'full' for complete context, mode:'lite' (default) for minimal tokens.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                git_url: {
+                    type: 'string',
+                    description: 'Git repository URL. Used to find project if project_id not provided.',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['lite', 'full'],
+                    description: 'Response mode: lite (default, minimal tokens) or full (complete context)',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Model being used for cost tracking. E.g., "opus", "sonnet", "haiku" for Claude, "gemini" for Gemini, "gpt-4o" for OpenAI.',
+                },
+                role: {
+                    type: 'string',
+                    description: 'Agent role (e.g., "developer", "validator", "deployer", "reviewer", "maintainer"). Custom roles accepted.',
+                },
+                hostname: {
+                    type: 'string',
+                    description: 'Machine hostname for worktree tracking. Pass os.hostname() to filter stale worktrees to only those created on this machine.',
+                },
+                agent_type: {
+                    type: 'string',
+                    description: 'Agent type (e.g., "claude", "gemini", "cursor", "windsurf"). Custom agent types accepted.',
+                },
+                agent_name: {
+                    type: 'string',
+                    description: 'Explicit agent name (for cloud/remote agents). If provided, uses this name instead of selecting from persona pool. Cloud agents should pass their spawner-assigned name.',
+                },
+            },
+        },
+    },
+    {
+        name: 'confirm_agent_setup',
+        description: `Confirm that agent setup is complete for this project. Call this after creating your agent's configuration file (e.g., .claude/CLAUDE.md, .gemini/GEMINI.md).
+
+This marks your agent type as fully onboarded to the project, so you won't receive setup instructions again.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'string',
+                    description: 'Project UUID',
+                },
+                agent_type: {
+                    type: 'string',
+                    description: 'Agent type that completed setup (e.g., "claude", "gemini", "cursor"). Custom agent types accepted.',
+                },
+            },
+            required: ['project_id', 'agent_type'],
+        },
+    },
+    {
+        name: 'get_help',
+        description: 'Get guidance on a specific topic. Use when unsure about workflows.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    enum: ['getting_started', 'tasks', 'validation', 'deployment', 'git', 'blockers', 'milestones', 'fallback', 'session', 'tokens', 'roles', 'knowledge', 'topics'],
+                    description: 'Help topic. Use "topics" to list all available.',
+                },
+            },
+            required: ['topic'],
+        },
+    },
+    {
+        name: 'get_token_usage',
+        description: 'Get token usage stats for this session. Monitor efficiency.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'report_token_usage',
+        description: `Report actual Claude API token usage for accurate cost tracking.
+
+IMPORTANT: MCP can only estimate tokens from tool I/O (~1-5% of actual usage). Call this tool after each API response to report actual usage from the Claude API response headers.
+
+The Claude API response includes 'usage.input_tokens' and 'usage.output_tokens' - pass those values here for accurate cost attribution.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                input_tokens: {
+                    type: 'number',
+                    description: 'Input tokens from Claude API response (usage.input_tokens)',
+                },
+                output_tokens: {
+                    type: 'number',
+                    description: 'Output tokens from Claude API response (usage.output_tokens)',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Model used for this API call (optional, uses session model if not provided)',
+                },
+            },
+            required: ['input_tokens', 'output_tokens'],
+        },
+    },
+    {
+        name: 'heartbeat',
+        description: `Send heartbeat to maintain 'active' status. Call every 30-60 seconds.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: {
+                    type: 'string',
+                    description: 'Session ID from start_work_session (optional, uses current session if not provided)',
+                },
+                current_worktree_path: {
+                    type: ['string', 'null'],
+                    description: 'Report your current git worktree path (e.g., "../project-task-abc123"). Set to null to clear.',
+                },
+                hostname: {
+                    type: 'string',
+                    description: 'Machine hostname (os.hostname()). Updates session hostname for worktree tracking.',
+                },
+            },
+        },
+    },
+    {
+        name: 'end_work_session',
+        description: `End session and release claimed tasks. Returns session summary.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: {
+                    type: 'string',
+                    description: 'Session ID to end (optional, uses current session if not provided)',
+                },
+            },
+        },
+    },
+    {
+        name: 'signal_idle',
+        description: `Signal that agent is idle (no more tasks). Call this when complete_task returns no next_task or when there's no work available. This provides real-time visibility on the dashboard instead of waiting for heartbeat timeout.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: {
+                    type: 'string',
+                    description: 'Session ID (optional, uses current session if not provided)',
+                },
+            },
+        },
+    },
+];

package/dist/tools/sprints.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Sprint Tool Definitions
+ *
+ * Tools for managing sprints with velocity tracking:
+ * - create_sprint
+ * - update_sprint
+ * - get_sprint
+ * - get_sprints
+ * - delete_sprint
+ * - start_sprint
+ * - complete_sprint
+ * - add_task_to_sprint
+ * - remove_task_from_sprint
+ * - get_sprint_backlog
+ * - get_sprint_velocity
+ */
+import type { Tool } from './types.js';
+export declare const sprintTools: Tool[];