Metadata-Version: 2.4
Name: geepers-mcp
Version: 2.0.0
Summary: Multi-agent orchestration and LLM provider abstraction via MCP protocol - 72 specialist agents, 22 orchestration patterns
Home-page: https://github.com/lukeslp/geepers-mcp
Author: Luke Steuber
Author-email: Luke Steuber <luke@lukesteuber.com>
License: MIT
Project-URL: Homepage, https://dr.eamer.dev/geepers/
Project-URL: Repository, https://github.com/lukeslp/geepers-mcp
Project-URL: Issues, https://github.com/lukeslp/geepers-mcp/issues
Project-URL: Documentation, https://dr.eamer.dev/geepers/
Keywords: mcp,orchestration,multi-agent,llm,beltalowda,swarm,geepers,claude-code,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geepers-kernel>=1.3.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: xai
Requires-Dist: openai>=1.0.0; extra == "xai"
Provides-Extra: mistral
Requires-Dist: requests>=2.31.0; extra == "mistral"
Provides-Extra: cohere
Requires-Dist: cohere>=5.0.0; extra == "cohere"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.3.0; extra == "gemini"
Provides-Extra: perplexity
Requires-Dist: openai>=1.0.0; extra == "perplexity"
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == "groq"
Provides-Extra: huggingface
Requires-Dist: huggingface-hub>=0.19.0; extra == "huggingface"
Provides-Extra: arxiv
Requires-Dist: arxiv>=2.0.0; extra == "arxiv"
Provides-Extra: wikipedia
Requires-Dist: wikipedia>=1.4.0; extra == "wikipedia"
Provides-Extra: youtube
Requires-Dist: google-api-python-client>=2.0.0; extra == "youtube"
Provides-Extra: tts
Requires-Dist: gtts>=2.5.0; extra == "tts"
Provides-Extra: citations
Requires-Dist: bibtexparser>=1.4.0; extra == "citations"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: documents
Requires-Dist: reportlab>=4.0.0; extra == "documents"
Requires-Dist: python-docx>=1.0.0; extra == "documents"
Requires-Dist: markdown>=3.5.0; extra == "documents"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "telemetry"
Provides-Extra: all
Requires-Dist: anthropic>=0.18.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: cohere>=5.0.0; extra == "all"
Requires-Dist: google-generativeai>=0.3.0; extra == "all"
Requires-Dist: groq>=0.4.0; extra == "all"
Requires-Dist: huggingface-hub>=0.19.0; extra == "all"
Requires-Dist: arxiv>=2.0.0; extra == "all"
Requires-Dist: wikipedia>=1.4.0; extra == "all"
Requires-Dist: google-api-python-client>=2.0.0; extra == "all"
Requires-Dist: gtts>=2.5.0; extra == "all"
Requires-Dist: bibtexparser>=1.4.0; extra == "all"
Requires-Dist: redis>=5.0.0; extra == "all"
Requires-Dist: reportlab>=4.0.0; extra == "all"
Requires-Dist: python-docx>=1.0.0; extra == "all"
Requires-Dist: markdown>=3.5.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Geepers MCP

Model Context Protocol (MCP) servers for multi-agent orchestration. Run parallel research agents across academic, news, code, and financial sources, then synthesize findings into PDF, DOCX, or Markdown reports.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/badge/PyPI-geepers--mcp-orange.svg)](https://pypi.org/project/geepers-mcp/)

**Author:** Luke Steuber
- [dr.eamer.dev](https://dr.eamer.dev)
- [@lukesteuber.com](https://bsky.app/profile/lukesteuber.com)

> Depends on [geepers-kernel](https://github.com/lukeslp/geepers-kernel) for LLM providers, orchestration, and data clients.

---

## Quick Start

```bash
pip install geepers-mcp[all]
```

Add at least one API key to `.env`:

```bash
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
XAI_API_KEY=xai-...
```

MCP tools become available in Claude Code right away:

```
Research quantum computing breakthroughs in 2025 using Beltalowda orchestration
```

---

## How it works

Six MCP servers expose 32+ tools. The orchestration layer coordinates them:

```
Claude Code Client
       |  MCP Protocol (stdio)
       v
Geepers MCP Plugin (6 MCP Servers)
  |           |           |           |
  v           v           v           v
Unified    Providers    Data       Cache
Orchestr.   Server    Fetching   Manager
  |           |           |           |
  v           v           v           v
Utilities  Web Search  Document   Redis
 Server     Server    Generator   Cache
```

**Beltalowda orchestration flow:**

1. Break a research task into 8 specialized angles
2. Run agents in parallel: arXiv, Semantic Scholar, news, Wikipedia, GitHub, YouTube, financial data, Open Library
3. Mid-level synthesis (Drummer) finds patterns, themes, contradictions
4. Executive synthesis (Camina) produces a summary with key insights
5. Generate PDF, DOCX, and Markdown reports with citations
6. Return structured `OrchestratorResult` with all outputs and metadata

---

## Orchestration tools

Start with the Unified Orchestrator Server:

| Tool | What it does |
|------|-------------|
| `orchestrate_research` | Beltalowda: 8 agents, Drummer synthesis, Camina summary |
| `orchestrate_search` | Swarm: 5+ specialized parallel agents |
| `get_orchestration_status` | Check progress of a running workflow |
| `cancel_orchestration` | Stop mid-execution |
| `list_orchestrator_patterns` | List available patterns |
| `list_registered_tools` | Browse all tool modules |
| `execute_registered_tool` | Run any tool directly |

---

## Data sources

32+ tool modules across seven categories:

- **Academic**: arXiv, Semantic Scholar, PubMed, Wikipedia, Open Library
- **News**: NewsAPI, RSS feeds, YouTube
- **Code**: GitHub repos, commits, user profiles
- **Finance**: stocks, company fundamentals, market news
- **Science**: NASA (APOD, Mars photos, satellite imagery)
- **Weather**: current conditions, forecasts, air quality
- **Web**: Brave Search, SerpAPI, generic web search

---

## LLM providers

Unified interface across 9 providers:

| Provider | Chat | Vision | Image Gen |
|----------|------|--------|-----------|
| Anthropic (Claude) | yes | yes | no |
| OpenAI (GPT) | yes | yes | yes |
| xAI (Grok) | yes | yes | yes |
| Mistral | yes | yes | no |
| Cohere | yes | no | no |
| Google (Gemini) | yes | yes | no |
| Perplexity | yes | yes | no |
| Groq (Llama) | yes | no | no |
| HuggingFace | yes | yes | yes |

---

## Installation

```bash
# Everything
pip install geepers-mcp[all]

# Specific providers only
pip install geepers-mcp[anthropic,openai,xai]

# From source
git clone https://github.com/lukeslp/geepers-mcp.git
cd geepers-mcp
pip install -e .[all]
```

### .env reference

```bash
# LLM Providers (at least one required)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
XAI_API_KEY=xai-...
MISTRAL_API_KEY=...
COHERE_API_KEY=...
GEMINI_API_KEY=...
PERPLEXITY_API_KEY=...
GROQ_API_KEY=...
HUGGINGFACE_API_KEY=...

# Data APIs (optional)
YOUTUBE_API_KEY=...
GITHUB_TOKEN=ghp_...
NASA_API_KEY=...
NEWS_API_KEY=...
ALPHAVANTAGE_API_KEY=...
OPENWEATHER_API_KEY=...

# Caching (optional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=...

# Documents (optional)
DEFAULT_DOCUMENT_FORMAT=pdf
CITATION_STYLE=apa
```

### MCP configuration

The plugin auto-configures `.mcp.json`. To override manually:

```json
{
  "mcpServers": {
    "geepers-unified": {
      "command": "python",
      "args": ["-m", "geepers_mcp.mcp.stdio_servers.unified_stdio"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}
```

### Verify

```bash
python -c "from geepers_mcp.config import ConfigManager; print('OK')"
```

---

## Custom orchestrators

```python
from shared.orchestration import BaseOrchestrator, OrchestratorConfig, SubTask, AgentType

class MyOrchestrator(BaseOrchestrator):
    async def decompose_task(self, task, context=None):
        return [
            SubTask(id="step1", description="First step", agent_type=AgentType.RESEARCHER),
            SubTask(id="step2", description="Second step", agent_type=AgentType.SYNTHESIZER)
        ]

    async def execute_subtask(self, subtask, context=None):
        result = await self.provider.complete(subtask.description)
        return SubTaskResult(subtask_id=subtask.id, output=result)

    async def synthesize_results(self, results, context=None):
        combined = "\n".join([r.output for r in results])
        return SynthesisResult(output=combined)
```

---

## Troubleshooting

**"No module named 'shared'"**
```bash
pip install geepers-kernel
```

**"No module named 'geepers_mcp'"**
```bash
pip install geepers-mcp
```

**"Provider not available: anthropic"**
```bash
pip install geepers-mcp[anthropic]
echo $ANTHROPIC_API_KEY  # verify key is set
```

**"Redis connection failed"**
```bash
redis-server
# or disable caching:
export REDIS_ENABLED=false
```

**Debug mode:**
```bash
export GEEPERS_DEBUG=true
export LOG_LEVEL=DEBUG
```

---

## Naming hierarchy

| Role | Responsibility | Pattern |
|------|----------------|---------|
| Conductor | Top-level coordinator | `conductor_<slug>` |
| Orchestrator | Mid-tier decomposition | `orchestrator_<slug>` |
| Agent | Narrow specialist | `agent_<slug>` |
| Utility | Atomic tool | `utility_<slug>` |

---

## License

MIT License. See [LICENSE](LICENSE).

**Luke Steuber**
- [dr.eamer.dev](https://dr.eamer.dev)
- [@lukesteuber.com](https://bsky.app/profile/lukesteuber.com)
