{"id":50838099,"url":"https://github.com/corezoid/simulator-ai-plugin","last_synced_at":"2026-06-14T05:05:38.258Z","repository":{"id":355851137,"uuid":"1229861118","full_name":"corezoid/simulator-ai-plugin","owner":"corezoid","description":"Claude Code \u0026 Codex plugin for Simulator.Company — a Go MCP server exposing the platform REST API plus skills for actors, graphs, forms, and financial accounts.","archived":false,"fork":false,"pushed_at":"2026-06-12T11:29:06.000Z","size":3450,"stargazers_count":51,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-12T13:18:03.756Z","etag":null,"topics":["ai-plugin","anthropic","bpm","business-process","claude","claude-code","golang","mcp","model-context-protocol","simulator-company"],"latest_commit_sha":null,"homepage":"https://simulator.company","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/corezoid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-05T13:01:10.000Z","updated_at":"2026-06-12T11:28:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"f7a9e262-ee8c-4c18-8198-24e6d635a93a","html_url":"https://github.com/corezoid/simulator-ai-plugin","commit_stats":null,"previous_names":["corezoid/simulator-ai-plugin"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/corezoid/simulator-ai-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corezoid%2Fsimulator-ai-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corezoid%2Fsimulator-ai-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corezoid%2Fsimulator-ai-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corezoid%2Fsimulator-ai-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/corezoid","download_url":"https://codeload.github.com/corezoid/simulator-ai-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/corezoid%2Fsimulator-ai-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34309716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-plugin","anthropic","bpm","business-process","claude","claude-code","golang","mcp","model-context-protocol","simulator-company"],"created_at":"2026-06-14T05:05:37.512Z","updated_at":"2026-06-14T05:05:38.251Z","avatar_url":"https://github.com/corezoid.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simulator.Company — Claude Code \u0026 Codex Plugin\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Go 1.25+](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go\u0026logoColor=white)](https://go.dev/dl/)\n[![MCP](https://img.shields.io/badge/MCP-2025--03--26-555)](https://modelcontextprotocol.io)\n[![Release](https://img.shields.io/github/v/release/corezoid/simulator-ai-plugin?sort=semver)](https://github.com/corezoid/simulator-ai-plugin/releases)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-D97757)](https://claude.ai/code)\n\n\u003e **Status:** stable — released, actively maintained. Supported clients: Claude Code ≥ 1.x, Codex. Go 1.24+ required. macOS and Linux tested.\n\nA plugin for [Claude Code](https://claude.ai/code) and [Codex](https://codex.openai.com) that connects the [Simulator.Company](https://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.\n\n## What it does\n\nThe 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:\n\n| Skill                | Activate with                                            | Covers                                                  |\n|----------------------|----------------------------------------------------------|---------------------------------------------------------|\n| `simulator`          | \"use Simulator\", \"call Simulator API\"                    | Full platform overview, all entities, MCP tools         |\n| `simulator-init`     | \"setup\", \"connect to simulator\", \"login to simulator\"    | OAuth login, workspace selection, environment setup     |\n| `simulator-graph`    | \"create actor\", \"link nodes\", \"add to layer\"             | Actors, links, layers, graph traversal, bulk push/pull  |\n| `simulator-forms`    | \"create form\", \"design template\", \"Account Template\"     | Form templates (Account Templates), field classes, system forms |\n| `simulator-actors`   | \"create a record\", \"fill in a template\", \"update actor data\" | Actor instances of a form, the `data` value protocol, search \u0026 filter |\n| `simulator-smart-forms` | \"smart form\", \"CDU\", \"edit page config\", \"push smart form\" | Smart Form lifecycle, pages, CDU protocol, releases  |\n| `simulator-finance`  | \"record transaction\", \"account balance\", \"transfer funds\"| Accounts, transactions, transfers, currencies, counters |\n| `simulator-charts`   | \"chart\", \"dashboard\", \"visualise on layer\"               | Dashboard charts \u0026 time-series visualisation on layers  |\n| `simulator-reactions`| \"comment on this actor\", \"reply\", \"pin comment\"          | Reactions: comments / events / approvals / ratings (threaded) |\n| `simulator-attachments` | \"upload a file\", \"attach document\", \"rename file\"     | Files: upload, attach/detach to actors \u0026 reactions      |\n| `simulator-access`   | \"share with\", \"grant access\", \"who can edit this\"        | Access rules: grant/revoke view/modify/… on objects     |\n\n## Requirements\n\n- [Claude Code](https://claude.ai/code) or [Codex](https://codex.openai.com) installed\n- [Go 1.24+](https://go.dev/dl/) available in `PATH` (the MCP server runs via `go run`, no build step needed)\n  ```bash\n  brew install golang        # macOS\n  sudo apt install golang    # Ubuntu/Debian\n  ```\n  Verify with `go version`.\n- A Simulator.Company account\n\n## Installation\n\n### Claude Code\n\n**From the GitHub marketplace:**\n\n```bash\nclaude plugin marketplace add corezoid/simulator-ai-plugin\nclaude plugin install simulator@simulator\n```\n\n**Or from a local clone:**\n\n```bash\ngit clone https://github.com/corezoid/simulator-ai-plugin\nclaude plugin marketplace add ./simulator-ai-plugin\nclaude plugin install simulator@simulator\n```\n\n### Codex\n\n**From the GitHub marketplace:**\n\n```bash\ncodex plugin marketplace add corezoid/simulator-ai-plugin\ncodex plugin install simulator@simulator\n```\n\n**Or from a local clone:**\n\n```bash\ngit clone https://github.com/corezoid/simulator-ai-plugin\ncodex plugin marketplace add ./simulator-ai-plugin\ncodex plugin install simulator@simulator\n```\n\nNo build step, no extra setup. The MCP server starts automatically on first use.\n\n### Updating\n\n```bash\nclaude plugin update simulator@simulator   # Claude Code\ncodex plugin update simulator@simulator    # Codex\n```\n\nRestart Claude Code / Codex after updating to apply the new version.\n\n## Authentication\n\nSimulator runs on many environments (cloud, on-prem, local dev), so the first step is to\n**choose one**. The `set-environment` tool takes a cloud preset — `mw.simulator.company`\n(default) or `sim.simulator.company` — or a custom/local URL (host or full URL; `/papi/1.0`\nis appended if omitted). It fetches that gateway's **public config** to derive the correct\nOAuth account URL — the platform authenticates through the `account` system, and one account\nmay back several environments, so the auth URL is determined per gateway rather than fixed.\nThe chosen API base and account URL are saved to `.env` (`SIMULATOR_API_BASE_URL`,\n`ACCOUNT_URL`). Switching environment later clears the token + workspace and requires a fresh\n`login`.\n\nNext Claude runs the `login` tool — your browser opens for OAuth2 sign-in against the chosen\nenvironment's account URL and the token is saved. Claude then lists your workspaces with\n`getWorkspaces` and lets you pick one **by name**; `set-workspace` (by `name` or `accId`)\nsaves the choice as `WORKSPACE_ID`. You never need to know the workspace id.\n\nThe 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.\n\nYou can also trigger login manually at any time:\n\n```\nlog in to Simulator\n```\n\n### Static token (optional)\n\nIf you prefer to manage the token yourself, set it in `.env` or export it before starting Claude Code or Codex:\n\n```bash\nexport ACCESS_TOKEN=your_token_here\n```\n\nThe static token takes priority over saved credentials.\n\n## Configuration\n\n| Environment variable          | Required | Description                                                                 |\n|-------------------------------|----------|-----------------------------------------------------------------------------|\n| `ACCESS_TOKEN`                | No       | Static token — overrides OAuth2 saved credentials                           |\n| `ACCESS_TOKEN_EXPIRES_AT`     | No       | Token expiry timestamp (RFC 3339) — written automatically after OAuth login |\n| `ACCOUNT_URL`                 | No       | OAuth account (SA) URL — set automatically by `set-environment` (derived from the gateway's public config); overrides the default `https://account.corezoid.com` |\n| `WORKSPACE_ID`                | No       | Default workspace ID (`accId`) — set automatically after `set-workspace`    |\n| `SIMULATOR_PROFILE`           | No       | Environment profile: `local` \\| `prod` (default `prod`); also via `--profile` |\n| `SIMULATOR_API_BASE_URL`      | No       | API base URL — set automatically by `set-environment`; overrides the profile (e.g. `http://localhost:9000/papi/1.0`) |\n| `SIMULATOR_ACCOUNT_URL`       | No       | Override the profile's OAuth account (SA) URL                                |\n| `SIMULATOR_OAUTH_CLIENT_ID`   | No       | OAuth2 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 |\n\nAll 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.\n\n## Usage\n\nOnce installed, just talk to Claude naturally:\n\n```\nCreate a business process graph for customer onboarding with three steps:\nDocument Collection → Review → Approval. Add all steps to a layer.\n```\n\n```\nCreate a Car form template with fields: make, model, year, color, VIN.\nAdd financial accounts: purchase value (USD asset), maintenance costs (USD expense),\nand a mileage counter (km).\n```\n\n```\nRecord a $450 maintenance transaction on the Toyota Camry actor.\nThen show me all accounts and their current balances.\n```\n\n```\nSearch for all actors of form type \"Task\" on the \"Main Process\" layer.\n```\n\n```\nPull layer 1a2b3c4d-... to a local YAML, let me edit it, then push it back.\n```\n\n## MCP Tools\n\nThe MCP server exposes a **curated, typed tool set (~95 tools)** scoped to the core\nscenarios — forms, actors, accounts, transactions, graph building, applications/smart forms\n— rather than the entire REST surface. Each tool maps to a backend operation by its\n`operationId`; a drift gate keeps the set in sync with the live `/papi/1.0` contract.\n\nRead tools take an optional **`filter`** parameter — a comma-separated allow-list of fields\nto return (e.g. `id,title,data.status`; dotted paths pick nested `data` fields). The backend\nprunes the response to just those fields, so prefer it whenever only part of an entity is\nneeded to keep responses (and token cost) small. Available on every read/lookup/list tool:\n`getActor`, `getActorByRef`, `searchActors`, `searchLayerActors`, `filterActors`, `getForm`,\n`getForms`, `searchForms`, `getAccount`, `getAccounts`, `getBalance`, `getCurrencies`, `getAccountNames`,\n`getTransactions`, `getTransfer`, `getRelatedActors`, `getLinkedActors`, `getActorLinks`,\n`getLayerActors`, `getEdgeTypes`, `searchAll`, `getWorkspaces`. (For `getLayerActors`/`searchAll` it projects\nthe actor/node items.)\n\n**Curated API operations** (one tool per backend operation):\n\n| Domain        | Tools                                                                                  |\n|---------------|----------------------------------------------------------------------------------------|\n| Forms         | `createForm` `getForm` `getForms` `searchForms` `updateForm` `deleteForm` `setFormStatus` `createFormAccount` `getFormAccounts` `removeFormAccount` `getLinkedForms` `getFormsTree` |\n| Actors        | `createActor` `getActor` `getActorByRef` `searchActors` `searchLayerActors` `filterActors` `updateActor` `deleteActor` `setActorStatus` `getSystemActor` `getCorezoidProcesses` |\n| Accounts      | `createAccount` `getAccount` `getAccounts` `getBalance` `getChildAccounts` `updateAccount` `setAccountAmount` `deleteAccount` `createAccountPair` `createCurrency` `getCurrencies` `searchCurrencies` `createAccountName` `getAccountNames` `updateAccountName` `searchAccountNames` |\n| Account tags \u0026 triggers | `saveAccountActors` (link Tags/AccountTriggers actors to a pair or one account) `getDataFieldActorsByActor` `saveDataFieldActorsByActor` `getDataFieldActorsByForm` `saveDataFieldActorsByForm` (data triggers on a data field) |\n| Counters      | `saveCounters` `setCounters` `getCounters` |\n| Access rules  | `getAccessRules` `saveAccessRules` `getTemplateActorsAccess` `saveTemplateActorsAccess` `getTreeLayerAccess` `saveTreeLayerAccess` `bulkSaveAccessRules` `bulkSaveAccountPairsAccessRules` |\n| Transactions  | `createTransaction` `finalizeTransaction` `atomCreateTransaction` `getTransactions` `getAccountTransactions` `getTransactionByRef` `createTransfer` `createTransferTwoStep` `getTransfer` `getTransferByRef` `filterTransfers` |\n| Graph (links) | `createLink` `massLink` `getEdge` `updateEdge` `deleteEdge` `existLink` `deleteEdgesByNodes` `getEdgeTypes` `getLayerActors` `getRelatedActors` `getLinkedActors` `getActorLinks` `manageLayerActors` `moveActors` `existLayerElement` `cleanGraphLayer` `layerStats` |\n| Reactions     | `createReaction` `updateReaction` `deleteReaction` `getReactions` `getReactionsStats` `markReactionsRead` `getPinnedReactions` `togglePinnedReaction` |\n| Attachments   | `getAttachments` `getActorAttachments` `addAttachments` `updateAttachment` `removeAttachments` `uploadBase64` |\n| Search        | `searchAll` (global text/semantic search across actors \u0026 users)                        |\n| Users         | `getUsers` `getUser` `searchUsers` (workspace members — resolve a userId/groupId for sharing) |\n| Setup         | `set-environment` (cloud preset or custom/local URL) `login` `getWorkspaces` `set-workspace` (by accId or name) |\n\n\n**Engine tools** (multi-call workflows + client-side computation):\n\n| Tool                     | Description                                                                                          |\n|--------------------------|------------------------------------------------------------------------------------------------------|\n| `pullGraphFile`          | Fetch all actors and edges from a layer and write them to `\u003clayerId\u003e.yaml` in the working directory  |\n| `pushGraphFile`          | Read `\u003clayerId\u003e.yaml` and sync it with the server layer: create / update / remove to match the file  |\n| `getAllLayerPlacements`  | Return every actor placement on a layer in one paginated call                                        |\n| `compactGraphLayout`     | Auto-layout a layer into domain-clustered grids (replaces the pull → edit → push loop)               |\n| `pruneLongEdges`         | Delete edges longer than a distance threshold; preserves hierarchy edges                             |\n| `uploadActorPicture` / `uploadActorPictureBulk` | Set actor pictures from URL / file / base64; auto-rasterise SVG → PNG; bulk dedupes by SHA-256 |\n| `createSmartForm`        | Create a new Smart Form actor with develop + production environments                                 |\n| `pullSmartForm`          | Download all env file trees of a Smart Form to `\u003cactorId\u003e/\u003cenv\u003e/` with `.manifest.json`              |\n| `pushSmartForm`          | Diff local develop files against `.manifest.json`, validate, and push changed files in one batch     |\n| `deploySmartForm`        | Deploy one Smart Form env to another (develop → production); creates a new release                   |\n| `listReleases`           | List releases for a Smart Form environment                                                           |\n| `diffReleases`           | Show added / removed / modified files between two releases                                           |\n| `rollbackRelease`        | Roll back to a prior release (forward-only: creates a new active release)                            |\n| `getFileHistory`         | List version history for a Smart Form file (fileId from `.manifest.json`)                            |\n| `getFileVersion`         | Fetch the source of one specific file version                                                        |\n| `rollbackFile`           | Restore a file to a prior version                                                                    |\n| `listTrash`              | List soft-deleted objects in a Smart Form environment                                                |\n| `restoreFromTrash`       | Restore a soft-deleted object from trash                                                             |\n| `createChart`            | Create a dashboard chart actor (dynamic `actorFilter` or explicit accounts mode)                     |\n\n## Architecture\n\n```\nClaude Code / Codex\n  └── simulator MCP server (go run ./cmd/server --profile local|prod)\n        ├── config      cloud presets + local / prod profiles (API base + account URL)\n        ├── auth        set-environment (public config → account URL), login (OAuth2 PKCE → .env), set-workspace\n        ├── tools       curated typed operations (forms, actors, accounts,\n        │               transactions, graph, apps) — one tool per backend op\n        ├── engines     pullGraphFile, pushGraphFile, compactGraphLayout,\n        │               pruneLongEdges, getAllLayerPlacements, uploadActorPicture(Bulk), createChart\n        └── apiclient   HTTP → Simulator /papi/1.0 (local :9000 or mw gateway)\n```\n\nThe server exposes a curated, typed tool set declared in Go (not a generic spec passthrough);\na drift gate validates those declarations against the backend's `papi-openapi.json`. Skills\nadd the domain knowledge on top. For the full design — profiles, the tool registry, engines,\nthe drift gate, and the auth flow — see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n### Simulator.Company Entity Model\n\n```\nWorkspace (accId)\n  ├── Forms          — templates defining actor structure and field types\n  │     └── Actors  — instances (nodes in the business process graph)\n  │           ├── Links        — directed edges connecting actors\n  │           ├── Layers       — visual views with actor positions\n  │           ├── Accounts     — financial/metric tracking (asset, expense, counter...)\n  │           │     ├── Transactions  — credits and debits on a single account\n  │           │     └── Transfers     — atomic movement between two accounts\n  │           ├── Reactions    — comments, approvals, ratings\n  │           └── Attachments  — file storage\n  ├── Currencies     — units of value for accounts (USD, EUR, Km, Units...)\n  ├── Account Names  — category labels for accounts\n  └── Link Types     — categories for edges between actors\n```\n\n## Skills reference\n\n### `/simulator`\nUniversal 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.\n\n### `/simulator-init`\nEnvironment 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.\n\n### `/simulator-graph`\nSpecialist for graph structure operations:\n- Create, update, search, and delete actors\n- Create single or bulk links between actors\n- Manage layers — add actors with positions, search by form or text, move between layers\n- Traverse the graph — get linked actors, actor links, global layer membership\n- Pull a whole layer to YAML, edit locally, push it back\n\n### `/simulator-forms`\nSpecialist for form template (Account Template / «Шаблон рахунків») design:\n- Create custom forms as `sections[]` of typed field items (`edit`, `check`, `radio`, `select`, `multiSelect`, `calendar`, `upload`, `label`, `button`, `image`)\n- Use static or dynamic `select` sources (layer, actorFilter, actors, currencies, accountNames, workspaceMembers, …)\n- Work with system forms (Graph, Layer, Event, Script/CDU, Account, Currency, Transaction...)\n- Update, version, and manage form status; attach accounts to the actors created from the form\n\n### `/simulator-actors`\nSpecialist for actor instances (the *records* of a form / Account Template):\n- Create and update actors with a `data` object keyed by the form's field `id`s (`item_\u003cdigits\u003e`)\n- Get the per-class `data` value shapes right (string / number / boolean / option arrays / `{type,title,value}` references / calendar objects)\n- Read by UUID or `(formId, ref)`, set status, delete\n- Search across the workspace (`searchActors`) and list/rank a form's actors, optionally by account balance (`filterActors`)\n\n### `/simulator-smart-forms`\nSpecialist for Smart Form (CDU / Script / Application) authoring:\n- Pull all env files to disk with `pullSmartForm`, push changes with `pushSmartForm`\n- Edit page `config` (grid → form → section → item), `locale`, `viewModel`, `definitions`, `styles`\n- Full CDU page protocol: 28 component types, templating (`[[locale]]` / `{{viewModel}}` / `$ref`), change protocol (200/205/302)\n- Deploy `develop → production` as an immutable release, list/diff/rollback releases\n- File history, version restore, and trash management\n\n### `/simulator-finance`\nSpecialist for financial and metric tracking:\n- Set up currencies and account name categories\n- Create accounts of any type on actors (asset, liability, expense, income, counter, state)\n- Record immediate or 2-step (authorize → complete/cancel) transactions\n- Create atomic multi-account transfers\n- Query balances, transaction history, and filter transfers\n\n### `/simulator-charts`\nSpecialist for dashboard charts and time-series visualisation on graph layers — builds\nchart actors via `createChart` (dynamic `actorFilter` or explicit accounts mode).\n\n## Project structure\n\n```\nsimulator-ai-plugin/\n├── .claude-plugin/\n│   ├── marketplace.json         # Claude Code marketplace listing (points to plugins/simulator)\n│   └── plugin.json              # Claude Code plugin manifest (root-level install target)\n├── .mcp.json                    # Root-level MCP server config (used when installed via marketplace)\n├── .agents/\n│   └── plugins/\n│       └── marketplace.json     # Codex marketplace listing (points to plugins/simulator)\n├── Makefile                     # build / vet / test / discovery / run-local / run-prod / inspect\n├── CHANGELOG.md\n├── CLAUDE.md                    # Repo guide for Claude Code (points to AGENTS.md)\n├── AGENTS.md                    # Repo guide for coding agents (canonical)\n├── docs/                        # Project / contributor documentation\n│   ├── ARCHITECTURE.md          # Plugin \u0026 MCP-server architecture\n│   └── INTEGRATION.md           # pong-server integration plan \u0026 status\n├── public/                      # Generated AI-discovery artifacts (llms.txt, .well-known/skills/index.json)\n└── plugins/simulator/           # Plugin root (CLAUDE_PLUGIN_ROOT for both Claude Code and Codex)\n    ├── .claude-plugin/\n    │   └── plugin.json          # Claude Code plugin manifest\n    ├── .codex-plugin/\n    │   └── plugin.json          # Codex plugin manifest\n    ├── .mcp.json                # MCP server configuration (go run ./cmd/server)\n    ├── mcp-server/              # Go MCP server source (see mcp-server/README.md)\n    │   ├── cmd/server/          # entry point: profile → tools → stdio\n    │   ├── cmd/gendiscovery/    # regenerate public/ discovery artifacts\n    │   ├── go.mod / go.sum\n    │   ├── internal/\n    │   │   ├── config/          # local/prod profiles\n    │   │   ├── apiclient/       # HTTP client (auth, accId, timeouts)\n    │   │   ├── tools/           # curated typed tools + testdata (drift spec, eval)\n    │   │   └── engines/         # graph sync, layout, prune, upload, chart\n    │   └── app/auth/            # OAuth2 PKCE flow + .env credential storage\n    ├── skills/\n    │   ├── simulator/                      # Universal assistant skill\n    │   │   ├── SKILL.md\n    │   │   └── references/api-operations.md\n    │   ├── simulator-init/                 # Environment setup skill\n    │   ├── simulator-graph/                # Graph specialist skill\n    │   ├── simulator-forms/                # Forms (Account Templates) specialist skill\n    │   ├── simulator-actors/               # Actor-instance / data-protocol specialist skill\n    │   ├── simulator-smart-forms/          # Smart Form (CDU) authoring specialist skill\n    │   ├── simulator-finance/              # Finance specialist skill\n    │   └── simulator-charts/               # Dashboard charts specialist skill\n    └── docs/                    # Plugin-shipped reference (referenced by skills)\n        ├── entities/            # Entity reference docs\n        └── user-flows/          # End-to-end walkthroughs\n```\n\n## Local development\n\nRun the plugin from this repo (developing it, or testing against a local `pong-server`),\nnot from the marketplace.\n\n**Requirements:** Go 1.24+, and a backend — a local `pong-server` on `http://localhost:9000`\n(profile `local`) or the public gateway (profile `prod`).\n\n### 1. Pick the environment\n\nCreate `plugins/simulator/mcp-server/.env`:\n\n```\nSIMULATOR_PROFILE=local      # or prod\n```\n\nRunning with the **`local` profile** (via `SIMULATOR_PROFILE=local` or `--profile local`) does\ntwo things for development:\n\n- the server starts pointed at a local `pong-server` on `http://localhost:9000`;\n- **`set-environment` additionally offers a `local` preset** (`localhost:9000`) — i.e.\n  `set-environment(preset=\"local\")` works. In the default `prod` profile that preset is\n  hidden, so end users are only offered the cloud gateways (`mw` / `sim`) and a custom URL.\n\n`login` / `set-workspace` (and `set-environment`) write `ACCESS_TOKEN` / `WORKSPACE_ID` /\n`SIMULATOR_API_BASE_URL` / `ACCOUNT_URL` back into this same file.\n\n### 2. Connect it in Claude Code\n\nPick **one** way (don't combine — two would register the `simulator` server twice):\n\n- **Plugin dir (recommended for dev):** start Claude Code pointing at the repo —\n  ```bash\n  claude --plugin-dir /Users/\u003cyou\u003e/PJ/control/simulator-ai-plugin/plugins/simulator\n  ```\n  To run against the **local** backend, prefix the launch with `SIMULATOR_PROFILE` — the\n  MCP server inherits it from the Claude Code process, so you don't have to edit `.env`:\n  ```bash\n  SIMULATOR_PROFILE=local claude --plugin-dir /Users/\u003cyou\u003e/PJ/control/simulator-ai-plugin/plugins/simulator\n  ```\n  (This targets `pong-server` on `:9000` and makes `set-environment` offer the `local`\n  preset; without it the server defaults to the `prod` profile. An env var set this way\n  wins over `mcp-server/.env`. Equivalently: put `SIMULATOR_PROFILE=local` in\n  `plugins/simulator/mcp-server/.env`.)\n- **Local marketplace install:**\n  ```\n  /plugin marketplace add /Users/\u003cyou\u003e/PJ/control/simulator-ai-plugin/plugins/simulator\n  /plugin install simulator@simulator\n  /reload-plugins\n  ```\n- **Project auto-load:** simply opening this repo as your project loads the root\n  `.mcp.json` (a project-scoped server) — approve it when Claude Code asks.\n\nVerify with `/mcp` — you should see **simulator** ✓ with ~50 tools.\n\n\u003e **Avoiding conflicts with the installed (prod) plugin.** If you also have the published\n\u003e `simulator@simulator` plugin installed, it registers the **same** `simulator` MCP server\n\u003e and the same skills — so two copies collide. While developing locally, **disable the prod\n\u003e plugin**:\n\u003e ```\n\u003e /plugin                       # toggle simulator@simulator OFF (or: claude plugin disable simulator@simulator)\n\u003e ```\n\u003e Re-enable it when you're done. Disabling is the only clean option if you're testing the\n\u003e **skills** (they reference tools by bare name, so with both active they'd drive whichever\n\u003e server wins — usually prod, against the prod backend).\n\u003e\n\u003e If you must run both at once (e.g. to call your dev tools explicitly via\n\u003e `mcp__simulator-dev__*` while keeping prod for normal use), rename the server in the root\n\u003e `.mcp.json` from `simulator` to `simulator-dev` so the MCP server names don't clash. The\n\u003e prod backend vs your local backend stay separate anyway — each instance reads its own\n\u003e `.env` (the installed plugin's dir vs `plugins/simulator/mcp-server/.env`).\n\n### 3. Authenticate and choose a workspace\n\n```\nlog in to Simulator          # OAuth in the browser → token saved to .env\nwhich workspaces do I have?  # getWorkspaces → list by name\nwork in \u003cworkspace name\u003e     # set-workspace(name=…) → saves WORKSPACE_ID\n```\n\n### 4. Restart after you change the plugin\n\nEdited Go code, a tool, `.env`, `.mcp.json`, or a skill? Reload — **no reinstall needed**:\n\n```\n/reload-plugins\n```\n\nThis kills and relaunches the Go MCP server (`go run ./cmd/server`), re-reading the source\nand `.env`. Check `/mcp` again if a server shows as failed (see its **Errors** tab in\n`/plugin`).\n\n### Run / test outside Claude Code\n\n```bash\nmake run-local      # go run ./cmd/server --profile local\nmake run-prod       # against the public gateway\nmake inspect        # MCP Inspector web UI wrapping the server (PROFILE=local|prod)\nmake test           # unit + scenario + drift + eval tests\nmake lint           # golangci-lint v2 (gosec clean; style backlog)\nmake eval           # behavioural eval, dry (needs ANTHROPIC_API_KEY)\nmake eval-live      # behavioural eval executing tools against the backend\n```\n\n`make inspect` launches the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)\n(needs Node.js / `npx`) — a browser UI to list and call the server's tools and read its\nresources by hand. It prints a `localhost:6274` URL with a session token; open it, hit\n**Connect**, then browse **Tools** / **Resources**. Authenticate first (the `login` tool or\na valid `.env`) since calls hit the real backend. See the\n[MCP server README](plugins/simulator/mcp-server/README.md#inspecting--debugging-with-the-mcp-inspector)\nfor the headless `--cli` mode.\n\n## Debugging\n\nRun the server directly against a profile (it logs startup config and request errors to\nstderr):\n\n```bash\ncd plugins/simulator/mcp-server\ngo run ./cmd/server --profile local\n```\n\nTests cover config, the HTTP client, the curated tools (scenarios + `-race`), the backend\ndrift gate, and the eval scenarios:\n\n```bash\ngo test ./...\n```\n\n## Compatibility\n\n| Component         | Supported versions            | Notes                                       |\n|-------------------|-------------------------------|---------------------------------------------|\n| Claude Code       | ≥ 1.x                         | MCP protocol 2025-03-26                     |\n| Codex             | current stable                | Same MCP server, same skills                |\n| Go toolchain      | 1.24+ (module declares 1.25)  | Required to run the MCP server via `go run` |\n| macOS             | 13 Ventura and later          | Tested on arm64 and amd64                   |\n| Linux             | Ubuntu 22.04+, Debian 12+     | amd64 tested                                |\n| Windows           | not tested                    | Likely works; PRs welcome                   |\n\n\u003e **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.\n\n## Links\n\n- [Simulator.Company](https://simulator.company)\n- [API Documentation](https://doc.simulator.company)\n- [Claude Code](https://claude.ai/code)\n- [MCP Protocol](https://modelcontextprotocol.io)\n\n## Contributing \u0026 support\n\n- [Contributing guide](CONTRIBUTING.md) — layout, build/verify, conventions\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Security policy](SECURITY.md) — report vulnerabilities privately\n- [Open an issue](https://github.com/corezoid/simulator-ai-plugin/issues)\n\n## License\n\n[MIT](LICENSE) © Simulator.Company (Corezoid)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorezoid%2Fsimulator-ai-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorezoid%2Fsimulator-ai-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorezoid%2Fsimulator-ai-plugin/lists"}