# MCP Counter POC - Code Execution Architecture

## Overview

This is a proof-of-concept (POC) demonstrating the **"Code execution with MCP"** pattern, which enables AI agents to execute JavaScript code on a server to control external applications. This architecture can be used as a foundation for building interactive, agent-controlled applications.

## What Does This POC Do?

This POC implements a **Model Context Protocol (MCP) server** that:
1. Exposes a `run_script` tool to AI agents (like Claude via Gemini CLI)
2. Executes JavaScript code in a sandboxed environment
3. Controls a web-based counter application via WebSocket
4. Synchronizes execution with frontend animations
# MCP Counter POC - Code Execution Architecture

## Overview

This is a proof-of-concept (POC) demonstrating the **"Code execution with MCP"** pattern, which enables AI agents to execute JavaScript code on a server to control external applications. This architecture can be used as a foundation for building interactive, agent-controlled applications.

## What Does This POC Do?

This POC implements a **Model Context Protocol (MCP) server** that:
1. Exposes a `run_script` tool to AI agents (like Claude via Gemini CLI)
2. Executes JavaScript code in a sandboxed environment
3. Controls a web-based counter application via WebSocket
4. Synchronizes execution with frontend animations

### Key Capability: Agent-Controlled UI
An AI agent can write JavaScript code that directly controls the counter displayed in a web browser, with execution paused until animations complete to ensure smooth user experience.

## Architecture

```mermaid
graph TD
    User[User Mobile/Desktop] -->|HTTPS| Vercel[Vercel Frontend]
    Vercel -->|WebSocket| Tunnel[Localtunnel URL]
    Tunnel -->|Tunnel| LocalServer[Local Server :3000]
    LocalServer -->|MCP| Agent[AI Agent (Gemini)]
    LocalServer -->|Sandbox| VM[VM Context]
```

### Components

1. **`server.js`** - MCP server with:
   - Express web server (port 3000)
   - WebSocket server for real-time communication
   - MCP server exposing `run_script` tool
   - VM sandbox for secure code execution

2. **`index.html`** - Frontend (Deployed on Vercel) with:
   - Real-time counter display
   - WebSocket client connecting to Localtunnel URL
   - Animation system (3-second delay per update)
   - Pause/Resume controls

3. **`launcher.js`** - Launcher for MCP integration
   - Spawns `server.js` with correct environment
   - Captures error logs for debugging

## The "Code Execution with MCP" Pattern

### Traditional Approach (Inefficient)
```
Agent calls: update_count(1)  → Server updates → Frontend shows 1
Agent waits...
Agent calls: update_count(2)  → Server updates → Frontend shows 2
Agent waits...
Agent calls: update_count(3)  → Server updates → Frontend shows 3
```
**Problem**: Multiple round-trips to the agent for simple loops.

### Code Execution Approach (Efficient)
```javascript
Agent calls: run_script({
  code: `
    for (let i = 1; i <= 3; i++) {
      await update_count(i);
    }
  `
})
```
The server executes the entire loop, pausing at each `update_count()` call until the frontend animation completes.

**Benefit**: Complex logic runs in a single agent turn, reducing token usage and latency.

## How It Works

1. **Agent Generates Code**
   - Claude (or another LLM) writes JavaScript to accomplish a task
   - Sends code via the `run_script` MCP tool

2. **Server Executes in Sandbox**
   - Code runs in a VM context with access to:
     - `update_count(n)`: Updates counter and pauses until frontend confirms
     - `console.log()`: Captures logs returned to agent
     - `setTimeout`, `Promise`: For delays and async operations

3. **WebSocket Synchronization**
   - Server broadcasts count updates to frontend
   - Frontend displays animation (3-second delay)
   - Frontend sends `turn_complete` signal when ready
   - Server resumes script execution

4. **Agent Receives Result**
   - Script logs and execution status returned to agent
   - Agent can continue with next actions

## Setup & Usage

### 1. Installation
```bash
npm install
```

### 2. Backend & MCP Setup
1.  Start the local backend:
    ```bash
    node server.js
    ```
2.  Configure Gemini (`.gemini/settings.json`):
    ```json
    {
      "mcpServers": {
        "pm-jarvis": {
          "command": "node",
          "args": ["C:\\path\\to\\project\\launcher.js"]
        }
      }
    }
    ```

### 3. Mobile Access (Localtunnel)
To access the app from a mobile device, expose your local backend:
```bash
npx localtunnel --port 3000
```
*   Copy the URL (e.g., `https://example.loca.lt`).
*   **Important:** Visit this URL in your browser first and enter your IP as the password.

### 4. Frontend (Vercel)
1.  Deploy to Vercel:
    ```bash
    vercel deploy --prod
    ```
2.  Open the Vercel URL on your device.
3.  Go to **Settings** and enter your **Localtunnel URL**.

## Use Cases as Base Architecture

This POC can be adapted for:

### 1. **Agent-Controlled Dashboards**
- Replace counter with charts/graphs
- Agent updates visualizations based on data analysis

### 2. **Interactive Forms & Workflows**
- Agent fills forms step-by-step
- Validates inputs and handles errors

### 3. **Real-time Notifications**
- Agent processes events and updates UI
- Users see live status without polling

### 4. **Game Controllers**
- Agent plays games by executing move sequences
- UI updates reflect game state

### 5. **IoT Device Control**
- Replace WebSocket frontend with IoT devices
- Agent sends control sequences to hardware

## License

MIT

## References

- [Anthropic: Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)