Model Context Protocol (MCP) Agent

A local AI command agent that processes instructions, executes automations, and returns results through a centralized desktop interface using Model Context Protocol (MCP).

System Overview

This system provides four MCP-compliant local services:

1. Call & Message Handler (Port 8000): Handles outbound calls and messaging with retry logic and secure auth
2. TTS Voice Service (Port 8001): Streaming voice output with audio playback
3. Messaging Bridge (Port 8002): Lightweight real-time messaging service (WhatsApp integration)
4. Task Router/Automation Proxy (Port 8003): Event creation and report dispatch

Setup Instructions

Prerequisites

• Python 3.8+
• pip
• Twilio account (for call services)
• Go 1.18+ (for lightweight bridge setup)

Installation

1. Clone this repository:

   git clone <repository-url>
   cd mcp-agent
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install fastapi uvicorn python-dotenv twilio pydantic httpx
   

4. Set up environment variables:

   cp .env.local .env
   

5. Edit .env with your secure credentials and configuration.

6. Create required directories:

   mkdir -p transcripts state
   

Configuration

Update the .env file with your specific configuration:

• MCP Authentication: Generate a secure token for API access
• Service Ports: Default ports are 8000-8003, can be customized
• Twilio: Add your Twilio credentials for call functionality
• WhatsMeow: Configure WhatsApp integration credentials
• Logging & Persistence: Customize paths and log levels as needed

Running the Services

1. Call & Message Handler (Port 8000)

uvicorn twilio_outbound_call:app --host 0.0.0.0 --port 8000 --reload

2. TTS Voice Service (Port 8001)

This service is not included in the current examples. Implementation would follow similar patterns to the other services.

3. Messaging Bridge (Port 8002)

Test the WhatsApp integration with:

python whatsmeow_hello.py

For the actual service in production:

uvicorn messaging_service:app --host 0.0.0.0 --port 8002 --reload

4. Example MCP Route (Orchestrator)

uvicorn mcp_route_example:app --host 0.0.0.0 --port 8003 --reload

Health Check

Verify all services are running:

curl http://localhost:8000/health
curl http://localhost:8001/health  # If implemented
curl http://localhost:8002/health  # If implemented
curl http://localhost:8003/health

API Usage Examples

Make an Outbound Call

curl -X POST http://localhost:8000/api/call \
  -H "Authorization: Bearer your_secure_mcp_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+15559876543",
    "request_id": "call_123456",
    "twiml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response><Say voice=\"alice\">Hello! This is a test call.</Say></Response>"
  }'

Send a WhatsApp Message

# Using the client script directly
python -c "import asyncio; from whatsmeow_hello import send_hello_message; asyncio.run(send_hello_message())"

# Or via the API when implemented:
curl -X POST http://localhost:8002/api/send \
  -H "Authorization: Bearer your_secure_mcp_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+15559876543",
    "message": "Hello from MCP!",
    "request_id": "msg_123456"
  }'

Use the MCP Tool Router

curl -X POST http://localhost:8003/api/tool \
  -H "Authorization: Bearer your_secure_mcp_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "send_message",
    "parameters": {"recipient": "+15559876543", "message": "Hello via tool router"},
    "request_id": "tool_123456"
  }'

Logging & Transcripts

All service activity is logged to:

• Log files: Each service maintains its own log file (e.g., call_service.log)
• Transcripts: Markdown-formatted logs are stored in the transcripts directory
• Console output: Real-time logs are displayed in the terminal

State Persistence

The system maintains state in ./state/agent_state.json. This enables recall of previous activities and continuation of workflows.

Security

• All API endpoints are secured with Bearer token authentication
• Secrets are loaded via environment variables
• No hardcoded credentials in any files

Troubleshooting

• Service won't start: Check port availability and environment configuration
• Authentication errors: Verify MCP_API_TOKEN is consistent across services
• External service failures: Check Twilio/WhatsApp credentials and quotas
• Missing transcripts: Ensure the transcripts directory is created and writable

Extending the System

To add new tools:

1. Create a new service file following the existing patterns
2. Register the tool in the MCP route handler
3. Update the MCP client to recognize and route to the new tool
4. Add necessary configuration to the .env file