Agents Mcp System

🤖 Agents MCP System

Production-Grade Multi-Agent Collaboration Framework

Powered by Model Context Protocol • Ollama • Streamlit

[](https://python.org) [](https://streamlit.io) [](https://ollama.ai) [](https://docker.com) [](tests/) [](LICENSE)

---

Executive Summary

Enterprise-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.

The 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.

Enter 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.

---

Architecture

                          ┌─────────────────────┐
                          │     User Query       │
                          └──────────┬──────────┘
                                     │
                                     ▼
                    ┌──────────────────────────────────┐
                    │         Streamlit UI              │
                    │  (app.py)                         │
                    │  • Task input & model config      │
                    │  • Real-time pipeline viz          │
                    │  • Markdown / PDF export           │
                    └──────────────┬───────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────┐
                    │       MCP Orchestrator            │
                    │  (orchestrator.py)                │
                    │  • Pipeline sequencing            │
                    │  • Shared AgentContext protocol    │
                    │  • Tool Manager integration       │
                    │  • Logging & error recovery        │
                    └──────────────┬───────────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                     │
              ▼                    ▼                     ▼
  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
  │   Agent Layer     │  │  Tool Manager    │  │  Ollama Client   │
  │                   │  │  (tool_manager)  │  │  (ollama_client)  │
  │  🔍 Researcher    │  │                  │  │                   │
  │  📋 Summarizer    │◄─┤  Connector Pool: │  │  • chat()          │
  │  📐 Planner       │  │  📁 FileSystem   │  │  • embed()         │
  │  💼 Communicator   │  │  🌐 WebSearch    │  │  • health_check()  │
  └──────────────────┘  │  🗄️ SQLite DB    │  │  • list_models()   │
                         │  🧠 ChromaDB     │  └──────────┬────────┘
                         │  🕐 DateTime     │             │
                         │  🧮 Calculator   │             ▼
                         └──────────────────┘  ┌──────────────────┐
                                                │   Ollama Server   │
                                                │  (Local LLM)      │
                                                │  llama3 · mistral  │
                                                │  gemma · phi3      │
                                                └──────────────────┘

---

Step-by-Step Flow: How Agents Interact with MCP

This section walks through exactly what happens when you submit a task, from UI input to final report.

Step 1: Task Submission

User types: "Generate a compliance summary for HR policies"
           → Clicks "🚀 Execute Pipeline"

The Streamlit UI (app.py) captures the task and instantiates the MCPOrchestrator.

Step 2: Orchestrator Initialization

orchestrator = MCPOrchestrator()  # Loads config.yaml

# What happens inside:
# 1. Parses config.yaml → agent configs + tool configs
# 2. Creates OllamaClient(base_url, timeout)
# 3. Creates ToolManager → instantiates enabled connectors
# 4. Creates agent instances in pipeline order:
#    [ResearcherAgent, SummarizerAgent, PlannerAgent, CommunicatorAgent]

Step 3: Pipeline Execution Begins

context = AgentContext(task="Generate a compliance summary...")
# context holds: task, messages=[], artifacts={}, tool_results={}

The orchestrator creates a shared AgentContext — this is the MCP-inspired "context protocol" that accumulates state as it flows through agents.

Step 4: Research Agent Executes

┌─────────────────────────────────────────────────────────┐
│ 🔍 Research Agent                                        │
│                                                          │
│  1. Receives: AgentContext(task="Generate a compliance…")│
│  2. Builds prompt:                                       │
│     system: "You are a Research Agent specializing in…"  │
│     user: "Research the following topic thoroughly…"     │
│  3. Calls: ollama_client.chat(model="llama3", messages)  │
│  4. Receives: ChatResponse(content="…findings…")         │
│  5. Appends to context:                                  │
│     → context.messages += Message(role="agent", …)       │
│     → context.artifacts["Research Agent"] = "…findings…" │
│  6. Yields: ("researcher", message) → UI updates         │
└─────────────────────────────────────────────────────────┘

Step 5: Summarizer Agent Executes

┌─────────────────────────────────────────────────────────┐
│ 📋 Summarizer Agent                                      │
│                                                          │
│  1. Receives: AgentContext with research artifacts        │
│  2. Reads: context.artifacts["Research Agent"]            │
│  3. Builds prompt:                                       │
│     system: "You are a Summarizer Agent…"                │
│     user: "Summarize these findings… [research output]"  │
│  4. Calls Ollama → gets condensed summary                │
│  5. Appends: context.artifacts["Summarizer Agent"] = …   │
│  6. Yields → UI shows summarizer output                  │
└─────────────────────────────────────────────────────────┘

Step 6: Planner Agent Executes

┌─────────────────────────────────────────────────────────┐
│ 📐 Planner Agent                                         │
│                                                          │
│  1. Receives: AgentContext with summary artifacts         │
│  2. Reads: context.artifacts["Summarizer Agent"]          │
│  3. Creates: structured action plan with priorities       │
│  4. Appends: context.artifacts["Planner Agent"] = …      │
└─────────────────────────────────────────────────────────┘

Step 7: Communicator Agent Produces Final Report

┌─────────────────────────────────────────────────────────┐
│ 💼 Communicator Agent                                     │
│                                                          │
│  1. Receives: AgentContext with ALL prior outputs         │
│  2. Reads: context.get_conversation_history()             │
│     → concatenates all agent contributions                │
│  3. Synthesizes: polished executive report                │
│  4. Output includes:                                     │
│     • Executive Summary                                   │
│     • Key Findings                                        │
│     • Action Items                                        │
│     • Next Steps                                          │
└─────────────────────────────────────────────────────────┘

Step 8: Export & Display

Pipeline complete!
├── 📄 Report Tab → rendered Markdown
├── 📥 Download Markdown → report_20240615_143022.md
├── 📑 Download PDF → report_20240615_143022.pdf
└── 📋 Logs Tab → timestamped execution log

---

How MCP Tool Connectors Work

Agents 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.

Tool Invocation Flow

Agent needs data
       │
       ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Agent asks   │────▶│ ToolManager  │────▶│  Connector   │
│  for tool     │     │  routes call │     │  executes    │
│  execution    │     │              │     │              │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                  │
       ┌──────────────────────────────────────────┘
       ▼
┌──────────────┐
│  ToolResult  │ → success, output, metadata
│  returned to │ → injected into AgentContext
│  agent       │ → available to downstream agents
└──────────────┘

Available Connectors (All Free)

| Connector | What It Does | Dependencies | API Key | |-----------|-------------|-------------|---------| | 📁 FileSystem | Read, list, and search files in a sandboxed directory | pathlib (built-in) | None | | 🌐 WebSearch | Query DuckDuckGo Instant Answer API for web results | requests | None | | 🗄️ SQLite DB | Run read-only SQL queries against a local database | sqlite3 (built-in) | None | | 🧠 ChromaDB | Semantic similarity search over document embeddings | chromadb>=0.4.22 | None | | 🕐 DateTime | Current time, timezone conversion, date arithmetic | datetime (built-in) | None | | 🧮 Calculator | Safe math expression evaluation (no eval()) | ast (built-in) | None |

Connector Configuration

All connectors are configured in config.yaml:

tools:
  filesystem:
    enabled: true
    params:
      base_dir: "data"

  web_search:
    enabled: true
    params: {}

  database:
    enabled: true
    params:
      db_path: "data/knowledge.db"

  vector_store:
    enabled: true
    params:
      collection_name: "mcp_knowledge"
      persist_dir: "data/chroma"

  datetime:
    enabled: true
    params: {}

  calculator:
    enabled: true
    params: {}

Security Features

• FileSystem: Sandboxed to data/ directory — path traversal attempts are blocked
• SQLite: Read-only access — only SELECT queries allowed; DROP, INSERT, UPDATE rejected
• Calculator: AST-based evaluation — no eval(), no code injection, exponent limit enforced
• WebSearch: Uses only the public DuckDuckGo API — no credentials stored

---

Agents

| Agent | Role | What It Does | |-------|------|-------------| | 🔍 Research Agent | Information Gathering | Investigates the topic with comprehensive analysis, facts, and data points | | 📋 Summarizer Agent | Knowledge Distillation | Condenses research into concise, actionable insights with clear structure | | 📐 Planner Agent | Strategic Planning | Organizes insights into workflows with priorities, timelines, and dependencies | | 💼 Communicator Agent | Executive Reporting | Synthesizes all outputs into a polished, presentation-ready report |

All agents are config-driven — model, temperature, system prompt, and token limits are defined in config.yaml.

---

Features

• MCP-Inspired Orchestration — protocol-based agent communication with shared context accumulation
• 6 Free MCP Tool Connectors — file system, web search, SQLite, ChromaDB, datetime, calculator
• Local LLM Inference — fully offline via Ollama (llama3, mistral, gemma, phi3)
• Real-Time Pipeline Visualization — watch agents collaborate step-by-step in the Streamlit UI
• Export — download final reports as Markdown or PDF
• Config-Driven Architecture — YAML-based agent + tool definitions, no hardcoded paths
• Docker-Ready — single-command deployment with Docker Compose
• Comprehensive Test Suite — 71 tests covering agents, orchestrator, and all connectors
• Security-First — sandboxed file access, read-only SQL, safe math evaluation
• Structured Logging — timestamped session logs for debugging and audit

---

Repository Structure

agents-mcp-system/
├── app.py                     # Streamlit UI — task input, pipeline viz, export
├── orchestrator.py            # MCP orchestration engine — pipeline + context
├── ollama_client.py           # Ollama REST API wrapper — chat, embed, health
├── tool_manager.py            # Tool connector registry and lifecycle manager
├── utils.py                   # Logging, file storage, PDF export helpers
├── config.yaml                # Agent + tool configuration (YAML)
├── requirements.txt           # Pinned Python dependencies
├── Dockerfile                 # Multi-stage container build
├── docker-compose.yml         # Ollama + App orchestration
├── agents/
│   ├── __init__.py            # Agent registry
│   ├── base.py                # BaseAgent ABC + Message/AgentContext protocol
│   ├── researcher.py          # Research Agent implementation
│   ├── summarizer.py          # Summarizer Agent implementation
│   ├── planner.py             # Planner Agent implementation
│   └── communicator.py        # Communicator Agent implementation
├── connectors/
│   ├── __init__.py            # Connector package exports
│   ├── base.py                # MCPTool ABC + ToolResult dataclass
│   ├── filesystem.py          # 📁 File system connector (sandboxed)
│   ├── websearch.py           # 🌐 DuckDuckGo web search connector
│   ├── database.py            # 🗄️ SQLite database connector (read-only)
│   ├── vectorstore.py         # 🧠 ChromaDB vector store connector
│   ├── datetime_tool.py       # 🕐 Date/time utilities connector
│   └── calculator.py          # 🧮 Safe math expression evaluator
├── tests/
│   ├── test_agents.py         # Agent unit tests (15 tests)
│   ├── test_orchestrator.py   # Orchestrator unit tests (11 tests)
│   └── test_connectors.py     # Connector + ToolManager tests (45 tests)
├── sample_tasks/
│   ├── compliance_summary.txt # Sample: HR compliance analysis
│   └── strategy_plan.md       # Sample: Go-to-market strategy
├── data/                      # Tool data directory (sandboxed)
├── outputs/                   # Generated reports (git-ignored)
└── logs/                      # Session logs (git-ignored)

---

Prerequisites

| Component | Version | Installation | |-----------|---------|-------------| | Python | 3.11+ | python.org | | Ollama | Latest | ollama.ai | | Docker | 24+ | docker.com (optional) |

---

Quick Start

1. Clone and Install

git clone https://github.com/maneeshkumar52/agents-mcp-system.git
cd agents-mcp-system

python -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .venv\Scripts\activate         # Windows

pip install -r requirements.txt

2. Start Ollama

# Terminal 1 — start the Ollama server
ollama serve

# Terminal 2 — pull a model (one-time)
ollama pull llama3

3. Launch the Application

streamlit run app.py

Open http://localhost:8501 → enter a task → watch agents collaborate → download the report.

---

Docker Deployment

Single Container

docker build -t agents-mcp-system .
docker run -p 8501:8501 \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  agents-mcp-system

Full Stack (Ollama + App)

docker compose up -d

# Pull a model into the containerized Ollama
docker compose exec ollama ollama pull llama3

# Open http://localhost:8501

---

Configuration

All agent behavior is controlled via config.yaml:

ollama:
  base_url: "http://localhost:11434"
  default_model: "llama3"
  timeout: 120

agents:
  researcher:
    name: "Research Agent"
    model: "llama3"
    temperature: 0.3
    max_tokens: 2048
    system_prompt: |
      You are a Research Agent specializing in ...

orchestration:
  pipeline: [resear

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [maneeshkumar52](https://github.com/maneeshkumar52)
- **Source:** [maneeshkumar52/agents-mcp-system](https://github.com/maneeshkumar52/agents-mcp-system)
- **License:** MIT

Install and usage instructions live in the source repository linked above.