{"id":45157421,"url":"https://github.com/couchbase-examples/couchbase-google-mcp-toolbox-demo","last_synced_at":"2026-02-20T05:02:42.372Z","repository":{"id":308533398,"uuid":"1000086112","full_name":"couchbase-examples/couchbase-google-mcp-toolbox-demo","owner":"couchbase-examples","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-06T11:40:16.000Z","size":298,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"initial-code","last_synced_at":"2025-08-06T13:25:03.801Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-11T08:41:57.000Z","updated_at":"2025-08-06T11:40:19.000Z","dependencies_parsed_at":"2025-08-06T13:25:06.839Z","dependency_job_id":"132a92f3-751c-4e4c-8600-74ae56a6951a","html_url":"https://github.com/couchbase-examples/couchbase-google-mcp-toolbox-demo","commit_stats":null,"previous_names":["couchbase-examples/couchbase-google-mcp-toolbox-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/couchbase-google-mcp-toolbox-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fcouchbase-google-mcp-toolbox-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fcouchbase-google-mcp-toolbox-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fcouchbase-google-mcp-toolbox-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fcouchbase-google-mcp-toolbox-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/couchbase-google-mcp-toolbox-demo/tar.gz/refs/heads/initial-code","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fcouchbase-google-mcp-toolbox-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-20T05:02:37.989Z","updated_at":"2026-02-20T05:02:42.366Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CPG Manufacturing AI Assistant Demo with Google MCP Toolbox for Databases \u0026 Couchbase Integration\n\nA comprehensive demonstration of a Consumer Packaged Goods (CPG) manufacturing system that uses **Couchbase**, **LangGraph**, and **Google MCP Toolbox for Databases** to address unplanned production line downtime and reduce Mean Time To Resolution (MTTR).\n\n## 🌟 Key Features\n\nThis demo combines the **MCP Toolbox for Databases MCP (Multi-Collection Provider) server** with **Couchbase Vector Search** and **LangGraph** to deliver:\n\n- **🧰 Natural-Language Tool Access** – The MCP server turns every SQL query in `tools.yaml` into a REST/LLM-friendly tool that agents can invoke with plain English.\n- **🎯 Specialized Multi-Tool Agents** – Five specialized LangGraph ReAct agents (troubleshooting, maintenance, monitoring, performance, general) with router-based selection; troubleshooting and general agents additionally tap the manual semantic-search tool.\n- **🔍 Semantic Manual Search** – Vector embeddings let operators retrieve the most relevant manual snippets for a given issue (exposed only to the agents that need it).\n- **💾 Resilient State \u0026 Replay** – `langgraph-checkpointer-couchbase` persists every agent step in Couchbase so conversations can resume or be audited later.\n- **⚡ High Throughput** – Connection pooling, async I/O and caching across database, embeddings and tool calls keep latency low even under load.\n\n## 🏗️ Architecture Overview\n\n```mermaid\ngraph TD\n    subgraph \"API Layer\"\n        API[\"FastAPI Backend (api.py)\"]\n    end\n\n    subgraph \"Agent Orchestration (LangGraph)\"\n        ManufacturingAgent[\"A top-level graph routes the query to the\u003cbr/\u003eappropriate specialized agent for resolution.\"]\n    end\n\n    subgraph \"Tool Layer\"\n        direction TB\n        Toolbox[\"MCP Toolbox for Databases Tools\u003cbr/\u003e(SQL-based via MCP Server)\"]\n        ManualSearch[\"Manual Search Tool\u003cbr/\u003e(Vector Search)\"]\n    end\n    \n    subgraph \"Data \u0026 State Persistence\"\n        CouchbaseDB[\"Couchbase Database\"]\n        Checkpointer[\"AsyncCouchbaseSaver\u003cbr/\u003e(LangGraph Checkpointer)\"]\n    end\n\n    %% Connections\n    API -- \"sends OperatorQuery\" --\u003e ManufacturingAgent\n    ManufacturingAgent -- \"Uses Tools\" --\u003e Toolbox\n    ManufacturingAgent -- \"Uses Tools\" --\u003e ManualSearch\n    ManufacturingAgent -- \"Persists state\" --\u003e Checkpointer\n    \n    Toolbox --\u003e CouchbaseDB\n    ManualSearch --\u003e CouchbaseDB\n    Checkpointer -- \"R/W state\" --\u003e CouchbaseDB\n\n    %% Styling\n    classDef api fill:#e3f2fd,stroke:#1976d2,stroke-width:2px\n    classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n    classDef tools fill:#fff8e1,stroke:#f57c00,stroke-width:2px\n    classDef data fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n    \n    class API api\n    class ManufacturingAgent agent\n    class Toolbox,ManualSearch tools\n    class CouchbaseDB,Checkpointer data\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.9+\n- Couchbase Server 7.0+\n- Google API key (for Gemini and embeddings)\n- Machine manual PDF file named `manual.pdf` (optional)\n\n### 1. Install Dependencies\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/genai-rag.git\ncd genai-rag\n\n# Install Python dependencies\npip install -r requirements.txt\n```\n\nKey dependencies include:\n\n- `couchbase==4.4.0` for database connectivity\n- `langgraph==0.4.7` for agent orchestration\n- `langchain-google-genai\u003e=2.1.5` for Google AI integration\n- `toolbox-langchain==0.2.0` for MCP Toolbox for Databases integration\n- `langgraph-checkpointer-couchbase\u003e=1.0.6` for state persistence\n\n### 2. Configure Environment\n\nCreate a `.env` file:\n\n```bash\n# Couchbase Configuration\nCOUCHBASE_CONNECTION_STRING=couchbase://localhost\nCOUCHBASE_USERNAME=Administrator\nCOUCHBASE_PASSWORD=password\nCOUCHBASE_BUCKET_NAME=cpg_manufacturing\n\n# AI Configuration\nGOOGLE_API_KEY=your_google_api_key_here\n\n# Application Configuration\nAPP_NAME=CPG Manufacturing AI Assistant\nDEBUG=true\n```\n\n### 3. Initialize the System\n\n```bash\n# Run the system setup\npython -m setup.setup_system\n```\n\nThis will:\n\n- Set up Couchbase database collections and indexes\n- Generate realistic manufacturing sample data\n- Process the machine manual (if `manual.txt` or `manual.pdf` is present)\n- Initialize vector embeddings for manual search\n- Optimize alert solutions using AI-powered similarity detection and intelligent merging\n\n### 4. Start the MCP Toolbox for Databases MCP Server\n\nThe MCP Toolbox for Databases **MCP (Multi-Collection Provider) server** exposes all database tools defined in `tools.yaml`.  \nMake sure you have `tools.yaml` configured with the correct Couchbase connection string, username and password first.\n\n#### Install the MCP Toolbox Binary\n\nFirst, download and install the `genai-toolbox` binary:\n\n```bash\n Download binary directly from GitHub releases\n# Visit: https://github.com/googleapis/genai-toolbox/releases\n# Download the appropriate binary for your OS and add to PATH\n```\n\n#### Start the Server\n\n```bash\n# Start the server on port 5000\ngenai-toolbox --tools-file tools.yaml --port 5000\n```\n\nThe server will read `tools.yaml`, automatically register the data sources and REST endpoints, and start listening on `http://localhost:5000`.\n\n**Note:** Make sure the binary is in your `$PATH` so you can run `genai-toolbox` from any folder.\n\n### 5. Start the Backend API\n\n```bash\n# Start the FastAPI backend\nuvicorn api:app --reload\n```\n\nThe API will be available at `http://localhost:8000`\n\n### 6. Launch the Web Interface\n\n```bash\n# Start the Streamlit application\nstreamlit run streamlit_app.py\n```\n\nAccess the application at `http://localhost:8501`\n\n## 🛠️ Component Architecture\n\n### Database Manager\n\nThe `DatabaseManager` class handles all database connections:\n\n```python\nfrom src.db import DatabaseManager\n\n# Automatic initialization of:\n# - Synchronous Couchbase cluster\n# - Asynchronous Couchbase cluster  \n# - LangGraph checkpointer with AsyncCouchbaseSaver\ndb_manager = DatabaseManager()\nawait db_manager.initialize()\n```\n\n### Couchbase Manual Retriever\n\nSemantic search tool for machine manuals:\n\n```python\nfrom src.tools.couchbase_manual_retriever import create_couchbase_manual_tools\n\n# Creates LangChain tool for manual search using:\n# - Google Generative AI embeddings (text-embedding-004)\n# - Couchbase vector search\n# - Semantic similarity matching\nmanual_tool = create_couchbase_manual_tools(cluster)\n```\n\n### Enhanced Manufacturing Agent\n\nLangGraph-based agent with specialized toolsets:\n\n```python\nfrom src.agents.enhanced_manufacturing_agent import create_manufacturing_agent\n\n# Creates a StateGraph workflow with router node and specialized agent nodes\n# Router analyzes query_type and routes to appropriate ReAct agent\n# Each agent has specialized tools and system prompts for their domain\nagent = create_manufacturing_agent(\n    cluster=cluster,\n    checkpointer=checkpointer,\n    toolbox_url=\"http://127.0.0.1:5000\"\n)\n```\n\n## 🧰 MCP Toolbox for Databases Integration\n\n### Available Toolsets\n\nThe system includes specialized toolsets for different manufacturing scenarios:\n\n| Toolset | Agent Type | Description | Use Cases |\n|---------|-----------|-------------|-----------|\n| `troubleshooting` | Troubleshooting Agent | Issue diagnosis and resolution | Problem solving, root cause analysis |\n| `maintenance-planning` | Maintenance Agent | Schedule and history tracking | Preventive maintenance, planning |\n| `production-monitoring` | Monitoring Agent | Real-time line status and alerts | Dashboard overview, status monitoring |\n| `performance-analysis` | Performance Agent | Efficiency and metrics analysis | KPI monitoring, optimization |\n| `full-manufacturing-suite` | General Agent | Complete toolset access | Comprehensive analysis |\n\n### Database Tools Configuration\n\nThe `tools.yaml` file defines SQL-based tools for:\n\n- **Production Line Management**: Status, efficiency, output metrics\n- **Machine Management**: Details, parameters, specifications  \n- **Alert Management**: Active alerts, critical issues, machine-specific alerts\n- **Maintenance Management**: History, scheduling, overdue tasks\n- **Performance Analysis**: Line efficiency, facility overview\n\n### Sample Agent Queries\n\nThe system handles sophisticated queries like:\n\n- **Troubleshooting**: \"Machine MCH_001 is showing high temperature alerts. What should I check?\"\n- **Maintenance**: \"Show me all overdue maintenance tasks and upcoming scheduled work\"\n- **Monitoring**: \"What's the current status of all production lines?\"\n- **Performance**: \"Analyze efficiency trends for LINE_01 over the past week\"\n\n## 📊 Data Models and Collections\n\n### Couchbase Collections Structure\n\n```mermaid\nerDiagram\n    PRODUCTION_LINES ||--o{ MACHINES : contains\n    MACHINES ||--o{ ALERTS : generates\n    MACHINES ||--o{ MAINTENANCE : requires\n    PRODUCTION_LINES ||--o{ METRICS : produces\n    MANUALS ||--o{ MANUAL_CHUNKS : contains\n    ALERTS ||--o{ SOLUTIONS : derives\n```\n\n### Collection Types\n\n- **production_lines**: Production line status and configuration\n- **machines**: Machine details, parameters, and specifications\n- **alerts**: Active and historical alerts with severity levels\n- **maintenance**: Maintenance records, schedules, and history\n- **metrics**: Production metrics and performance data\n- **manuals**: Processed manual content with vector embeddings\n- **solutions**: AI-optimized manufacturing solutions with vector embeddings for semantic search\n\n## 🔧 Configuration\n\n### Database Configuration\n\nThe system uses a multi-collection Couchbase setup:\n\n```python\n# config.py\ncouchbase_collections = {\n    \"manuals\": \"manuals\",\n    \"machines\": \"machines\", \n    \"production_lines\": \"production_lines\",\n    \"alerts\": \"alerts\",\n    \"maintenance\": \"maintenance\",\n    \"metrics\": \"metrics\",\n    \"solutions\": \"solutions\"\n}\n```\n\n### Agent Configuration\n\nDifferent system prompts for specialized agents:\n\n- **Troubleshooting Agent**: Safety-first error resolution\n- **Maintenance Agent**: Proactive maintenance planning\n- **Monitoring Agent**: Real-time production visibility\n- **Performance Agent**: Data-driven efficiency analysis\n- **General Agent**: Comprehensive manufacturing support\n\n## 🎯 Use Cases Demonstrated\n\n### 1. Intelligent Troubleshooting\n\n- **Challenge**: Machine failures causing production stops\n- **Solution**: AI analyzes alerts, searches manuals, provides step-by-step resolution\n- **Benefits**: Reduces MTTR from hours to minutes with precise guidance\n\n### 2. Predictive Maintenance\n\n- **Challenge**: Unexpected equipment failures\n- **Solution**: AI correlates maintenance schedules with historical data\n- **Benefits**: Prevents failures through proactive maintenance scheduling\n\n### 3. Production Optimization\n\n- **Challenge**: Suboptimal line efficiency\n- **Solution**: AI analyzes performance trends and suggests improvements\n- **Benefits**: Increases Overall Equipment Effectiveness (OEE)\n\n### 4. Operator Knowledge Support\n\n- **Challenge**: Complex troubleshooting procedures\n- **Solution**: AI provides instant access to relevant manual sections\n- **Benefits**: Empowers operators with expert-level guidance\n\n## 🧪 Running the Demo\n\n### Complete Setup Process\n\n```bash\n# 1. Install dependencies\npip install -r requirements.txt\n\n# 2. Initialize database and generate sample data\npython -m setup.setup_system\n\n# 3. Start MCP Toolbox for Databases MCP Server (in separate terminal)\ngenai-toolbox --tools-file tools.yaml --port 5000\n\n# 4. Start backend API (in separate terminal)\nuvicorn api:app --reload --host 0.0.0.0 --port 8000\n\n# 5. Start web interface (in separate terminal)\nstreamlit run streamlit_app.py\n\n# Generate machine status report with alerts from last 24 hours\npython -m setup.list_machine_alerts\n\n# Generate report for custom time period (e.g., last 48 hours)\npython -m setup.list_machine_alerts 48\n```\n\n## 📈 Performance Metrics\n\nThe system tracks comprehensive metrics:\n\n- **Agent Performance**: Response time and accuracy\n- **Database Performance**: Query execution time and connection health\n- **Tool Usage**: MCP Toolbox for Databases tool execution statistics\n- **Manual Search**: Vector search relevance and speed\n- **System Health**: Overall availability and error rates\n\n### Monitoring Dashboard\n\nBuilt-in monitoring through Streamlit interface:\n\n```python\n# Performance metrics displayed in web interface\nsystem_metrics = {\n    \"api_response_time\": \"\u003c 500ms average\",\n    \"database_query_time\": \"\u003c 100ms average\", \n    \"agent_success_rate\": \"98%\",\n    \"manual_search_accuracy\": \"0.92 average\",\n    \"system_uptime\": \"99.5%\"\n}\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- **Google MCP Toolbox for Databases Team**: For the powerful database integration framework\n- **Couchbase**: For the scalable NoSQL database platform with vector search\n- **LangChain/LangGraph**: For the AI agent orchestration framework\n- **Google AI**: For the Gemini language model and embedding capabilities\n- **Sentence Transformers**: For additional embedding model support\n\n## 📚 Additional Resources\n\n- [Google MCP Toolbox for Databases Documentation](https://googleapis.github.io/genai-toolbox/)\n- [Couchbase Vector Search Documentation](https://docs.couchbase.com/server/current/vector-search/vector-search.html)\n- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)\n- [Google AI for Developers](https://ai.google.dev/)\n- [Streamlit Documentation](https://docs.streamlit.io/)\n\n---\n\n## Built with ❤️ for Manufacturing Excellence\n\nThis demo showcases how Google MCP Toolbox for Databases combined with Couchbase's powerful vector search capabilities revolutionizes manufacturing operations through intelligent, context-aware troubleshooting assistance. The modular architecture ensures scalability, maintainability, and seamless integration with enterprise manufacturing systems.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fcouchbase-google-mcp-toolbox-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Fcouchbase-google-mcp-toolbox-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fcouchbase-google-mcp-toolbox-demo/lists"}