MCP Vibe Agent

---

Table of Contents

• Project Overview
• Features & Capabilities
• Installation
• Quick Start
• Detailed Usage
  • CLI Usage
  • Python API Usage
  • Jupyter Integration
  • Multi-Agent Orchestration
  • RAG, LLM, and Tool Integration
  • Quality, Security, and Refactoring
  • Memory, Vector Store, and Session Management
  • Web Server and API
  • Professional CLI
  • Example Workflows
• Configuration
• Testing & Linting
• Contributing
• Community & Support
• Citation
• License
• Changelog & Versioning
• Acknowledgements
• Further Reading & Tutorials

---

Project Overview

MCP Vibe Agent is a modular, extensible, and production-ready multi-agent framework for code generation, refactoring, documentation, testing, security, and more. It integrates state-of-the-art LLMs (Google Gemini, OpenAI, Groq, Anthropic, etc.), retrieval-augmented generation (RAG), memory, vector stores, and a rich set of tools for professional software development and research.

• Multi-agent orchestration for collaborative workflows
• Retrieval-augmented generation (RAG) for context-aware code and documentation
• Integrated LLM support (Google, OpenAI, Groq, Anthropic, custom)
• Quality, security, and refactoring agents
• Jupyter, CLI, and web server integration
• Memory, vector store, and session management
• Professional CLI and benchmarking tools

---

Features & Capabilities

High-Level Features

• Modular agent architecture (code generation, refactoring, testing, security, documentation, etc.)
• Multi-agent system with orchestration and workflow management
• RAG (Retrieval-Augmented Generation) for context-aware LLM outputs
• LLM integration: Google Gemini, OpenAI, Groq, Anthropic, custom providers
• Quality checking, code review, and benchmarking
• Secure sandboxed code execution and retry system
• Memory management: session, vector, and document memory
• Web server and API for remote access
• Jupyter notebook magic commands and integration
• Professional CLI for advanced workflows
• Extensible tool registry and plugin system

Detailed Module Breakdown

• mcp_vibe_agent/agents/: Specialized agents for code generation, refactoring, debugging, documentation, security, and testing
• mcp_vibe_agent/core/: Core agent logic, multi-agent system, decision engine, execution engine, memory, and loop
• mcp_vibe_agent/llms/: LLM manager, provider clients, model configs, and key management
• mcp_vibe_agent/rag/: RAG system for project context grounding
• mcp_vibe_agent/quality/: Quality checker, diff generator, file tracker, and test generator
• mcp_vibe_agent/execution/: Retry system and sandboxed code executor
• mcp_vibe_agent/memory/: Memory manager, session manager, and vector store
• mcp_vibe_agent/terminal/: Terminal interface, agent terminal, and interactive shell
• mcp_vibe_agent/web/: Web server, session manager, authentication, and websocket support
• mcp_vibe_agent/jupyter/: Jupyter magic commands and notebook interface
• mcp_vibe_agent/v2/: Advanced orchestration, RBAC, audit logging, and enhanced LLM support
• mcp_vibe_agent/tools/: Tool registry, execution tools, file manager, package manager, and web search
• mcp_vibe_agent/ui/: Model selector and UI utilities
• mcp_vibe_agent/utils/: Logging, config, error handling, and metrics

---

Installation

Requirements

• Python 3.8+
• pip (or conda)
• (Optional) Jupyter Notebook/Lab for notebook integration

Install from PyPI

pip install mcp-vibe-agent

Install from Source

git clone https://github.com/your-org/your-repo.git
cd your-repo
pip install -e .

Install Extra Dependencies

For Jupyter, web, or advanced features:

pip install mcp-vibe-agent[jupyter,web]

---

Quick Start

Minimal Example

from mcp_vibe_agent import VibeAgent
agent = VibeAgent(llm="google")
response = await agent.chat("Generate a Python function to compute factorial.")
print(response)

CLI Example

python -m mcp_vibe_agent.cli --task "Refactor this code for readability" --file my_script.py

---

Detailed Usage

CLI Usage

• Run python -m mcp_vibe_agent.cli --help for all options
• Example: python -m mcp_vibe_agent.cli --task "Generate tests" --file my_module.py

Python API Usage

• Import agents, tools, and managers from mcp_vibe_agent
• See examples/ for full scripts

Jupyter Integration

• Load magic commands:

  %load_ext mcp_vibe_agent.jupyter.magic_commands
  %vibe_init --llm google
  %%vibe
  Write a function to reverse a string in Python

• See Jupyter Notebook Basics

Multi-Agent Orchestration

• Use CrewAIOrchestrator and CrewAIAgent for workflow automation
• Example:

  from mcp_vibe_agent.v2.crewai_integration import CrewAIAgent, CrewAIOrchestrator
  agents = [CrewAIAgent("coder", "Write code", "", llm_manager)]
  orchestrator = CrewAIOrchestrator(agents)
  tasks = [{"agent": "coder", "description": "Implement a REST API"}]
  results = await orchestrator.run_workflow(tasks)

RAG, LLM, and Tool Integration

• Use RAGEnhancedAgent for context-aware code and documentation
• Integrate with Google, OpenAI, Groq, Anthropic, or custom LLMs
• Register and use custom tools via the tool registry

Quality, Security, and Refactoring

• Use QualityChecker, SecurityAgent, and RefactorAgent for code review and improvement
• Example:

  from mcp_vibe_agent.quality.quality_checker import QualityChecker
  checker = QualityChecker()
  result = await checker.check_code("def foo(): pass")
  print(result)

Memory, Vector Store, and Session Management

• Use MemoryManager, VectorStore, and SessionManager for advanced memory and retrieval
• Example:

  from mcp_vibe_agent.memory.memory_manager import MemoryManager
  memory = MemoryManager()
  session = memory.get_session("my-session")
  memory.add_message("my-session", "user", "Hello!")

Web Server and API

• Start the web server:

  python -m mcp_vibe_agent.web.server

• Access the web UI at http://localhost:8000
• Use REST API endpoints for remote access

Professional CLI

• Use professional_cli.py for advanced workflows, benchmarking, and evaluation
• Example:

  python -m mcp_vibe_agent.professional_cli --task "Benchmark code quality"

Example Workflows

• See examples/ for:
  • Code generation and execution
  • Integrated workflow with RAG, quality, and retry
  • Jupyter notebook usage
  • MCP server integration
  • Simple usage scripts

---

Configuration

API Keys

• Store API keys in ~/.mcp_vibe_agent/api_keys.json or set environment variables:
  • GOOGLE_API_KEY, OPENAI_API_KEY, GROQ_API_KEY, ANTHROPIC_API_KEY
• Use the APIKeyManager to manage keys programmatically

Settings

• Edit mcp_vibe_agent/config/settings.py for global settings
• Use environment variables for overrides

Customization

• Register custom tools, agents, or LLM providers via the plugin system
• Extend or override agent behaviors by subclassing

---

Testing & Linting

Running Tests

pytest

Linting

• Use Pylint for static analysis:

  pylint mcp_vibe_agent/

• Use flake8 or black for style and formatting

---

Contributing

We welcome contributions! Please see the following guidelines:

• Fork the repository and create a feature branch
• Write clear, well-documented code and tests
• Run tests and lint before submitting a pull request
• Follow the Code of Conduct
• See pyOpenSci README best practices

---

Community & Support

• GitHub Issues for bug reports and feature requests
• Discussions for Q&A and ideas
• Email Support
• Documentation

---

Citation

If you use MCP Vibe Agent in your research, please cite:

@software{mcp_vibe_agent,
  author = {Your Name and Contributors},
  title = {MCP Vibe Agent: Modular Multi-Agent Framework for LLM-Driven Code Generation and Analysis},
  year = {2025},
  url = {https://github.com/your-org/your-repo},
  version = {1.0.0}
}

---

License

This project is licensed under the MIT License. See LICENSE for details.

---

Changelog & Versioning

See CHANGELOG.md for release notes and version history.

---

Acknowledgements

• Jupyter Project
• OpenAI, Google Gemini, Groq, Anthropic
• pyOpenSci
• Pylint
• All contributors and users

---

Further Reading & Tutorials

• Jupyter Notebook Basics
• How to Write a Great README
• Pylint Documentation
• Ultimate Project README Example
• Saturn Cloud: Jupyter Notebook Run All Cells Guide

---

For more, see the docs/ directory or visit our documentation site.