SimArch MCP server
Commit Oct 27, 2026Orchestrate autonomous AI organizations and execute time-compressed world simulations through enforceable role contracts and persistent task DAGs.
Also known as isiraglobal/SimArch
- Stars
- 1
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 27, 2026
- License
- Apache-2.0
What is SimArch MCP?
SimArch orchestrates autonomous AI organizations and execute time-compressed world simulations through enforceable role contracts and persistent task DAGs. It exposes 8 tools, such as simarch_toggle_localhost, simarch_form_organization, simarch_create_task.
Summary generated from the project's README
About SimArch MCP server
Orchestrating autonomous AI organizations and running time-compressed simulations is what SimArch enables for developers and researchers. It transforms AI agents from simple conversational partners into contract-bound digital workers that operate within formal role contracts, strict authority scopes, and budget caps. The platform uses a persistent 10-state task lifecycle managed via a SQLite WAL store to ensure work continues even after a process crash.
Users interact with the system through a native Model Context Protocol (MCP) server using standard input/output, making it compatible with tools like Claude Code, Cursor, and Windsurf. Unlike traditional frameworks that require always-on background servers, this system remains locked by default and only opens network ports on-demand via the simarch_toggle_localhost tool. This approach allows for high-fidelity discrete-event world simulations and decision intelligence scoring without unnecessary resource bloat or security exposure.
What you can do with it
- 1Deploy an autonomous workforceA developer can dynamically synthesize a structured AI organization with specific roles, budgets, and authority scopes to achieve a mission.
- 2Execute complex task dependenciesYou can manage intricate workflows by adding accountable tasks into a project DAG with specific acceptance criteria and dependencies.
- 3Simulate long-term business outcomesUsers can run discrete-event models that advance months or years in milliseconds to project organizational consequences.
- 4Audit AI agent deliverablesThe system ensures accountability by requiring an independent review verdict from an auditor role before unblocking dependent tasks.
Written from the project's README. Every use case is checked against a quote from it.
SimArch MCP tools 8
Detected from the READMEsimarch_toggle_localhostsimarch_form_organizationsimarch_create_tasksimarch_submit_deliverablesimarch_evaluate_decisionsimarch_run_simulationsimarch_get_project_statussimarch_query_memory
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableisiraglobal/simarch is public and reachablegithub.com/isiraglobal/simarch ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-27github.com/isiraglobal/simarch ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSimArch — Simulation Architecture
Autonomous AI Organizations · Persistent Digital Workforce · Decision Intelligence · Time-Compressed World Simulation · Hardwired AI Tool Extension
Table of Contents
- 1. What is SimArch?
- 2. How SimArch Differs from Conventional Agent Frameworks
- 3. Complete Architecture Overview
- 4. Hardwired AI Extension & Localhost Locking
- 5. Core Architectural Pillars
- 5.1 Workforce Formation & Enforceable Role Contracts
- 5.2 10-State Task Lifecycle & Persistent DAG Execution
- 5.3 Independent Deliverable Review & Audit Protocol
- 5.4 Decision Intelligence & Binary Counterfactual Trees
- 5.5 Time-Compressed Discrete-Event World Simulation
- 5.6 Scoped Memory Isolation & Contradiction Guard
- 5.7 Controlled Self-Improvement Loop
- 6. Installation & Quickstart
- 7. Python Agentic SDK Usage
- 8. Real Execution Output (Smoke Test)
- 9. Command-Line Interface (CLI) Reference
- 10. Repository Directory Layout
- 11. Configuration & Model Providers
- 12. Security Architecture & Invariants
- 13. Current Capabilities & Roadmap
- 14. Contributing
- 15. License
- 16. Citation
1. What is SimArch?
Build an organization. Give it a mission. Watch it work.
SimArch (Simulation Architecture) is an open-source platform for orchestrating autonomous AI organizations, operating persistent digital workforces, evaluating decision intelligence graphs, and executing time-compressed discrete-event world simulations.
SimArch is also designed to be hardwired directly as an extension into modern AI tools and agents (Claude Code, Cursor, Windsurf, Antigravity, and autonomous Python swarms).
Why SimArch?
Most multi-agent frameworks treat AI agents as conversational chat partners passing prompts back and forth. When applied to real-world software, research, or enterprise automation, chat-based frameworks suffer from:
- No real accountability: Declaring "I have completed the task" in natural language without verifiable artifacts or code checks.
- Unconstrained execution: Agents operating with unbounded tool privileges, circular dependencies, and infinite loops.
- Lost state upon crash: Ephemeral memory lost whenever a process restarts or an exception occurs.
- No strategic foresight: Inability to simulate organizational consequences (burn, churn, customer acquisition, runway) across months or years before executing.
- Always-on localhost bloat: Spawning persistent background HTTP servers that occupy ports and consume resources when an agent only needs tool calling.
SimArch solves this by treating AI agents as contract-bound corporate employees:
- Workers belong to formal Role Contracts with strict authority scopes, tool permissions, and budget caps.
- Work moves through a 10-state persistent task DAG in SQLite with WAL mode, distributed leases, and crash recovery.
- Every completed task requires an independent review verdict from an auditor role before unblocking dependent tasks.
- Strategic decisions are scored using multi-criteria utility graphs and binary counterfactual flip conditions.
- World simulations run discrete-event models advancing months in milliseconds with causal feedback loops.
- The entire platform functions as an in-process extension or standard stdio MCP server, with zero open network ports by default.
2. How SimArch Differs from Conventional Agent Frameworks
| Capability | Conventional Multi-Agent Frameworks | SimArch Autonomous Organizations |
|---|---|---|
| Accountability | Chat messages stating "done" | Verifiable deliverables, code artifacts, and independent auditor review verdicts |
| Governance | Freeform prompt instructions | Enforceable role contracts, tool whitelists, and runtime privilege escalation guards |
| Persistence | Ephemeral memory sessions | SQLite WAL store with thread-safe worker leases and automated crash recovery |
| Coordination | Ad-hoc message flooding | Directed task DAGs, topological unblocking, and cycle prevention |
| Strategic Decisions | Single-prompt heuristic opinions | Directed decision graphs, multi-criteria utility scoring, and counterfactual flip trees |
| World Simulation | Wall-clock sleep delays | Discrete-event simulation advancing years in milliseconds with causal feedback loops |
| Network Footprint | Always-on background web server | Locked & dormant by default; AI agent decides on-demand when to spin it up |
| AI Tool Integration | Bespoke wrappers or REST calls | Hardwired via Model Context Protocol (MCP stdio) for Claude Code, Cursor, etc. |
| Inference Cost | Requires expensive external API keys | Zero-cost deterministic local provider for 100% offline development and testing |
3. Complete Architecture Overview
SimArch is built as a clean, modular monolith with explicit contracts between subsystems:
graph TD
User([Human Operator / AI Tool / Agent]) --> Extension[SimArch AI Extension & MCP Stdio Server]
subgraph Organization & Governance
Extension --> Formation[Workforce Formation Planner]
Formation --> Org[Organization & Role Contracts]
Org --> PermEnforcer[Runtime Permission Enforcer]
end
subgraph Execution & Persistence
Extension --> Engine[Task DAG & Workflow Engine]
Engine --> Scheduler[Persistent Scheduler & Worker Leases]
Scheduler --> Workers[Accountable Digital Workers]
Workers --> Review[Independent Review & Audit Engine]
Review --> Storage[(SQLite WAL Store & Audit Log)]
PermEnforcer -. "Guards" .-> Workers
end
subgraph Intelligence & Simulation
Extension --> Decision[Decision Intelligence Engine]
Decision --> Counterfactual[Counterfactual Delta Analysis & Flip Trees]
Extension --> Simulation[Discrete-Event World Simulation]
Simulation --> MonteCarlo[Monte Carlo Scenario Projections]
end
subgraph Memory & Context Isolation
Workers --> ScopedMemory[Scoped Memory Engine: Org/Dept/Project/Employee/Task]
ScopedMemory --> Retrieval[Token-Budget Assembly & Contradiction Guard]
end
subgraph OnDemand Interface
Extension --> LockController[Localhost Lock Controller]
LockController -. "Unlocked by AI Agent on demand" .-> Dashboard[Operational Web Dashboard: 127.0.0.1:8400]
end
4. Hardwired AI Extension & Localhost Locking
SimArch is hardwired to act as a native toolset for modern AI coding assistants and autonomous swarms.
4.1 Localhost Locking Policy (The AI Agent Decides)
In automated multi-agent environments, running an always-on background web server listening on localhost (127.0.0.1:8400) creates unnecessary socket overhead, port collisions, and security exposure:
- Zero Open Ports by Default: SimArch opens zero network sockets on startup. All operations (organization formation, task DAG execution, deliverable audits, decision scoring, and world simulations) run in-process or over standard I/O (stdio).
- On-Demand Activation: If and only if the AI agent determines that a human operator would benefit from visual inspection (e.g. reviewing an interactive organization chart or decision tree), the agent calls:
{ "name": "simarch_toggle_localhost", "arguments": { "enable": true, "port": 8400 } } - Controlled Re-Locking: Once visual review is complete or the workflow finishes, the agent invokes
simarch_toggle_localhost(enable=false)to terminate the server, release the socket, and lock localhost down again.
4.2 Native Model Context Protocol (MCP) Server
SimArch implements the standard Model Context Protocol (MCP) using standard input/output (stdio). This means AI tools run SimArch as a subprocess without network traffic or API keys.
You can inspect ready-to-copy JSON configuration snippets for your active IDE at any time:
simarch extension-config
4.3 Tool Configuration for Claude Code, Cursor, Windsurf, & Agents
A. Claude Code & Claude Desktop
Add to your claude_desktop_config.json (or pass to Claude Code via mcp.json):
{
"mcpServers": {
"simarch": {
"command": "simarch-mcp",
"args": []
}
}
}
B. Cursor & Windsurf
Create or update .cursor/mcp.json or .mcp.json in your project root (pre-configured in this repository):
{
"mcpServers": {
"simarch": {
"command": "simarch",
"args": ["mcp"]
}
}
}
C. Python Multi-Agent Frameworks (LangChain, CrewAI, AutoGen)
Export tool schemas directly to OpenAI or Anthropic format:
from simarch.extension import SimArchAIExtension
ext = SimArchAIExtension()
# OpenAI function calling format
openai_tools = ext.get_tool_definitions(format="openai")
# Anthropic tool format
anthropic_tools = ext.get_tool_definitions(format="anthropic")
4.4 Complete MCP Tools Reference
The following tools are exposed over MCP stdio and Python:
| Tool Name | Parameters | Description |
|---|---|---|
simarch_toggle_localhost |
enable: bool, port: int |
Controls Localhost: Starts or terminates 127.0.0.1:8400 on-demand when visual inspection is needed. |
simarch_form_organization |
name: str, objective: str, scale: str |
Dynamically synthesizes an autonomous AI organization with roles, contracts, authority scopes, and budgets. |
simarch_create_task |
project_id: str, org_id: str, assigned_role_id: str, objective: str, criteria: list, depends_on: list |
Adds an accountable task into the project DAG with acceptance criteria and dependencies. |
simarch_submit_deliverable |
task_id: str, summary: str, evidence: list, artifacts: list |
Submits concrete evidence and advances task to independent auditor review. |
simarch_evaluate_decision |
project_id: str, org_id: str, owner_role_id: str, objective: str, criteria: list, alternatives: list |
Computes weighted multi-criteria utility, select winner, outputs rationale, and generates binary flip trees. |
simarch_run_simulation |
project_id: str, duration_days: int, marketing_spend: float, hiring_rate: float |
Runs discrete-event world simulation with causal feedback loops (cash, burn, churn, CAC, runway). |
simarch_get_project_status |
project_id: str |
Returns current task DAG topology, unblocking progress, worker leases, and deliverable review states. |
simarch_query_memory |
scope: str, scope_id: str, query: str, limit: int |
Retrieves context within isolated scopes (Organization, Department, Project, Employee, Task) with contradiction guards. |
5. Core Architectural Pillars
5.1 Workforce Formation & Enforceable Role Contracts
SimArch rejects amorphous agent swarms. The WorkforceFormationPlanner analyzes a high-level corporate objective and constructs a formal team structure:
- Role Contracts: Every employee has a defined title, authority scopes (e.g.
['technical_implementation'],['deliverable_review']), and hourly billing budget. - Runtime Privilege Escalation Guard: The
PermissionEnforcervalidates every action against the assigned role's contract. If a worker attempts to audit their own task or call an unwhitelisted tool, SimArch rejects the action with an immutable audit violation.
5.2 10-State Task Lifecycle & Persistent DAG Execution
Tasks are nodes in a directed acyclic graph (DAG) tracked in SQLite with WAL mode. Every task progresses through 10 distinct states:
[DRAFT] ──> [READY] ──> [ASSIGNED] ──> [RUNNING] ──> [REVIEW] ──> [APPROVED] ──> [COMPLETED]
▲ │
│ ▼
└─────────────────────────────── [REVISION_REQUESTED]
[BLOCKED] ──> (Topologically unblocked when parent tasks complete) ──> [READY]
[CANCELLED] (Terminal administrative override)
- Topological Unblocking: Tasks with unresolved dependencies remain
BLOCKED. As parent tasks achieveCOMPLETED, dependent tasks automatically promote toREADY. - Worker Leases & Crash Recovery: Workers acquire a 30-second heartbeat lease on a task. If an agent crashes or disconnects, the persistent scheduler detects the expired lease, resets the task to
READY, and reassigns it without data loss.
5.3 Independent Deliverable Review & Audit Protocol
A core law of SimArch: A worker cannot approve their own work.
- When a specialist submits a deliverable, the task enters
REVIEW. - SimArch assigns an independent Auditor Role (
Quality & Verification Auditor). - The auditor inspects concrete evidence against acceptance criteria. If criteria are unmet, the auditor issues a
REVISION_REQUESTEDverdict with actionable feedback, returning the task to the DAG.
5.4 Decision Intelligence & Binary Counterfactual Trees
Strategic choices are not left to conversational guesswork:
- Multi-Criteria Utility Scoring: Alternatives are scored across weighted criteria (e.g., Security, Simplicity, Cost, Performance).
- Grounded Winning Rationale: The winning alternative is justified by an explicit mathematical breakdown.
- Binary Alternative Trees & Flip Conditions: SimArch calculates the exact sensitivity threshold required for the runner-up to beat the winner:
"If Distributed Cluster cost dropped by $15,000.00 or risk decreased from high to low, the decision would flip."
- Counterfactual Delta Analysis: Computes cost and risk deltas between chosen options and rejected alternatives.
5.5 Time-Compressed Discrete-Event World Simulation
SimArch decouples simulation time from human wall-clock time. Simulating 365 days of company operations executes in under 20 milliseconds:
- Causal Feedback Equations: $$\text{Monthly Burn} = (\text{Team Size} \times \text{Salary}) + \text{Marketing Spend}$$ $$\Delta \text{Customers} = \left(\frac{\text{Marketing Budget}}{\text{CAC}}\right) \times \left(1 + \frac{\text{Product Readiness}}{100}\right) - \text{Churn}$$
- Runway & Insolvency Tracking: Automatically computes when cash reaches zero under current burn rates.
- Monte Carlo Analysis: Runs hundreds of iterations across parameter distributions to output $P_{10}$, $P_{50}$, and $P_{90}$ projections.
5.6 Scoped Memory Isolation & Contradiction Guard
Memories are partitioned across five strict tiers:
ORGANIZATION: Company bylaws, regulatory guidelines, and global architecture.DEPARTMENT: Functional procedures (engineering, finance, legal).PROJECT: Specific milestones, acceptance criteria, and deliverable history.EMPLOYEE: Private working scratchpads (isolated from peer specialists).TASK: Ephemeral execution context.
Contradiction Guard: When an agent attempts to record a memory that asserts the opposite of an existing recorded invariant, SimArch flags the contradiction and downweights the assertion during context assembly.
5.7 Controlled Self-Improvement Loop
SimArch learns from execution performance through an 8-stage adaptation lifecycle:
$$\text{OBSERVE} \longrightarrow \text{PROPOSE} \longrightarrow \text{EVALUATE} \longrightarrow \text{APPROVE} \longrightarrow \text{VERSION} \longrightarrow \text{DEPLOY} \longrightarrow \text{MONITOR} \longrightarrow \text{ROLLBACK}$$
Security Invariant: The adaptation engine strictly forbids modifying security rules, authorization checks, budget caps, or core runtime code. Any proposal attempting privilege modification is automatically rejected.
6. Installation & Quickstart
6.1 Installation
Prerequisites
- Python 3.10, 3.11, 3.12, or 3.13
- SQLite 3.35+ (standard library)
Clone & Install
git clone https://github.com/isiraglobal/SimArch.git
cd SimArch
pip install -e .
6.2 Zero-Cost Smoke Test (100% Offline)
SimArch comes with an offline deterministic local provider that requires zero external API keys or network calls. Run the comprehensive smoke test:
simarch smoke-test
Or execute the standalone Python demonstration:
python3 examples/first_organization.py
6.3 On-Demand Operational Web Dashboard
While localhost is locked by default during automated agent workflows, you can start the operational web dashboard on-demand:
simarch serve --port 8400
Open http://127.0.0.1:8400 to inspect:
- Organization Hierarchy: Dynamic role contracts, authority scopes, and budget limits.
- Project DAG: Interactive graph showing
READY,BLOCKED,RUNNING, andCOMPLETEDtasks. - Deliverables & Reviews: Auditor feedback, verification evidence, and audit trails.
- Decision Intelligence: Utility score rankings and binary comparison trees.
- Simulation: 12-month discrete-event cash curves, customer acquisition, and Monte Carlo runs.
- Audit Log: Immutable append-only record of all runtime events.
7. Python Agentic SDK Usage
Any Python AI agent, swarm, or script can import and use the extension directly without any network overhead:
from simarch.extension import SimArchAIExtension
# 1. Initialize Extension (Zero open ports, SQLite WAL persistence)
ext = SimArchAIExtension()
# 2. Form Autonomous Organization from Objective
org = ext.form_organization(
name="Vanguard Intelligence",
objective="Autonomous security audit and compliance reporting",
scale="compact"
)
print("Formed Organization:", org["name"], "Roles:", len(org["roles"]))
# 3. Create Strategic Task in DAG
task = ext.create_task(
project_id="proj_alpha",
org_id=org["org_id"],
assigned_role_id=org["roles"][1]["id"],
objective="Audit authentication gateway for privilege escalation",
acceptance_criteria=["Zero unauthorized role elevations", "Pass regression suite"]
)
print("Created Task:", task["task_id"], "State:", task["state"])
# 4. Submit Deliverable & Trigger Independent Auditor Review
review = ext.submit_deliverable(
task_id=task["task_id"],
summary="Authentication gateway audited. 0 elevations found.",
evidence=["Regression test suite passed (100%)", "Audit log verified"],
artifacts=["reports/auth_audit.json"]
)
print("Deliverable Review:", review["review_status"], "-", review["feedback"])
# 5. Multi-Criteria Decision Intelligence
decision = ext.evaluate_decision(
project_id="proj_alpha",
org_id=org["org_id"],
owner_role_id=org["roles"][0]["id"],
objective="Select encryption protocol",
criteria=[
{"name": "Security", "weight": 0.6, "description": "Cryptographic strength"},
{"name": "Performance", "weight": 0.4, "description": "Throughput"}
],
alternatives=[
{"name": "ChaCha20-Poly1305", "description": "Fast AEAD", "scores": {"Security": 9.5, "Performance": 9.0}},
{"name": "AES-256-GCM", "description": "Hardware accelerated", "scores": {"Security": 9.5, "Performance": 8.5}}
]
)
print("Winning Choice:", decision["chosen_option"])
print("Rationale:", decision["rationale"])
# 6. Run Time-Compressed World Simulation (365 days)
sim = ext.run_simulation(
project_id="proj_alpha",
duration_days=365,
marketing_spend=12000.0,
hiring_rate=2.0
)
print("Simulation complete. Final cash:", sim["final_cash"], "Customers:", sim["customer_count"])
# 7. Localhost is locked by default:
status = ext.get_localhost_status()
print("Localhost status:", status) # {'active': False, 'locked': True}
# If the agent decides human visual review is helpful:
ext.toggle_localhost(enable=True, port=8400)
# ... human reviews at http://127.0.0.1:8400 ...
# Agent locks it back down:
ext.toggle_localhost(enable=False)
SimArch MCP questions
What tools does SimArch MCP provide?
It exposes 8 tools, including simarch_toggle_localhost, simarch_form_organization, simarch_create_task, simarch_submit_deliverable, simarch_evaluate_decision.
How does SimArch handle security and network exposure?
SimArch opens zero network sockets on startup and runs operations in-process or via stdio. It uses a localhost locking policy where the AI agent must explicitly decide to enable the web dashboard on-demand.
Can I use SimArch with existing AI coding assistants?
Yes, it is designed as a native extension for tools like Claude Code, Cursor, and Windsurf via the Model Context Protocol (MCP).