模型上下文协议服务器

┌─────────────────────────────────────┐
│          AI Coding Assistant        │
│  (Cursor / Claude Desktop / Windsurf│)
└────────────────┬────────────────────┘
                 │  MCP (stdio / SSE)
                 ▼
┌─────────────────────────────────────┐
│               pulsar                │
│  ┌──────────┐  ┌──────────────────┐ │
│  │Tool Layer│  │  Schema / Types  │ │
│  └────┬─────┘  └──────────────────┘ │
│       │                             │
│  ┌────▼──────────────────────────┐  │
│  │         Service Layer         │  │
│  │  Horizon Client  │  RPC Client│  │
│  │  Soroban CLI     │  XDR Codec │  │
│  └────┬─────────────────────┬────┘  │
└───────┼─────────────────────┼───────┘
        │                     │
        ▼                     ▼
┌──────────────┐    ┌──────────────────┐
│ Stellar      │    │  Soroban RPC     │
│ Horizon API  │    │  (Mainnet /      │
│ (REST)       │    │   Testnet / etc) │
└──────────────┘    └──────────────────┘

brew install stellar-cli

cargo install --locked stellar-cli --features opt

stellar --version
# stellar 21.x.x

# 1. Clone the repository
git clone https://github.com/your-org/pulsar.git
cd pulsar

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. (Optional) Link globally so any MCP host can find it
npm link

pulsar --version

npx pulsar

# Pull the image from GitHub Container Registry
docker pull ghcr.io/benelabs/pulsar:latest

# Run with environment variables
docker run --rm -e STELLAR_NETWORK=testnet ghcr.io/benelabs/pulsar:latest

# Run with a custom .env file
docker run --rm --env-file .env ghcr.io/benelabs/pulsar:latest

# Build the Docker image
docker build -t pulsar .

# Run the container
docker run --rm -e STELLAR_NETWORK=testnet pulsar

# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration

# Run with docker-compose
docker-compose up

# ─── Network ────────────────────────────────────────────────────────────────
# Options: mainnet | testnet | futurenet | custom
STELLAR_NETWORK=testnet

# Override the Horizon REST endpoint (optional)
HORIZON_URL=https://horizon-testnet.stellar.org

# Override the Soroban RPC endpoint (optional)
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org

# Comma-separated list of Soroban RPC endpoints for latency-based routing.
# If provided, pulsar will automatically route requests to the fastest healthy endpoint.
# Example: SOROBAN_RPC_URLS=https://rpc1.example.com,https://rpc2.example.com
SOROBAN_RPC_URLS=

# ─── Signing (optional — required only for submit_transaction) ───────────────
# WARNING: Never commit a funded secret key to version control.
# Use a dedicated low-value keypair for development.
STELLAR_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# ─── Soroban CLI ────────────────────────────────────────────────────────────
# Path to the stellar/soroban CLI binary (auto-detected if on PATH)
STELLAR_CLI_PATH=stellar

# ─── Server ─────────────────────────────────────────────────────────────────
# Log level: error | warn | info | debug | trace
LOG_LEVEL=info

# Tool execution audit log path (defaults to audit.log)
AUDIT_LOG_PATH=audit.log
# ─── Metrics (optional) ──────────────────────────────────────────────────────
# Enable Prometheus metrics export (default: true)
METRICS_ENABLED=true

# Port for metrics HTTP endpoint (default: 9090)
METRICS_PORT=9090
# ─── RPC Routing ─────────────────────────────────────────────────────────────
# Health check interval in milliseconds (default: 30000)
# RPC_HEALTH_CHECK_INTERVAL_MS=30000

# Maximum acceptable latency for an RPC endpoint in milliseconds before marking it unhealthy (default: 2000)
# RPC_LATENCY_THRESHOLD_MS=2000

http://localhost:9090/metrics

GET http://localhost:9090/health

{
  "status": "ok",
  "uptime": 123.456
}

scrape_configs:
  - job_name: 'pulsar'
    static_configs:
      - targets: ['localhost:9090']
    scrape_interval: 15s
    scrape_timeout: 10s

METRICS_ENABLED=false

{
  "mcpServers": {
    "pulsar": {
      "command": "npx",
      "args": ["-y", "pulsar"],
      "env": {
        "STELLAR_NETWORK": "testnet",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

{
  "mcpServers": {
    "pulsar": {
      "command": "node",
      "args": ["/absolute/path/to/pulsar/dist/index.js"],
      "env": {
        "STELLAR_NETWORK": "testnet"
      }
    }
  }
}

{
  "mcpServers": {
    "pulsar": {
      "command": "npx",
      "args": ["-y", "pulsar"],
      "env": {
        "STELLAR_NETWORK": "testnet"
      }
    }
  }
}

{
  "pulsar": {
    "command": "npx",
    "args": ["-y", "pulsar"],
    "env": {
      "STELLAR_NETWORK": "testnet"
    }
  }
}

# Spawn the server manually to test it
node dist/index.js

# Send a raw list-tools request (for debugging)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

{
  "account_id": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
  "sequence": "12345678901",
  "subentry_count": 3,
  "balances": [
    {
      "asset_type": "native",
      "asset_code": "XLM",
      "balance": "9842.1234567",
      "buying_liabilities": "0.0000000",
      "selling_liabilities": "0.0000000",
    },
    {
      "asset_type": "credit_alphanum4",
      "asset_code": "USDC",
      "asset_issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "balance": "250.0000000",
      "limit": "922337203685.4775807",
      "is_authorized": true,
    },
  ],
  "network": "testnet",
}

{
  "network": "testnet",
  "requested": 3,
  "succeeded": 2,
  "failed": 1,
  "max_concurrency": 3,
  "duration_ms": 184,
  "results": [
    {
      "status": "success",
      "account_id": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
      "balances": [
        {
          "asset_type": "native",
          "balance": "9842.1234567",
        },
      ],
    },
    {
      "status": "error",
      "account_id": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHG",
      "error_code": "NETWORK_ERROR",
      "message": "Account not found - it may not be funded yet",
      "details": {
        "status": 404,
        "account_id": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHG",
      },
    },
  ],
}

{
  "min_accepted_fee": "100",
  "max_accepted_fee": "10000",
  "avg_accepted_fee": "5000",
  "p_10": "1000",
  "p_20": "1500",
  "p_30": "2000",
  "p_40": "2500",
  "p_50": "3000",
  "p_60": "3500",
  "p_70": "4000",
  "p_80": "4500",
  "p_90": "5000",
  "p_95": "6000",
  "p_99": "8000",
  "last_ledger": "48234567",
  "last_ledger_base_fee": "100",
  "ledger_capacity_usage": 0.75,
  "recommended_fee_stroops": "3000",
  "network": "testnet"
}

{
  "liquidity_pool_id": "POOL_ABC123...",
  "fee_bp": 30,
  "type": "constant_product",
  "reserves": [
    { "asset": "XLM", "amount": "1000.1234567" },
    { "asset": "USDC:GA...", "amount": "500.0000000" }
  ],
  "total_shares": "2000.1234567",
  "network": "testnet"
}

**Example prompt:**

> _"Find all USDC assets on mainnet with a reputation score of at least 8."_

---

### `fetch_contract_spec`

Fetch the ABI interface specification of a deployed Soroban smart contract. Returns the full list of functions, their parameter types, and return types — in both raw XDR and decoded JSON form.

**Input:**

| Parameter     | Type     | Required | Description                                                            |
| ------------- | -------- | -------- | ---------------------------------------------------------------------- |
| `contract_id` | `string` | Yes      | The Soroban contract address (`C...`)                                  |
| `network`     | `string` | No       | Override the network for this call (`mainnet`, `testnet`, `futurenet`) |

**Output:**

```jsonc
{
  "contract_id": "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE",
  "network": "testnet",
  "functions": [
    {
      "name": "transfer",
      "doc": "Transfer tokens from one account to another.",
      "inputs": [
        { "name": "from", "type": "Address" },
        { "name": "to", "type": "Address" },
        { "name": "amount", "type": "i128" },
        { "name": "amount", "type": "i128" }
      ],
      "outputs": [{ "type": "bool" }],
    },
    {
      "name": "balance",
      "inputs": [{ "name": "id", "type": "Address" }],
      "outputs": [{ "type": "i128" }],
    },
  ],
  "events": [
    {
      "name": "transfer",
      "topics": [{ "type": "Symbol" }, { "type": "Address" }, { "type": "Address" }],
      "data": { "type": "i128" },
    },
  ],
  "raw_xdr": "AAAAAgAAAA...",
}

{
  "network": "testnet",
  "latest_ledger": 123456,
  "events": [
    {
      "id": "event-1",
      "type": "contract",
      "ledger": 123456,
      "ledger_closed_at": "2026-01-01T00:00:00Z",
      "paging_token": "123456-1",
      "in_successful_contract_call": true,
      "tx_hash": "abcdef123456",
      "contract_id": "CA...",
      "topic_raw": ["AAAA..."],
      "topic_native": ["bridge_event"],
      "value_raw": "AAAA...",
      "value_native": 42
    }
  ]
}

{
  "status": "success",
  "return_value": {
    "type": "i128",
    "value": "1000000000",
  },
  "cost": {
    "cpu_instructions": 512340,
    "memory_bytes": 98304,
  },
  "footprint": {
    "read_only": ["ledger_key_1_xdr", "ledger_key_2_xdr"],
    "read_write": ["ledger_key_3_xdr"],
  },
  "min_resource_fee": "12345",
  "events": [],
  "error": null,
}

{
  "contract_id": "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE",
  "storage_type": "persistent",
  "key": { "type": "symbol", "value": "Balance" },
  "network": "testnet",
  "entries": [
    {
      "key_xdr": "AAAAAgAAAA...",
      "entry_xdr": "AAAABgAAAAEA...",
      "last_modified_ledger": 48123456,
      "live_until_ledger": 48199999
    }
  ]
}

{
  "entry_type": "contract_data",
  "decoded": {
    "contract": "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE",
    "key": {
      "type": "Symbol",
      "value": "Balance",
    },
    "val": {
      "type": "Map",
      "value": [
        {
          "key": { "type": "Address", "value": "GBBD47IF..." },
          "val": { "type": "i128", "value": "5000000000" },
        },
      ],
          "val": { "type": "i128", "value": "5000000000" }
        }
      ]
    },
    "durability": "persistent",
    "last_modified_ledger": 48123456,
  },
  "raw_xdr": "AAAABgAAAAEA...",
  "compression": {
    "enabled": true,
    "requested_algorithm": "auto",
    "inspected_fields": ["val.data"],
    "decompressed_fields": [
      {
        "path": "val.data",
        "algorithm": "gzip",
        "utf8": "{\"version\":1,\"blob\":\"...\"}",
        "byte_length": 26
      }
    ],
    "skipped_fields": []
  }
}

{
  "status": "SUCCESS",
  "hash": "aabbccdd1122...",
  "ledger": 48123789,
  "created_at": "2026-03-16T14:30:00Z",
  "fee_charged": "1234",
  "return_value": {
    "type": "bool",
    "value": true,
  },
  "result_xdr": "AAAAAAAAAGQ...",
}

{
  "status": "FAILED",
  "hash": "aabbccdd1122...",
  "error_result_xdr": "AAAAAAAAAGT...",
  "diagnostic_events": [
    {
      "event": "contract error",
      "message": "HostError: Error(Contract, #1)",
    },
  ],
}

{
  "type": "payment",
  "destination": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
  "amount": 100.5,
  "asset_code": "USDC",        // Optional - omit for native XLM
  "asset_issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"  // Required if asset_code provided
}

{
  "type": "change_trust",
  "asset_code": "USDC",
  "asset_issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
  "limit": "1000000"  // Optional - defaults to maximum uint64
}

{
  "type": "manage_data",
  "name": "user_preference",
  "value": "dark_mode"  // Optional - omit to clear the entry
}

{
  "type": "set_options",
  "inflation_destination": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
  "home_domain": "example.com",
  "master_weight": 1,
  "low_threshold": 2,
  "med_threshold": 3,
  "high_threshold": 4,
  "signer_address": "GD5DJOWB5G4H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6",
  "signer_type": "ed25519_public_key",
  "signer_weight": 1
}

{
  "type": "account_merge",
  "destination": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
}

{
  "type": "create_account",
  "destination": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
  "starting_balance": 2.5
}

{
  "transaction_xdr": "AAAAAgAAAABGDW...==",
  "network": "testnet",
  "source_account": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
  "operations": [
    {
      "type": "payment",
      "description": "Payment of 100.5 XLM to GD5DJOWB5G4H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6H6"
    }
  ],
  "fee": "100000",
  "timeout": 30
}

For `basis_points_to_percent` / `percent_to_basis_points` the output contains only `operation` and `result` (a number, not a fixed-point integer).

**Example prompt:**

> _"What is the compound interest on a principal of 1,000 USDC at 5% annual rate (500 bps) over 12 monthly periods?"_
### `compute_vesting_schedule`

Calculate a token vesting / timelock release schedule for team members, investors, or advisors. Given a total allocation, start time, cliff, vesting duration, and release frequency, the tool returns the amount already released, the amount still locked, and a period-by-period schedule.

**Input:**

| Parameter                   | Type     | Required | Description                                                      |
| --------------------------- | -------- | -------- | ---------------------------------------------------------------- |
| `total_amount`              | `number` | Yes      | Total token amount to vest                                       |
| `start_timestamp`           | `number` | Yes      | Unix timestamp when vesting begins                               |
| `cliff_seconds`             | `number` | Yes      | Seconds before any tokens unlock (cliff period)                  |
| `vesting_duration_seconds`  | `number` | Yes      | Total vesting period in seconds                                  |
| `release_frequency_seconds` | `number` | Yes      | How often tokens unlock after cliff (e.g. `2592000` for monthly) |
| `beneficiary_type`          | `string` | Yes      | Category: `team`, `investor`, `advisor`, or `other`              |
| `current_timestamp`         | `number` | No       | Optional override for "now" (defaults to current time)           |

**Output:**

```jsonc
{
  "beneficiary_type": "team",
  "total_amount": "1000000.0000000",
  "start_date": "2024-11-13T12:00:00.000Z",
  "cliff_date": "2025-11-13T12:00:00.000Z",
  "end_date": "2028-11-13T12:00:00.000Z",
  "released_amount": "250000.0000000",
  "unreleased_amount": "750000.0000000",
  "vesting_percentage": 25.0,
  "next_release_date": "2025-12-13T12:00:00.000Z",
  "schedule": [
    {
      "release_date": "2025-12-13T12:00:00.000Z",
      "amount": "20833.3333333",
      "released": true,
    },
    {
      "release_date": "2026-01-13T12:00:00.000Z",
      "amount": "20833.3333333",
      "released": false,
    },
  ],
}

{
  "status": "success",
  "return_value": { "type": "void" },
  "cost": {
    "cpu_instructions": 725400,
    "memory_bytes": 112000
  },
  "min_resource_fee": "15432",
  "events": [...]
}

{
  "mode": "direct",
  "transaction_xdr": "AAAAAgAAAAE...",
  "predicted_contract_id": "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE",
  "network": "testnet",
  "source_account": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
}

{
  "mode": "factory",
  "transaction_xdr": "AAAAAgAAAAE...",
  "optimization": {
    "min_resource_fee": "2500",
    "cpu_instructions": "345",
    "memory_bytes": "678"
  },
  "network": "testnet",
  "source_account": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
}

{
  "status": "SUCCESS",
  "signed_xdr": "AAAAAgAAAAE...",
  "network": "testnet"
}

{
  "format": "json",
  "content_type": "application/json",
  "schema_count": 7,
  "include_examples": true,
  "data": {
    "version": "1.0.0",
    "server": "pulsar",
    "description": "Pulsar MCP Server — Stellar/Soroban tools for automated blockchain operations...",
    "tools": [
      {
        "name": "get_account_balance",
        "description": "Query the current XLM and issued asset balances...",
        "category": "query",
        "inputSchema": { "type": "object", "properties": { ... } },
        "outputSchema": { "type": "object", "properties": { ... } },
        "examples": {
          "input": { "account_id": "GBBD47IF..." },
          "output": { "account_id": "GBBD47IF...", "balances": [...] }
        }
      },
      ...
    ],
    "metadata": {
      "total_tools": 7,
      "categories": { "query": 1, "transaction": 2, "contract": 2, "utility": 2 },
      "security_notes": [...],
      "stellar_best_practices": [...]
    }
  }
}

{
  "is_safe": false,
  "risk_level": "HIGH",
  "findings": [
    {
      "level": "HIGH",
      "type": "ACCOUNT_MERGE",
      "message": "DANGEROUS: This operation will permanently delete account..."
    }
  ],
  "operation_count": 1,
  "total_fee": "100",
  "summary": "Transaction with 1 operation(s): accountMerge."
  "network": "testnet",
  "sample_size": 10,
  "average_consensus_seconds": 5.123,
  "min_consensus_seconds": 4.891,
  "max_consensus_seconds": 6.204,
  "std_dev_seconds": 0.412,
  "sampled_at": "2026-04-28T12:00:00.000Z",
  "ledgers": [
    {
      "sequence": 999991,
      "closed_at": "2026-04-28T11:59:55.000Z",
      "close_time_seconds": 5.0
    },
    {
      "sequence": 999992,
      "closed_at": "2026-04-28T11:59:60.000Z",
      "close_time_seconds": 5.0
    }
  ]
}

**Resource Weight Units:**

- `cpu_instructions`: Cost multiplier per CPU instruction
- `memory_bytes`: Cost multiplier per byte of memory
- `ledger_entry_read`: Cost for reading a ledger entry
- `ledger_entry_write`: Cost for writing to a ledger entry
- `ledger_entry_create`: Cost for creating a new ledger entry
- `transmit_bytes`: Cost per byte of transaction data

**Fee Thresholds:**

- `min_resource_fee`: Minimum fee required per transaction (in stroops)
- `max_cpu_instructions`: Maximum CPU instructions allowed per transaction
- `max_memory_bytes`: Maximum memory (in bytes) allowed per transaction
- Ledger entry limits: Maximum bytes for read, write, and create operations

**Example prompt:**

> _"What are the current resource weights and fee thresholds on testnet? I want to estimate the cost of my transaction."_
  "wasm_path": "/workspace/target/wasm32v1-none/release/governor.wasm",
  "size_bytes": 178432,
  "size_kb": 174.25,
  "max_size_kb": 256,
  "exceeds_limit": false,
  "diagnostics": {
    "custom_section_bytes": 8120,
    "code_section_bytes": 129744,
    "data_section_bytes": 14688,
    "section_breakdown": []
  },
  "suggested_commands": [
    "cargo build --release --target wasm32v1-none",
    "stellar contract optimize --wasm <input.wasm> --wasm-out <optimized.wasm>",
    "wasm-opt -Oz -o <optimized.wasm> <input.wasm>"
  ],
  "recommendations": [
    {
      "id": "strip-custom-sections",
      "priority": "high",
      "title": "Strip debug/custom sections",
      "rationale": "Custom/debug sections increase binary size and are not needed for on-chain execution.",
      "action": "Enable symbol stripping and optimization pass to remove custom sections from the final WASM artifact."
    }
  ]
}

**Supported Features by Protocol Version:**

| Protocol Version | Key Features Added |
|---|---|
| 11 | Soroban smart contracts, footprint expiration, fee bumps |
| 12 | Liquidity pools, claimable balances |
| 13 | Contract data TTL, contract instance storage |
| 14 | Smart contract auth, envelope types |
| 15 | Contract cost model, CPU instructions |
| 16 | Stellar Asset Contract, WASM v2 |
| 17+ | Complex contract auth, enhanced fee structures |

**Example prompts:**

> _"What protocol version is testnet currently running and what features are available?"_

> _"Check if mainnet supports Soroban smart contracts yet."_

> _"Compare protocol versions between mainnet and testnet to see what's different."_
  "status": "success",
  "action": "swap",
  "transaction_xdr": "AAAAAgAAAAE...",
  "message": "Swap transaction built. Simulate before submitting."
}

{
  "status": "success",
  "action": "add_liquidity",
  "transaction_xdr": "AAAAAgAAAAE...",
  "message": "Add liquidity transaction built. Simulate before submitting."
}

{
  "status": "success",
  "action": "remove_liquidity",
  "transaction_xdr": "AAAAAgAAAAE...",
  "message": "Remove liquidity transaction built. Simulate before submitting."
}

{
  "status": "SUCCESS",
  "signed_xdr": "AAAAAgAAAAE...",
  "network": "testnet"
  "result": "1000000000000000000",
  "operation": "add",
  "bounds": "u64",
  "formatted": "Result of 500000000000000000 add 500000000000000000 is 1000000000000000000 (within u64 bounds)"
}

**Example prompt:**

> _"Get a quote for swapping 10 XLM to USDC on AMM `CA3D...` with current reserves."_

#### Get Pool Information

Query the current state of an AMM pool, including reserves for both assets and total LP shares in circulation.

**Input (action: `get_pool_info`):**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `amm_contract_id` | `string` | Yes | AMM contract ID (`C...`) |
| `asset_a_code` | `string` | Yes | First asset code |
| `asset_a_issuer` | `string` | No | Issuer of first asset (omit for XLM) |
| `asset_b_code` | `string` | Yes | Second asset code |
| `asset_b_issuer` | `string` | No | Issuer of second asset (omit for XLM) |
| `network` | `string` | No | Override network |

**Output:**

```jsonc
{
  "contract_id": "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE",
  "base_asset": "USD",
  "quote_asset": "XLM",
  "price": "1000000",
  "network": "testnet"
  "status": "success",
  "pool": {
    "asset_a": {
      "code": "XLM",
      "issuer": "native",
      "reserve": "1000000000"
    },
    "asset_b": {
      "code": "USDC",
      "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
      "reserve": "2000000000"
    },
    "total_shares": "1414213562",
    "contract_id": "CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE"
  },
  "constant_product": "2000000000000000000"
}

output = (reserve_out * amount_in * (1 - fee)) / (reserve_in + amount_in * (1 - fee))

shares = sqrt(amount_a * amount_b)

shares = min((amount_a * total_shares) / reserve_a, (amount_b * total_shares) / reserve_b)

amount_a = (shares_burned * reserve_a) / total_shares
amount_b = (shares_burned * reserve_b) / total_shares

Me: Check the XLM and USDC balance of GBBD47... on testnet before I send anything.
AI: [calls get_account_balance] — The account holds 9,842.12 XLM and 250.00 USDC. It has 3 subentries, so the minimum balance is 2 XLM base + 0.5 per subentry = 3.5 XLM. Safe to proceed.

Me: Fetch the contract spec for CA3D... and generate a fully-typed TypeScript client for all its functions.
AI: [calls fetch_contract_spec] — Here is a TypeScript client using @stellar/stellar-sdk ...

Me: I built this transaction XDR. Simulate it and tell me if it will succeed and what the fee will be.
AI: [calls simulate_transaction] — The simulation succeeded. Return value is `true`. The min resource fee is 12,345 stroops (~0.001234 XLM). CPU: 512,340 instructions. Looks good to submit.

Me: Here's a ledger entry XDR from querying the contract storage. What's in it?
AI: [calls decode_ledger_entry] — This is a persistent ContractData entry for contract CA3D.... The key is the Symbol "Balance" and the value is a Map with one entry: address GBBD47... → i128 value 5,000,000,000 (which at 7 decimal places is 500.0000000 tokens).

Me: Submit this signed XDR to testnet and wait for confirmation.
AI: [calls submit_transaction with wait_for_result: true] — Submitted! Hash: aabbcc... Confirmed in ledger 48,123,789. Fee charged: 1,234 stroops. Return value: true.

pulsar/
├── src/
│   ├── index.ts              # MCP server entrypoint, tool registration
│   ├── tools/
│   │   ├── get_account_balance.ts
│   │   ├── fetch_contract_spec.ts
│   │   ├── simulate_transaction.ts
│   │   ├── decode_ledger_entry.ts
│   │   ├── submit_transaction.ts
│   │   ├── compute_vesting_schedule.ts
│   │   ├── deploy_contract.ts
│   │   └── track_ledger_consensus_time.ts
│   │   └── get_protocol_version.ts
│   ├── services/
│   │   ├── horizon.ts        # Horizon REST client wrapper
│   │   ├── soroban-rpc.ts    # Soroban JSON-RPC client wrapper
│   │   ├── stellar-cli.ts    # Shell-out wrapper for the Stellar CLI
│   │   └── xdr.ts            # XDR encode/decode helpers
│   ├── schemas/
│   │   └── index.ts          # Zod schemas for all tool inputs/outputs
│   └── config.ts             # Network config, env var loading
├── tests/
│   ├── unit/
│   └── integration/
├── contracts/                  # Soroban Rust workspaces
│   └── reference/            # Reference contracts and test suite
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

# Build the reference contracts (generates AI-ready WASM specs)
npm run build:contracts

# Run the comprehensive unit test suite
npm run test:contracts

import { z } from 'zod';
import { McpToolHandler } from '../types.js';

export const myNewToolSchema = z.object({
  some_param: z.string().describe('Description for the AI to understand'),
});

export const myNewTool: McpToolHandler<typeof myNewToolSchema> = async (input) => {
  const { some_param } = input;
  // ... implementation
  return { result: '...' };
};

import { myNewTool, myNewToolSchema } from './tools/my_new_tool.js';

server.tool(
  'my_new_tool',
  'One-sentence description visible to the AI assistant',
  myNewToolSchema.shape,
  myNewTool
);

# Development mode with hot-reload
npm run dev

# Build and run
npm run build && node dist/index.js

# Test the server interactively (pipe JSON-RPC requests)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js | jq .

# Run all unit tests
npm test

# Run integration tests (requires testnet access)
npm run test:integration

# Run end-to-end (E2E) tests (requires testnet access and stellar CLI)
RUN_INTEGRATION_TESTS=true npx vitest tests/e2e

# Run with coverage
npm run test:coverage

# Lint
npm run lint

# Type-check only (no emit)
npm run typecheck

# Fetch metrics in Prometheus format
curl http://localhost:9090/metrics

# Health check endpoint
curl http://localhost:9090/health

# Average tool execution time (last 5 minutes)
rate(pulsar_tool_duration_seconds_sum[5m]) / rate(pulsar_tool_duration_seconds_count[5m])

# Tool error rate
rate(pulsar_tool_errors_total[5m])

# Current heap memory usage in MB
pulsar_heap_memory_used_bytes / 1024 / 1024

# Active tool invocations
pulsar_active_tool_invocations

# Total successful invocations by tool
sum by (tool_name) (pulsar_tool_invocations_total{status="success"})

docker run -p 9090:9090 ghcr.io/benelabs/pulsar:latest

METRICS_ENABLED=false

# Fork and clone
git clone https://github.com/your-username/pulsar.git
cd pulsar

# Install deps
npm install

# Create a feature branch
git checkout -b feat/my-feature

# Make your changes, add tests
npm test && npm run lint

# Open a PR