# 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/)
