MCP Task Bridge Server

A Model Context Protocol (MCP) server that bridges Claude Code to the Vibe task management API, enabling AI-powered task planning and management.

Overview

This MCP server provides tools, prompts, and resources for Claude to:

• List tasks by project with pagination support
• Update task planning status (pending, planning, approved, rejected)
• Replace or merge task planning schemas with automatic validation
• Append to task plan history with payload size limits
• Generate structured task implementation plans
• Review implementations against original plans
• Access read-only task data through resources
• Full structured logging and error diagnostics

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager
• Access to the Vibe API (running locally or deployed)
• Claude Desktop application

Installation

Quick Install with NPX (Recommended)

npx vibe-mcp-task-bridge

Global Installation

npm install -g vibe-mcp-task-bridge
vibe-mcp-task-bridge

Local Development

1. Clone or navigate to the repository:

cd mcp-server

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Configuration

Environment Variables

Create a .env file in the mcp-server directory:

# API base URL (required)
MCP_TASK_API_BASE=http://localhost:3000/api

# API bypass token (required - must match MCP_BYPASS_TOKEN in main app)
# This is the token that authenticates the MCP server to your API
DEV_API_KEY=your-mcp-bypass-token-here

# Environment (development/production)
NODE_ENV=development

Important: The DEV_API_KEY must match the MCP_BYPASS_TOKEN you set in your main application's environment variables.

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Using NPX (Recommended)

{
  "mcpServers": {
    "vibe-tasks": {
      "command": "npx",
      "args": ["@vibe-platform/mcp-task-bridge"],
      "env": {
        "MCP_TASK_API_BASE": "http://localhost:3000/api",
        "DEV_API_KEY": "your-mcp-bypass-token-here"
      }
    }
  }
}

Setup Steps:

1. Generate a secure token: openssl rand -hex 32
2. Add to your main app's .env: MCP_BYPASS_TOKEN=<your-token>
3. Add to Claude config above: "DEV_API_KEY": "<same-token>"
4. Ensure your user ID is set: MCP_USER_ID=137005985 (or your actual ID)

Using Local Build

{
  "mcpServers": {
    "vibe-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/server.js"],
      "env": {
        "MCP_TASK_API_BASE": "http://localhost:3000/api",
        "DEV_API_KEY": "your-dev-api-key-here"
      }
    }
  }
}

Usage

Once configured, Claude will automatically have access to the following capabilities:

Tools

Interactive tools for task management:

tasks.list

List tasks for a specific project with optional pagination.

Parameters:

• projectId (string, required): The project ID to filter tasks (must be valid CUID)
• cursor (string, optional): Pagination cursor for the next page
• limit (number, optional): Number of tasks to return (1-100, default: 10)

Example:

Use the tasks.list tool to show me all tasks for project "clj123abc"

tasks.update

Update a task's planning status and/or plan schema.

Parameters:

• taskId (string, required): The task ID to update (must be valid CUID)
• planningStatus (string, optional): Set status to 'pending', 'planning', 'approved', or 'rejected'
• specReplace (any, optional): Replace the entire currentPlanSchema
• specMerge (any, optional): Merge updates into the existing currentPlanSchema
• historyAppend (array, optional): Append entries to the planHistory array

Validation Rules:

• Cannot use both specReplace and specMerge in the same update
• All JSON payloads are limited to 200KB to prevent memory issues
• At least one update field must be provided
• Task and project IDs must be valid CUIDs

Example:

Update task "clj456def" to set the planning status to "approved"

Prompts

Pre-configured prompts for task planning:

generate_task_plan

Generate a structured implementation plan for a task.

Arguments:

• task_description (required): The task or feature to implement
• project_context (optional): Context about the project and tech stack
• requirements (optional): Specific requirements or acceptance criteria

Example:

Use the generate_task_plan prompt to create a plan for "Add user authentication with JWT"

review_task_implementation

Review an implementation against the original plan.

Arguments:

• task_plan (required): The original task plan or requirements
• implementation_summary (required): Summary of what was implemented
• changed_files (optional): List of files that were changed

Example:

Use the review_task_implementation prompt to review the authentication implementation

Resources

Read-only access to task data:

task://project/{projectId}/active

Get all active tasks for a specific project.

Example:

Read the resource task://project/clj123abc/active to see all active tasks

Development

Running in Development Mode

For development with hot reload:

npm run dev

Type Checking

Run TypeScript type checking without building:

npm run typecheck

Building

Compile TypeScript to JavaScript:

npm run build

Logging & Monitoring

The server uses structured JSON logging to stderr with the following features:

• Structured Format: All logs are JSON formatted for easy parsing
• Operation Tracking: Each operation gets a unique ID for tracing
• Performance Metrics: Response times automatically measured
• Error Context: Detailed error information with stack traces (dev mode)
• Sensitive Data Protection: API keys and tokens are redacted

Example log entry:

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "level": "INFO",
  "message": "Task updated successfully",
  "operation": "tasks.update",
  "taskId": "clj456def",
  "duration_ms": 145,
  "metadata": {
    "updatedFields": ["planningStatus", "currentPlanSchema"]
  }
}

Error Handling

The server provides detailed error diagnostics for common issues:

| Error Code | Description | Resolution | |------------|-------------|------------| | VALIDATION_ERROR | Input validation failed | Check parameter types and CUID format | | AUTHENTICATION_ERROR | API key invalid or missing | Verify DEV_API_KEY environment variable | | NOT_FOUND | Resource not found | Verify the task/project ID exists | | PAYLOAD_TOO_LARGE | Payload exceeds 200KB | Split into smaller operations | | NETWORK_ERROR | Network request failed | Check API connectivity and MCP_TASK_API_BASE | | TIMEOUT_ERROR | Request timeout | API may be slow or unresponsive | | DATABASE_ERROR | Database operation failed | Check database connectivity | | RATE_LIMIT_ERROR | Too many requests | Implement exponential backoff |

Security

Current Implementation (MVP)

• API keys are never logged (automatically redacted)
• Sensitive fields are sanitized before logging
• Payload size limits prevent memory exhaustion (200KB max)
• Input validation prevents injection attacks
• All inputs validated with Zod schemas

Future Enhancements (Post-MVP)

• OAuth 2.0 token extraction from Claude headers
• Per-user rate limiting
• Request signing and verification
• Audit logging for compliance

Architecture

Components

• Server (server.ts): Main MCP server with stdio transport
• Handlers (handlers.ts): Business logic for tool operations
• Validation (validation.ts): Zod schemas and payload validation
• Logger (logger.ts): Structured logging system
• API Client (api-client.ts): HTTP client for Vibe API
• Merger (merger.ts): Deep merge algorithm for plan schemas

Data Flow

1. Claude sends tool request via stdio
2. Server validates input with Zod schemas
3. Handler processes request with logging
4. API client makes HTTP call to Vibe API
5. Response validated and returned to Claude
6. All operations logged to stderr

Troubleshooting

Server Won't Start

1. Check Node.js version: node --version (must be 18.0.0+)
2. Verify dependencies installed: npm install
3. Check environment variables in .env file
4. Ensure the API is running at MCP_TASK_API_BASE

Connection Issues

1. Verify the API URL is correct and accessible
2. Test API connectivity: curl http://localhost:3000/api/health
3. Check firewall/network settings
4. Review server logs for specific error messages

Tool Errors

1. Check the structured logs for diagnostic hints
2. Verify input parameters match schema requirements
3. Ensure payloads don't exceed 200KB limit
4. Validate CUIDs format for task/project IDs
5. Check if resources exist in the database

Debug Mode

Enable debug logging by setting:

NODE_ENV=development

This will include:

• Stack traces for errors
• Additional debug messages
• Request/response details

Future Roadmap

The following placeholders exist for post-MVP features:

1. Authentication: The extractAuthToken function in logger.ts is ready for Bearer token extraction
2. Rate Limiting: Infrastructure in place for handling rate limits
3. Conflict Resolution: Merge algorithm can be extended with validation
4. Metrics Collection: Performance data ready for monitoring systems
5. Health Checks: Endpoint for service health monitoring

Support

For issues or questions:

1. Check the structured logs for diagnostic information
2. Review error codes and diagnostic hints above
3. Ensure all prerequisites are met
4. Verify configuration matches the examples
5. Check existing issues in the repository

License

[Your License Here]