# Universal MCP Capability - Quick Start

**Transform your Synqed agents into MCP-enabled superpowers in 3 steps!**

## TL;DR

```bash
cd synqed-python
python universal_mcp_demo.py
```

You'll see:
- ✅ 3 agents with MCP superpowers
- ✅ 6 MCP tools auto-exported  
- ✅ Circular MCP+A2A demonstrated
- ✅ "Synqed is now an Agent Operating System!"

## What You Get

Every Synqed agent automatically gets:

### 1. MCP Client (Call Tools)

```python
async def my_agent_logic(context: AgentLogicContext):
    # context.mcp is automatically available!
    result = await context.mcp.call_tool("zoom.create_meeting", {
        "topic": "Team Sync",
        "start_time": "2025-11-25T10:00:00Z"
    })
    return context.send("USER", f"Meeting: {result['join_url']}")
```

### 2. MCP Export (Be Called)

```python
from synqed_mcp.integrate import AgentExporter

exporter = AgentExporter(mcp_server, router)
exporter.export_agent("my_agent", ["do_task", "query_data"])

# Now external clients can call:
# - my_agent.do_task
# - my_agent.query_data
```

## 3-Step Integration

### Step 1: Create Your Agent (Normal Synqed)

```python
from synqed import Agent, AgentLogicContext

async def my_agent_logic(context: AgentLogicContext):
    latest = context.latest_message
    if not latest:
        return context.send("USER", "Ready!")
    
    # Your agent logic here
    # context.mcp is automatically available!
    
    return context.send("USER", "Done!")

my_agent = Agent(
    name="my_agent",
    logic=my_agent_logic
)
```

### Step 2: Export as MCP Tool

```python
from synqed_mcp.integrate import AgentExporter

exporter = AgentExporter(mcp_server, router)
exporter.export_agent(
    "my_agent",
    ["execute", "query"],  # task types
    descriptions={
        "execute": "Execute a task",
        "query": "Query for data"
    }
)
```

### Step 3: Done!

Your agent now:
- ✅ Can call MCP tools via `context.mcp`
- ✅ Is callable as MCP tool externally
- ✅ Maintains A2A message flow
- ✅ No additional setup needed

## Real Example

### Agent That Uses MCP Internally

```python
async def salesforce_logic(context: AgentLogicContext):
    task = json.loads(context.latest_message.content)
    
    if task["task_type"] == "query_leads":
        # Get leads from Salesforce
        leads = query_salesforce(task["payload"]["query"])
        
        # 🔥 USE MCP TO SCHEDULE FOLLOW-UP
        if hasattr(context, 'mcp'):
            zoom_result = await context.mcp.call_tool(
                "zoom.create_meeting",
                {
                    "topic": f"Follow-up for {len(leads)} leads",
                    "start_time": "2025-11-25T14:00:00Z"
                }
            )
        
        return context.send("USER", json.dumps({
            "leads": leads,
            "meeting_scheduled": zoom_result.get("join_url")
        }))
```

## Available MCP Tools

### Register Tools for Your Agents

```python
# define what mcp tools are available to your agents
tool_registry = {
    "salesforce.query_leads": {
        "agent": "salesforce",
        "task_type": "query_leads"
    },
    "zoom.create_meeting": {
        "agent": "zoom",
        "task_type": "create_meeting"
    },
    "content_creator.generate": {
        "agent": "content_creator",
        "task_type": "generate"
    }
}

# tools are automatically available to all agents
```

## Architecture in One Picture

```
External Client → MCP Server → A2A → Agent Logic
                                          ↓
                                    context.mcp
                                          ↓
                                    MCP Tools → Other Agents
```

## Benefits

### Before (Manual)
```python
# had to create mcp tool manually
@mcp.tool()
async def call_salesforce(query: str):
    # manual routing code
    pass

# agents couldn't use mcp tools
# no automatic export
```

### After (Universal)
```python
# automatic export
exporter.export_agent("salesforce", ["query_leads"])

# automatic injection
async def agent_logic(context):
    result = await context.mcp.call_tool("zoom.create_meeting", {...})
    # ✅ works automatically!
```

## Run The Demo

```bash
# see it in action
python universal_mcp_demo.py

# start mcp server
python universal_mcp_demo.py --serve
```

## What Makes This Universal

1. **Every agent** gets MCP client automatically
2. **Every agent** can be exported as MCP tool
3. **Zero scaffolding** per agent
4. **A2A preserved** - no shortcuts
5. **Composable** - agents call agents via MCP

## Key Files

```
synqed_mcp/integrate/
├── injector.py    # Injects context.mcp into agents
└── exporter.py    # Exports agents as MCP tools

universal_mcp_demo.py  # Full working demo
```

## Common Patterns

### Pattern 1: Agent Calls External MCP Tool

```python
async def my_logic(context):
    # call zoom tool
    meeting = await context.mcp.call_tool("zoom.create_meeting", {...})
    return context.send("USER", f"Created: {meeting['join_url']}")
```

### Pattern 2: External Client Calls Agent

```
Claude Desktop → salesforce.query_leads → A2A → Salesforce Agent
```

### Pattern 3: Agent Calls Another Agent via MCP

```python
async def agent_a_logic(context):
    # agent A calls agent B via MCP (maintains A2A flow)
    result = await context.mcp.call_tool("agent_b.do_something", {...})
```

### Pattern 4: Circular Composition

```
Salesforce → (via MCP) → Zoom
Zoom → (via MCP) → ContentCreator  
ContentCreator → (via MCP) → Salesforce
```

All while maintaining proper A2A message flow!

## Next Steps

1. **Run the demo:** `python universal_mcp_demo.py`
2. **Add your agents:** Use the 3-step integration
3. **Call from Claude:** Connect Claude Desktop
4. **Build workflows:** Compose agents via MCP

## Documentation

- **Full Architecture:** See `UNIVERSAL_MCP_ARCHITECTURE.md`
- **Implementation:** See `synqed_mcp/integrate/`
- **Demo Code:** See `universal_mcp_demo.py`

## Summary

**Synqed is now an Agent Operating System** where MCP is a universal capability available to every agent automatically.

No scaffolding. No boilerplate. Just pure agent superpowers. 🚀

```bash
python universal_mcp_demo.py
```

