@vibescope/mcp-server 0.0.1 → 0.1.0

package/dist/handlers/tool-docs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tool Documentation
+ *
+ * This file contains detailed documentation for all MCP tools.
+ * It is loaded dynamically by get_tool_info to reduce memory footprint
+ * when tool documentation is not needed.
+ */
+export declare const TOOL_INFO: Record<string, string>;

package/dist/handlers/tool-docs.js

@@ -0,0 +1,657 @@
+/**
+ * Tool Documentation
+ *
+ * This file contains detailed documentation for all MCP tools.
+ * It is loaded dynamically by get_tool_info to reduce memory footprint
+ * when tool documentation is not needed.
+ */
+export const TOOL_INFO = {
+    start_work_session: `# start_work_session
+Initialize agent session and get assigned work.
+
+**Parameters:**
+- project_id (optional): Project UUID
+- git_url (optional): Git URL to find project
+- mode: 'lite' (default) or 'full' for complete context
+
+**Returns:** session_id, persona, project info, next_task
+
+**Example:** start_work_session(git_url: "https://github.com/org/repo")`,
+    get_help: `# get_help
+Get workflow guidance on specific topics.
+
+**Parameters:**
+- topic (required): One of: getting_started, tasks, validation, deployment, git, blockers, milestones, fallback, session, tokens, topics
+
+**Example:** get_help(topic: "deployment")`,
+    get_token_usage: `# get_token_usage
+Get token usage statistics for current session.
+
+**Returns:** total calls, total tokens, breakdown by tool, averages`,
+    heartbeat: `# heartbeat
+Send heartbeat to maintain active status. Call every 30-60 seconds.
+
+**Parameters:**
+- session_id (optional): Uses current session if not provided`,
+    end_work_session: `# end_work_session
+End session and release claimed tasks.
+
+**Parameters:**
+- session_id (optional): Uses current session if not provided
+
+**Returns:** Session summary with tasks completed, time spent`,
+    get_project_context: `# get_project_context
+Get full project context including goals, instructions, tasks, blockers, decisions.
+
+**Parameters:**
+- project_id (optional): Project UUID
+- git_url (optional): Git URL to find project
+
+Without params, lists all projects.`,
+    get_git_workflow: `# get_git_workflow
+Get git workflow config and branching instructions.
+
+**Parameters:**
+- project_id (required): Project UUID
+- task_id (optional): Include branch naming suggestion
+
+**Returns:** workflow type, branch names, auto-settings`,
+    create_project: `# create_project
+Create a new project to track.
+
+**Parameters:**
+- name (required): Project display name
+- description: Brief description
+- goal: What "done" looks like
+- git_url: Repository URL
+- tech_stack: Array of technologies`,
+    update_project: `# update_project
+Update project settings.
+
+**Parameters:**
+- project_id (required): Project UUID
+- name, description, goal, git_url, tech_stack, status
+- git_workflow: none, trunk-based, github-flow, git-flow
+- git_main_branch, git_develop_branch, git_auto_branch, git_auto_tag`,
+    update_project_readme: `# update_project_readme
+Sync README content to the dashboard.
+
+**Parameters:**
+- project_id (required): Project UUID
+- readme_content (required): Markdown content`,
+    get_tasks: `# get_tasks
+Get tasks for a project.
+
+**Parameters:**
+- project_id (required): Project UUID
+- status (optional): pending, in_progress, completed, cancelled
+- limit (optional): Max tasks (default 50)`,
+    get_next_task: `# get_next_task
+Get highest priority pending task not claimed by another agent.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** task or null, may suggest fallback activity`,
+    add_task: `# add_task
+Create a new task.
+
+**Parameters:**
+- project_id (required): Project UUID
+- title (required): Task title
+- description: Detailed description
+- priority: 1-5 (1=highest, default 3)
+- estimated_minutes: Time estimate`,
+    update_task: `# update_task
+Update task status, progress, or details.
+
+**Parameters:**
+- task_id (required): Task UUID
+- status: pending, in_progress, completed, cancelled
+- progress_percentage: 0-100
+- progress_note: Brief note (auto-logged)
+- title, description, priority, estimated_minutes, git_branch
+
+**Best practice:** Include progress_note with progress_percentage`,
+    complete_task: `# complete_task
+Mark task as done.
+
+**Parameters:**
+- task_id (required): Task UUID
+- summary: What was done
+
+**Returns:** next_task, validation_count, blockers_count, deployment_priority`,
+    delete_task: `# delete_task
+Delete a task.
+
+**Parameters:**
+- task_id (required): Task UUID`,
+    batch_update_tasks: `# batch_update_tasks
+Update multiple tasks at once.
+
+**Parameters:**
+- updates (required): Array of {task_id, status?, progress_percentage?, progress_note?, priority?}`,
+    batch_complete_tasks: `# batch_complete_tasks
+Complete multiple tasks at once.
+
+**Parameters:**
+- completions (required): Array of {task_id, summary?}`,
+    add_task_reference: `# add_task_reference
+Add a reference URL to a task.
+
+**Parameters:**
+- task_id (required): Task UUID
+- url (required): Reference URL
+- label (optional): Display label`,
+    remove_task_reference: `# remove_task_reference
+Remove a reference URL from a task.
+
+**Parameters:**
+- task_id (required): Task UUID
+- url (required): URL to remove`,
+    add_milestone: `# add_milestone
+Add a milestone/step to a task.
+
+**Parameters:**
+- task_id (required): Task UUID
+- title (required): Milestone title
+- description (optional): Details
+- order_index (optional): Position (0-based)`,
+    update_milestone: `# update_milestone
+Update a milestone.
+
+**Parameters:**
+- milestone_id (required): Milestone UUID
+- title, description, status (pending/in_progress/completed), order_index`,
+    complete_milestone: `# complete_milestone
+Mark milestone as completed.
+
+**Parameters:**
+- milestone_id (required): Milestone UUID`,
+    delete_milestone: `# delete_milestone
+Delete a milestone.
+
+**Parameters:**
+- milestone_id (required): Milestone UUID`,
+    get_milestones: `# get_milestones
+Get all milestones for a task.
+
+**Parameters:**
+- task_id (required): Task UUID`,
+    log_progress: `# log_progress
+Record a progress update.
+
+**Parameters:**
+- project_id (required): Project UUID
+- summary (required): Brief summary
+- task_id (optional): Link to task
+- details (optional): Extended notes`,
+    get_activity_feed: `# get_activity_feed
+Get combined activity feed.
+
+**Parameters:**
+- project_id (required): Project UUID
+- types (optional): Array of task, progress, blocker, decision
+- created_by (optional): agent or user
+- since (optional): ISO date string
+- limit (optional): Max items (default 50)`,
+    add_blocker: `# add_blocker
+Record a blocker preventing progress.
+
+**Parameters:**
+- project_id (required): Project UUID
+- description (required): What is blocking`,
+    resolve_blocker: `# resolve_blocker
+Mark a blocker as resolved.
+
+**Parameters:**
+- blocker_id (required): Blocker UUID
+- resolution_note (optional): How it was resolved`,
+    get_blockers: `# get_blockers
+Get blockers for a project.
+
+**Parameters:**
+- project_id (required): Project UUID
+- status (optional): open or resolved (default: open)`,
+    delete_blocker: `# delete_blocker
+Delete a blocker.
+
+**Parameters:**
+- blocker_id (required): Blocker UUID`,
+    log_decision: `# log_decision
+Record an architectural decision.
+
+**Parameters:**
+- project_id (required): Project UUID
+- title (required): Decision title
+- description (required): What was decided
+- rationale (optional): Why
+- alternatives_considered (optional): Array of alternatives`,
+    get_decisions: `# get_decisions
+Get recorded decisions.
+
+**Parameters:**
+- project_id (required): Project UUID`,
+    delete_decision: `# delete_decision
+Delete a decision.
+
+**Parameters:**
+- decision_id (required): Decision UUID`,
+    add_idea: `# add_idea
+Record an improvement idea.
+
+**Parameters:**
+- project_id (required): Project UUID
+- title (required): Idea title
+- description (optional): Details
+- status (optional): raw, exploring, planned, in_development, shipped`,
+    update_idea: `# update_idea
+Update an idea.
+
+**Parameters:**
+- idea_id (required): Idea UUID
+- title, description, status, doc_url`,
+    get_ideas: `# get_ideas
+Get recorded ideas.
+
+**Parameters:**
+- project_id (required): Project UUID
+- status (optional): Filter by status`,
+    delete_idea: `# delete_idea
+Delete an idea.
+
+**Parameters:**
+- idea_id (required): Idea UUID`,
+    convert_idea_to_task: `# convert_idea_to_task
+Convert an idea to a task. Creates a new task from the idea's title and description.
+
+**Parameters:**
+- idea_id (required): Idea UUID to convert
+- priority (optional): Task priority 1-5 (default: 3)
+- estimated_minutes (optional): Estimated time
+- update_status (optional): Update idea to 'in_development' (default: true)
+
+**Returns:**
+- task_id: Created task UUID
+- Links idea and task together`,
+    add_finding: `# add_finding
+Record an audit/review finding.
+
+**Parameters:**
+- project_id (required): Project UUID
+- title (required): Finding title
+- category: performance, security, code_quality, accessibility, documentation, architecture, testing, other
+- description: Details with impact and suggested fix
+- severity: info, low, medium, high, critical
+- file_path, line_number, related_task_id (optional)`,
+    get_findings: `# get_findings
+Get audit findings.
+
+**Parameters:**
+- project_id (required): Project UUID
+- category, severity, status (optional filters)
+- limit (optional): Max items`,
+    update_finding: `# update_finding
+Update a finding.
+
+**Parameters:**
+- finding_id (required): Finding UUID
+- status: open, addressed, dismissed, wontfix
+- resolution_note, title, description, severity`,
+    delete_finding: `# delete_finding
+Delete a finding.
+
+**Parameters:**
+- finding_id (required): Finding UUID`,
+    get_tasks_awaiting_validation: `# get_tasks_awaiting_validation
+Get completed tasks needing validation.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Tasks with reviewing status (who's reviewing, when started)`,
+    claim_validation: `# claim_validation
+Claim a completed task for review. Shows "being reviewed" on dashboard.
+
+**Parameters:**
+- task_id (required): Task UUID to claim
+
+**Note:** Claim before reviewing to prevent duplicate work.`,
+    validate_task: `# validate_task
+Validate a completed task.
+
+**Parameters:**
+- task_id (required): Task UUID
+- approved (required): true/false
+- validation_notes: What was checked, issues found`,
+    request_deployment: `# request_deployment
+Request a deployment.
+
+**Parameters:**
+- project_id (required): Project UUID
+- environment: development, staging, production
+- version_bump: patch, minor, major
+- notes, git_ref (optional)`,
+    claim_deployment_validation: `# claim_deployment_validation
+Claim pending deployment for validation.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+Next: Run build+tests, then call report_validation`,
+    report_validation: `# report_validation
+Report build/test results.
+
+**Parameters:**
+- project_id (required): Project UUID
+- build_passed (required): boolean
+- tests_passed (required): boolean
+- error_message (if failed)`,
+    check_deployment_status: `# check_deployment_status
+Get active deployment status.
+
+**Parameters:**
+- project_id (required): Project UUID`,
+    start_deployment: `# start_deployment
+Start deployment (requires 'ready' status).
+
+**Parameters:**
+- project_id (required): Project UUID`,
+    complete_deployment: `# complete_deployment
+Mark deployment complete.
+
+**Parameters:**
+- project_id (required): Project UUID
+- success (required): boolean
+- summary: What was deployed or why failed`,
+    cancel_deployment: `# cancel_deployment
+Cancel active deployment.
+
+**Parameters:**
+- project_id (required): Project UUID
+- reason (optional): Why cancelled`,
+    schedule_deployment: `# schedule_deployment
+Schedule a deployment for a specific time.
+
+**Parameters:**
+- project_id (required): Project UUID
+- scheduled_at (required): ISO 8601 datetime
+- schedule_type (optional): once, daily, weekly, monthly (default: once)
+- auto_trigger (optional): Whether agents auto-trigger (default: true)
+- environment (optional): development, staging, production (default: production)
+- version_bump (optional): patch, minor, major (default: patch)
+- notes (optional): Notes about the deployment
+- git_ref (optional): Git branch or commit
+
+**Example:** schedule_deployment(project_id, scheduled_at: "2025-01-15T10:00:00Z", schedule_type: "weekly")`,
+    get_scheduled_deployments: `# get_scheduled_deployments
+List scheduled deployments for a project.
+
+**Parameters:**
+- project_id (required): Project UUID
+- include_disabled (optional): Include disabled schedules (default: false)`,
+    update_scheduled_deployment: `# update_scheduled_deployment
+Update a scheduled deployment's configuration.
+
+**Parameters:**
+- schedule_id (required): Schedule UUID
+- scheduled_at (optional): New scheduled time
+- schedule_type (optional): once, daily, weekly, monthly
+- auto_trigger (optional): Whether to auto-trigger
+- enabled (optional): Enable or disable
+- environment, version_bump, notes, git_ref (optional)`,
+    delete_scheduled_deployment: `# delete_scheduled_deployment
+Delete a scheduled deployment.
+
+**Parameters:**
+- schedule_id (required): Schedule UUID`,
+    trigger_scheduled_deployment: `# trigger_scheduled_deployment
+Manually trigger a scheduled deployment.
+
+Creates a new deployment using the schedule's configuration.
+Updates schedule: last_triggered_at, trigger_count, next scheduled_at (for recurring).
+
+**Parameters:**
+- schedule_id (required): Schedule UUID`,
+    check_due_deployments: `# check_due_deployments
+Check for scheduled deployments that are due.
+
+Returns schedules where: enabled AND auto_trigger AND scheduled_at <= NOW()
+
+Use this to find deployments to trigger when working on a project.
+
+**Parameters:**
+- project_id (required): Project UUID`,
+    start_fallback_activity: `# start_fallback_activity
+Start background activity when no tasks.
+
+**Parameters:**
+- project_id (required): Project UUID
+- activity (required): feature_ideation, code_review, performance_audit, ux_review, cost_analysis, security_review, test_coverage, documentation_review, dependency_audit, validate_completed_tasks`,
+    stop_fallback_activity: `# stop_fallback_activity
+Stop current fallback activity.
+
+**Parameters:**
+- project_id (required): Project UUID
+- summary (optional): What was accomplished`,
+    get_activity_history: `# get_activity_history
+Get background activity history.
+
+**Parameters:**
+- project_id (required): Project UUID
+- activity_type (optional): Filter by type
+- limit (optional): Max items`,
+    get_activity_schedules: `# get_activity_schedules
+Get activity schedules.
+
+**Parameters:**
+- project_id (required): Project UUID`,
+    get_pending_requests: `# get_pending_requests
+Get unacknowledged user requests.
+
+**Parameters:**
+- project_id (required): Project UUID`,
+    acknowledge_request: `# acknowledge_request
+Mark a request as handled.
+
+**Parameters:**
+- request_id (required): Request UUID`,
+    answer_question: `# answer_question
+Answer a user question from dashboard.
+
+**Parameters:**
+- request_id (required): Request UUID
+- answer (required): Your answer`,
+    discover_tools: `# discover_tools
+List available tools by category.
+
+**Parameters:**
+- category (optional): Filter to specific category
+
+Without category, returns all categories with tool counts.
+With category, returns tools in that category with brief descriptions.`,
+    get_tool_info: `# get_tool_info
+Get detailed info for a specific tool.
+
+**Parameters:**
+- tool_name (required): Name of the tool
+
+Returns: full documentation, parameters, examples, best practices.`,
+    // Organization tools
+    list_organizations: `# list_organizations
+List organizations the current user belongs to.
+
+**Parameters:** None
+
+**Returns:** Array of organizations with role and joined_at`,
+    create_organization: `# create_organization
+Create a new organization. You become the owner.
+
+**Parameters:**
+- name (required): Organization display name
+- description (optional): Brief description
+- slug (optional): URL-friendly identifier (auto-generated if not provided)
+
+**Example:** create_organization(name: "Acme Corp", description: "Our development team")`,
+    update_organization: `# update_organization
+Update organization details. Requires admin role.
+
+**Parameters:**
+- organization_id (required): Organization UUID
+- name, description, logo_url (optional updates)`,
+    delete_organization: `# delete_organization
+Delete an organization. Requires owner role. Removes all shares.
+
+**Parameters:**
+- organization_id (required): Organization UUID
+
+**Warning:** This will remove all project shares with this organization.`,
+    list_org_members: `# list_org_members
+List members of an organization.
+
+**Parameters:**
+- organization_id (required): Organization UUID
+
+**Returns:** Array of members with role and joined_at`,
+    invite_member: `# invite_member
+Invite a user to an organization by email. Requires admin role.
+
+**Parameters:**
+- organization_id (required): Organization UUID
+- email (required): Email address to invite
+- role (optional): admin, member, or viewer (default: member)
+
+**Returns:** Invite details with token`,
+    update_member_role: `# update_member_role
+Change a member's role. Requires admin role.
+
+**Parameters:**
+- organization_id (required): Organization UUID
+- user_id (required): User UUID to update
+- role (required): admin, member, or viewer
+
+**Note:** Cannot change your own role or the owner's role.`,
+    remove_member: `# remove_member
+Remove a member from an organization. Requires admin role.
+
+**Parameters:**
+- organization_id (required): Organization UUID
+- user_id (required): User UUID to remove
+
+**Note:** Cannot remove the owner. Their org-scoped API keys are invalidated.`,
+    leave_organization: `# leave_organization
+Leave an organization.
+
+**Parameters:**
+- organization_id (required): Organization UUID
+
+**Note:** Owner cannot leave. Must transfer ownership or delete organization.`,
+    share_project_with_org: `# share_project_with_org
+Share a project with an organization. You must own the project.
+
+**Parameters:**
+- project_id (required): Project UUID
+- organization_id (required): Organization UUID to share with
+- permission (optional): read, write, or admin (default: read)
+
+**Permission levels:**
+- read: View project and tasks
+- write: Add/update tasks, log progress
+- admin: All write permissions plus deployments`,
+    update_project_share: `# update_project_share
+Update the permission level for a project share.
+
+**Parameters:**
+- project_id (required): Project UUID
+- organization_id (required): Organization UUID
+- permission (required): read, write, or admin`,
+    unshare_project: `# unshare_project
+Remove a project share from an organization.
+
+**Parameters:**
+- project_id (required): Project UUID
+- organization_id (required): Organization UUID
+
+**Note:** Org members will lose access immediately.`,
+    list_project_shares: `# list_project_shares
+List all organizations a project is shared with.
+
+**Parameters:**
+- project_id (required): Project UUID
+
+**Returns:** Array of shares with organization info and permission level`,
+    // Cost monitoring tools
+    get_cost_summary: `# get_cost_summary
+Get cost summary (daily/weekly/monthly) for a project.
+
+**Parameters:**
+- project_id (required): Project UUID
+- period: 'daily' | 'weekly' | 'monthly' (default: daily)
+- limit: Max records to return (default: 30)
+
+**Returns:** Cost summary with totals and breakdown by model`,
+    get_cost_alerts: `# get_cost_alerts
+Get cost alerts for the current user.
+
+**Parameters:**
+- project_id (optional): Filter by project
+
+**Returns:** Array of configured cost alerts`,
+    add_cost_alert: `# add_cost_alert
+Add a cost threshold alert.
+
+**Parameters:**
+- project_id (optional): Specific project or null for all
+- threshold_amount (required): Amount in USD
+- threshold_period (required): 'daily' | 'weekly' | 'monthly'
+- alert_type: 'warning' | 'critical' (default: warning)
+
+**Example:** add_cost_alert(threshold_amount: 50, threshold_period: "daily", alert_type: "warning")`,
+    update_cost_alert: `# update_cost_alert
+Update an existing cost alert.
+
+**Parameters:**
+- alert_id (required): Alert UUID
+- threshold_amount: New amount in USD
+- threshold_period: New period
+- alert_type: New alert type
+- enabled: Enable/disable the alert`,
+    delete_cost_alert: `# delete_cost_alert
+Delete a cost alert.
+
+**Parameters:**
+- alert_id (required): Alert UUID to delete`,
+    get_task_costs: `# get_task_costs
+Get cost breakdown by task for a project.
+
+**Parameters:**
+- project_id (required): Project UUID
+- limit: Max tasks to return (default: 20)
+
+**Returns:** Tasks sorted by estimated cost with model breakdown`,
+    // Knowledge base tools
+    query_knowledge_base: `# query_knowledge_base
+Query aggregated project knowledge in a single call. Reduces token usage by combining multiple data sources.
+
+**Parameters:**
+- project_id (required): Project UUID
+- scope: 'summary' (default) or 'detailed' (includes rationales, descriptions)
+- categories: Array of categories to include (default: all)
+  - findings: Audit findings (security, performance, code quality)
+  - qa: Questions and answers
+  - decisions: Architectural decisions
+  - completed_tasks: Tasks with completion summaries
+  - blockers: Resolved blockers with resolution notes
+  - progress: Recent progress logs
+- limit: Max items per category (default: 5, max: 20)
+- search_query: Optional text search across all knowledge
+
+**Returns:**
+- project: name, goal, tech_stack
+- stats: counts for each category, findings by severity
+- Category data based on selection
+
+**Token savings:** Replaces up to 6 separate tool calls (get_findings, get_decisions, get_tasks, get_blockers, etc.) with one call.
+
+**Example:** query_knowledge_base(project_id, categories: ["findings", "decisions"], limit: 10)`,
+};

package/dist/handlers/types.d.ts

@@ -1,4 +1,3 @@
-import type { SupabaseClient } from '@supabase/supabase-js';
 /**
  * Authentication context from API key validation
  */
@@ -28,6 +27,15 @@ export interface TokenUsage {
     byModel: Record<string, ModelTokens>;
     currentModel: string | null;
 }
+/**
+ * Agent role for specialized work routing
+ * - developer: General development work, picks up any available task (default)
+ * - validator: Focuses on validating completed tasks
+ * - deployer: Handles deployment coordination and monitoring
+ * - reviewer: Code review and quality checks
+ * - maintainer: Task management, git orchestration, housekeeping
+ */
+export type AgentRole = 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
 /**
  * Session state that persists across tool calls
  */
@@ -35,6 +43,7 @@ export interface SessionState {
     instanceId: string;
     currentSessionId: string | null;
     currentPersona: string | null;
+    currentRole: AgentRole | null;
     tokenUsage: TokenUsage;
 }
 /**
@@ -61,11 +70,10 @@ export interface UserUpdates {
  * Context passed to all handlers
  */
 export interface HandlerContext {
-    supabase: SupabaseClient;
     auth: AuthContext;
     session: SessionState;
     /** Update session state (for handlers that modify session) */
-    updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'tokenUsage'>>) => void;
+    updateSession: (updates: Partial<Pick<SessionState, 'currentSessionId' | 'currentPersona' | 'currentRole' | 'tokenUsage'>>) => void;
     /** Get user updates since last sync (for session handlers) */
     getUserUpdates?: (projectId: string) => Promise<UserUpdates | undefined>;
     /** Select an available persona for the agent */

package/dist/handlers/validation.d.ts

@@ -1,5 +1,5 @@
 /**
- * Validation Handlers
+ * Validation Handlers (Migrated to API Client)
  *
  * Handles cross-agent task validation:
  * - get_tasks_awaiting_validation