convez.ai
MCP Server
corezoid

simulator-ai-plugin

corezoid/simulator-ai-plugin

Ver no GitHub
BomPluginScore · de 0 a 100

Claude Code & Codex plugin for Simulator.Company — a Go MCP server exposing the platform REST API plus skills for actors, graphs, forms, and financial accounts.

Instalação

$npx convez-ai corezoid/simulator-ai-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
62
Forks
13
Acompanhando
1
Saúde
100%
Último commit
há 5 dias
Versão
v2.15.0
Issues abertas
11
Contribuidores
4

README

A tradução para o português deste README ainda está na fila.

Simulator.Company — Claude Code & Codex Plugin

License: MIT Go 1.25+ MCP Release Claude Code

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.

What it does

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:

SkillActivate withCovers
simulator"use Simulator", "call Simulator API"Full platform overview, all entities, MCP tools
simulator-init"setup", "connect to simulator", "login to simulator"OAuth login, workspace selection, environment setup
simulator-graph"create actor", "link nodes", "add to layer"Actors, links, layers, graph traversal, bulk push/pull
simulator-forms"create form", "design template", "Account Template"Form templates (Account Templates), field classes, system forms
simulator-actors"create a record", "fill in a template", "update actor data"Actor instances of a form, the data value protocol, search & filter
simulator-smart-forms"smart form", "CDU", "edit page config", "push smart form"Smart Form lifecycle, pages, CDU protocol, releases
simulator-finance"record transaction", "account balance", "transfer funds"Accounts, transactions, transfers, currencies, counters
simulator-charts"chart", "dashboard", "visualise on layer"Dashboard charts & time-series visualisation on layers
simulator-reactions"comment on this actor", "reply", "pin comment"Reactions: comments / events / approvals / ratings (threaded)
simulator-attachments"upload a file", "attach document", "rename file"Files: upload, attach/detach to actors & reactions
simulator-access"share with", "grant access", "who can edit this"Access rules: grant/revoke view/modify/… on objects

Requirements

  • 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

Installation

Claude Code

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

Codex

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.

Updating

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

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

Authentication

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

Static token (optional)

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.

Configuration

Environment variableRequiredDescription
ACCESS_TOKENNoStatic token — overrides OAuth2 saved credentials
ACCESS_TOKEN_EXPIRES_ATNoToken expiry timestamp (RFC 3339) — written automatically after OAuth login
ACCOUNT_URLNoOAuth account (SA) URL — set automatically by set-environment (derived from the gateway's public config); overrides the default https://account.corezoid.com
WORKSPACE_IDNoDefault workspace ID (accId) — set automatically after set-workspace
SIMULATOR_PROFILENoEnvironment profile: local | prod (default prod); also via --profile
SIMULATOR_API_BASE_URLNoAPI base URL — set automatically by set-environment; overrides the profile (e.g. http://localhost:9000/papi/1.0)
SIMULATOR_ACCOUNT_URLNoOverride the profile's OAuth account (SA) URL
SIMULATOR_OAUTH_CLIENT_IDNoOAuth2 client ID — on-prem deployments with a custom authorization server should set this to their own client ID; cloud (account.corezoid.com) users do not need it

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.

Usage

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.

MCP Tools

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):

DomainTools
FormscreateForm getForm getForms searchForms updateForm deleteForm setFormStatus createFormAccount getFormAccounts removeFormAccount getLinkedForms getFormsTree
ActorscreateActor getActor getActorByRef searchActors searchLayerActors filterActors updateActor deleteActor setActorStatus getSystemActor getCorezoidProcesses
AccountscreateAccount getAccount getAccounts getBalance getChildAccounts updateAccount setAccountAmount deleteAccount createCurrency getCurrencies searchCurrencies createAccountName getAccountNames updateAccountName searchAccountNames
CounterssaveCounters setCounters getCounters
Access rulesgetAccessRules saveAccessRules getTemplateActorsAccess saveTemplateActorsAccess getTreeLayerAccess saveTreeLayerAccess bulkSaveAccessRules bulkSaveAccountPairsAccessRules
TransactionscreateTransaction finalizeTransaction atomCreateTransaction getTransactions getAccountTransactions getTransactionByRef createTransfer createTransferTwoStep getTransfer getTransferByRef filterTransfers
Graph (links)createLink massLink getEdge updateEdge deleteEdge existLink deleteEdgesByNodes getEdgeTypes getLayerActors getRelatedActors getLinkedActors getActorLinks manageLayerActors moveActors existLayerElement cleanGraphLayer layerStats
ReactionscreateReaction updateReaction deleteReaction getReactions getReactionsStats markReactionsRead getPinnedReactions togglePinnedReaction
AttachmentsgetAttachments addAttachments updateAttachment removeAttachments uploadBase64
SearchsearchAll (global text/semantic search across actors & users)
UsersgetUsers getUser searchUsers (workspace members — resolve a userId/groupId for sharing)
Setupset-environment (cloud preset or custom/local URL) login getWorkspaces set-workspace (by accId or name)

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

ToolDescription
pullGraphFileFetch all actors and edges from a layer and write them to <layerId>.yaml in the working directory
pushGraphFileRead <layerId>.yaml and sync it with the server layer: create / update / remove to match the file
getAllLayerPlacementsReturn every actor placement on a layer in one paginated call
compactGraphLayoutAuto-layout a layer into domain-clustered grids (replaces the pull → edit → push loop)
pruneLongEdgesDelete edges longer than a distance threshold; preserves hierarchy edges
uploadActorPicture / uploadActorPictureBulkSet actor pictures from URL / file / base64; auto-rasterise SVG → PNG; bulk dedupes by SHA-256
createSmartFormCreate a new Smart Form actor with develop + production environments
pullSmartFormDownload all env file trees of a Smart Form to <actorId>/<env>/ with .manifest.json
pushSmartFormDiff local develop files against .manifest.json, validate, and push changed files in one batch
deploySmartFormDeploy one Smart Form env to another (develop → production); creates a new release
listReleasesList releases for a Smart Form environment
diffReleasesShow added / removed / modified files between two releases
rollbackReleaseRoll back to a prior release (forward-only: creates a new active release)
getFileHistoryList version history for a Smart Form file (fileId from .manifest.json)
getFileVersionFetch the source of one specific file version
rollbackFileRestore a file to a prior version
listTrashList soft-deleted objects in a Smart Form environment
restoreFromTrashRestore a soft-deleted object from trash
createChartCreate a dashboard chart actor (dynamic actorFilter or explicit accounts mode)

Architecture

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.

Simulator.Company Entity Model

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

Skills reference

/simulator

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.

/simulator-init

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.

/simulator-graph

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

/simulator-forms

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

/simulator-actors

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)

/simulator-smart-forms

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

/simulator-finance

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

/simulator-charts

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

Project structure

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
├── 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

Local development

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

1. Pick the environment

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.

2. Connect it in Claude Code

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

3. Authenticate and choose a workspace

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

4. Restart after you change the plugin

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

Run / test outside Claude Code

make run-local      # go run ./cmd/server --profile local
make run-prod       # against the public gateway
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

Debugging

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

Compatibility

ComponentSupported versionsNotes
Claude Code≥ 1.xMCP protocol 2025-03-26
Codexcurrent stableSame MCP server, same skills
Go toolchain1.24+ (module declares 1.25)Required to run the MCP server via go run
macOS13 Ventura and laterTested on arm64 and amd64
LinuxUbuntu 22.04+, Debian 12+amd64 tested
Windowsnot testedLikely works; PRs welcome

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.

Links

Contributing & support

License

MIT © Simulator.Company (Corezoid)

Ver o original no GitHub

Bom para

Relacionados