{"id":"c9c64dfd-9046-40d8-a945-56eacac4d161","slug":"agents-mcp-system","kind":"mcp","name":"agents-mcp-system","summary":"Production-grade multi-agent collaboration framework powered by MCP orchestration, Ollama (local LLM), and Streamlit UI","owner":"maneeshkumar52","repoUrl":"https://github.com/maneeshkumar52/agents-mcp-system","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-04-18T05:28:42.000Z","addedAt":"2026-10-21T06:00:02.706Z","logoUrl":"https://avatars.githubusercontent.com/u/51368003?u=07c88034c61076fc469408969be2892f31ec5e8a&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","design-media","memory-knowledge"],"tags":["ai-agents","docker","llm","local-llm","multi-agent-system","ollama","python","streamlit"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T07:51:03.504Z","sample":false,"url":"https://conduits.dev/tools/agents-mcp-system","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n# 🤖 Agents MCP System\n\n**Production-Grade Multi-Agent Collaboration Framework**\n\n*Powered by Model Context Protocol  •  Ollama  •  Streamlit*\n\n[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://python.org)\n[![Streamlit](https://img.shields.io/badge/Streamlit-1.32+-FF4B4B?logo=streamlit&logoColor=white)](https://streamlit.io)\n[![Ollama](https://img.shields.io/badge/Ollama-Local_LLM-000000?logo=ollama&logoColor=white)](https://ollama.ai)\n[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?logo=docker&logoColor=white)](https://docker.com)\n[![Tests](https://img.shields.io/badge/Tests-71_passing-brightgreen?logo=pytest)](tests/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n</div>\n\n---\n\n## Executive Summary\n\nEnterprise-grade multi-agent system where four specialized AI agents collaborate through an **MCP-inspired orchestration pipeline** to solve complex business tasks — research, summarization, strategic planning, and professional reporting — all running **locally** via Ollama with zero cloud dependency.\n\nThe system includes **6 free MCP tool connectors** (file system, web search, SQLite database, ChromaDB vector store, date/time, calculator) that agents can invoke to access external resources during execution.\n\nEnter a business query (e.g., *\"Generate a compliance summary for HR policies\"*) and watch agents collaboratively produce a polished, executive-ready report in real time through the Streamlit UI.\n\n---\n\n## Architecture\n\n```\n                          ┌─────────────────────┐\n                          │     User Query       │\n                          └──────────┬──────────┘\n                                     │\n                                     ▼\n                    ┌──────────────────────────────────┐\n                    │         Streamlit UI              │\n                    │  (app.py)                         │\n                    │  • Task input & model config      │\n                    │  • Real-time pipeline viz          │\n                    │  • Markdown / PDF export           │\n                    └──────────────┬───────────────────┘\n                                   │\n                                   ▼\n                    ┌──────────────────────────────────┐\n                    │       MCP Orchestrator            │\n                    │  (orchestrator.py)                │\n                    │  • Pipeline sequencing            │\n                    │  • Shared AgentContext protocol    │\n                    │  • Tool Manager integration       │\n                    │  • Logging & error recovery        │\n                    └──────────────┬───────────────────┘\n                                   │\n              ┌────────────────────┼────────────────────┐\n              │                    │                     │\n              ▼                    ▼                     ▼\n  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐\n  │   Agent Layer     │  │  Tool Manager    │  │  Ollama Client   │\n  │                   │  │  (tool_manager)  │  │  (ollama_client)  │\n  │  🔍 Researcher    │  │                  │  │                   │\n  │  📋 Summarizer    │◄─┤  Connector Pool: │  │  • chat()          │\n  │  📐 Planner       │  │  📁 FileSystem   │  │  • embed()         │\n  │  💼 Communicator   │  │  🌐 WebSearch    │  │  • health_check()  │\n  └──────────────────┘  │  🗄️ SQLite DB    │  │  • list_models()   │\n                         │  🧠 ChromaDB     │  └──────────┬────────┘\n                         │  🕐 DateTime     │             │\n                         │  🧮 Calculator   │             ▼\n                         └──────────────────┘  ┌──────────────────┐\n                                                │   Ollama Server   │\n                                                │  (Local LLM)      │\n                                                │  llama3 · mistral  │\n                                                │  gemma · phi3      │\n                                                └──────────────────┘\n```\n\n---\n\n## Step-by-Step Flow: How Agents Interact with MCP\n\nThis section walks through **exactly what happens** when you submit a task, from UI input to final report.\n\n### Step 1: Task Submission\n\n```\nUser types: \"Generate a compliance summary for HR policies\"\n           → Clicks \"🚀 Execute Pipeline\"\n```\n\nThe Streamlit UI (`app.py`) captures the task and instantiates the `MCPOrchestrator`.\n\n### Step 2: Orchestrator Initialization\n\n```python\norchestrator = MCPOrchestrator()  # Loads config.yaml\n\n# What happens inside:\n# 1. Parses config.yaml → agent configs + tool configs\n# 2. Creates OllamaClient(base_url, timeout)\n# 3. Creates ToolManager → instantiates enabled connectors\n# 4. Creates agent instances in pipeline order:\n#    [ResearcherAgent, SummarizerAgent, PlannerAgent, CommunicatorAgent]\n```\n\n### Step 3: Pipeline Execution Begins\n\n```python\ncontext = AgentContext(task=\"Generate a compliance summary...\")\n# context holds: task, messages=[], artifacts={}, tool_results={}\n```\n\nThe orchestrator creates a **shared `AgentContext`** — this is the MCP-inspired \"context protocol\" that accumulates state as it flows through agents.\n\n### Step 4: Research Agent Executes\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 🔍 Research Agent                                        │\n│                                                          │\n│  1. Receives: AgentContext(task=\"Generate a compliance…\")│\n│  2. Builds prompt:                                       │\n│     system: \"You are a Research Agent specializing in…\"  │\n│     user: \"Research the following topic thoroughly…\"     │\n│  3. Calls: ollama_client.chat(model=\"llama3\", messages)  │\n│  4. Receives: ChatResponse(content=\"…findings…\")         │\n│  5. Appends to context:                                  │\n│     → context.messages += Message(role=\"agent\", …)       │\n│     → context.artifacts[\"Research Agent\"] = \"…findings…\" │\n│  6. Yields: (\"researcher\", message) → UI updates         │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Step 5: Summarizer Agent Executes\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 📋 Summarizer Agent                                      │\n│                                                          │\n│  1. Receives: AgentContext with research artifacts        │\n│  2. Reads: context.artifacts[\"Research Agent\"]            │\n│  3. Builds prompt:                                       │\n│     system: \"You are a Summarizer Agent…\"                │\n│     user: \"Summarize these findings… [research output]\"  │\n│  4. Calls Ollama → gets condensed summary                │\n│  5. Appends: context.artifacts[\"Summarizer Agent\"] = …   │\n│  6. Yields → UI shows summarizer output                  │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Step 6: Planner Agent Executes\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 📐 Planner Agent                                         │\n│                                                          │\n│  1. Receives: AgentContext with summary artifacts         │\n│  2. Reads: context.artifacts[\"Summarizer Agent\"]          │\n│  3. Creates: structured action plan with priorities       │\n│  4. Appends: context.artifacts[\"Planner Agent\"] = …      │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Step 7: Communicator Agent Produces Final Report\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ 💼 Communicator Agent                                     │\n│                                                          │\n│  1. Receives: AgentContext with ALL prior outputs         │\n│  2. Reads: context.get_conversation_history()             │\n│     → concatenates all agent contributions                │\n│  3. Synthesizes: polished executive report                │\n│  4. Output includes:                                     │\n│     • Executive Summary                                   │\n│     • Key Findings                                        │\n│     • Action Items                                        │\n│     • Next Steps                                          │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Step 8: Export & Display\n\n```\nPipeline complete!\n├── 📄 Report Tab → rendered Markdown\n├── 📥 Download Markdown → report_20240615_143022.md\n├── 📑 Download PDF → report_20240615_143022.pdf\n└── 📋 Logs Tab → timestamped execution log\n```\n\n---\n\n## How MCP Tool Connectors Work\n\nAgents can leverage **MCP tool connectors** to access external resources. The `ToolManager` loads enabled connectors from `config.yaml` and makes them available to the orchestration pipeline.\n\n### Tool Invocation Flow\n\n```\nAgent needs data\n       │\n       ▼\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│  Agent asks   │────▶│ ToolManager  │────▶│  Connector   │\n│  for tool     │     │  routes call │     │  executes    │\n│  execution    │     │              │     │              │\n└──────────────┘     └──────────────┘     └──────┬───────┘\n                                                  │\n       ┌──────────────────────────────────────────┘\n       ▼\n┌──────────────┐\n│  ToolResult  │ → success, output, metadata\n│  returned to │ → injected into AgentContext\n│  agent       │ → available to downstream agents\n└──────────────┘\n```\n\n### Available Connectors (All Free)\n\n| Connector | What It Does | Dependencies | API Key |\n|-----------|-------------|-------------|---------|\n| 📁 **FileSystem** | Read, list, and search files in a sandboxed directory | `pathlib` (built-in) | None |\n| 🌐 **WebSearch** | Query DuckDuckGo Instant Answer API for web results | `requests` | None |\n| 🗄️ **SQLite DB** | Run read-only SQL queries against a local database | `sqlite3` (built-in) | None |\n| 🧠 **ChromaDB** | Semantic similarity search over document embeddings | `chromadb>=0.4.22` | None |\n| 🕐 **DateTime** | Current time, timezone conversion, date arithmetic | `datetime` (built-in) | None |\n| 🧮 **Calculator** | Safe math expression evaluation (no `eval()`) | `ast` (built-in) | None |\n\n### Connector Configuration\n\nAll connectors are configured in `config.yaml`:\n\n```yaml\ntools:\n  filesystem:\n    enabled: true\n    params:\n      base_dir: \"data\"\n\n  web_search:\n    enabled: true\n    params: {}\n\n  database:\n    enabled: true\n    params:\n      db_path: \"data/knowledge.db\"\n\n  vector_store:\n    enabled: true\n    params:\n      collection_name: \"mcp_knowledge\"\n      persist_dir: \"data/chroma\"\n\n  datetime:\n    enabled: true\n    params: {}\n\n  calculator:\n    enabled: true\n    params: {}\n```\n\n### Security Features\n\n- **FileSystem**: Sandboxed to `data/` directory — path traversal attempts are blocked\n- **SQLite**: Read-only access — only `SELECT` queries allowed; `DROP`, `INSERT`, `UPDATE` rejected\n- **Calculator**: AST-based evaluation — no `eval()`, no code injection, exponent limit enforced\n- **WebSearch**: Uses only the public DuckDuckGo API — no credentials stored\n\n---\n\n## Agents\n\n| Agent | Role | What It Does |\n|-------|------|-------------|\n| 🔍 **Research Agent** | Information Gathering | Investigates the topic with comprehensive analysis, facts, and data points |\n| 📋 **Summarizer Agent** | Knowledge Distillation | Condenses research into concise, actionable insights with clear structure |\n| 📐 **Planner Agent** | Strategic Planning | Organizes insights into workflows with priorities, timelines, and dependencies |\n| 💼 **Communicator Agent** | Executive Reporting | Synthesizes all outputs into a polished, presentation-ready report |\n\nAll agents are **config-driven** — model, temperature, system prompt, and token limits are defined in `config.yaml`.\n\n---\n\n## Features\n\n- **MCP-Inspired Orchestration** — protocol-based agent communication with shared context accumulation\n- **6 Free MCP Tool Connectors** — file system, web search, SQLite, ChromaDB, datetime, calculator\n- **Local LLM Inference** — fully offline via Ollama (llama3, mistral, gemma, phi3)\n- **Real-Time Pipeline Visualization** — watch agents collaborate step-by-step in the Streamlit UI\n- **Export** — download final reports as Markdown or PDF\n- **Config-Driven Architecture** — YAML-based agent + tool definitions, no hardcoded paths\n- **Docker-Ready** — single-command deployment with Docker Compose\n- **Comprehensive Test Suite** — 71 tests covering agents, orchestrator, and all connectors\n- **Security-First** — sandboxed file access, read-only SQL, safe math evaluation\n- **Structured Logging** — timestamped session logs for debugging and audit\n\n---\n\n## Repository Structure\n\n```\nagents-mcp-system/\n├── app.py                     # Streamlit UI — task input, pipeline viz, export\n├── orchestrator.py            # MCP orchestration engine — pipeline + context\n├── ollama_client.py           # Ollama REST API wrapper — chat, embed, health\n├── tool_manager.py            # Tool connector registry and lifecycle manager\n├── utils.py                   # Logging, file storage, PDF export helpers\n├── config.yaml                # Agent + tool configuration (YAML)\n├── requirements.txt           # Pinned Python dependencies\n├── Dockerfile                 # Multi-stage container build\n├── docker-compose.yml         # Ollama + App orchestration\n├── agents/\n│   ├── __init__.py            # Agent registry\n│   ├── base.py                # BaseAgent ABC + Message/AgentContext protocol\n│   ├── researcher.py          # Research Agent implementation\n│   ├── summarizer.py          # Summarizer Agent implementation\n│   ├── planner.py             # Planner Agent implementation\n│   └── communicator.py        # Communicator Agent implementation\n├── connectors/\n│   ├── __init__.py            # Connector package exports\n│   ├── base.py                # MCPTool ABC + ToolResult dataclass\n│   ├── filesystem.py          # 📁 File system connector (sandboxed)\n│   ├── websearch.py           # 🌐 DuckDuckGo web search connector\n│   ├── database.py            # 🗄️ SQLite database connector (read-only)\n│   ├── vectorstore.py         # 🧠 ChromaDB vector store connector\n│   ├── datetime_tool.py       # 🕐 Date/time utilities connector\n│   └── calculator.py          # 🧮 Safe math expression evaluator\n├── tests/\n│   ├── test_agents.py         # Agent unit tests (15 tests)\n│   ├── test_orchestrator.py   # Orchestrator unit tests (11 tests)\n│   └── test_connectors.py     # Connector + ToolManager tests (45 tests)\n├── sample_tasks/\n│   ├── compliance_summary.txt # Sample: HR compliance analysis\n│   └── strategy_plan.md       # Sample: Go-to-market strategy\n├── data/                      # Tool data directory (sandboxed)\n├── outputs/                   # Generated reports (git-ignored)\n└── logs/                      # Session logs (git-ignored)\n```\n\n---\n\n## Prerequisites\n\n| Component | Version | Installation |\n|-----------|---------|-------------|\n| **Python** | 3.11+ | [python.org](https://python.org) |\n| **Ollama** | Latest | [ollama.ai](https://ollama.ai) |\n| **Docker** | 24+ | [docker.com](https://docker.com) *(optional)* |\n\n---\n\n## Quick Start\n\n### 1. Clone and Install\n\n```bash\ngit clone https://github.com/maneeshkumar52/agents-mcp-system.git\ncd agents-mcp-system\n\npython -m venv .venv\nsource .venv/bin/activate        # macOS/Linux\n# .venv\\Scripts\\activate         # Windows\n\npip install -r requirements.txt\n```\n\n### 2. Start Ollama\n\n```bash\n# Terminal 1 — start the Ollama server\nollama serve\n\n# Terminal 2 — pull a model (one-time)\nollama pull llama3\n```\n\n### 3. Launch the Application\n\n```bash\nstreamlit run app.py\n```\n\nOpen **http://localhost:8501** → enter a task → watch agents collaborate → download the report.\n\n---\n\n## Docker Deployment\n\n### Single Container\n\n```bash\ndocker build -t agents-mcp-system .\ndocker run -p 8501:8501 \\\n  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \\\n  agents-mcp-system\n```\n\n### Full Stack (Ollama + App)\n\n```bash\ndocker compose up -d\n\n# Pull a model into the containerized Ollama\ndocker compose exec ollama ollama pull llama3\n\n# Open http://localhost:8501\n```\n\n---\n\n## Configuration\n\nAll agent behavior is controlled via `config.yaml`:\n\n```yaml\nollama:\n  base_url: \"http://localhost:11434\"\n  default_model: \"llama3\"\n  timeout: 120\n\nagents:\n  researcher:\n    name: \"Research Agent\"\n    model: \"llama3\"\n    temperature: 0.3\n    max_tokens: 2048\n    system_prompt: |\n      You are a Research Agent specializing in ...\n\norchestration:\n  pipeline: [researcher, summarizer, planner, communicator]\n```\n\n**Customization options:**\n- Change `model` per agent to use different LLMs for different tasks\n- Adjust `temperature` for creativity vs. precision trade-offs\n- Modify `system_prompt` to specialize agents for your domain\n- Reorder or remove agents from the `pipeline` list\n\n---\n\n## Running Tests\n\n```bash\n# Run the full test suite (71 tests)\npytest tests/ -v\n\n# Run with coverage\npytest tests/ -v --tb=short\n```\n\nThe test suite uses mocked Ollama responses — **no running Ollama instance required** for testing.\n\n---\n\n## Usage Examples\n\n### Compliance Analysis\n```\nTask: \"Generate a comprehensive compliance summary for enterprise HR policies\n       covering GDPR, workplace safety, and anti-discrimination regulations.\"\n```\n\n### Go-to-Market Strategy\n```\nTask: \"Develop a Q3 go-to-market strategy for launching an AI-powered customer\n       support platform targeting mid-market SaaS companies.\"\n```\n\n### Technical Architecture Review\n```\nTask: \"Evaluate the microservices architecture of our e-commerce platform and\n       recommend improvements for scalability and reliability.\"\n```\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `ConnectionError: Cannot reach Ollama` | Ollama not running | Run `ollama serve` in a separate terminal |\n| `Model not found` | Model not pulled | Run `ollama pull llama3` (or your chosen model) |\n| `config.yaml not found` | Wrong working directory | Run `streamlit run app.py` from the project root |\n| Slow responses | Large model on limited hardware | Switch to a smaller model (`phi3`, `gemma:2b`) in `config.yaml` |\n| PDF export unavailable | `fpdf2` not installed | Run `pip install fpdf2` |\n\n---\n\n## Production Checklist\n\n- [ ] Pin Ollama model versions for reproducibility\n- [ ] Configure log rotation for `logs/` directory\n- [ ] Set up output archival for `outputs/` directory\n- [ ] Enable HTTPS via reverse proxy (nginx/Caddy) in production\n- [ ] Add authentication middleware for multi-user deployments\n- [ ] Monitor Ollama GPU/memory usage for capacity planning\n- [ ] Back up `config.yaml` in version control\n- [ ] Review tool connector permissions (file access scope, SQL query limits)\n- [ ] Populate the vector store with domain-specific documents\n- [ ] Configure DuckDuckGo rate limiting for high-traffic deployments\n\n---\n\n## Adding Custom Connectors\n\nCreate a new connector by extending `MCPTool`:\n\n```python\nfrom connectors.base import MCPTool, ToolResult\n\nclass MyCustomTool(MCPTool):\n    @property\n    def name(self) -> str:\n        return \"my_tool\"\n\n    @property\n    def description(self) -> str:\n        return \"Description shown to agents in their system prompt\"\n\n    def execute(self, **kwargs) -> ToolResult:\n        # Your tool logic here\n        return ToolResult(tool_name=self.name, success=True, output=\"result\")\n```\n\nThen register it in `tool_manager.py`:\n\n```python\nTOOL_REGISTRY[\"my_tool\"] = MyCustomTool\n```\n\nAnd add config in `config.yaml`:\n\n```yaml\ntools:\n  my_tool:\n    enabled: true\n    params: {}\n```\n\n---\n\n## License\n\nThis project is licensed under the MIT License — see [LICENSE](LICENSE) for details.\n"}