@mrsimpson/responsible-vibe-mcp
Advanced tools
A Model Context Protocol server that acts as an intelligent conversation state manager and development guide for LLMs
A Model Context Protocol (MCP) server that acts as an intelligent conversation state manager and development guide for LLMs. This server orchestrates feature development conversations by maintaining state, determining development phases, and providing contextual instructions to guide LLMs through structured development processes.
Vibe Feature MCP serves as a conversation coordinator that:
User: "implement auth"
↓
LLM: calls whats_next()
↓
Responsible-Vibe-MCP: analyzes context → determines phase → returns instructions
↓
LLM: follows instructions → interacts with user → updates plan file
↓
LLM: calls whats_next() again
↓
[cycle continues...]
Responsible-Vibe-MCP implements a plan-file-centric information architecture with clear separation of responsibilities across different components:
| Component | Responsibility | Information Type | Maintenance |
|---|---|---|---|
| System Prompt | Generic workflow guidance | How to use the system | Static |
| Tool Descriptions | Generic tool usage | What each tool does | Static |
| Tool Responses | Dynamic phase guidance | What to do right now | Dynamic |
| Plan File | Project context & tasks | What we've done/decided | LLM-maintained |
System Prompt: "How to use tools"
Tool Descriptions: "What tools do" (generic)
Tool Responses: "Check plan file section X, work on tasks Y, Z" (specific)
Plan File: "[ ] Task 1 [x] Task 2 Decision: chose approach A" (tracking)
graph TB
subgraph "Vibe Feature MCP Server"
CM[Conversation Manager]
TM[Transition Engine]
IM[Instruction Generator]
PM[Plan Manager]
DB[(SQLite Database)]
end
subgraph "Development Phases"
IDLE[Idle]
REQ[Requirements]
DES[Design]
IMP[Implementation]
QA[Quality Assurance]
TEST[Testing]
COMP[Complete]
end
subgraph "Persistent Storage"
DBFILE[~/.responsible-vibe-mcp/db.sqlite]
PF[Project Plan Files]
GIT[Git Repository Context]
end
subgraph "LLM Client"
LLM[LLM Application]
USER[User]
CWD[Current Working Directory]
end
USER --> LLM
LLM --> CM
CM --> DB
CM --> TM
TM --> IM
IM --> PM
DB --> DBFILE
PM --> PF
CM --> GIT
IDLE --> TM
REQ --> TM
DES --> TM
IMP --> TM
QA --> TM
TEST --> TM
COMP --> TM
IM --> LLM
The Conversation Manager handles conversation identification, state persistence, and coordination between components.
Responsibilities:
Key Features:
The Transition Engine manages the development state machine and determines appropriate phase transitions.
Responsibilities:
Key Features:
The Instruction Generator creates phase-specific guidance for the LLM based on current conversation state.
Responsibilities:
Key Features:
The Plan Manager handles the creation, updating, and maintenance of project development plan files.
Responsibilities:
Key Features:
The database provides persistent storage for conversation state and metadata.
Schema Design:
Key Features:
sequenceDiagram
participant User as User
participant LLM as LLM
participant SM as State Manager
participant CM as Conversation Manager
participant DB as SQLite Database
participant TM as Transition Engine
participant IM as Instruction Generator
participant PM as Plan Manager
participant FS as File System
User->>LLM: "implement auth"
LLM->>CM: whats_next(context, user_input, conversation_summary, recent_messages)
Note over LLM,CM: Server stores NO message history - LLM provides context
CM->>FS: detect project path + git branch
CM->>DB: lookup/create conversation state
DB-->>CM: conversation state (phase, plan path only)
CM->>TM: analyze phase transition
TM->>TM: analyze LLM-provided context
TM->>TM: evaluate current phase
TM-->>CM: phase decision
CM->>IM: generate instructions
IM->>DB: get project context
IM-->>CM: phase-specific instructions
CM->>PM: update plan file path
PM-->>CM: plan file location
CM->>DB: update conversation state (phase only)
CM-->>LLM: instructions + metadata
LLM->>User: follow instructions
LLM->>FS: update plan file
Note over User,FS: Cycle continues with each user interaction
User Input → Project Detection → Git Branch Detection → Conversation ID Generation → Database Lookup
Conversation ID → State Retrieval → Context Analysis → Phase Determination → State Update → Persistence
Current Phase → Project Context → Conversation History → Instruction Template → Customized Instructions
Project Path → Branch Detection → Plan File Path → Content Generation → File Updates → Progress Tracking
whats_next tool interfaceThe server operates as a state machine that transitions between development phases. While the diagram shows the typical linear progression, users can transition directly to any phase at any time using the proceed_to_phase tool
For a comprehensive reference of all state transitions, including detailed instructions and transition reasons, see TRANSITIONS.md.
The server includes comprehensive logging with configurable levels for debugging, monitoring, and troubleshooting:
Set the log level using the LOG_LEVEL environment variable:
# Debug level (most verbose)
LOG_LEVEL=DEBUG npx tsx src/index.ts
# Production level
LOG_LEVEL=INFO node dist/index.js
For detailed logging documentation, see LOGGING.md.
The server manages five core development phases, each with specific guidance:
The server ensures the LLM maintains a living development plan document:
Development must be explicitly initiated using the start_development tool, which allows users to select their preferred workflow:
start_development({ workflow: "waterfall" })
Available workflows include:
.vibe/state-machine.yamlImportant: The
start_developmenttool must be called before any other tools (whats_next,proceed_to_phase,resume_workflow). This ensures that development follows a deliberate workflow selection process.
After development has been started, the responsible-vibe-mcp server guides users through a structured development process using a two-tool approach that gives users full control over phase transitions:
whats_nextwhats_next() after each user interactionproceed_to_phasewhats_next() suggests moving forwardproceed_to_phase() to explicitly transition to the next phaseflowchart TD
A[User Request] --> B[LLM calls whats_next]
B --> C{Phase Complete?}
C -->|No| D[Continue Current Phase]
D --> E[Follow Phase Instructions]
E --> F[Update Plan File]
F --> G[User Interaction]
G --> B
C -->|Yes| H[Suggest Phase Transition]
H --> I{User Ready?}
I -->|No| D
I -->|Yes| J[LLM calls proceed_to_phase]
J --> K[Transition to Next Phase]
K --> B
User: "I want to implement user authentication"
LLM: *calls whats_next()*
responsible-vibe-mcp: "New feature detected. Starting requirements analysis. Ask the user clarifying questions about WHAT they need for authentication..."
LLM: *asks clarifying questions, updates plan file*
LLM: *calls whats_next()*
responsible-vibe-mcp: "Continue requirements gathering. You still need to clarify password policies and session management..."
LLM: *completes all requirements tasks*
LLM: *calls whats_next()*
responsible-vibe-mcp: "All requirements tasks are complete! ✅ You can proceed to design phase using 'proceed_to_phase' tool, or continue refining requirements if needed."
LLM: "Great! We've covered all authentication requirements. Let's move to design."
LLM: *calls proceed_to_phase(target_phase: "design", reason: "requirements complete")*
responsible-vibe-mcp: "Transitioning to design phase. Help the user design the technical solution. Ask about architecture, technologies, and quality goals..."
Each phase is considered complete when:
Users can always choose to:
proceed_to_phase to return to earlier phases if issues are discoveredThis approach ensures users maintain full control over the development process while receiving structured guidance from responsible-vibe-mcp.
development-planplan://currentconversation-statestate://currentwhats_nextThe primary tool that analyzes conversation state and provides LLM instructions.
Parameters:
context (string, optional): Additional context about current conversationuser_input (string, optional): Latest user input for analysisconversation_summary (string, optional): LLM-provided summary of the conversation so farrecent_messages (array, optional): Array of recent conversation messages that LLM considers relevantReturns:
phase (string): Current development phaseinstructions (string): Detailed instructions for the LLMplan_file_path (string): Path to the plan file to updatetransition_reason (string): Why this phase was chosencompleted_tasks (array): Tasks that should be marked as completeproceed_to_phaseTool for explicitly transitioning to a new development phase when current phase is complete.
Parameters:
target_phase (string): The phase to transition to (depends on selected workflow - e.g., waterfall: requirements, design, implementation, qa, testing, complete; epcc: explore, plan, code, commit; minor-enhancement: explore, implement)reason (string, optional): Reason for transitioning nowReturns:
phase (string): New development phaseinstructions (string): Instructions for the new phaseplan_file_path (string): Path to the plan file to updatetransition_reason (string): Confirmation of phase transitionstart_developmentTool for beginning a new development project with a structured workflow. Must be called before any other development tools.
Parameters:
workflow (string): Choose your development workflow:
Returns:
phase (string): Initial development phaseinstructions (string): Instructions for the initial phaseplan_file_path (string): Path to the plan fileconversation_id (string): Unique conversation identifierworkflow (object): State machine object with workflow detailsresume_workflowTool for resuming development workflow after conversation compression. Returns comprehensive project context, current state, system prompt instructions, and next steps to seamlessly continue development.
Parameters:
include_system_prompt (boolean, optional): Whether to include system prompt instructions (default: true)simple_prompt (boolean, optional): Whether to use simplified system prompt when included (default: true)Returns:
workflow_status: Current conversation and project state information
conversation_id: Unique conversation identifiercurrent_phase: Current development phase from databaseproject_path: Absolute project pathgit_branch: Current git branchstate_machine: State machine information and available phasesplan_status: Plan file analysis and status
exists: Whether plan file existspath: Path to plan fileanalysis: Extracted tasks, decisions, and progress (if file exists)system_prompt: Complete system prompt instructions (if requested)recommendations: Phase-specific next steps and guidance
immediate_actions: Recommended next actionsphase_guidance: Current phase-specific guidancepotential_issues: Potential issues to be aware ofgenerated_at: Timestamp when response was generatedtool_version: Tool version for compatibility trackingUsage:
// Get complete workflow resumption info (recommended)
resume_workflow()
// Get workflow info without system prompt
resume_workflow({ include_system_prompt: false })
// Get workflow info with verbose system prompt
resume_workflow({ simple_prompt: false })
When to use:
reset_developmentTool for resetting conversation state and development progress. This permanently deletes conversation state and plan file, while soft-deleting interaction logs for audit trail.
Parameters:
confirm (boolean, required): Must be true to execute reset - prevents accidental resetsreason (string, optional): Optional reason for reset (for logging and audit trail)Returns:
success (boolean): Whether reset was successfulreset_items (array): List of items that were deleted/resetconversation_id (string): The conversation that was resetmessage (string): Human-readable result messageReset Behavior:
Usage:
// Reset development with confirmation
reset_development({ confirm: true })
// Reset with reason for audit trail
reset_development({
confirm: true,
reason: "Starting new feature approach"
})
When to use:
Safety Features:
confirm: true parameter to prevent accidental executionphase-guidanceProvides detailed guidance prompts for specific development phases.
Arguments:
phase (string): Development phase namecontext (string): Additional context or specific questionssequenceDiagram
participant User as User
participant LLM as LLM
participant Server as Vibe Feature MCP
participant FS as File System
User->>LLM: "implement auth"
LLM->>Server: whats_next(context: "user wants auth")
Server->>FS: Check conversation state
FS-->>Server: No existing state
Server->>Server: Transition to "requirements"
Server-->>LLM: "Analyze user's auth request. Ask clarifying questions about WHAT they need. Break down into tasks in plan file. Mark completed tasks."
LLM->>User: Ask clarifying questions about auth
User->>LLM: Provides requirements details
LLM->>FS: Update plan file with tasks
LLM->>Server: whats_next(context: "gathered requirements")
Server->>FS: Check progress & conversation
Server->>Server: Requirements complete? → Transition to "design"
Server-->>LLM: "Help user design technical solution. Ask about quality goals & technologies. Update plan file. Mark completed requirements tasks."
loop Development Flow
LLM->>User: Follow phase instructions
User->>LLM: Respond with information
LLM->>FS: Update plan file & mark completed tasks
LLM->>Server: whats_next(context: "current progress")
Server->>Server: Evaluate progress & determine next phase
Server-->>LLM: Phase-specific instructions + "Update completed tasks"
end
User: "I need to implement user authentication for my web app"
LLM: *calls whats_next(context: "user wants auth", user_input: "implement user authentication")*
Responsible-Vibe-MCP Response:
{
"phase": "requirements",
"instructions": "Analyze the user's authentication request. Ask clarifying questions about WHAT they need: What type of authentication? What user data? What security requirements? Break down their needs into specific tasks and add them to the development plan file at ./auth-feature-plan.md. Mark any completed requirements tasks as you progress.",
"plan_file_path": "./auth-feature-plan.md",
"transition_reason": "New feature request detected, starting requirements analysis",
"completed_tasks": []
}
LLM: "I'll help you implement authentication! Let me understand your requirements better:
1. What type of authentication do you need? (email/password, social login, multi-factor?)
2. What user information do you want to store?
3. Do you have any specific security requirements?
4. What's your current tech stack?
*[Creates ./auth-feature-plan.md with initial authentication tasks]*"
User: "I need email/password auth with optional Google login. Store email, name, and profile picture. Using React frontend with Node.js backend."
LLM: *calls whats_next(context: "user clarified basic auth requirements", user_input: "email/password + Google, React/Node stack", conversation_summary: "User wants to implement authentication for web app, clarified basic requirements")*
Responsible-Vibe-MCP Response:
{
"phase": "requirements",
"instructions": "Continue gathering requirements. Ask about password policies, session management, user roles, forgot password flow, data validation. Update the plan file with detailed requirements. Mark basic requirements gathering as complete.",
"plan_file_path": "./auth-feature-plan.md",
"transition_reason": "Still in requirements phase, need more details",
"completed_tasks": ["basic_auth_type_identified", "tech_stack_confirmed"]
}
LLM: "Great! Let me gather a few more details:
1. Any password complexity requirements?
2. How long should user sessions last?
3. Do you need user roles/permissions?
4. Need forgot password functionality?
5. Any specific validation rules for user data?
*[Updates plan file marking basic requirements as complete, adds detailed requirement tasks]*"
User: "Standard password rules, 24-hour sessions, just basic user role for now, yes to forgot password, standard email validation."
LLM: *calls whats_next(context: "requirements seem complete", user_input: "password rules, 24h sessions, basic roles, forgot password, email validation")*
Responsible-Vibe-MCP Response:
{
"phase": "requirements",
"instructions": "All requirements tasks are complete! ✅ You have documented: authentication type, user data, security requirements, tech stack, password policies, session management, user roles, and forgot password flow. You can proceed to design phase using 'proceed_to_phase' tool, or continue refining requirements if needed.",
"plan_file_path": "./auth-feature-plan.md",
"transition_reason": "All requirements tasks completed",
"completed_tasks": ["requirements_documented", "user_confirmed_scope", "security_requirements_defined", "technical_constraints_identified"]
}
LLM: "Perfect! We've covered all the authentication requirements comprehensively. Let's move to the design phase."
LLM: *calls proceed_to_phase(target_phase: "design", reason: "requirements complete")*
Responsible-Vibe-MCP Response:
{
"phase": "design",
"instructions": "Help the user design the technical solution. Ask about database schema, API endpoints, security measures (JWT, bcrypt), third-party services for Google auth, error handling strategies. Ask about quality goals and specific technologies they prefer. Update the plan file with design decisions and mark completed requirements tasks as done.",
"plan_file_path": "./auth-feature-plan.md",
"transition_reason": "Explicit transition to design phase",
"completed_tasks": []
}
LLM: "Perfect! Now let's design the technical solution:
**Database Design:**
- Users table: id, email, password_hash, name, profile_picture, google_id, role, created_at
- Sessions table: id, user_id, token, expires_at
**API Endpoints:**
- POST /auth/register
- POST /auth/login
- POST /auth/google
- POST /auth/forgot-password
- POST /auth/reset-password
- GET /auth/me
- POST /auth/logout
**Security Measures:**
- JWT tokens for session management
- bcrypt for password hashing
- Input validation and sanitization
Do you approve this design? Any changes needed?
*[Updates plan file with design details, marks requirements tasks as complete]*"
User: "Yes, looks good. Let's implement it."
LLM: *calls whats_next(context: "design approved by user", user_input: "approved design, ready to implement")*
Responsible-Vibe-MCP Response:
{
"phase": "design",
"instructions": "All design tasks are complete! ✅ You have defined the architecture, database schema, API endpoints, and security measures. You can proceed to implementation phase using 'proceed_to_phase' tool, or continue refining the design if needed.",
"plan_file_path": "./auth-feature-plan.md",
"transition_reason": "All design tasks completed",
"completed_tasks": ["architecture_defined", "database_schema_designed", "api_endpoints_planned", "security_measures_defined"]
}
LLM: "Excellent! The design is solid and approved. Let's move to implementation."
LLM: *calls proceed_to_phase(target_phase: "implementation", reason: "design complete and approved")*
Responsible-Vibe-MCP Response:
{
"phase": "implementation",
"instructions": "Guide the user through implementing the authentication system. Start with backend setup (user model, middleware, API endpoints), then frontend components. Follow coding best practices, include proper error handling, and write basic tests. Update the plan file with implementation progress and mark completed design tasks.",
"plan_file_path": "./auth-feature-plan.md",
"transition_reason": "Explicit transition to implementation phase",
"completed_tasks": []
}
LLM: "Let's implement this step by step:
**Step 1: Backend Setup**
First, let's set up the user model and authentication middleware...
```javascript
// User model
const userSchema = new mongoose.Schema({
email: { type: String, required: true, unique: true },
password_hash: { type: String, required: true },
name: { type: String, required: true },
profile_picture: String,
google_id: String,
role: { type: String, default: 'user' }
});
Step 2: JWT Middleware Here's the authentication middleware...
[Continues with implementation guidance, updates plan file]"
[Process continues through implementation, QA, and testing phases...]
To properly integrate with responsible-vibe-mcp, the LLM should be configured with a system prompt that establishes the interaction pattern. The key requirement for the stateless approach is that the LLM must provide conversation context when calling whats_next().
When calling whats_next(), the LLM should provide:
This stateless approach ensures that responsible-vibe-mcp can make informed decisions about phase transitions without storing potentially inconsistent conversation history.
For a complete system prompt template, see SYSTEM_PROMPT.md.
Vibe Feature MCP includes a comprehensive interaction logging system that records all tool calls and responses for debugging and analysis purposes:
whats_next and proceed_to_phase toolsAll interaction logs are stored in the local SQLite database in the .vibe directory of your project. The data is stored without masking or filtering, as it is kept locally on your system.
Logs can be queried by conversation ID for analysis and debugging purposes. No UI is provided in the current implementation, but the database can be accessed directly using SQLite tools.
Note: All interaction data is stored locally on your system and is never transmitted to external services.
The project includes comprehensive test coverage with different test execution options to balance thoroughness with development speed:
npm test # Interactive test runner
npm run test:run # Single test run (quiet, no noisy tests)
npm run test:all # Run all tests including noisy ones
npm run test:noisy # Run only the noisy MCP contract test
npm run test:mcp-contract # Run MCP contract test (with custom state machine check)
npm run test:ui # Interactive test UI
The test setup automatically:
LOG_LEVEL=ERROR for clean output during testingNODE_ENV=test, VITEST=true)INCLUDE_NOISY_TESTS=trueThe MCP contract test spawns actual server processes and uses the MCP SDK, which:
By excluding it from the default test run, developers get:
npm run test:allFAQs
A Model Context Protocol server that acts as an intelligent conversation state manager and development guide for LLMs
We found that @mrsimpson/responsible-vibe-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket Firewall Enterprise is now available with flexible deployment, configurable policies, and expanded language support.
Security News
Open source dashboard CNAPulse tracks CVE Numbering Authorities’ publishing activity, highlighting trends and transparency across the CVE ecosystem.
Product
Detect malware, unsafe data flows, and license issues in GitHub Actions with Socket’s new workflow scanning support.