From ba1f3f2c9688a02793967571da82009866fd9526 Mon Sep 17 00:00:00 2001 From: Andrew Kim Joseph Date: Tue, 25 Aug 2026 22:24:45 +0300 Subject: [PATCH 1/6] docs(build-with-ai): add Celina SDK, MCP, hosted MCP, and API pages Adds a Celina section under build-on-celo/build-with-ai/celina/ with an index page and one Guide page each for the SDK, local stdio MCP server, hosted MCP endpoint, and REST API. Wires the new pages into docs.json navigation, cross-links from mcp/index.mdx and overview.mdx. Co-authored-by: Cursor --- build-on-celo/build-with-ai/celina/api.mdx | 66 +++++++++ .../build-with-ai/celina/hosted-mcp.mdx | 81 +++++++++++ build-on-celo/build-with-ai/celina/index.mdx | 22 +++ build-on-celo/build-with-ai/celina/mcp.mdx | 131 ++++++++++++++++++ build-on-celo/build-with-ai/celina/sdk.mdx | 74 ++++++++++ build-on-celo/build-with-ai/mcp/index.mdx | 2 + build-on-celo/build-with-ai/overview.mdx | 4 + docs.json | 11 ++ 8 files changed, 391 insertions(+) create mode 100644 build-on-celo/build-with-ai/celina/api.mdx create mode 100644 build-on-celo/build-with-ai/celina/hosted-mcp.mdx create mode 100644 build-on-celo/build-with-ai/celina/index.mdx create mode 100644 build-on-celo/build-with-ai/celina/mcp.mdx create mode 100644 build-on-celo/build-with-ai/celina/sdk.mdx diff --git a/build-on-celo/build-with-ai/celina/api.mdx b/build-on-celo/build-with-ai/celina/api.mdx new file mode 100644 index 000000000..4798a472b --- /dev/null +++ b/build-on-celo/build-with-ai/celina/api.mdx @@ -0,0 +1,66 @@ +--- +title: "Celina API" +sidebarTitle: "API" +description: "Call Celo mainnet reads, quotes, and governance/staking data over plain HTTP with no API key" +--- + +**Celina API** is a public, read-only REST API for clients and agents that don't speak MCP — it exposes the same tool catalog as the Celina [MCP server](/build-on-celo/build-with-ai/celina/mcp) over plain HTTP. + +## Prerequisites + +None. Every route is public, keyless, and open CORS — no API key, Bearer token, or OAuth flow. + +## How it works + +Each tool in the catalog is a route: `GET /v1/:name` returns its metadata, `POST /v1/:name` invokes it with a JSON body of snake_case arguments. The base URL is: + +```text +https://api.usecelina.xyz +``` + +## List available tools + +```bash +curl -sS https://api.usecelina.xyz/v1/tools +``` + +Returns `{ count, tools: [{ name, title, description, inputs }] }` — the authoritative, live list of every tool the API exposes. + +## Call a tool + +```bash +# Network status +curl -sS https://api.usecelina.xyz/v1/get_network_status \ + -H 'Content-Type: application/json' \ + -d '{}' + +# Stablecoin balances for an address +curl -sS https://api.usecelina.xyz/v1/get_stablecoin_balances \ + -H 'Content-Type: application/json' \ + -d '{"address":"0xYourAddress"}' +``` + +The API exposes around 48 read and quote tools — the `read` family of the shared catalog (no `prepare_*`, `estimate_*`, or `execute_*` tools): chain reads, balances, Mento FX / Uniswap v4 / Aave / GoodDollar quotes, governance and staking reads, humanness check, Self Agent ID lookups, and AgentKarma reputation. + +## Troubleshooting + +| Response | Cause | Body shape | +|---|---|---| +| `404` | Tool name in the path doesn't exist in the catalog | `{"error":"Unknown tool: ${name}"}` | +| `400` | Request body isn't valid JSON | `{"error":"Invalid JSON body"}` | +| `400` | Request body parsed but isn't a JSON object | `{"error":"JSON body must be an object"}` | +| `400` | Body failed the tool's input schema | `{"error":"${path}: ${issue.message}; ..."}` | +| `400` | A tool needs a wallet address and none was passed | `{"error":"Pass an explicit address, wallet_address, or from. This API has no server wallet."}` | +| `502` | The tool ran but the underlying call failed (RPC error, no route, etc.) | `{"error":"${message}"}` | + +## Resources + +| Resource | Link | +|---|---| +| GitHub repository | [andrewkimjoseph/celina-api](https://github.com/andrewkimjoseph/celina-api) | +| GitBook documentation | [andrewkimjoseph.gitbook.io/celina-api](https://andrewkimjoseph.gitbook.io/celina-api) | + +## Related + +- [Celina SDK](/build-on-celo/build-with-ai/celina/sdk) — the library this API wraps +- [Celina Hosted MCP](/build-on-celo/build-with-ai/celina/hosted-mcp) — the same catalog over MCP instead of REST diff --git a/build-on-celo/build-with-ai/celina/hosted-mcp.mdx b/build-on-celo/build-with-ai/celina/hosted-mcp.mdx new file mode 100644 index 000000000..a506b9146 --- /dev/null +++ b/build-on-celo/build-with-ai/celina/hosted-mcp.mdx @@ -0,0 +1,81 @@ +--- +title: "Celina Hosted MCP" +sidebarTitle: "Hosted MCP" +description: "Connect to a public, keyless Streamable HTTP MCP endpoint for Celo mainnet reads, quotes, and governance/staking data" +--- + +**Celina Hosted MCP** is a public Streamable HTTP deployment of the Celina [MCP server](/build-on-celo/build-with-ai/celina/mcp), for anyone who wants read and quote access to Celo mainnet with no installation and no private key. + + + The hosted endpoint cannot sign transactions. For sends, swaps, staking, or governance writes, run the [local MCP server](/build-on-celo/build-with-ai/celina/mcp) with your own key instead. + + +## Prerequisites + +- An MCP client that supports Streamable HTTP servers (Cursor, Claude Desktop), or [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge a stdio-only client + +## How it works + +The endpoint runs the same `createServer()` factory as the local MCP server, with `serverKeyToolsEnabled: false` and `estimateToolsEnabled: false` — no wallet, no gas estimation, and Self session tools disabled because sessions can't persist on a stateless deployment. Around 48 read/quote tools remain registered. + +## Connect your MCP client + +```text +https://mcp.usecelina.xyz/api/mcp +``` + +An [A2A](https://a2aproject.github.io/A2A/) agent card is also available at `https://mcp.usecelina.xyz/api/a2a`, and a health check at `https://mcp.usecelina.xyz/api/health`. + +For MCP hosts that support Streamable HTTP servers directly: + +```json +{ + "mcpServers": { + "celina-mcp": { + "url": "https://mcp.usecelina.xyz/api/mcp" + } + } +} +``` + +For stdio-only clients, bridge through `mcp-remote`: + +```json +{ + "mcpServers": { + "celina-mcp": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.usecelina.xyz/api/mcp"] + } + } +} +``` + +## Available tools + +- Chain reads: network status, blocks, transactions, accounts, ENS +- Balances: CELO, stablecoins, registry tokens, NFTs +- Quotes: Mento FX, Uniswap v4, Aave balances, GoodDollar reserve +- Governance & staking reads: proposals, votes, validator groups, delegates, staking eligibility +- Humanness check, Self Agent ID lookups, AgentKarma reputation +- Attribution tag verification + +## Troubleshooting + +| Symptom | Cause | What to do | +|---|---|---| +| MCP call to a write tool (e.g. `send_token`, `execute_lock_celo`) fails with JSON-RPC error `-32602`: `Tool ${name} not found` | Write tools aren't registered on the hosted deployment (`serverKeyToolsEnabled: false`) | Run the [local MCP server](/build-on-celo/build-with-ai/celina/mcp) with `CELO_PRIVATE_KEY` set instead | +| A2A `message/send` on a write tool returns `Tool "${tool}" is not available on hosted A2A (read-only profile).` | Same read-only filtering applies to the A2A endpoint | Use the local MCP server, or call a read/quote tool over A2A instead | +| `get_wallet_address` isn't available, or a tool errors asking for an address | The hosted deployment has no server wallet | Pass an explicit `address` argument to any tool that needs one | + +## Resources + +| Resource | Link | +|---|---| +| GitHub repository | [andrewkimjoseph/celina-mcp-remote](https://github.com/andrewkimjoseph/celina-mcp-remote) | +| Health check | [mcp.usecelina.xyz/api/health](https://mcp.usecelina.xyz/api/health) | + +## Related + +- [Celina MCP Server](/build-on-celo/build-with-ai/celina/mcp) — the local stdio server with writes +- [Celina API](/build-on-celo/build-with-ai/celina/api) — the same read catalog over plain REST instead of MCP diff --git a/build-on-celo/build-with-ai/celina/index.mdx b/build-on-celo/build-with-ai/celina/index.mdx new file mode 100644 index 000000000..776fffc47 --- /dev/null +++ b/build-on-celo/build-with-ai/celina/index.mdx @@ -0,0 +1,22 @@ +--- +title: "Celina" +sidebarTitle: "Overview" +description: "Give an LLM read, prepare, and execute access to Celo mainnet through an SDK, a local MCP server, a hosted MCP server, and a REST API" +--- + +Celina is a third-party, open-source stack for app and agent developers that gives an LLM a wallet on Celo mainnet — chain reads, transaction preparation, and execution for transfers, Mento FX, Uniswap v4, Aave v3, GoodDollar, governance, staking, and Self Agent ID, backed by one shared tool catalog reused identically across four surfaces. + + + + TypeScript library for a custom backend — server-side reads, unsigned transaction preparation, and ERC-4337 account abstraction. + + + Local stdio MCP server for Cursor and Claude Desktop — holds a private key on your machine and can sign writes. + + + Public Streamable HTTP MCP endpoint with no install and no keys — reads and quotes only. + + + Public, keyless REST API for the same read-only catalog, for clients that don't speak MCP. + + diff --git a/build-on-celo/build-with-ai/celina/mcp.mdx b/build-on-celo/build-with-ai/celina/mcp.mdx new file mode 100644 index 000000000..526060a41 --- /dev/null +++ b/build-on-celo/build-with-ai/celina/mcp.mdx @@ -0,0 +1,131 @@ +--- +title: "Celina MCP Server" +sidebarTitle: "MCP Server" +description: "Run a local stdio MCP server that signs Celo mainnet transfers, DeFi, governance, and staking writes with your own key" +--- + +**`@andrewkimjoseph/celina-mcp`** is an open-source [Model Context Protocol](/build-on-celo/build-with-ai/mcp/index) server for Celo mainnet, for developers who want their AI assistant to sign transactions with a key that stays on their own machine. Running it locally over stdio gives the assistant the full Celina tool catalog, including writes. + + + If you don't need writes, or don't want to install anything, use the [Hosted MCP](/build-on-celo/build-with-ai/celina/hosted-mcp) endpoint instead — no keys required. + + +## Prerequisites + +- Node.js 20 or 22 LTS +- An MCP client that supports stdio servers (Cursor, Claude Desktop, LM Studio, Continue, MCP Inspector) + +```bash +npm i -g @andrewkimjoseph/celina-mcp@latest +``` + +## How it works + +The server uses up to two independent wallets, selected per tool with a `signer` argument (`"celo"` or `"self_agent"`). Every prepared write is simulated with `simulatePreparedStep` before broadcast, and stamped with a Celina [attribution tag](/build-on-celo/attribution-tags) (ERC-8021) so on-chain activity can be traced back to the calling app. + +## Configure environment variables + +| Variable | Required | Description | +|---|---|---| +| `CELO_PRIVATE_KEY` | For writes | Main wallet used to sign transfers, swaps, staking, and governance transactions | +| `SELF_AGENT_PRIVATE_KEY` | Optional | Separate Self Agent ID wallet — can act alone for humanness-gated governance/staking | +| `SELF_AGENT_API_BASE` | Optional | Override for the Self REST API (defaults to `https://app.ai.self.xyz`) | +| `CELO_RPC_URL_MAINNET` | Optional | Override the default Forno mainnet RPC | +| `ETH_RPC_URL_MAINNET` | Optional | Ethereum RPC used for ENS resolution | + +Private keys accept 64 hex characters with or without a `0x` prefix. Only set the keys you plan to use — `SELF_AGENT_PRIVATE_KEY` becomes the default signer when `CELO_PRIVATE_KEY` is not set; when both are set, `CELO_PRIVATE_KEY` is the default and either can be selected explicitly with `signer: "celo" | "self_agent"`. + +## Connect your MCP client + +GUI clients like Cursor and Claude Desktop often spawn MCP servers with a minimal `PATH` that doesn't include nvm, fnm, Homebrew, or npm's global bin. A bare `"command": "celina-mcp"` then fails with `spawn celina-mcp ENOENT`. Find the binary's absolute path first, then paste it into `"command"`: + +- **macOS / Linux:** `which celina-mcp` +- **Windows (cmd):** `where celina-mcp` +- **Windows (PowerShell):** `(Get-Command celina-mcp).Source` + +### Cursor / Claude Desktop (macOS, Linux) + +Add this to your MCP settings (Cursor: Settings → MCP; Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`), replacing `"command"` with your `which celina-mcp` output: + +```json +{ + "mcpServers": { + "celina-mcp": { + "type": "stdio", + "command": "/Users/YourName/.nvm/versions/node/v24.15.0/bin/celina-mcp", + "args": [], + "env": { + "CELO_PRIVATE_KEY": "0x...", + "SELF_AGENT_PRIVATE_KEY": "0x..." + } + } + } +} +``` + +### Claude Desktop (Windows) + +Config file: `%APPDATA%\Claude\claude_desktop_config.json`, replacing `"command"` with your `where celina-mcp` (or `Get-Command`) output: + +```json +{ + "mcpServers": { + "celina-mcp": { + "type": "stdio", + "command": "C:\\Users\\YourName\\AppData\\Roaming\\npm\\celina-mcp.cmd", + "args": [], + "env": { + "CELO_PRIVATE_KEY": "0x...", + "SELF_AGENT_PRIVATE_KEY": "0x..." + } + } + } +} +``` + +If path lookup returns nothing, install globally first, or as a last resort use `"command": "node"` with `"args": ["/@andrewkimjoseph/celina-mcp/build/index.js"]`. + +## Available tools + +The server registers the full shared Celina tool catalog — around 90 tools in total: + +| Category | Examples | +|---|---| +| Network & accounts | `get_network_status`, `get_block`, `get_transaction`, `get_account`, `get_celo_account_registration`, `execute_register_celo_account`, `resolve_ens`, `get_wallet_address` | +| Tokens & transfers | `get_celo_balances`, `get_stablecoin_balances`, `get_token_info`, `get_token_balance`, `get_gas_fee_data`, `estimate_send`, `send_token` | +| Mento FX | `get_mento_fx_quote`, `estimate_mento_fx`, `execute_mento_fx` | +| Uniswap v4 | `get_uniswap_quote`, `estimate_uniswap_swap`, `execute_uniswap_swap` | +| Aave v3 | `get_aave_balances`, `supply_aave`, `withdraw_aave` | +| GoodDollar | `get_gooddollar_whitelisting_info`, `get_gooddollar_ubi_entitlement`, `claim_daily_gooddollar_ubi`, `get_gooddollar_reserve_quote`, `execute_gooddollar_reserve_swap`, `execute_connect_gooddollar_identity` | +| Governance (humanness-gated writes) | `get_governance_proposals`, `get_votable_proposals`, `execute_vote`, `execute_upvote`, `execute_lock_celo`, `execute_unlock_celo`, `execute_revoke_governance_votes` | +| Staking (humanness-gated writes) | `get_staking_balances`, `get_validator_groups`, `get_stake_eligibility`, `execute_stake`, `execute_activate_stake`, `execute_unstake`, `execute_delegate_power` | +| Humanness | `check_humanness` — passes if Self Agent ID **or** GoodDollar whitelist succeeds | +| NFTs & contracts | `get_nft_info`, `get_nft_balance`, `call_contract_function`, `estimate_contract_gas`, `execute_contract_function` | +| Self Agent ID | `verify_self_agent`, `lookup_self_agent`, `register_self_agent`, `check_self_registration`, `get_self_identity`, `sign_self_request`, `authenticated_self_fetch` | +| AgentKarma | `get_agentkarma_reputation`, `get_agentkarma_celo_agent`, `check_agentkarma_counterparty` | +| Attribution | `check_attribution_tag`, `verify_attribution_tag` | + +## Troubleshooting + +| Symptom | Cause | What to do | +|---|---|---| +| MCP disconnects after ~60s; logs show `notifications/cancelled` | Cold `npx -y` start or slow first import exceeds the client's handshake timeout | Install globally (`npm i -g @andrewkimjoseph/celina-mcp@latest`); set `"command"` to the absolute path from `which`/`where`/`Get-Command`; use Node 20/22 LTS | +| Reconnect loop; logs show `spawn celina-mcp ENOENT` | The GUI client's `PATH` is missing npm's global bin (nvm/fnm/Homebrew on macOS; npm global prefix on Windows), or the binary isn't installed | Run `which`/`where`/`Get-Command` and paste that absolute path into `"command"`. If lookup is empty, install globally first, or use `"command": "node"` with `"args": ["/@andrewkimjoseph/celina-mcp/build/index.js"]` | +| `Cannot find package 'ox'` on MCP start | npm hoisted `permissionless` without `ox` at the same level | Run `npm i -g ox`, or upgrade to `@andrewkimjoseph/celina-mcp@0.18.7`+ | +| `ERESOLVE overriding peer dependency` for `permissionless` / `ox` on install | `permissionless@0.2.57`'s optional peer wants an older `ox` than Celina pins | Safe to ignore on `0.18.11`+, or install with `--legacy-peer-deps` | +| `EPIPE: broken pipe` in logs | The client closed stdio before a late `initialize` response | Fix slow startup with a global install and an absolute `"command"` path | +| Write tools fail immediately | `CELO_PRIVATE_KEY` / `SELF_AGENT_PRIVATE_KEY` is unset, invalid, or a placeholder like `0x...` | Set a real 64-hex-character key (with or without `0x`) and restart the client — invalid keys no longer block read-only tools, but writes need a real key | + +## Resources + +| Resource | Link | +|---|---| +| GitHub repository | [andrewkimjoseph/celina-mcp](https://github.com/andrewkimjoseph/celina-mcp) | +| npm package | [@andrewkimjoseph/celina-mcp](https://www.npmjs.com/package/@andrewkimjoseph/celina-mcp) | +| Local install guide | [usecelina.xyz/mcp/local](https://www.usecelina.xyz/mcp/local) | + +## Related + +- [Celina Hosted MCP](/build-on-celo/build-with-ai/celina/hosted-mcp) — the same catalog with no install and no keys, reads only +- [Celina SDK](/build-on-celo/build-with-ai/celina/sdk) — the library this server wraps +- [Attribution tags](/build-on-celo/attribution-tags) — how writes are tagged on-chain diff --git a/build-on-celo/build-with-ai/celina/sdk.mdx b/build-on-celo/build-with-ai/celina/sdk.mdx new file mode 100644 index 000000000..7cd2c4798 --- /dev/null +++ b/build-on-celo/build-with-ai/celina/sdk.mdx @@ -0,0 +1,74 @@ +--- +title: "Celina SDK" +sidebarTitle: "SDK" +description: "Add Celo mainnet reads, unsigned transaction preparation, and ERC-4337 account abstraction to a TypeScript backend" +--- + +**`@andrewkimjoseph/celina-sdk`** is a TypeScript library for app and agent developers building a custom backend on Celo mainnet — Node.js API routes, workers, or CLIs. It provides chain reads, methods that prepare unsigned transactions for wallet signing, and an optional ERC-4337 client for sponsored account abstraction. It also ships the shared tool catalog used by the Celina [MCP server](/build-on-celo/build-with-ai/celina/mcp), [hosted MCP](/build-on-celo/build-with-ai/celina/hosted-mcp), and [API](/build-on-celo/build-with-ai/celina/api). + +## Prerequisites + +- Node.js 20 or later +- The SDK is server-side only — it pulls in Node-only dependencies and is not meant to be bundled into a browser app + +```bash +npm i @andrewkimjoseph/celina-sdk +``` + +## How it works + +`createCelinaClient()` exposes one namespace per domain (`token`, `governance`, `staking`, `gooddollar`, `mentoFx`, `uniswap`, `aave`, `nft`, `contract`, `self`, `agentKarma`, `ens`, `humanness`, `blockchain`, `account`, `transaction`). Read methods return data directly; write flows go through a `prepare*` method that returns a `SerializedPreparedFlow` (`chainId: 42220`) for a wallet (wagmi/viem) to simulate and sign — the SDK itself never holds a private key. + +## Read balances and chain data + +```ts +import { createCelinaClient } from "@andrewkimjoseph/celina-sdk"; + +const celina = createCelinaClient({ + // ERC-8021 attribution: codes celina, celo_862c21dd97a7, my_app + attributionTags: ["celo_862c21dd97a7", "my_app"], +}); + +await celina.token.getStablecoinBalances("0xYourAddress"); +const proposals = await celina.governance.getProposals({ stage: "Queued" }); +``` + +## Prepare and simulate a transaction + +Prepared flows return unsigned steps for the caller's wallet to sign — simulate each step first so failures surface before the wallet prompt: + +```ts +import { simulatePreparedStep } from "@andrewkimjoseph/celina-sdk/simulation"; + +const flow = await celina.transaction.prepareSend("0xFrom", "0xTo", "USDm", "10"); + +for (const step of flow.steps) { + await simulatePreparedStep(step); // dry-run before the wallet signs +} +// flow.steps -> sendTransactionAsync from the caller's wallet +``` + +## Troubleshooting + +| Symptom | Cause | What to do | +|---|---|---| +| `Unknown token "${token}" on Celo mainnet. Use ${...}.` | Token symbol isn't in the registry (`token.service.ts`) | Use one of the listed symbols — the error names them | +| `Insufficient ${symbol} balance. Required ${amount} ${symbol}, available ${available}.` | Wallet balance below the amount requested (`token.service.ts`) | Fund the wallet or lower the amount | +| `Simulation failed for "${step.description}": ...` | `simulatePreparedStep` caught a revert before broadcast (`simulation/simulate-prepared-step.ts`) | Read the appended reason — usually insufficient balance or allowance | +| `Mento FX market is currently closed. FX quotes and execution are unavailable until the market reopens.` | Mento FX has scheduled market hours (`mento-fx.service.ts`) | Retry when the market reopens; use Uniswap v4 for an alternative route | +| `No Uniswap v4 route for ${tokenIn} → ${tokenOut}.` | No pool exists for that pair (`uniswap.service.ts`) | Try a different token pair, or route through Mento FX / GoodDollar reserve | +| Build fails when bundling for a browser | The SDK imports Node-only modules (`node:fs`, `@agentkarma/sdk`, `@celo/attribution-tags`) | Keep the SDK server-side; use `@andrewkimjoseph/celina-sdk/simulation` (browser-safe) or wagmi/viem directly in the browser | + +## Resources + +| Resource | Link | +|---|---| +| GitHub repository | [andrewkimjoseph/celina-sdk](https://github.com/andrewkimjoseph/celina-sdk) | +| npm package | [@andrewkimjoseph/celina-sdk](https://www.npmjs.com/package/@andrewkimjoseph/celina-sdk) | +| GitBook documentation | [andrewkimjoseph.gitbook.io/celina-sdk](https://andrewkimjoseph.gitbook.io/celina-sdk) | + +## Related + +- [Celina MCP Server](/build-on-celo/build-with-ai/celina/mcp) — runs this SDK's tool catalog locally with a signing key +- [Celina API](/build-on-celo/build-with-ai/celina/api) — the same read catalog over plain REST, no SDK install needed +- [Attribution tags](/build-on-celo/attribution-tags) — how the `attributionTags` option is applied on-chain diff --git a/build-on-celo/build-with-ai/mcp/index.mdx b/build-on-celo/build-with-ai/mcp/index.mdx index 613cf123e..9bd41e972 100644 --- a/build-on-celo/build-with-ai/mcp/index.mdx +++ b/build-on-celo/build-with-ai/mcp/index.mdx @@ -12,6 +12,8 @@ description: Learn about the Model Context Protocol and how to use Celo-specific - Governance Proposals - [Celo Docs MCP Server](/build-on-celo/build-with-ai/use-docs-with-ai) - Search the documentation from your editor +- [Celina](/build-on-celo/build-with-ai/celina/index) + - Give your LLM a wallet on Celo — balances, transfers, DeFi, governance, staking, and Self Agent ID