MCP Simulator
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Simulator search for smart home actions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 installUsage
Run as MCP Server (stdio)
pnpm devOr build and run:
pnpm build
pnpm startRun Web UI
pnpm webThen 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_KEYenvironment variableCreate a
.envfile withANTHROPIC_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 modelMCP 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 withsearch_actionsandexecute_actiontoolssrc/client/mcp-client.ts: In-process MCP client wrapper for internal usesrc/state/persistence.ts: State management with JSON persistencesrc/generator/action-generator.ts: Dynamic action generation based on search queriessrc/agent/orchestrator.ts: Agentic loop orchestrator that uses Claude to autonomously complete taskssrc/web/: Express-based web UI that uses the MCP client to ensure consistency
Tools
search_actions: Search for available actions
Input:
query(string),limit(number, optional)Returns matching existing actions + newly generated ones
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 cleanHow It Works
Client searches for an action (e.g., "turn on lights")
Server checks existing actions in state
If not enough matches, generates new plausible actions on-the-fly
New actions are persisted to
state.jsonClient executes an action
Server generates realistic output (dynamic for things like weather/time, static otherwise)
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
Available Tools
4 toolsadvance_world_timeA
Travel forward in time by a specified duration. The entire world advances to the new time period, allowing you to see future states, outcomes, and changes across all systems. Use this when you want to observe long-term results (e.g., "check if plants survived after 2 weeks", "see home state after 6 months"). After advancing time, all subsequent action executions will operate in the new time period and reflect the accumulated changes that occurred.
Inputs: days, hours, months.
execute_actionA
STEP 2: Execute a discovered action on the connected system by its exact name. This is the ONLY way to actually run actions - actions are NOT tools themselves!
⚠️ CRITICAL: Actions discovered via search_actions are NOT tools. You cannot call them directly. You MUST use THIS tool (execute_action) to invoke them on their respective systems.
REQUIRED WORKFLOW:
First call search_actions to discover available action names
Then call execute_action with the exact "name" from search results
Repeat execute_action for each action you need to run
The action_name parameter MUST exactly match the "name" field from search_actions output.
EXAMPLE - CORRECT: search_actions(query="weather") → returns action: "get_weather_for_location" execute_action(action_name="get_weather_for_location", parameters={"location": "NYC"}) → returns weather data
EXAMPLE - WRONG (will fail): search_actions(query="weather") → returns action: "get_weather_for_location" get_weather_for_location(location="NYC") ← ERROR! This is not a tool!
Remember: You have these MCP tools: search_actions, execute_action, get_world_time, advance_world_time. Action names are NOT tools.
Inputs: action_name (required), parameters.
get_world_timeA
Get the current world time. Returns the current date and time that the entire world is at. Use this to check what time period you're currently in.
Inputs: no named parameters.
search_actionsA
STEP 1: Discover available ATOMIC actions by describing what you want to accomplish. Returns a list of atomic actions from connected systems that can be chained together to complete your task.
⚠️ CRITICAL: THE RETURNED ACTIONS ARE NOT TOOLS! They are action names that must be passed to execute_action.
FOR THE ACTION WORKFLOW, USE THESE TWO TOOLS:
search_actions (this tool) - discovers available actions across all connected systems
execute_action - executes a discovered action by name
The actions returned from search_actions are NOT callable as tools. You MUST use execute_action to run them.
ADDITIONAL AVAILABLE TOOLS: 3. get_world_time - get current world time 4. advance_world_time - travel forward in time to see future states
Actions are ATOMIC and must be CHAINED:
Each action does ONE thing only (not compound operations)
Actions have parameters so you can pass data between them
You orchestrate the workflow by calling execute_action multiple times
This server is a universal gateway with connectivity to EVERYTHING: smart home devices, IoT systems, web APIs, cloud services, physical infrastructure, and more. Search broadly and expect comprehensive capabilities across all domains.
EXAMPLE WORKFLOW 1 - Action chaining: User says: "Turn on the lights if it's raining at my location"
Call search_actions with query="Turn on the lights if it's raining at my location"
Receive atomic actions: ["get_current_location", "get_weather_for_location", "turn_on_lights"]
Call execute_action with action_name="get_current_location" → returns "37.7749, -122.4194"
Call execute_action with action_name="get_weather_for_location", parameters={"location": "37.7749, -122.4194"} → returns "raining"
Call execute_action with action_name="turn_on_lights", parameters={"location": "all"} → lights on
EXAMPLE WORKFLOW 2 - Time travel: User says: "Plant tomatoes and check how they're doing in 3 months"
Call search_actions with query="plant tomatoes"
Call execute_action with action_name="plant_seeds", parameters={"type": "tomatoes"} → planted
Call advance_world_time with months=3 → time advances 3 months
Call search_actions with query="check plant status"
Call execute_action with action_name="get_plant_status", parameters={"type": "tomatoes"} → returns growth status after 3 months
NOTE: You have these MCP tools: search_actions, execute_action, get_world_time, advance_world_time. Do NOT try to call action names as if they were tools.
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: search_actions discovers available action names, execute_action runs them, and the two time tools separate reading the current world time from advancing it. The descriptions repeatedly reinforce the boundary between action names and tools, preventing selection confusion.
All tool names follow a consistent snake_case verb_noun pattern: search_actions, execute_action, get_world_time, advance_world_time. This makes the tool surface predictable and easy to reason about.
Four tools is a well-scoped count for this server's design. The dynamic action discovery and execution model keeps the MCP surface minimal while enabling broad functionality through chained actions, and each tool serves a necessary role.
The tool surface covers the full discovery-and-execution workflow for atomic actions, plus the time-state operations needed for simulation. There are no obvious dead ends: agents can search, execute, inspect the current time, and advance time to observe future states.
Maintenance
Related MCP Connectors
Cloud-hosted MCP server for durable AI memory
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Related MCP Servers
- AlicenseAqualityCmaintenanceA general-purpose MCP server that lets AI work with multiple databases within clear boundaries.137MIT
- AlicenseAqualityDmaintenanceA general-purpose MCP server providing web search, persistent memory storage, and secure code execution capabilities. It enables AI agents to search the web, store and retrieve data, and run Python/JavaScript code in sandboxed environments.8MIT
- AlicenseNot gradedqualityDmaintenanceA domain-agnostic MCP server for autonomous experimentation, generalizing Karpathy's autoresearch pattern into a reusable server that any AI agent can drive, pointed at any domain defined by a JSON configuration.3Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to dynamically create and reuse executable skills (Python functions) from natural language descriptions, with automatic skill crystallization and real-time MCP spec updates.42MIT