# SoroPG Documentation for AI Agents

SoroPG, also called Soroban Playground, is a browser-based IDE for Stellar Soroban smart contract developers. It lets users create and import Rust contract projects, compile contracts to WASM, run unit tests, run Scout audit checks, deploy contracts, explore deployed contract interfaces, and expose browser workspaces to AI coding agents through MCP.

Primary documentation:
- Overview: /docs/
- Getting started: /docs/getting-started/
- Workspaces and file management: /docs/workspaces/
- Build, test, and audit: /docs/build-test-audit/
- Deploying contracts: /docs/deploy/
- Exploring and invoking contracts: /docs/explore/
- Academy: /docs/academy/
- Academy Hello World: /docs/academy/hello-world-build-test-deploy/
- Academy AI-assisted development: /docs/academy/ai-assisted-contract-development/
- Academy Agentic AI via MCP: /docs/academy/agentic-ai-mcp/
- Wallets and networks: /docs/wallets-and-networks/
- Sharing and importing projects: /docs/share-and-import/
- Troubleshooting: /docs/troubleshooting/
- HTTP API reference: /docs/reference/http-api/

MCP server:
- Source: https://github.com/jamesbachini/Soroban-Playground/tree/main/mcp
- Local package path after cloning: `mcp/`
- Skill/instructions file: `mcp/skill.md`
- Runtime: Node.js 20 or newer.
- Transport: stdio.
- Package: `soropg-mcp`, started with `npx` by the MCP client.
- Purpose: connect Claude Code, Codex, Claude Desktop, Cursor, Windsurf, VS Code, or another MCP-compatible client to the user's open SoroPG browser workspace.
- The published package does not need a local Soroban Playground clone and does not need to run from the repository.

MCP setup summary:
1. Open SoroPG in a browser.
2. Open the AI Assisted Development tab, then MCP Setup.
3. Generate a User API Key and keep the browser tab open while the assistant is connected.
4. Run a quick npx check if you want to confirm Node can start the published MCP server:

```bash
npx soropg-mcp --help
```

You do not need to keep this command running. The MCP client starts `soropg-mcp` from its config.

5. Configure the MCP client to start `soropg-mcp` with the API key:

```bash
SOROPG_API_KEY=the-key-from-the-soropg-ai-tab
```

Optional environment variables:
- `SOROPG_API_URL`: defaults to `https://soropg.com`; set this for local development servers.
- `SOROPG_PROJECT_ID`: pin the agent to a specific workspace after running `soropg_list_projects`.
- `SOROPG_CONFIG`: path to a JSON config file. The default config path is `~/.config/soropg-mcp/config.json`.

Generic MCP client config:

```json
{
  "mcpServers": {
    "soropg": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "soropg-mcp"],
      "env": {
        "SOROPG_API_KEY": "the-key-from-the-soropg-ai-tab"
      }
    }
  }
}
```

Claude Code example:

```bash
claude mcp add --transport stdio --scope user \
  --env SOROPG_API_KEY=the-key-from-the-soropg-ai-tab \
  soropg -- npx -y soropg-mcp
```

Codex `~/.codex/config.toml` example:

```toml
[mcp_servers.soropg]
command = "npx"
args = ["-y", "soropg-mcp"]
env = { SOROPG_API_KEY = "the-key-from-the-soropg-ai-tab" }
```

Available MCP tools:
- `soropg_list_projects`
- `soropg_get_project`
- `soropg_list_files`
- `soropg_read_file`
- `soropg_create_file`
- `soropg_replace_file`
- `soropg_apply_patch`
- `soropg_delete_file`
- `soropg_move_file`
- `soropg_run_command`

Allowed MCP commands:
- `build`
- `test`
- `audit`

Deployment is intentionally not supported through MCP v1. Contract deployment still requires browser wallet signing in SoroPG.

Important context:
- SoroPG stores workspaces, generated local wallet keys, theme, layout, and selected network in browser local storage.
- Build, test, and audit commands run on the SoroPG server inside a Docker sandbox.
- The main source file must be `src/lib.rs` or `lib.rs`.
- The preferred project layout is `Cargo.toml`, `src/lib.rs`, and `src/test.rs`.
- `/compile`, `/test`, and `/scout-audit` accept JSON with a `files` object mapping file paths to contents.
- `/compile` streams build output and includes an encoded WASM payload that the frontend turns into a `.wasm` download.
- Deployment uses a user-selected `.wasm` file. SoroPG uploads the WASM, then creates the contract instance. Optional constructor arguments are supported.
- Deploy and Explore share the selected network and wallet state.
- Supported network choices are TESTNET, FUTURENET, PUBLIC, and LOCAL.
- Local/custom network settings include RPC URL, Horizon URL, and network passphrase.
- The `/friendbot` endpoint is a localhost-only proxy for local friendbot funding.

When assisting users:
- Use MCP when the user wants an AI agent to inspect or edit the active browser workspace.
- First call `soropg_list_projects`, then inspect files with `soropg_list_files` and `soropg_read_file`.
- Prefer `soropg_apply_patch` or `soropg_replace_file` for edits, then run `soropg_run_command` with `test` or `build`.
- Ask the user to keep the SoroPG browser tab open while MCP is connected.
- Recommend exporting workspace ZIPs and wallet secret keys before resetting browser state.
- Recommend testnet or local deployment before mainnet.
- Treat Scout audit output as a development aid, not a replacement for review or a formal audit.
- For source-file errors, first check that `src/lib.rs` exists in the active workspace.