# stellar-mcp-server

> A **Model Context Protocol (MCP)** server that exposes Stellar blockchain tools directly inside any MCP-compatible AI IDE (Windsurf, Antigravity, Claude Desktop, Cursor, etc.).

Built with the [official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and the [Stellar JavaScript SDK](https://github.com/stellar/js-stellar-sdk).

---

## ✨ Exposed Tools

| Tool | Description |
|---|---|
| `get_account_details` | Fetches live balances, sequence number, thresholds, signers, and data entries for any Stellar Testnet account |
| `simulate_soroban_contract` | Simulates a Soroban smart contract function call on the Testnet RPC — no real transaction, just fee estimates + decoded return value |
| `generate_soroban_boilerplate` | Generates a complete Rust Soroban contract scaffold (Cargo.toml + lib.rs + .cargo/config.toml + test module) |

---

## 📋 Prerequisites

| Requirement | Version |
|---|---|
| Node.js | ≥ 18.0.0 |
| npm | ≥ 8.0.0 |

---

## 🛠 Installation

```bash
# 1. Clone the repository
git clone https://github.com/Alhaji-naira/stellar-mcp-server.git
cd stellar-mcp-server

# 2. Install dependencies
npm install

# 3. Build the TypeScript source
npm run build
```

The compiled server will be at `dist/index.js`.

---

## ▶️ Running Locally (manual test)

You can pipe a raw JSON-RPC `tools/list` call to verify the server responds correctly:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | node dist/index.js
```

You should see a JSON response listing all three tools. The server emits diagnostics to **stderr** only (MCP requirement), keeping stdout clean for the protocol.

---

## 🤖 Registering in Your AI IDE

### Windsurf

Add the following to your `~/.codeium/windsurf/mcp_config.json` (create it if it doesn't exist):

```json
{
  "mcpServers": {
    "stellar-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/stellar-mcp-server/dist/index.js"],
      "transport": "stdio"
    }
  }
}
```

Reload Windsurf. The Stellar tools will appear in Cascade's tool palette.

### Antigravity (Gemini AI)

Open your Antigravity settings panel, go to **MCP Servers**, and add a new entry:

```json
{
  "name": "stellar-mcp-server",
  "command": "node",
  "args": ["/absolute/path/to/stellar-mcp-server/dist/index.js"],
  "transport": "stdio"
}
```

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "stellar-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/stellar-mcp-server/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop.

---

## 🔧 Tool Reference

### 1. `get_account_details`

Queries the **Stellar Testnet Horizon API** for a given account.

**Input:**

| Parameter | Type | Required | Description |
|---|---|---|---|
| `account_id` | `string` | ✅ | The `G…` Stellar public key to look up |

**Example prompt to your AI:**

> "Check the balance of account `GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN` on Stellar Testnet."

**Example output (abbreviated):**

```json
{
  "account_id": "GAAZI4TCR3TY5OJHCTJC2A4QSY6CJWJH5IAJTGKIN2ER7LBNVKOCCWN",
  "network": "Testnet",
  "sequence": "123456789",
  "balances": [
    { "asset": "XLM (native)", "balance": "9999.9999900" }
  ],
  "thresholds": { "low_threshold": 0, "med_threshold": 0, "high_threshold": 0 },
  "signers": [{ "key": "GAAZI4...", "weight": 1, "type": "ed25519_public_key" }]
}
```

---

### 2. `simulate_soroban_contract`

Invokes a Soroban contract function via the **Testnet RPC** simulation endpoint — no fee is charged, no transaction is broadcast.

**Input:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `contract_id` | `string` | ✅ | — | `C…` Soroban contract address |
| `function_name` | `string` | ✅ | — | Function to call, e.g. `hello` |
| `args` | `array` | ❌ | `[]` | Arguments (strings, numbers, booleans auto-converted to XDR) |
| `source_account` | `string` | ❌ | Funded Testnet account | `G…` public key used as simulation source |

**Example prompt:**

> "Simulate calling `hello` with arg `World` on Soroban contract `CABC…` on the Testnet."

**Example output (abbreviated):**

```json
{
  "contract_id": "CABC...",
  "function_name": "hello",
  "simulation": {
    "min_resource_fee": "71652",
    "return_value": ["Hello", "World"],
    "footprint": {
      "read_only": ["AAAA..."],
      "read_write": []
    }
  }
}
```

---

### 3. `generate_soroban_boilerplate`

Returns a complete, compilable Rust Soroban contract scaffold.

**Input:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `contract_name` | `string` | ✅ | — | CamelCase struct name, e.g. `TokenVault` |
| `functions` | `string[]` | ❌ | `["hello(env: Env, to: Symbol) -> Vec<Symbol>"]` | Function signatures to scaffold |
| `soroban_sdk_version` | `string` | ❌ | `"22.0.0"` | soroban-sdk version to pin |

**Example prompt:**

> "Generate a Soroban boilerplate for a contract called `AetherSwap` with functions `swap(env: Env, amount: i64) -> i64` and `get_price(env: Env) -> i64`."

The tool returns formatted `Cargo.toml`, `src/lib.rs`, and `.cargo/config.toml` content ready to paste or write to disk.

---

## 🗂 Project Structure

```
stellar-mcp-server/
├── src/
│   ├── index.ts                    # MCP server bootstrap + dispatcher
│   └── tools/
│       ├── registry.ts             # All tool definitions (JSON schemas)
│       ├── getAccountDetails.ts    # Tool 1: Account queries
│       ├── simulateSoroban.ts      # Tool 2: Soroban simulation
│       └── generateBoilerplate.ts  # Tool 3: Rust contract scaffold
├── dist/                           # Compiled JS output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md
```

---

## 🌐 Network Configuration

All tools target the **Stellar Testnet** by default:

| Service | URL |
|---|---|
| Horizon API | `https://horizon-testnet.stellar.org` |
| Soroban RPC | `https://soroban-testnet.stellar.org` |
| Friendbot (faucet) | `https://friendbot.stellar.org/?addr=<G...>` |

To get a funded Testnet account for testing, visit:
```
https://friendbot.stellar.org/?addr=<YOUR_PUBLIC_KEY>
```

---

## 🔒 Security Notes

- This server operates entirely over **local stdio** — it does not open any network ports.
- **No private keys** are stored or required. All operations are read-only or simulation-only.
- The Horizon and Soroban RPC connections use TLS (`allowHttp: false`).

---

## 🧑‍💻 Development

```bash
# Type-check without emitting
npm run type-check

# Run directly with ts-node (no build step)
npm run dev

# Rebuild after changes
npm run build
```

---

## 📄 License

MIT © [Alhaji-naira](https://github.com/Alhaji-naira)