Skip to main content
Glama
FokkeZB

MCP Simulator

by FokkeZB
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoNumber of days to advance
hoursNoNumber of hours to advance (can be fractional)
monthsNoNumber of months to advance (approximated as 30 days each)

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: it discloses that the entire world advances, that the change persists, and that all subsequent action executions will operate in the new time period with accumulated changes. This is exactly the kind of side-effect context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences front-load the core action, then give usage examples, then state the crucial persistence side effect. Every sentence earns its place with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter tool with no output schema, the description covers what it does, when to use it, and the important state-changing consequence. It leaves minor ambiguity about whether at least one duration parameter must be supplied, since no parameters are required by the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all three parameters with full coverage (days, hours, months), so the description need not repeat them. It adds no further semantic detail about units or combination rules; the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Travel forward in time... entire world advances') and clarifies the result is observing future states. This makes it clearly distinct from siblings like get_world_time (reading current time) and execute_action (taking an action), even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use the tool ('Use this when you want to observe long-term results') and provides concrete examples for 2 weeks and 6 months. It does not explicitly name alternative tools or exclusion cases, so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
parametersNoParameters for the action. Check the action's "parameters" and "required" fields from search results.
action_nameYesThe EXACT action name from search_actions results. Must be a perfect character-for-character match with the "name" field to route to the correct system.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It discloses critical behavior: actions are not direct tools, exact name matching is required for routing, and this tool is the sole invocation mechanism. It gives a concrete example but does not discuss potential side effects, authentication, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose and has some redundancy—'actions are NOT tools' is repeated and the Remember line restates sibling tools—but the critical, confusing nature of actions versus tools justifies the repetition. It is well-structured with a workflow, correct example, and wrong example, making the length acceptable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generic executor of dynamically discovered actions, the description is complete: it covers the prerequisite search step, exact name matching, parameter sourcing, and the boundary between tools and actions. The lack of an output schema is mitigated by a concrete example showing expected usage, so an agent has enough to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by emphasizing character-for-character exact matching for action_name and instructing the agent to populate parameters using the action's own 'parameters' and 'required' fields from search results. The concrete example reinforces this.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Execute a discovered action on the connected system by its exact name.' It clearly differentiates from siblings by emphasizing that this is the ONLY way to run actions and that actions are not tools themselves.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lays out a required workflow: call search_actions first, then execute_action with the exact name, and repeat as needed. It provides a correct example, a wrong example that would fail, and explicitly warns against calling action names as tools, leaving no ambiguity about when to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations available, the description carries the burden and conveys read-only behavior through 'Get' and 'Returns'. It adds the global-scope nuance ('entire world'), though it does not discuss format, timezone, or edge cases. For a parameterless getter, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler. The first states the action, the second adds return detail and usage guidance. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, parameterless getter with no output schema, the description tells the agent what the tool returns and when to use it. Minor ambiguity about the exact returned format or timezone exists, but it does not hinder correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so baseline 4 applies. There are no parameter semantics to clarify, and the description adds no unnecessary parameter detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get the current world time') and clarifies what is returned. It is clearly distinct from siblings like advance_world_time because it emphasizes 'current' and 'check' rather than modifying time.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs when to use the tool ('Use this to check what time period you're currently in'), giving clear context. It does not name alternatives or exclusions, but the intended use is obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of actions to return (default: 5)
queryYesDescribe what you want to accomplish in natural language. The gateway will discover relevant actions from all connected systems. Examples: "Turn on the lights if it's raining", "Check the weather and adjust the thermostat", "Lock the front door and turn off all lights"

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral burden. It transparently explains that returned actions are not callable, must be chained, and require execute_action. It also reveals atomicity and cross-system scope, though it does not address potential side effects, authentication, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is heavily over-specified with repeated warnings, multiple workflow examples, and broad claims about universal connectivity. While it is front-loaded with critical information, much of the content is redundant and could be condensed without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite verbosity, the description fully equips an agent to use the tool correctly within the wider action workflow: it explains chaining, names sibling tools, provides two end-to-end examples, and explicitly prohibits calling returned actions as tools. Nothing essential for invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description reinforces that query is a natural-language description of the desired outcome, but adds little beyond the schema's own examples for the limit parameter. The chaining details are more about execute_action than about search_actions' parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Discover available ATOMIC actions by describing what you want to accomplish' and explicitly contrasts it with execute_action. It also clarifies that returned actions are not tools, which distinguishes this tool's output from being directly invocable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit workflow guidance: use search_actions to discover actions, then execute_action to run them, and warns not to treat action names as tools. It also names sibling tools (get_world_time, advance_world_time) and shows concrete example workflows, leaving little ambiguity about when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.0
    • First observedadvance_world_time
    • First observedexecute_action
    • First observedget_world_time
    • First observedsearch_actions
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.5/5.0
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 issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mcp-toolkit

    YoshiLoL0526
    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
  • CatoBot autoexperiment MCP Server by IamCatoBot

    CatoBot autoexperiment MCPofficial

    IamCatoBot
    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

  • AutoLearn MCP Server

    autolearnai
    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

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/FokkeZB/mcp-simulator'

If you have feedback or need assistance with the MCP directory API, please join our Discord server