# 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

## Installation

```bash
pnpm install
```

## Usage

### Run as MCP Server (stdio)

```bash
pnpm dev
```

Or build and run:

```bash
pnpm build
pnpm start
```

### Run Web UI

```bash
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:
```bash
# 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):

```json
{
  "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

```bash
# 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