Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (responsible-vibe-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Responsible Vibe MCP Server

An intelligent conversation coordinator for AI coding agents that provides structured development workflows through the Model Context Protocol (MCP).

What is Responsible Vibe MCP?

Responsible Vibe MCP transforms your AI coding agent into a structured development partner that:

Guides Development Workflows: Takes you through proven development phases (requirements → design → implementation → testing)
Maintains Project Memory: Keeps track of decisions, progress, and context across conversations
Provides Phase-Specific Guidance: Tells your AI exactly what to focus on at each development stage
Manages Project Documentation: Creates and maintains architecture, requirements, and design documents

Quick Start

🚀 1-Command Setup

Choose your AI coding agent and run the setup command:

# For Amazon Q CLI
npx responsible-vibe-mcp --generate-config amazonq-cli

# For Claude Code
npx responsible-vibe-mcp --generate-config claude

# For Gemini CLI
npx responsible-vibe-mcp --generate-config gemini

This automatically creates all necessary configuration files with the correct system prompt and MCP server settings.

✅ Verify Setup

Start a conversation with your AI agent and ask:

"Help me implement a new feature"

Your agent should automatically call MCP tools and guide you through a structured development process.

How It Works

flowchart LR
    A[You] --> B[AI Agent]
    B --> C[responsible-vibe-mcp]
    C --> D[Development Plan]
    C --> E[Project Docs]

    style C fill:#e1f5fe

You interact with your AI coding agent normally
AI agent calls responsible-vibe-mcp tools automatically (via system prompt)
MCP server provides phase-specific guidance and maintains project context
Development progresses through structured workflows with persistent memory

Example Development Flow

You: "I need user authentication for my app"

AI Agent: *calls whats_next() automatically*
↓
MCP Server: "Start requirements phase. Ask about auth type, user data, security needs..."
↓
AI Agent: "Let me understand your requirements:
1. What type of authentication? (email/password, social login, etc.)
2. What user information do you need to store?
3. Any specific security requirements?"

[Conversation continues through requirements → design → implementation → testing]

Available Workflows

waterfall: Full-featured development (requirements → design → implementation → QA → testing)
epcc: Explore → Plan → Code → Commit (Anthropic's methodology)
bugfix: Reproduce → Analyze → Fix → Verify
minor: Streamlined for small changes
greenfield: New projects from scratch
custom: Define your own in .vibe/workflow.yaml

Key Features

🧠 Long-Term Memory: Project context survives across conversations and restarts
📋 Structured Workflows: Proven development methodologies built-in
📚 Smart Documentation: Auto-generates and maintains project docs
🔄 Phase Transitions: Clear progression through development stages
🎯 Contextual Guidance: AI gets specific instructions for each phase
🔧 Git Integration: Optional automatic commits with configurable behavior
👥 Review System: Optional quality gates before phase transitions

Requirements

Node.js 18.0.0+
AI Coding Agent (Amazon Q, Claude, Gemini, etc.)
Git repository (optional, for commit features)

Manual Setup

If you prefer manual configuration:

1. Get System Prompt

npx responsible-vibe-mcp --system-prompt

2. Configure Your AI Agent

Add the system prompt to your AI agent's configuration.

3. Add MCP Server

Configure your agent to connect to npx responsible-vibe-mcp.

Documentation

📖 Complete documentation available at: https://mrsimpson.github.io/responsible-vibe-mcp/

Quick Links

Getting Started - Detailed setup for all agents
How It Works - Understanding the development flow
Workflows - Available development methodologies
Long-Term Memory - Project context and documentation system

Troubleshooting

Agent doesn't call MCP tools?

Verify system prompt is configured correctly
Check MCP server connection in agent settings

"Tool not found" errors?

Ensure npx responsible-vibe-mcp runs successfully
Restart your agent/IDE after configuration

Need help?

Check the troubleshooting guide
Test with MCP Inspector: npx @modelcontextprotocol/inspector

Contributing

This project uses conventional commits for version management:

# Install dependencies
npm install

# Run tests (always use --run flag)
npm run test:run

# Make changes with conventional commits
git commit -m "feat: add new feature"
git commit -m "fix: resolve issue"

See development documentation for detailed contributor information.