@vibescope/mcp-server 0.2.5 → 0.2.7

package/dist/index.js

@@ -40,89 +40,89 @@ const handlerRegistry = buildHandlerRegistry();
 // Embedded Knowledge Base (on-demand help topics)
 // ============================================================================
 const KNOWLEDGE_BASE = {
-    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
-   - 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
-4. Call complete_task when done - it returns your next task
+    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
+   - 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
+4. Call complete_task when done - it returns your next task
 5. Use get_help(topic) when you need guidance on specific workflows`,
-    tasks: `# Task Workflow
-- Mark task in_progress with update_task before starting
-- Update progress_percentage regularly (every 15-20% progress)
-- Include progress_note to auto-log milestones
-- One task at a time - complete current before starting another
-- complete_task returns next_task and context counts (validation, blockers, deployment)
+    tasks: `# Task Workflow
+- Mark task in_progress with update_task before starting
+- Update progress_percentage regularly (every 15-20% progress)
+- Include progress_note to auto-log milestones
+- One task at a time - complete current before starting another
+- complete_task returns next_task and context counts (validation, blockers, deployment)
 - Priority: 1=highest, 5=lowest`,
-    validation: `# Task Validation
-Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
-1. Check: get_tasks_awaiting_validation(project_id)
-2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
-3. Review code changes and run tests
-4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
+    validation: `# Task Validation
+Completed tasks need validation before deployment. PRIORITIZE validation over new tasks.
+1. Check: get_tasks_awaiting_validation(project_id)
+2. Claim: claim_validation(task_id) - marks "being reviewed" on dashboard
+3. Review code changes and run tests
+4. Complete: validate_task(task_id, approved: true/false, validation_notes: "...")
 Self-validation allowed when single-agent or to unblock deployment.`,
-    deployment: `# Deployment Workflow
-1. Ensure all completed tasks are validated first
-2. request_deployment(project_id, environment: "production")
-3. claim_deployment_validation(project_id) - claim for validation
-4. Run: pnpm build && pnpm test
-5. report_validation(project_id, build_passed: true, tests_passed: true)
-6. start_deployment(project_id) - returns project's deployment_instructions
-7. Follow the instructions (e.g., push to main, run deploy command)
+    deployment: `# Deployment Workflow
+1. Ensure all completed tasks are validated first
+2. request_deployment(project_id, environment: "production")
+3. claim_deployment_validation(project_id) - claim for validation
+4. Run: pnpm build && pnpm test
+5. report_validation(project_id, build_passed: true, tests_passed: true)
+6. start_deployment(project_id) - returns project's deployment_instructions
+7. Follow the instructions (e.g., push to main, run deploy command)
 8. complete_deployment(project_id, success: true, summary: "...")`,
-    git: `# Git Workflow
-Call get_git_workflow(project_id) for project-specific config.
-Workflows: none, trunk-based, github-flow, git-flow
-- trunk-based: commit directly to main
-- github-flow: feature branches, merge via PR
-- git-flow: develop/release branches
+    git: `# Git Workflow
+Call get_git_workflow(project_id) for project-specific config.
+Workflows: none, trunk-based, github-flow, git-flow
+- trunk-based: commit directly to main
+- github-flow: feature branches, merge via PR
+- git-flow: develop/release branches
 Update task git_branch when working on a branch.`,
-    blockers: `# Working with Blockers
-When stuck and need human input:
-1. add_blocker(project_id, description: "What's blocking")
-2. Ask your question to the user
-3. resolve_blocker(blocker_id, resolution_note: "How resolved")
+    blockers: `# Working with Blockers
+When stuck and need human input:
+1. add_blocker(project_id, description: "What's blocking")
+2. Ask your question to the user
+3. resolve_blocker(blocker_id, resolution_note: "How resolved")
 Only use for genuine blockers requiring decisions - not routine questions.`,
-    milestones: `# Task Milestones
-For complex tasks, break into milestones:
-1. add_milestone(task_id, title: "Design schema")
-2. add_milestone(task_id, title: "Implement API")
-3. Update with complete_milestone(milestone_id) as you go
+    milestones: `# Task Milestones
+For complex tasks, break into milestones:
+1. add_milestone(task_id, title: "Design schema")
+2. add_milestone(task_id, title: "Implement API")
+3. Update with complete_milestone(milestone_id) as you go
 Dashboard shows progress bar with completed/total.`,
-    fallback: `# Fallback Activities
-When no tasks available, get_next_task suggests activities:
-- feature_ideation, code_review, performance_audit
-- security_review, test_coverage, documentation_review
-1. start_fallback_activity(project_id, activity: "code_review")
-2. Do the work, use add_finding for issues, add_idea for improvements
+    fallback: `# Fallback Activities
+When no tasks available, get_next_task suggests activities:
+- feature_ideation, code_review, performance_audit
+- security_review, test_coverage, documentation_review
+1. start_fallback_activity(project_id, activity: "code_review")
+2. Do the work, use add_finding for issues, add_idea for improvements
 3. stop_fallback_activity(project_id, summary: "...")`,
-    session: `# Session Management
-- start_work_session(git_url, model) initializes and returns next_task
-- ALWAYS pass model parameter ("opus", "sonnet", "haiku") for cost tracking
-- 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
-- NEVER STOP: After completing a task, immediately start the next one
-- When context grows large: /clear then start_work_session to continue fresh
+    session: `# Session Management
+- start_work_session(git_url, model) initializes and returns next_task
+- ALWAYS pass model parameter ("opus", "sonnet", "haiku") for cost tracking
+- 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
+- NEVER STOP: After completing a task, immediately start the next one
+- When context grows large: /clear then start_work_session to continue fresh
 - Your progress is saved to the dashboard - nothing is lost on /clear`,
-    tokens: `# Token Efficiency
-Be mindful of token costs - every tool call has a cost.
-- Use mode:'lite' (default) - saves ~85% vs full mode
-- Call get_token_usage() to check consumption
-- /compact when context grows large
-- Batch related updates when possible
+    tokens: `# Token Efficiency
+Be mindful of token costs - every tool call has a cost.
+- Use mode:'lite' (default) - saves ~85% vs full mode
+- Call get_token_usage() to check consumption
+- /compact when context grows large
+- Batch related updates when possible
 - Trust lite mode; only use full mode for initial exploration`,
-    topics: `# Available Help Topics
-- getting_started: Basic workflow overview
-- tasks: Working on tasks, progress tracking
-- validation: Cross-agent task validation
-- deployment: Deployment coordination
-- git: Git workflow configuration
-- blockers: Handling blockers
-- milestones: Breaking down complex tasks
-- fallback: Background activities when idle
-- session: Session management
+    topics: `# Available Help Topics
+- getting_started: Basic workflow overview
+- tasks: Working on tasks, progress tracking
+- validation: Cross-agent task validation
+- deployment: Deployment coordination
+- git: Git workflow configuration
+- blockers: Handling blockers
+- milestones: Breaking down complex tasks
+- fallback: Background activities when idle
+- session: Session management
 - tokens: Token efficiency tips`,
 };
 // ============================================================================

package/dist/templates/agent-guidelines.js

@@ -5,183 +5,183 @@
  * in every project using Vibescope for agent tracking. These guidelines ensure
  * agents follow proper workflows and maintain visibility.
  */
-export const AGENT_GUIDELINES_TEMPLATE = `# Vibescope Agent Guidelines
-
-## Quick Start
-
-\`\`\`
-start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus")
-\`\`\`
-
-**IMPORTANT:** Always pass your model (opus/sonnet/haiku) to enable cost tracking. Check your system prompt for "You are powered by the model named..." to determine your model.
-
-This returns your persona, project info, and \`next_task\`. Start working immediately.
-
-## CRITICAL: MCP Connection Required
-
-**If the Vibescope MCP server fails to connect, you MUST end your session immediately.**
-
-### Why This Is Non-Negotiable
-
-Working without MCP connection causes:
-- **No progress visibility** - Humans can't see what you're doing
-- **Lost work tracking** - Tasks aren't tracked, time is wasted
-- **Workflow violations** - Other agents may conflict with your work
-- **Dashboard confusion** - Project state becomes inconsistent
-
-### Connection Failure Handling
-
-**If \`start_work_session\` fails or returns an error:**
-
-1. **Do NOT proceed with any work**
-2. **Inform the user** that MCP connection failed
-3. **End the session** - do not attempt workarounds
-4. **Provide troubleshooting steps:**
-   - Check if MCP server is configured: \`claude mcp list\`
-   - Verify API key is set: check \`.mcp.json\` or environment
-   - Restart Claude Code after fixing configuration
-
-**Example error responses you might see:**
-\`\`\`
-Error: Failed to start session
-Error: VIBESCOPE_API_KEY not set
-Error: Network error connecting to Vibescope API
-Error: MCP server 'vibescope' not found
-\`\`\`
-
-### Recovery Steps
-
-If MCP connection fails, tell the user:
-
-\`\`\`
-MCP connection to Vibescope failed. I cannot proceed without task tracking.
-
-To fix:
-1. Run: claude mcp list (verify vibescope is configured)
-2. Check API key: ensure VIBESCOPE_API_KEY is set
-3. Restart Claude Code
-4. Try again with: start_work_session(git_url: "...")
-
-I am ending this session to prevent untracked work.
-\`\`\`
-
-**Never "work around" a broken MCP connection.** The whole point of Vibescope is visibility and coordination. Working without it defeats the purpose.
-
-## Core Workflow
-
-1. **Start session** → \`start_work_session(git_url, model)\` - Always include your model!
-2. **Mark task in progress** → \`update_task(task_id, status: "in_progress")\` - Returns git workflow instructions!
-3. **Set up worktree** → Create isolated worktree for this task (see Git Workflow below)
-4. **Update progress** → \`update_task(task_id, progress_percentage: 50, progress_note: "...")\`
-5. **Complete task** → \`complete_task(task_id, summary: "...")\` - **MANDATORY, see below!**
-6. **Clean up** → Remove worktree, then start next task immediately
-
-## CRITICAL: Always Call complete_task (MANDATORY)
-
-**You MUST call \`complete_task()\` when you finish a task.** This is not optional.
-
-### When to Call complete_task
-
-Call \`complete_task()\` immediately after:
-- ✅ Creating and pushing a PR
-- ✅ Merging changes (for trunk-based workflow)
-- ✅ Finishing any unit of work, even if no code changes
-
-**Do NOT wait for:**
-- ❌ PR to be reviewed/merged (that's what validation is for)
-- ❌ User confirmation
-- ❌ "Perfect" summary - a brief summary is fine
-
-### The Rule
-
-\`\`\`
-PR created + pushed → complete_task() → THEN worry about next steps
-\`\`\`
-
-**If you create a PR and don't call \`complete_task()\`, you have failed the workflow.**
-
-## CRITICAL: Git Worktrees for Multi-Agent
-
-When multiple agents share a repository, you **MUST** use git worktrees to prevent conflicts.
-
-**Before starting ANY task:**
-\`\`\`bash
-# For git-flow: ensure you're on develop first, then create worktree
-git checkout develop
-git pull origin develop
-git worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>
-cd ../worktree-<task-short-id>
-\`\`\`
-
-**After task is merged:**
-\`\`\`bash
-git worktree remove ../worktree-<task-short-id>
-\`\`\`
-
-**Why?** Branch switching in shared repos causes file conflicts between agents. Worktrees provide isolated directories.
-
-Run \`get_help("git")\` for full worktree documentation.
-
-## CRITICAL: Never Ask Permission
-
-**You must NEVER:**
-- Ask "Should I continue to the next task?" → Just continue
-- Ask "Should I clear my context?" → Just clear it
-- Ask "What should I do next?" → Check \`next_task\` or use fallback activities
-- Say "All tasks are done, let me know what to do" → Use \`get_next_task\` or start fallback activity
-- Wait for confirmation before clearing context → Just do it
-
-**You must ALWAYS:**
-- Call \`complete_task()\` immediately after creating/pushing a PR - this is non-negotiable
-- Immediately start the next task after completing one
-- Clear context and restart session automatically when needed
-- Keep working until there are genuinely no tasks and no fallback activities
-
-## Continuous Work
-
-**IMPORTANT: Never stop working!** When you complete a task:
-1. \`complete_task\` returns \`next_task\` → Start it immediately
-2. No \`next_task\`? → Call \`get_next_task(project_id)\`
-3. Still no tasks? → Start a \`fallback_activity\` (code_review, security_review, etc.)
-
-**When context grows large or responses slow down:**
-1. Run \`/clear\` to reset conversation
-2. Immediately call \`start_work_session(git_url, model)\` to reload context
-3. Continue with \`next_task\` from the response
-
-**Do NOT ask the user if you should clear context. Just do it.** The dashboard tracks all your progress, so nothing is lost when you clear.
-
-## Need Help?
-
-Use \`get_help(topic)\` for detailed guidance:
-
-| Topic | Description |
-|-------|-------------|
-| \`getting_started\` | Basic workflow overview |
-| \`tasks\` | Working on tasks, progress tracking |
-| \`validation\` | Cross-agent task validation |
-| \`deployment\` | Deployment coordination |
-| \`git\` | Git workflow configuration |
-| \`blockers\` | Handling blockers |
-| \`milestones\` | Breaking down complex tasks |
-| \`fallback\` | Background activities when idle |
-| \`session\` | Session management |
-| \`topics\` | List all available topics |
-
-## MCP Server Not Connected?
-
-### Quick Setup (Claude Code)
-
-\`\`\`bash
-claude mcp add vibescope npx @vibescope/mcp-server@latest \\
-  --env VIBESCOPE_API_KEY=your_key
-\`\`\`
-
-### Manual Setup
-
-1. Copy \`.mcp.json.example\` to \`.mcp.json\`
-2. Get \`VIBESCOPE_API_KEY\` from https://vibescope.dev/dashboard/settings
-3. Restart Claude Code
+export const AGENT_GUIDELINES_TEMPLATE = `# Vibescope Agent Guidelines
+
+## Quick Start
+
+\`\`\`
+start_work_session(git_url: "https://github.com/YOUR/REPO", model: "opus")
+\`\`\`
+
+**IMPORTANT:** Always pass your model (opus/sonnet/haiku) to enable cost tracking. Check your system prompt for "You are powered by the model named..." to determine your model.
+
+This returns your persona, project info, and \`next_task\`. Start working immediately.
+
+## CRITICAL: MCP Connection Required
+
+**If the Vibescope MCP server fails to connect, you MUST end your session immediately.**
+
+### Why This Is Non-Negotiable
+
+Working without MCP connection causes:
+- **No progress visibility** - Humans can't see what you're doing
+- **Lost work tracking** - Tasks aren't tracked, time is wasted
+- **Workflow violations** - Other agents may conflict with your work
+- **Dashboard confusion** - Project state becomes inconsistent
+
+### Connection Failure Handling
+
+**If \`start_work_session\` fails or returns an error:**
+
+1. **Do NOT proceed with any work**
+2. **Inform the user** that MCP connection failed
+3. **End the session** - do not attempt workarounds
+4. **Provide troubleshooting steps:**
+   - Check if MCP server is configured: \`claude mcp list\`
+   - Verify API key is set: check \`.mcp.json\` or environment
+   - Restart Claude Code after fixing configuration
+
+**Example error responses you might see:**
+\`\`\`
+Error: Failed to start session
+Error: VIBESCOPE_API_KEY not set
+Error: Network error connecting to Vibescope API
+Error: MCP server 'vibescope' not found
+\`\`\`
+
+### Recovery Steps
+
+If MCP connection fails, tell the user:
+
+\`\`\`
+MCP connection to Vibescope failed. I cannot proceed without task tracking.
+
+To fix:
+1. Run: claude mcp list (verify vibescope is configured)
+2. Check API key: ensure VIBESCOPE_API_KEY is set
+3. Restart Claude Code
+4. Try again with: start_work_session(git_url: "...")
+
+I am ending this session to prevent untracked work.
+\`\`\`
+
+**Never "work around" a broken MCP connection.** The whole point of Vibescope is visibility and coordination. Working without it defeats the purpose.
+
+## Core Workflow
+
+1. **Start session** → \`start_work_session(git_url, model)\` - Always include your model!
+2. **Mark task in progress** → \`update_task(task_id, status: "in_progress")\` - Returns git workflow instructions!
+3. **Set up worktree** → Create isolated worktree for this task (see Git Workflow below)
+4. **Update progress** → \`update_task(task_id, progress_percentage: 50, progress_note: "...")\`
+5. **Complete task** → \`complete_task(task_id, summary: "...")\` - **MANDATORY, see below!**
+6. **Clean up** → Remove worktree, then start next task immediately
+
+## CRITICAL: Always Call complete_task (MANDATORY)
+
+**You MUST call \`complete_task()\` when you finish a task.** This is not optional.
+
+### When to Call complete_task
+
+Call \`complete_task()\` immediately after:
+- ✅ Creating and pushing a PR
+- ✅ Merging changes (for trunk-based workflow)
+- ✅ Finishing any unit of work, even if no code changes
+
+**Do NOT wait for:**
+- ❌ PR to be reviewed/merged (that's what validation is for)
+- ❌ User confirmation
+- ❌ "Perfect" summary - a brief summary is fine
+
+### The Rule
+
+\`\`\`
+PR created + pushed → complete_task() → THEN worry about next steps
+\`\`\`
+
+**If you create a PR and don't call \`complete_task()\`, you have failed the workflow.**
+
+## CRITICAL: Git Worktrees for Multi-Agent
+
+When multiple agents share a repository, you **MUST** use git worktrees to prevent conflicts.
+
+**Before starting ANY task:**
+\`\`\`bash
+# For git-flow: ensure you're on develop first, then create worktree
+git checkout develop
+git pull origin develop
+git worktree add ../worktree-<task-short-id> -b feature/<task-id>-<title>
+cd ../worktree-<task-short-id>
+\`\`\`
+
+**After task is merged:**
+\`\`\`bash
+git worktree remove ../worktree-<task-short-id>
+\`\`\`
+
+**Why?** Branch switching in shared repos causes file conflicts between agents. Worktrees provide isolated directories.
+
+Run \`get_help("git")\` for full worktree documentation.
+
+## CRITICAL: Never Ask Permission
+
+**You must NEVER:**
+- Ask "Should I continue to the next task?" → Just continue
+- Ask "Should I clear my context?" → Just clear it
+- Ask "What should I do next?" → Check \`next_task\` or use fallback activities
+- Say "All tasks are done, let me know what to do" → Use \`get_next_task\` or start fallback activity
+- Wait for confirmation before clearing context → Just do it
+
+**You must ALWAYS:**
+- Call \`complete_task()\` immediately after creating/pushing a PR - this is non-negotiable
+- Immediately start the next task after completing one
+- Clear context and restart session automatically when needed
+- Keep working until there are genuinely no tasks and no fallback activities
+
+## Continuous Work
+
+**IMPORTANT: Never stop working!** When you complete a task:
+1. \`complete_task\` returns \`next_task\` → Start it immediately
+2. No \`next_task\`? → Call \`get_next_task(project_id)\`
+3. Still no tasks? → Start a \`fallback_activity\` (code_review, security_review, etc.)
+
+**When context grows large or responses slow down:**
+1. Run \`/clear\` to reset conversation
+2. Immediately call \`start_work_session(git_url, model)\` to reload context
+3. Continue with \`next_task\` from the response
+
+**Do NOT ask the user if you should clear context. Just do it.** The dashboard tracks all your progress, so nothing is lost when you clear.
+
+## Need Help?
+
+Use \`get_help(topic)\` for detailed guidance:
+
+| Topic | Description |
+|-------|-------------|
+| \`getting_started\` | Basic workflow overview |
+| \`tasks\` | Working on tasks, progress tracking |
+| \`validation\` | Cross-agent task validation |
+| \`deployment\` | Deployment coordination |
+| \`git\` | Git workflow configuration |
+| \`blockers\` | Handling blockers |
+| \`milestones\` | Breaking down complex tasks |
+| \`fallback\` | Background activities when idle |
+| \`session\` | Session management |
+| \`topics\` | List all available topics |
+
+## MCP Server Not Connected?
+
+### Quick Setup (Claude Code)
+
+\`\`\`bash
+claude mcp add vibescope npx @vibescope/mcp-server@latest \\
+  --env VIBESCOPE_API_KEY=your_key
+\`\`\`
+
+### Manual Setup
+
+1. Copy \`.mcp.json.example\` to \`.mcp.json\`
+2. Get \`VIBESCOPE_API_KEY\` from https://vibescope.dev/dashboard/settings
+3. Restart Claude Code
 `;
 /**
  * Get the agent guidelines template
@@ -195,13 +195,13 @@ export function getAgentGuidelinesTemplate() {
  * @returns A brief summary of key guidelines
  */
 export function getAgentGuidelinesSummary() {
-    return `## Essential Agent Guidelines
-
-1. **MCP Connection Required** - If start_work_session fails, END SESSION IMMEDIATELY
-2. **Always call complete_task()** - After creating a PR, call complete_task() right away
-3. **Use git worktrees** - Create worktrees for each task to avoid conflicts
-4. **Never ask permission** - Just continue working, clear context when needed
-5. **Continuous work** - Never stop; use get_next_task or fallback activities
-
+    return `## Essential Agent Guidelines
+
+1. **MCP Connection Required** - If start_work_session fails, END SESSION IMMEDIATELY
+2. **Always call complete_task()** - After creating a PR, call complete_task() right away
+3. **Use git worktrees** - Create worktrees for each task to avoid conflicts
+4. **Never ask permission** - Just continue working, clear context when needed
+5. **Continuous work** - Never stop; use get_next_task or fallback activities
+
 For full guidelines, create a \`.claude/CLAUDE.md\` file in your project with the agent guidelines template.`;
 }

package/dist/token-tracking.js

@@ -19,8 +19,10 @@ export function estimateTokens(obj) {
         const json = JSON.stringify(obj);
         return Math.max(1, Math.ceil(json.length / 4));
     }
-    catch {
-        // If JSON serialization fails, return a minimal estimate
+    catch (error) {
+        // Log warning when serialization fails (e.g., circular references, BigInt)
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.warn(`[Vibescope] Token estimation failed: ${errorMessage}. Returning minimal estimate of 1 token.`);
         return 1;
     }
 }