Skip to main content
Glama
MCP Simulator
by FokkeZB

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

Available Tools

4 tools
advance_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:

  1. First call search_actions to discover available action names

  2. Then call execute_action with the exact "name" from search results

  3. 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:

  1. search_actions (this tool) - discovers available actions across all connected systems

  2. 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"

  1. Call search_actions with query="Turn on the lights if it's raining at my location"

  2. Receive atomic actions: ["get_current_location", "get_weather_for_location", "turn_on_lights"]

  3. Call execute_action with action_name="get_current_location" → returns "37.7749, -122.4194"

  4. Call execute_action with action_name="get_weather_for_location", parameters={"location": "37.7749, -122.4194"} → returns "raining"

  5. 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"

  1. Call search_actions with query="plant tomatoes"

  2. Call execute_action with action_name="plant_seeds", parameters={"type": "tomatoes"} → planted

  3. Call advance_world_time with months=3 → time advances 3 months

  4. Call search_actions with query="check plant status"

  5. 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

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      42
      MIT