Create MCP

/create-mcp                    # Starts the wizard from the beginning
/create-mcp "calendar"         # Jumps ahead with a service hint

┌─────────────────────────────────────────────────────────────┐
│                    YOUR QUESTION                            │
│         "What features are customers using most?"           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    AI REASONING                             │
│  "I need support ticket data. I have a Zendesk MCP tool    │
│   called `get_ticket_stats`. Let me call it..."            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP TOOL CALL                            │
│  Tool: get_feature_usage                                    │
│  Input: { "days": 30, "limit": 10 }                        │
│  ─────────────────────────────────────────────────────────  │
│  │ GUARDRAILS:                                          │  │
│  │ ✓ Defined input schema - can't send bad data         │  │
│  │ ✓ Authenticated connection - uses real credentials   │  │
│  │ ✓ Structured output - returns consistent format      │  │
│  │ ✓ Deterministic - same query = same results          │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    REAL DATA RESPONSE                       │
│  { "features": [                                            │
│    { "name": "Dashboard", "usage": 89% },                   │
│    { "name": "Reports", "usage": 67% },                     │
│    { "name": "Guides", "usage": 45% }                       │
│  ]}                                                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    AI SYNTHESIS                             │
│  "Your top 3 features by usage are Dashboard (89%),        │
│   Reports (67%), and Guides (45%). Dashboard dominates -   │
│   consider investing more there."                          │
└─────────────────────────────────────────────────────────────┘

🔌 **MCP Server Creation Wizard**

MCP (Model Context Protocol) lets Dex connect to external tools and services. Instead of guessing or saying "I don't have access", AI can query real data and give you accurate answers.

**The difference MCP makes:**
- ❌ Without: "I'd estimate you have around 10-15 support tickets..."
- ✅ With: "Zendesk shows 32 tickets, 12 high priority, avg response time 2.3hrs"

**Examples of what you can build:**
- 📅 Calendar → "What meetings do I have tomorrow? Who's attending?"
- 📧 Email → "Find emails from Sarah about the Q1 roadmap"
- 💬 Slack → "What did #product-team discuss today?"
- 📊 Analytics → "Show me feature adoption for our enterprise tier"
- 🔗 Any API → If it has an API, we can probably connect it

**Benefits:**
- Real data, not AI guessing
- Guardrails prevent hallucination
- Live queries, not stale training data
- Structured tools with validation

**This wizard will:**
1. Help you describe what you want to connect
2. Design the integration together
3. Generate the MCP server code
4. Integrate it into Dex
5. Update all documentation so future sessions know how to use it

Ready to get started? **What would you like to connect Dex to?**

(Just describe it in plain English — e.g., "my Google Calendar", "Notion database", "company CRM")

What service or tool do you want to connect?

Examples:
- A specific app (Google Calendar, Notion, Salesforce)
- A type of data (my emails, my tasks, my documents)
- An API you have access to

Your answer:

How do you currently access this service?

1. I log in with username/password
2. I have an API key
3. It uses OAuth (Google, Microsoft login)
4. It's a local file or database
5. Something else

This helps me understand what authentication we'll need.

What specific information do you want Dex to access?

Be specific about:
- What types of data (events, messages, records)
- What you'd want to read vs. write
- Any specific fields that matter most

Example: "I want to see my calendar events - title, time, attendees. Just reading, no need to create events."

How would you actually use this in practice?

Give me 2-3 example questions or commands you'd want to ask:
- "Show me today's meetings"
- "Find emails from [person] about [topic]"
- "What's the status of [account]?"

This shapes what tools we'll build.

**Understood. Here's what we're building:**

📦 **Service:** [service name]
🔐 **Auth method:** [auth type]
📊 **Data access:** [read/write + what data]
🎯 **Primary use cases:**
1. [use case 1]
2. [use case 2]
3. [use case 3]

Does this capture what you want? (yes / let me clarify)

**Proposed MCP Tools**

Based on your use cases, here's what I suggest building:

| Tool Name | What It Does | Example Usage |
|-----------|--------------|---------------|
| `[tool_1]` | [description] | "[natural language example]" |
| `[tool_2]` | [description] | "[natural language example]" |
| `[tool_3]` | [description] | "[natural language example]" |

**Input parameters for each:**

### `[tool_1]`
- `param_1` (required): [description]
- `param_2` (optional): [description]

### `[tool_2]`
...

**Questions:**
1. Do these tools cover your use cases?
2. Should any tool do more or less?
3. Are there additional scenarios I missed?

**Final Tool Design**

We're building an MCP server called `[server-name]` with:

| Tool | Purpose | Inputs |
|------|---------|--------|
| [tool] | [purpose] | [inputs summary] |

**Authentication:** [method + what user needs to provide]
**Configuration:** [any env vars or config needed]

Ready to build? (yes / let me adjust)

#!/usr/bin/env python3
"""
MCP Server for [Service Name]
[Brief description of what this server does]

Tools:
- [tool_1]: [description]
- [tool_2]: [description]
"""

import os
import json
import logging
from typing import Dict, List, Optional, Any
from datetime import datetime

from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.server.stdio
import mcp.types as types

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Configuration from environment
[RELEVANT_CONFIG_VARS]

# ============================================================================
# SERVICE CLIENT
# ============================================================================

class [ServiceName]Client:
    """Client for interacting with [Service]"""
    
    def __init__(self):
        [initialization code]
    
    [methods for each operation]

# ============================================================================
# MCP SERVER
# ============================================================================

app = Server("[server-name]-mcp")
client = [ServiceName]Client()

@app.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    """List all available tools"""
    return [
        types.Tool(
            name="[tool_name]",
            description="[tool description]",
            inputSchema={
                "type": "object",
                "properties": {
                    [property definitions]
                },
                "required": [required fields]
            }
        ),
        # ... more tools
    ]

@app.call_tool()
async def handle_call_tool(
    name: str, arguments: dict | None
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
    """Handle tool calls"""
    
    if name == "[tool_name]":
        [implementation]
        return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
    
    # ... more tool handlers
    
    return [types.TextContent(type="text", text=f"Unknown tool: {name}")]

async def _main():
    """Async main entry point"""
    logger.info("Starting [Service] MCP Server")
    
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="[server-name]-mcp",
                server_version="1.0.0",
                capabilities=app.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                ),
            ),
        )

def main():
    """Sync entry point"""
    import asyncio
    asyncio.run(_main())

if __name__ == "__main__":
    main()

#!/bin/bash
# Launch [Service] MCP server
cd "$(dirname "$0")"
source venv/bin/activate 2>/dev/null || true
python [service_name]_server.py

**Server Created!** ✅

Files generated:
- `core/mcp/[service_name]_server.py` — The MCP server
- `core/mcp/requirements.txt` — Updated with dependencies

**Before we integrate, you'll need to:**

[Auth-specific instructions based on Phase 1]

Examples:
- For API key: "Add [SERVICE]_API_KEY to your environment or .env file"
- For OAuth: "Run the OAuth setup script: `python core/mcp/setup_[service]_auth.py`"
- For local: "No additional setup needed"

Let me know when you're ready to integrate.

### [Service Name] Integration

**Server:** `core/mcp/[service_name]_server.py`
**Purpose:** [what it does]

**Available Tools:**

| Tool | What It Does | Example |
|------|--------------|---------|
| `[tool]` | [description] | "[natural example]" |

**Configuration Required:**
- `[ENV_VAR]`: [description]

**Usage examples:**
- "[natural language request]" → uses `[tool]` tool
- "[another request]" → uses `[another_tool]` tool

<mcp_instructions>
### [service-name]-mcp

[Description of the server and when to use it]

**Tools:**
- `[tool_name]`: [when to use and what it returns]

</mcp_instructions>

| **[Service]** | [Brief description of capabilities] |

### [Service] MCP Server

Server: `core/mcp/[service_name]_server.py`

#### Available Tools

| Tool | Purpose |
|------|---------|
| `[tool]` | [description] |

#### Usage

[How to use in natural language, what to expect]

#### Configuration

| Variable | Description |
|----------|-------------|
| `[ENV_VAR]` | [what it's for] |