Status: stable — released, actively maintained. Supported clients: Claude Code ≥ 1.x, Codex. Go 1.24+ required. macOS and Linux tested.

A plugin for Claude Code and Codex that connects the Simulator.Company platform to Claude via MCP (Model Context Protocol). Claude gets direct access to the Simulator REST API and domain knowledge to manage actors, graphs, forms, and financial accounts through natural conversation.

The plugin bundles a Go MCP server that exposes the full Simulator.Company public API as MCP tools and provides specialist skills that teach Claude the platform's entity model and common workflows:

• Claude Code or Codex installed
• Go 1.24+ available in PATH (the MCP server runs via go run, no build step needed)

  brew install golang        # macOS
  sudo apt install golang    # Ubuntu/Debian

  Verify with go version.
• A Simulator.Company account

From the GitHub marketplace:

claude plugin marketplace add corezoid/simulator-ai-plugin
claude plugin install simulator@simulator

Or from a local clone:

git clone https://github.com/corezoid/simulator-ai-plugin
claude plugin marketplace add ./simulator-ai-plugin
claude plugin install simulator@simulator

From the GitHub marketplace:

codex plugin marketplace add corezoid/simulator-ai-plugin
codex plugin install simulator@simulator

Or from a local clone:

git clone https://github.com/corezoid/simulator-ai-plugin
codex plugin marketplace add ./simulator-ai-plugin
codex plugin install simulator@simulator

No build step, no extra setup. The MCP server starts automatically on first use.

claude plugin update simulator@simulator   # Claude Code
codex plugin update simulator@simulator    # Codex

Restart Claude Code / Codex after updating to apply the new version.

Simulator runs on many environments (cloud, on-prem, local dev), so the first step is to choose one. The set-environment tool takes a cloud preset — mw.simulator.company (default) or sim.simulator.company — or a custom/local URL (host or full URL; /papi/1.0 is appended if omitted). It fetches that gateway's public config to derive the correct OAuth account URL — the platform authenticates through the account system, and one account may back several environments, so the auth URL is determined per gateway rather than fixed. The chosen API base and account URL are saved to .env (SIMULATOR_API_BASE_URL, ACCOUNT_URL). Switching environment later clears the token + workspace and requires a fresh login.

Next Claude runs the login tool — your browser opens for OAuth2 sign-in against the chosen environment's account URL and the token is saved. Claude then lists your workspaces with getWorkspaces and lets you pick one by name; set-workspace (by name or accId) saves the choice as WORKSPACE_ID. You never need to know the workspace id.

The token is saved to .env in your working directory (mode 0600) and reused on every subsequent session. When it expires, the login flow triggers again automatically.

You can also trigger login manually at any time:

log in to Simulator

If you prefer to manage the token yourself, set it in .env or export it before starting Claude Code or Codex:

export ACCESS_TOKEN=your_token_here

The static token takes priority over saved credentials.

All values are read from a .env file in the current working directory at startup, and the login / set-workspace tools persist their results back to that file.

Once installed, just talk to Claude naturally:

Create a business process graph for customer onboarding with three steps:
Document Collection → Review → Approval. Add all steps to a layer.

Create a Car form template with fields: make, model, year, color, VIN.
Add financial accounts: purchase value (USD asset), maintenance costs (USD expense),
and a mileage counter (km).

Record a $450 maintenance transaction on the Toyota Camry actor.
Then show me all accounts and their current balances.

Search for all actors of form type "Task" on the "Main Process" layer.

Pull layer 1a2b3c4d-... to a local YAML, let me edit it, then push it back.

The MCP server exposes a curated, typed tool set (~95 tools) scoped to the core scenarios — forms, actors, accounts, transactions, graph building, applications/smart forms — rather than the entire REST surface. Each tool maps to a backend operation by its operationId; a drift gate keeps the set in sync with the live /papi/1.0 contract.

Read tools take an optional filter parameter — a comma-separated allow-list of fields to return (e.g. id,title,data.status; dotted paths pick nested data fields). The backend prunes the response to just those fields, so prefer it whenever only part of an entity is needed to keep responses (and token cost) small. Available on every read/lookup/list tool: getActor, getActorByRef, searchActors, searchLayerActors, filterActors, getForm, getForms, searchForms, getAccount, getAccounts, getBalance, getCurrencies, getAccountNames, getTransactions, getTransfer, getRelatedActors, getLinkedActors, getActorLinks, getLayerActors, getEdgeTypes, searchAll, getWorkspaces. (For getLayerActors/searchAll it projects the actor/node items.)

Curated API operations (one tool per backend operation):

Engine tools (multi-call workflows + client-side computation):

Claude Code / Codex
  └── simulator MCP server (go run ./cmd/server --profile local|prod)
        ├── config      cloud presets + local / prod profiles (API base + account URL)
        ├── auth        set-environment (public config → account URL), login (OAuth2 PKCE → .env), set-workspace
        ├── tools       curated typed operations (forms, actors, accounts,
        │               transactions, graph, apps) — one tool per backend op
        ├── engines     pullGraphFile, pushGraphFile, compactGraphLayout,
        │               pruneLongEdges, getAllLayerPlacements, uploadActorPicture(Bulk), createChart
        └── apiclient   HTTP → Simulator /papi/1.0 (local :9000 or mw gateway)

The server exposes a curated, typed tool set declared in Go (not a generic spec passthrough); a drift gate validates those declarations against the backend's papi-openapi.json. Skills add the domain knowledge on top. For the full design — profiles, the tool registry, engines, the drift gate, and the auth flow — see docs/ARCHITECTURE.md.

Workspace (accId)
  ├── Forms          — templates defining actor structure and field types
  │     └── Actors  — instances (nodes in the business process graph)
  │           ├── Links        — directed edges connecting actors
  │           ├── Layers       — visual views with actor positions
  │           ├── Accounts     — financial/metric tracking (asset, expense, counter...)
  │           │     ├── Transactions  — credits and debits on a single account
  │           │     └── Transfers     — atomic movement between two accounts
  │           ├── Reactions    — comments, approvals, ratings
  │           └── Attachments  — file storage
  ├── Currencies     — units of value for accounts (USD, EUR, Km, Units...)
  ├── Account Names  — category labels for accounts
  └── Link Types     — categories for edges between actors

Universal Simulator assistant. Knows the full platform model, all entity types, and common workflow sequences. Use this when you need guidance across multiple domains or want to explore what's possible.

Environment setup assistant — runs login, picks a workspace, and saves credentials to .env. Use it the first time you connect to Simulator or when switching workspaces.

Specialist for graph structure operations:

• Create, update, search, and delete actors
• Create single or bulk links between actors
• Manage layers — add actors with positions, search by form or text, move between layers
• Traverse the graph — get linked actors, actor links, global layer membership
• Pull a whole layer to YAML, edit locally, push it back

Specialist for form template (Account Template / «Шаблон рахунків») design:

• Create custom forms as sections[] of typed field items (edit, check, radio, select, multiSelect, calendar, upload, label, button, image)
• Use static or dynamic select sources (layer, actorFilter, actors, currencies, accountNames, workspaceMembers, …)
• Work with system forms (Graph, Layer, Event, Script/CDU, Account, Currency, Transaction...)
• Update, version, and manage form status; attach accounts to the actors created from the form

Specialist for actor instances (the records of a form / Account Template):

• Create and update actors with a data object keyed by the form's field ids (item_<digits>)
• Get the per-class data value shapes right (string / number / boolean / option arrays / {type,title,value} references / calendar objects)
• Read by UUID or (formId, ref), set status, delete
• Search across the workspace (searchActors) and list/rank a form's actors, optionally by account balance (filterActors)

Specialist for Smart Form (CDU / Script / Application) authoring:

• Pull all env files to disk with pullSmartForm, push changes with pushSmartForm
• Edit page config (grid → form → section → item), locale, viewModel, definitions, styles
• Full CDU page protocol: 28 component types, templating ([[locale]] / {{viewModel}} / $ref), change protocol (200/205/302)
• Deploy develop → production as an immutable release, list/diff/rollback releases
• File history, version restore, and trash management

Specialist for financial and metric tracking:

• Set up currencies and account name categories
• Create accounts of any type on actors (asset, liability, expense, income, counter, state)
• Record immediate or 2-step (authorize → complete/cancel) transactions
• Create atomic multi-account transfers
• Query balances, transaction history, and filter transfers

Specialist for dashboard charts and time-series visualisation on graph layers — builds chart actors via createChart (dynamic actorFilter or explicit accounts mode).

simulator-ai-plugin/
├── .claude-plugin/
│   ├── marketplace.json         # Claude Code marketplace listing (points to plugins/simulator)
│   └── plugin.json              # Claude Code plugin manifest (root-level install target)
├── .mcp.json                    # Root-level MCP server config (used when installed via marketplace)
├── .agents/
│   └── plugins/
│       └── marketplace.json     # Codex marketplace listing (points to plugins/simulator)
├── Makefile                     # build / vet / test / discovery / run-local / run-prod / inspect
├── CHANGELOG.md
├── CLAUDE.md                    # Repo guide for Claude Code (points to AGENTS.md)
├── AGENTS.md                    # Repo guide for coding agents (canonical)
├── docs/                        # Project / contributor documentation
│   ├── ARCHITECTURE.md          # Plugin & MCP-server architecture
│   └── INTEGRATION.md           # pong-server integration plan & status
├── public/                      # Generated AI-discovery artifacts (llms.txt, .well-known/skills/index.json)
└── plugins/simulator/           # Plugin root (CLAUDE_PLUGIN_ROOT for both Claude Code and Codex)
    ├── .claude-plugin/
    │   └── plugin.json          # Claude Code plugin manifest
    ├── .codex-plugin/
    │   └── plugin.json          # Codex plugin manifest
    ├── .mcp.json                # MCP server configuration (go run ./cmd/server)
    ├── mcp-server/              # Go MCP server source (see mcp-server/README.md)
    │   ├── cmd/server/          # entry point: profile → tools → stdio
    │   ├── cmd/gendiscovery/    # regenerate public/ discovery artifacts
    │   ├── go.mod / go.sum
    │   ├── internal/
    │   │   ├── config/          # local/prod profiles
    │   │   ├── apiclient/       # HTTP client (auth, accId, timeouts)
    │   │   ├── tools/           # curated typed tools + testdata (drift spec, eval)
    │   │   └── engines/         # graph sync, layout, prune, upload, chart
    │   └── app/auth/            # OAuth2 PKCE flow + .env credential storage
    ├── skills/
    │   ├── simulator/                      # Universal assistant skill
    │   │   ├── SKILL.md
    │   │   └── references/api-operations.md
    │   ├── simulator-init/                 # Environment setup skill
    │   ├── simulator-graph/                # Graph specialist skill
    │   ├── simulator-forms/                # Forms (Account Templates) specialist skill
    │   ├── simulator-actors/               # Actor-instance / data-protocol specialist skill
    │   ├── simulator-smart-forms/          # Smart Form (CDU) authoring specialist skill
    │   ├── simulator-finance/              # Finance specialist skill
    │   └── simulator-charts/               # Dashboard charts specialist skill
    └── docs/                    # Plugin-shipped reference (referenced by skills)
        ├── entities/            # Entity reference docs
        └── user-flows/          # End-to-end walkthroughs

Run the plugin from this repo (developing it, or testing against a local pong-server), not from the marketplace.

Requirements: Go 1.24+, and a backend — a local pong-server on http://localhost:9000 (profile local) or the public gateway (profile prod).

Create plugins/simulator/mcp-server/.env:

SIMULATOR_PROFILE=local      # or prod

Running with the local profile (via SIMULATOR_PROFILE=local or --profile local) does two things for development:

• the server starts pointed at a local pong-server on http://localhost:9000;
• set-environment additionally offers a local preset (localhost:9000) — i.e. set-environment(preset="local") works. In the default prod profile that preset is hidden, so end users are only offered the cloud gateways (mw / sim) and a custom URL.

login / set-workspace (and set-environment) write ACCESS_TOKEN / WORKSPACE_ID / SIMULATOR_API_BASE_URL / ACCOUNT_URL back into this same file.

Pick one way (don't combine — two would register the simulator server twice):

• Plugin dir (recommended for dev): start Claude Code pointing at the repo —

  claude --plugin-dir /Users/<you>/PJ/control/simulator-ai-plugin/plugins/simulator

  To run against the local backend, prefix the launch with SIMULATOR_PROFILE — the MCP server inherits it from the Claude Code process, so you don't have to edit .env:

  SIMULATOR_PROFILE=local claude --plugin-dir /Users/<you>/PJ/control/simulator-ai-plugin/plugins/simulator

  (This targets pong-server on :9000 and makes set-environment offer the local preset; without it the server defaults to the prod profile. An env var set this way wins over mcp-server/.env. Equivalently: put SIMULATOR_PROFILE=local in plugins/simulator/mcp-server/.env.)
• Local marketplace install:

  /plugin marketplace add /Users/<you>/PJ/control/simulator-ai-plugin/plugins/simulator
  /plugin install simulator@simulator
  /reload-plugins
  

• Project auto-load: simply opening this repo as your project loads the root .mcp.json (a project-scoped server) — approve it when Claude Code asks.

Verify with /mcp — you should see simulator ✓ with ~50 tools.

Avoiding conflicts with the installed (prod) plugin. If you also have the published simulator@simulator plugin installed, it registers the same simulator MCP server and the same skills — so two copies collide. While developing locally, disable the prod plugin:

/plugin                       # toggle simulator@simulator OFF (or: claude plugin disable simulator@simulator)

Re-enable it when you're done. Disabling is the only clean option if you're testing the skills (they reference tools by bare name, so with both active they'd drive whichever server wins — usually prod, against the prod backend).

If you must run both at once (e.g. to call your dev tools explicitly via mcp__simulator-dev__* while keeping prod for normal use), rename the server in the root .mcp.json from simulator to simulator-dev so the MCP server names don't clash. The prod backend vs your local backend stay separate anyway — each instance reads its own .env (the installed plugin's dir vs plugins/simulator/mcp-server/.env).

log in to Simulator          # OAuth in the browser → token saved to .env
which workspaces do I have?  # getWorkspaces → list by name
work in <workspace name>     # set-workspace(name=…) → saves WORKSPACE_ID

Edited Go code, a tool, .env, .mcp.json, or a skill? Reload — no reinstall needed:

/reload-plugins

This kills and relaunches the Go MCP server (go run ./cmd/server), re-reading the source and .env. Check /mcp again if a server shows as failed (see its Errors tab in /plugin).

make run-local      # go run ./cmd/server --profile local
make run-prod       # against the public gateway
make inspect        # MCP Inspector web UI wrapping the server (PROFILE=local|prod)
make test           # unit + scenario + drift + eval tests
make lint           # golangci-lint v2 (gosec clean; style backlog)
make eval           # behavioural eval, dry (needs ANTHROPIC_API_KEY)
make eval-live      # behavioural eval executing tools against the backend

make inspect launches the MCP Inspector (needs Node.js / npx) — a browser UI to list and call the server's tools and read its resources by hand. It prints a localhost:6274 URL with a session token; open it, hit Connect, then browse Tools / Resources. Authenticate first (the login tool or a valid .env) since calls hit the real backend. See the MCP server README for the headless --cli mode.

Run the server directly against a profile (it logs startup config and request errors to stderr):

cd plugins/simulator/mcp-server
go run ./cmd/server --profile local

Tests cover config, the HTTP client, the curated tools (scenarios + -race), the backend drift gate, and the eval scenarios:

go test ./...

Note: If your Go installation is older than the module's go directive, the toolchain manager will try to download a newer version from proxy.golang.org. In air-gapped environments set GOTOOLCHAIN=local and install a matching Go version manually.

• Simulator.Company
• API Documentation
• Claude Code
• MCP Protocol

• Contributing guide — layout, build/verify, conventions
• Code of Conduct
• Security policy — report vulnerabilities privately
• Open an issue

MIT © Simulator.Company (Corezoid)