MCP Integration

Complete guide to Vibe's 38 built-in MCP tools powered by @su-record/hi-ai.

---

Table of Contents

1. What is MCP?
2. Installation & Setup
3. Tool Categories
4. Code Analysis Tools
5. Project Intelligence Tools
6. Thinking & Planning Tools
7. Memory & Context Tools
8. UI & Design Tools
9. Requirements & Planning Tools
10. Prompt Engineering Tools
11. Browser Automation Tools
12. Time & Utility Tools
13. Usage Examples

---

What is MCP?

MCP (Model Context Protocol) is an open standard that allows AI assistants to securely access development tools and resources. Think of it as a plugin system for AI.

Why MCP?

Traditional AI assistants are isolated - they can't:

• ❌ Analyze your codebase structure
• ❌ Check code complexity metrics
• ❌ Remember context across sessions
• ❌ Access project-specific information

With MCP:

• ✅ 38 specialized tools at AI's disposal
• ✅ Secure access to project resources
• ✅ Context preservation across sessions
• ✅ Automated analysis without manual intervention

How Vibe Uses MCP

User: "vibe run Task 1-1"
     ↓
Vibe Agent Selected (Backend Python Expert)
     ↓
Agent uses MCP tools automatically:
  1. find_symbol() - Locate existing code
  2. analyze_complexity() - Check code quality
  3. validate_code_quality() - Score implementation
  4. save_memory() - Store context for next task
     ↓
Task completed with quality guarantees

---

Installation & Setup

Step 1: Install Vibe

npm install -g @su-record/vibe

This installs:

• Vibe CLI commands
• @su-record/hi-ai MCP server (38 tools)

Step 2: Initialize Your Project

cd /path/to/your/project
vibe init

This registers the MCP server for your project (local configuration).

Verify Installation

From your project directory:

claude mcp list

Expected output:

vibe: node /path/to/@su-record/vibe/node_modules/@su-record/hi-ai/dist/index.js - ✓ Connected

Important Notes

⚠️ Per-Project Registration: MCP servers are registered per-project, not globally. You must run vibe init in each project where you want to use Vibe.

⚠️ Directory Context: claude mcp list must be run from within your project directory.

Re-register MCP Server

If the MCP server is not connected:

# Make sure you're in your project directory
cd /path/to/your/project

# Re-run init (safe to run multiple times)
vibe init

# Verify
claude mcp list

---

Tool Categories

Vibe includes 38 MCP tools across 9 categories:

Category	Tools	Purpose
Code Analysis	5	Complexity, quality, coupling analysis
Project Intelligence	2	Symbol search, reference finding
Thinking & Planning	6	Problem breakdown, reasoning chains
Memory & Context	10	Session management, context preservation
UI & Design	1	ASCII UI mockups
Requirements & Planning	4	PRD, user stories, roadmaps
Prompt Engineering	2	Prompt analysis and enhancement
Browser Automation	4	Web testing, network monitoring
Time & Utility	4	Time management, formatting

---

Code Analysis Tools

1. analyze_complexity

Calculates cyclomatic and cognitive complexity metrics.

Purpose:

• Identify complex functions that need refactoring
• Enforce complexity standards (CC ≤ 10, Cognitive ≤ 15)
• Track technical debt

Input:

{
  "file_path": "src/service.py",
  "language": "python"
}

Output:

{
  "file": "src/service.py",
  "language": "python",
  "functions": [
    {
      "name": "process_notification",
      "line": 45,
      "cyclomatic_complexity": 15,
      "cognitive_complexity": 18,
      "issues": [
        "High cyclomatic complexity (target: ≤10)",
        "High cognitive complexity (target: ≤15)",
        "Consider extracting conditions into separate functions"
      ]
    }
  ],
  "summary": {
    "total_functions": 8,
    "avg_cyclomatic": 6.2,
    "avg_cognitive": 7.8,
    "high_complexity_count": 2
  }
}

Usage in Vibe:

vibe analyze --code
# Internally calls analyze_complexity for all files

Supports:

• Python
• TypeScript/JavaScript
• Dart
• Java
• Go
• Rust

---

2. validate_code_quality

Comprehensive code quality scoring with recommendations.

Purpose:

• Get overall quality score (0-100)
• Identify anti-patterns
• Receive actionable improvement suggestions

Input:

{
  "file_path": "src/service.py",
  "standards": {
    "max_complexity": 10,
    "max_function_length": 20,
    "max_nesting": 3
  }
}

Output:

{
  "file": "src/service.py",
  "score": 78,
  "grade": "C+",
  "issues": [
    {
      "type": "complexity",
      "severity": "high",
      "line": 45,
      "message": "Function 'process_notification' has CC of 15 (limit: 10)",
      "suggestion": "Extract conditional logic into separate validation functions"
    },
    {
      "type": "length",
      "severity": "medium",
      "line": 120,
      "message": "Function 'handle_request' is 35 lines (limit: 20)",
      "suggestion": "Split into smaller functions: parse_request, validate_request, execute_request"
    }
  ],
  "strengths": [
    "Good type hints coverage (95%)",
    "Proper error handling with specific exceptions",
    "Clear docstrings for public methods"
  ],
  "recommendations": [
    "Refactor process_notification into 3 smaller functions",
    "Add unit tests (current coverage: 65%, target: 80%)",
    "Consider using Strategy pattern for notification types"
  ]
}

Usage in Vibe:

vibe verify "feature-name"
# Calls validate_code_quality for all changed files

---

3. check_coupling_cohesion

Analyzes module coupling and cohesion metrics.

Purpose:

• Detect tight coupling between modules
• Identify low cohesion (unrelated functions in same module)
• Find circular dependencies

Input:

{
  "project_path": "src/",
  "language": "python"
}

Output:

{
  "coupling": {
    "score": 0.6,
    "status": "medium",
    "pairs": [
      {
        "module_a": "controllers/user_controller.py",
        "module_b": "services/user_service.py",
        "coupling_score": 0.8,
        "issue": "High coupling - Controller directly accesses Service internals",
        "suggestion": "Use dependency injection and interfaces"
      }
    ]
  },
  "cohesion": {
    "modules": [
      {
        "path": "utils/helpers.py",
        "cohesion_score": 0.3,
        "issue": "Low cohesion - Unrelated utilities mixed",
        "functions": [
          "format_date",
          "send_email",
          "calculate_distance",
          "parse_json"
        ],
        "suggestion": "Split into date_utils.py, email_utils.py, geo_utils.py, json_utils.py"
      }
    ]
  },
  "circular_dependencies": [
    {
      "cycle": ["services/user.py", "services/notification.py", "services/user.py"],
      "suggestion": "Extract shared types into models/user_types.py"
    }
  ]
}

Usage in Vibe:

vibe analyze --arch
# Analyzes coupling/cohesion across project

---

4. suggest_improvements

AI-powered code improvement suggestions.

Purpose:

• Get refactoring recommendations
• Learn best practices
• Improve code readability and maintainability

Input:

{
  "code": "def process(data): ...",
  "context": "This function handles user notifications",
  "language": "python"
}

Output:

{
  "suggestions": [
    {
      "type": "naming",
      "priority": "high",
      "current": "def process(data):",
      "improved": "def process_user_notification(notification_data: NotificationData):",
      "reason": "Function name should be specific and descriptive. Add type hints."
    },
    {
      "type": "error_handling",
      "priority": "medium",
      "issue": "Missing error handling for database operations",
      "solution": "Wrap database calls in try-except, handle specific exceptions"
    },
    {
      "type": "performance",
      "priority": "low",
      "issue": "N+1 query in user lookup",
      "solution": "Use eager loading with .options(joinedload(User.settings))"
    }
  ],
  "refactored_code": "...",
  "complexity_before": 12,
  "complexity_after": 7
}

Usage in Vibe: Automatically used during vibe run when agent detects improvable code.

---

5. apply_quality_rules

Enforces project-specific coding standards.

Purpose:

• Apply consistent formatting
• Enforce naming conventions
• Validate code against project rules

Input:

{
  "file_path": "src/service.py",
  "rules": {
    "max_line_length": 88,
    "naming_convention": "snake_case",
    "require_docstrings": true,
    "require_type_hints": true
  }
}

Output:

{
  "violations": [
    {
      "line": 12,
      "rule": "naming_convention",
      "message": "Class name 'userService' should be 'UserService' (PascalCase)"
    },
    {
      "line": 23,
      "rule": "require_docstrings",
      "message": "Public method 'get_user' missing docstring"
    }
  ],
  "auto_fixed": 5,
  "manual_review": 2
}

Usage in Vibe:

vibe verify "feature-name"
# Checks all changed files against quality rules

---

Project Intelligence Tools

6. find_symbol

Locate function, class, or variable definitions.

Purpose:

• Find where code is defined
• Navigate large codebases quickly
• Understand code structure

Input:

{
  "symbol": "UserService",
  "project_path": "src/",
  "language": "python"
}

Output:

{
  "symbol": "UserService",
  "type": "class",
  "definitions": [
    {
      "file": "src/services/user_service.py",
      "line": 15,
      "context": "class UserService:\n    def __init__(self, db: Database):\n        self.db = db",
      "methods": [
        "get_user",
        "create_user",
        "update_user",
        "delete_user"
      ]
    }
  ]
}

Usage in Vibe: Agents use this to understand existing code before making changes.

---

7. find_references

Find all usages of a symbol.

Purpose:

• See where code is used
• Assess impact of changes
• Identify dead code

Input:

{
  "symbol": "get_user",
  "project_path": "src/",
  "language": "python"
}

Output:

{
  "symbol": "get_user",
  "total_references": 12,
  "references": [
    {
      "file": "src/controllers/user_controller.py",
      "line": 34,
      "context": "user = self.user_service.get_user(user_id)"
    },
    {
      "file": "src/services/notification_service.py",
      "line": 89,
      "context": "user = await user_service.get_user(recipient_id)"
    }
  ],
  "unused": false
}

Usage in Vibe: Before refactoring, agents check how code is used across the project.

---

Thinking & Planning Tools

8. create_thinking_chain

Generate step-by-step reasoning chain.

Purpose:

• Break down complex problems
• Document decision-making process
• Create structured thought process

Input:

{
  "problem": "How to implement Redis caching for user settings?",
  "context": "FastAPI backend, PostgreSQL database, 100k DAU"
}

Output:

{
  "chain": [
    {
      "step": 1,
      "thought": "Identify what to cache",
      "reasoning": "User settings are read frequently (every request) but changed rarely",
      "decision": "Cache entire user_settings object"
    },
    {
      "step": 2,
      "thought": "Choose cache key format",
      "reasoning": "Need unique key per user, easy to invalidate",
      "decision": "Format: 'user_settings:{user_id}'"
    },
    {
      "step": 3,
      "thought": "Determine TTL",
      "reasoning": "Settings rarely change, but need freshness guarantee",
      "decision": "TTL: 1 hour (3600 seconds)"
    },
    {
      "step": 4,
      "thought": "Handle cache invalidation",
      "reasoning": "When user updates settings, cache must be cleared",
      "decision": "Delete key on update: redis.delete(f'user_settings:{user_id}')"
    }
  ],
  "conclusion": "Implement read-through cache with 1h TTL and invalidation on update"
}

Usage in Vibe: Used during vibe plan to document technical decisions.

---

9. step_by_step_analysis

Detailed problem breakdown with substeps.

Purpose:

• Analyze complex requirements
• Generate implementation steps
• Identify edge cases

Input:

{
  "requirement": "Implement notification settings with 6 categories",
  "constraints": ["FastAPI backend", "Flutter frontend", "PostgreSQL database"]
}

Output:

{
  "analysis": {
    "phase_1": {
      "name": "Backend Implementation",
      "steps": [
        {
          "step": "1.1",
          "action": "Create database table user_notification_settings",
          "details": "6 boolean columns, foreign key to users, timestamps",
          "estimated_time": "1 hour"
        },
        {
          "step": "1.2",
          "action": "Create Pydantic schemas",
          "details": "NotificationSettingsUpdate, NotificationSettingsResponse",
          "estimated_time": "0.5 hours"
        }
      ]
    }
  }
}

Usage in Vibe: Powers vibe tasks command for task decomposition.

---

10-13. Other Thinking Tools

Tool	Purpose	Use Case
analyze_problem	Structured problem analysis	Understand requirements deeply
break_down_problem	Decompose into subproblems	Handle complex features
think_aloud_process	Explain reasoning	Debugging and learning
format_as_plan	Convert analysis to plan	Generate technical plans

---

Memory & Context Tools

14. save_memory

Store information for future sessions.

Purpose:

• Preserve project context
• Remember decisions and rationale
• Build knowledge base over time

Input:

{
  "key": "notification_system_design",
  "content": {
    "decision": "Use FCM for push notifications",
    "rationale": "Already integrated, supports iOS/Android/Web",
    "date": "2025-11-17",
    "alternatives_considered": ["OneSignal", "Pusher", "Custom APNS/FCM"]
  },
  "tags": ["architecture", "notifications", "infrastructure"]
}

Output:

{
  "id": "mem_123abc",
  "status": "saved",
  "expires_at": null
}

Usage in Vibe: Automatically saves context after each task completion.

---

15. recall_memory

Retrieve stored information.

Input:

{
  "key": "notification_system_design"
}

Output:

{
  "key": "notification_system_design",
  "content": { ... },
  "created_at": "2025-11-17T10:30:00Z",
  "accessed_count": 5
}

---

16. search_memories

Search stored memories by keyword.

Input:

{
  "query": "Redis caching",
  "tags": ["performance"],
  "limit": 10
}

Output:

{
  "results": [
    {
      "key": "redis_caching_strategy",
      "content": { ... },
      "relevance": 0.95
    }
  ]
}

---

17-23. Other Memory Tools

Tool	Purpose
update_memory	Modify existing memory
delete_memory	Remove outdated information
list_memories	View all stored memories
auto_save_context	Automatic checkpointing
start_session	Begin new work session
restore_session_context	Resume previous session
prioritize_memory	Mark important memories

---

UI & Design Tools

24. preview_ui_ascii

Generate ASCII UI mockups.

Input:

{
  "description": "Login form with email, password, and submit button",
  "width": 80
}

Output:

┌─────────────────────────────────────────┐
│            Welcome Back                  │
├─────────────────────────────────────────┤
│                                          │
│         ┌─────────────────────┐          │
│  Email: │                     │          │
│         └─────────────────────┘          │
│                                          │
│         ┌─────────────────────┐          │
│  Pass:  │ ••••••••••••        │          │
│         └─────────────────────┘          │
│                                          │
│         ┌─────────────────────┐          │
│         │      Sign In        │          │
│         └─────────────────────┘          │
│                                          │
└─────────────────────────────────────────┘

Components:
- Header (Welcome Back)
- EmailInput (with validation)
- PasswordInput (masked)
- SubmitButton (primary action)

Usage:

vibe ui "notification settings with 6 toggles"

---

Requirements & Planning Tools

25. analyze_requirements

Extract requirements from natural language.

Input:

{
  "text": "Users need to control their notifications because we're getting complaints about too many alerts..."
}

Output:

{
  "requirements": [
    {
      "id": "REQ-001",
      "type": "functional",
      "description": "Users can toggle notification categories",
      "priority": "HIGH",
      "acceptance_criteria": [
        "UI displays 6 category toggles",
        "Changes persist to database",
        "Changes take effect immediately"
      ]
    }
  ]
}

---

26. create_user_stories

Generate user stories from requirements.

Input:

{
  "feature": "Notification Settings",
  "requirements": [ ... ]
}

Output:

{
  "user_stories": [
    {
      "id": "US-001",
      "title": "Toggle notification categories",
      "story": "As a user, I want to toggle notification categories so that I only receive alerts I care about",
      "acceptance_criteria": [ ... ],
      "story_points": 3
    }
  ]
}

---

27. feature_roadmap

Generate feature timeline.

Input:

{
  "features": ["Notification Settings", "Dark Mode", "Offline Support"],
  "timeline": "Q1 2025"
}

Output:

{
  "roadmap": {
    "Q1_2025": {
      "January": ["Notification Settings"],
      "February": ["Dark Mode"],
      "March": ["Offline Support"]
    }
  }
}

---

28. generate_prd

Create Product Requirements Document.

Output:

# PRD: Notification Settings

## Overview
Allow users to customize notification preferences...

## Goals
- Reduce churn by 5%
- Improve user satisfaction...

## Requirements
...

---

Prompt Engineering Tools

29. analyze_prompt

Evaluate prompt quality.

Input:

{
  "prompt": "Make the app better"
}

Output:

{
  "score": 35,
  "issues": [
    "Too vague - 'better' is subjective",
    "No specific goals or metrics",
    "Missing context about current state"
  ],
  "suggestions": [
    "Specify what aspect to improve (performance, UX, features)",
    "Add measurable success criteria",
    "Provide current baseline metrics"
  ]
}

---

30. enhance_prompt

Improve prompt effectiveness.

Input:

{
  "prompt": "Add notifications"
}

Output:

{
  "enhanced": "Implement a notification settings system that allows users to toggle 6 categories (likes, comments, follows, mentions, feed updates, marketing) with default states. Include API endpoints, database migration, and Flutter UI. Target: P95 < 500ms, 100k DAU scale.",
  "improvements": [
    "Added specific feature details",
    "Included technical requirements",
    "Specified scale and performance targets"
  ]
}

---

Browser Automation Tools

31-34. Browser Tools

Tool	Purpose	Use Case
inspect_network_requests	Monitor HTTP traffic	Debug API calls
monitor_console_logs	Capture browser logs	Find JS errors
browserUtils	Page interactions	E2E testing
browserPool	Manage browser instances	Parallel testing

Usage: Primarily for testing and debugging web applications.

---

Time & Utility Tools

35. getCurrentTime

Get current time with timezone.

Output:

{
  "timestamp": "2025-11-17T15:30:00Z",
  "timezone": "UTC",
  "formatted": "November 17, 2025 3:30 PM"
}

Usage: Timestamping memories, logs, and reports.

---

36-38. Utility Tools

Tool	Purpose
format_output	Consistent formatting
validate_json	JSON schema validation
parse_markdown	Markdown parsing

---

Usage Examples

Example 1: Complete Task Workflow

// Agent executes Task 1-1: Database Migration

// Step 1: Check existing schema
const existingTables = await mcp.find_symbol("user_notification_settings");

// Step 2: Generate migration
const thinkingChain = await mcp.create_thinking_chain(
  "Design user_notification_settings table"
);

// Step 3: Implement migration
// ... write migration code ...

// Step 4: Validate code quality
const quality = await mcp.validate_code_quality("alembic/versions/xxx.py");

// Step 5: Check complexity
const complexity = await mcp.analyze_complexity("alembic/versions/xxx.py");

// Step 6: Save context
await mcp.save_memory({
  task: "Task 1-1",
  completion: "Migration created with 6 boolean columns",
  quality_score: quality.score,
  files: ["alembic/versions/xxx_add_notification_settings.py"]
});

---

Example 2: Code Refactoring

// Before refactoring, analyze code
const coupling = await mcp.check_coupling_cohesion("src/");
const complexity = await mcp.analyze_complexity("src/service.py");
const suggestions = await mcp.suggest_improvements("src/service.py");

// Refactor based on suggestions
// ... refactor code ...

// Verify improvements
const newComplexity = await mcp.analyze_complexity("src/service.py");
console.log(`Complexity: ${complexity.avg} → ${newComplexity.avg}`);

---

Example 3: Planning New Feature

// Analyze requirements
const requirements = await mcp.analyze_requirements(userInput);

// Generate user stories
const stories = await mcp.create_user_stories(requirements);

// Break down into tasks
const breakdown = await mcp.step_by_step_analysis(stories[0]);

// Create thinking chain for implementation
const chain = await mcp.create_thinking_chain(
  "Implement notification settings backend"
);

// Generate PRD
const prd = await mcp.generate_prd(requirements);

---

Best Practices

1. Let Agents Use Tools Automatically

Don't manually call MCP tools - agents use them automatically during execution.

# ✅ Good: Let agent decide which tools to use
vibe run "Task 1-1"

# ❌ Bad: Don't manually call MCP tools
# (Tools are for agent use, not direct CLI)

2. Trust the Memory System

Agents save context automatically - no need to manually manage memory.

3. Review Tool Output in Reports

vibe analyze --code
# Check .vibe/reports/analysis-*.md for MCP tool results

4. Use Verification

vibe verify "feature-name"
# Leverages multiple MCP tools for comprehensive check

---

Troubleshooting

MCP Server Not Connected

# Check status
claude mcp list

# Reinstall
cd $(npm root -g)/@su-record/vibe
npm run postinstall

# Verify
claude mcp list

Tools Not Working

Ensure Claude Code is running and MCP server shows "✓ Connected".

Performance Issues

MCP tools are optimized for speed, but large codebases may take longer. Use --verbose to see progress.

---

Further Reading

• MCP Specification: modelcontextprotocol.io
• hi-ai Repository: github.com/su-record/hi-ai
• Smithery: smithery.ai/server/@su-record/hi-ai

---

Next Steps:

• Agents Guide - Learn how agents use these tools
• Examples - See tools in action
• Best Practices - Maximize tool effectiveness

---

← Back to Command Reference | Home | Next: Agents Guide →