vibe-check-mcp-server

Analyzes an AI agent's current reasoning path against the original user request to identify tunnel vision, scope creep, and over-engineering through structured metacognitive prompts sent to the Gemini API. The vibe_check tool accepts the agent's plan, original request, optional thinking logs, and available tools, then returns pattern-interrupt questions designed to break reasoning lock-in by surfacing hidden assumptions and alternative approaches.

The vibe_distill tool accepts a complex agent plan and uses Gemini API to extract essential elements, identify unnecessary abstractions, and generate a simplified version that preserves core functionality while removing scope creep. It analyzes the plan's complexity, identifies over-engineered components, and returns both a distilled plan and a rationale explaining what was removed and why.

Accepts and accumulates thinking logs from agent reasoning steps, enabling vibe_check to analyze the full reasoning trajectory rather than isolated snapshots. The thinking log parameter allows agents to pass their step-by-step reasoning, which vibe_check uses to understand how the agent arrived at its current plan and identify where reasoning diverged from the original intent. Supports optional phase tracking to understand which stage of reasoning the agent is in.

Accepts optional confidence level parameters in vibe_check calls to track how certain the agent is about its current plan. Enables vibe_check to calibrate its pattern-interrupt intensity based on confidence — low-confidence plans receive more aggressive questioning, while high-confidence plans receive lighter oversight. Supports both explicit confidence scores and implicit confidence inference from the plan description.

Accepts optional focusAreas parameter that allows users to specify which aspects of the agent's plan should receive heightened pattern detection scrutiny (e.g., 'database design', 'API architecture', 'error handling'). Vibe_check uses these focus areas to concentrate its pattern-interrupt questions on the specified domains rather than analyzing the entire plan uniformly. Enables domain-specific oversight without requiring domain expertise in the system.

The vibe_learn tool maintains a pattern database of recurring reasoning mistakes and over-engineering patterns observed across agent sessions. It accepts feedback about what went wrong (e.g., 'agent over-engineered the database schema'), stores it with context, and makes this pattern history available to vibe_check for future sessions. This creates a self-improving feedback loop where the system learns from past agent failures.

Implements a Model Context Protocol (MCP) server that exposes the three vibe_check tools (vibe_check, vibe_distill, vibe_learn) as callable resources to MCP-compatible clients like Claude. The server handles MCP request validation, parameter extraction, tool routing, Gemini API integration, and response formatting according to MCP specification. Built on the MCP SDK with TypeScript, it manages the full request-response lifecycle.

Abstracts all interactions with Google's Gemini API (gemini-2.0-flash model) behind a unified integration layer that handles API authentication, request formatting, response parsing, error handling, and retry logic. The integration accepts prompts and context from the three vibe_check tools, sends them to Gemini, and returns structured responses. Includes error handling for API failures, rate limiting, and invalid responses.

Maintains session context across multiple vibe_check calls within a single agent workflow, allowing the system to track thinking logs, available tools, focus areas, and previous pattern detections. The vibe_check tool accepts an optional sessionId parameter that enables it to accumulate context across multiple invocations, improving pattern detection accuracy by understanding the full reasoning trajectory rather than isolated snapshots.

Provides pre-configured Smithery integration that enables Claude to discover and use vibe-check tools without manual MCP setup. The integration includes a Smithery configuration file that registers the vibe-check MCP server, tool definitions, and parameter schemas, allowing Claude users to enable vibe-check oversight with a single configuration step rather than manual MCP server setup.

Implements a structured questioning framework that generates targeted metacognitive questions designed to surface hidden assumptions in agent reasoning and break tunnel vision. The vibe_check tool uses Gemini to analyze the agent's plan, identify implicit assumptions (e.g., 'assumes the database must be normalized'), and generate questions that challenge those assumptions (e.g., 'Have you considered a simpler denormalized schema?'). Questions are contextualized to the specific plan and original user request.

Analyzes agent-generated plans to identify complexity hotspots, categorize components as essential vs optional, and extract the minimal viable solution. The vibe_distill tool uses Gemini to parse the plan, identify unnecessary abstractions, redundant components, and scope creep, then generates a simplified version with explicit rationale for what was removed. Includes categorization of components by criticality and impact.

Provides Docker configuration for containerized deployment of the vibe-check MCP server, enabling easy deployment to cloud platforms, Kubernetes clusters, or local Docker environments. Includes Dockerfile with optimized Node.js runtime, environment variable configuration for API keys, and health check endpoints. Supports both direct Docker deployment and orchestration through container platforms.