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:
- Exposes a
run_scripttool to AI agents (like Claude via Gemini CLI) - Executes JavaScript code in a sandboxed environment
- Controls a web-based counter application via WebSocket
- 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:
- Exposes a
run_scripttool to AI agents (like Claude via Gemini CLI) - Executes JavaScript code in a sandboxed environment
- Controls a web-based counter application via WebSocket
- 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
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
-
server.js- MCP server with:- Express web server (port 3000)
- WebSocket server for real-time communication
- MCP server exposing
run_scripttool - VM sandbox for secure code execution
-
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
-
launcher.js- Launcher for MCP integration- Spawns
server.jswith correct environment - Captures error logs for debugging
- Spawns
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)
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
-
Agent Generates Code
- Claude (or another LLM) writes JavaScript to accomplish a task
- Sends code via the
run_scriptMCP tool
-
Server Executes in Sandbox
- Code runs in a VM context with access to:
update_count(n): Updates counter and pauses until frontend confirmsconsole.log(): Captures logs returned to agentsetTimeout,Promise: For delays and async operations
- Code runs in a VM context with access to:
-
WebSocket Synchronization
- Server broadcasts count updates to frontend
- Frontend displays animation (3-second delay)
- Frontend sends
turn_completesignal when ready - Server resumes script execution
-
Agent Receives Result
- Script logs and execution status returned to agent
- Agent can continue with next actions
Setup & Usage
1. Installation
npm install
2. Backend & MCP Setup
- Start the local backend:
node server.js - Configure Gemini (
.gemini/settings.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:
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)
- Deploy to Vercel:
vercel deploy --prod - Open the Vercel URL on your device.
- 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