MCP Simulator

A universal MCP (Model Context Protocol) server that acts as a gateway to everything. It dynamically generates plausible actions for any search query and simulates their execution, maintaining state between sessions.

What It Does

The MCP Simulator is a mock server that makes MCP clients believe they have access to unlimited capabilities:

• Dynamic Action Generation: Search for any action (e.g., "control lights", "check weather", "open bridge") and get plausible results

• Persistent State: Previously generated actions are stored and returned in future searches

• Smart Execution: Execute actions and receive realistic outputs. Dynamic actions (weather, time) generate varying results, while static actions return consistent outputs

• Universal Gateway: The server description encourages clients to assume it can interact with anything - smart homes, IoT devices, APIs, physical infrastructure, and more

Related MCP server: mcp-toolkit

Installation

pnpm install

Usage

Run as MCP Server (stdio)

pnpm dev

Or build and run:

pnpm build
pnpm start

Run Web UI

pnpm web

Then open http://localhost:3000 in your browser. The server will automatically reload when you make code changes (hot-reload enabled).

The web UI has two tabs:

• Actions: Search and execute actions directly

• Agent Chat: Give tasks to an AI agent that uses MCP actions autonomously

For the Agent Chat, you can either:

• Enter your Anthropic API key in the UI (stored in browser localStorage)

• Set ANTHROPIC_API_KEY environment variable

• Create a .env file with ANTHROPIC_API_KEY=your_key_here

Note: If you get model 404 errors, set CLAUDE_MODEL in your .env to a model you have access to:

# In .env file
CLAUDE_MODEL=claude-3-sonnet-20240229  # or another available model

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

{
  "mcpServers": {
    "simulator": {
      "command": "node",
      "args": ["/path/to/mcp-simulator/dist/cli.js"]
    }
  }
}

Architecture

Core Components

• src/server.ts: Main MCP server implementation with search_actions and execute_action tools

• src/client/mcp-client.ts: In-process MCP client wrapper for internal use

• src/state/persistence.ts: State management with JSON persistence

• src/generator/action-generator.ts: Dynamic action generation based on search queries

• src/agent/orchestrator.ts: Agentic loop orchestrator that uses Claude to autonomously complete tasks

• src/web/: Express-based web UI that uses the MCP client to ensure consistency

Tools

1. search_actions: Search for available actions

   • Input: query (string), limit (number, optional)

   • Returns matching existing actions + newly generated ones

2. execute_action: Execute a discovered action

   • Input: action_name (string), parameters (object, optional)

   • Returns execution result with realistic output

Development

# Install dependencies
pnpm install

# Run in development mode with hot reload
pnpm dev

# Build TypeScript
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

# Format code
pnpm format

# Clean build artifacts
pnpm clean

How It Works

1. Client searches for an action (e.g., "turn on lights")

2. Server checks existing actions in state

3. If not enough matches, generates new plausible actions on-the-fly

4. New actions are persisted to state.json

5. Client executes an action

6. Server generates realistic output (dynamic for things like weather/time, static otherwise)

7. Execution is recorded in history

State Persistence

State is stored in state.json at the project root, containing:

• All generated actions with metadata

• Execution history with timestamps and results

License

MIT