@andrewkimjoseph/celina 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Kim Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# Celina — Celo MCP Server
+
+**Celina** is an open-source [Model Context Protocol](https://modelcontextprotocol.io) server that gives LLMs read + write access to **Celo mainnet** — balances, stablecoins, sends, swaps (quote stub), and chain reads.
+
+Website: [celina.andrewkimjoseph.com](https://celina.andrewkimjoseph.com)
+
+## Install
+
+```bash
+npm i @andrewkimjoseph/celina
+```
+
+npm: [@andrewkimjoseph/celina](https://www.npmjs.com/package/@andrewkimjoseph/celina)
+
+## Quick start
+
+**From npm** (stdio MCP server):
+
+```bash
+npx @andrewkimjoseph/celina
+```
+
+**From source** (development):
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## Deploy to Render
+
+This project includes a [Render Blueprint](render.yaml) for one-click deployment as a public Streamable HTTP MCP server.
+
+### 1. Generate an RSA key pair
+
+```bash
+openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
+openssl rsa -pubout -in private.pem -out public.pem
+```
+
+### 2. Deploy
+
+1. Push this repo to GitHub
+2. Render Dashboard → **New → Blueprint** → connect the repo
+3. Set `WALLET_ENCRYPTION_PRIVATE_KEY` in the Render Environment tab (paste contents of `private.pem`)
+4. Your MCP endpoint will be at `https://celina.onrender.com/mcp`
+
+> **Note:** Free Render services spin down after ~15 minutes of inactivity. Cold starts can take 30–60 seconds and may cause MCP client timeouts. Use a Starter plan for always-on hosting.
+
+## Cursor / Claude Desktop config
+
+### Remote (Render — recommended)
+
+```json
+{
+  "mcpServers": {
+    "celina": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://celina.onrender.com/mcp",
+        "--transport",
+        "http-only"
+      ]
+    }
+  }
+}
+```
+
+Or with streamable HTTP directly:
+
+```json
+{
+  "mcpServers": {
+    "celina": {
+      "type": "streamable-http",
+      "url": "https://celina.onrender.com/mcp"
+    }
+  }
+}
+```
+
+### Local stdio (npm)
+
+```json
+{
+  "mcpServers": {
+    "celina": {
+      "command": "npx",
+      "args": ["-y", "@andrewkimjoseph/celina"]
+    }
+  }
+}
+```
+
+### Local stdio (from source)
+
+```json
+{
+  "mcpServers": {
+    "celina": {
+      "command": "node",
+      "args": ["/absolute/path/to/celina/build/index.js"]
+    }
+  }
+}
+```
+
+For local write tools, add a funded mainnet wallet:
+
+```json
+"env": {
+  "CELO_PRIVATE_KEY": "0x..."
+}
+```
+
+Never commit private keys. Use env vars only.
+
+## Write tools (hosted mode)
+
+Write tools (`send_token`, `estimate_send`) accept an RSA-encrypted private key per request — never plaintext.
+
+### Flow
+
+1. Fetch the server's public key:
+   - MCP tool: `get_wallet_encryption_public_key`
+   - HTTP: `GET https://celina.onrender.com/public-key`
+2. Encrypt your key locally:
+
+```bash
+npm run encrypt-key -- --url https://celina.onrender.com --key 0xYOUR_PRIVATE_KEY
+```
+
+3. Give the agent the encrypted blob (base64 output) along with your transaction details
+4. The agent calls `send_token` with the `encryptedPrivateKey` parameter
+
+The server decrypts the key ephemerally to sign the transaction — it is not stored.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CELO_RPC_URL_MAINNET` | Forno public RPC | Override mainnet RPC |
+| `CELO_PRIVATE_KEY` | — | Local stdio write tools only |
+| `WALLET_ENCRYPTION_PRIVATE_KEY` | — | RSA private key PEM for HTTP write tools |
+| `PORT` | `10000` | HTTP server port (set by Render) |
+
+Copy `.env.example` to `.env` for local development.
+
+## Known tokens
+
+All supported tokens live in a single registry (`src/config/chains.ts`):
+
+| Category | Symbols |
+|----------|---------|
+| Native | `CELO` |
+| Mento stablecoins | `USDm`, `EURm`, `BRLm`, `XOFm`, `KESm`, `PHPm`, `COPm`, `GBPm`, `CADm`, `AUDm`, `ZARm`, `GHSm`, `NGNm`, `JPYm`, `CHFm` |
+| Bridged / third-party | `USDT`, `USDC`, `vEUR`, `vGBP`, `vCHF`, `USDM`, `USDA`, `EURA`, `USDGLO`, `BRLA`, `COPM` |
+| GoodDollar | `GoodDollar`, `G$` (`0x62B8B11039FcfE5aB0C56E502b1C372A3d2a9c7A`) |
+
+Token symbols are resolved case-insensitively. Legacy aliases `cUSD` and `cEUR` map to `USDm` and `EURm`. You can also pass any ERC-20 contract address directly.
+
+- `get_celo_balances` — check specific tokens (defaults to `CELO` + `USDm`)
+- `get_stablecoin_balances` — scan all registry stablecoins in one call (omits zero balances by default)
+
+## Tools (v0.2)
+
+| Tool | Type | Description |
+|------|------|-------------|
+| `get_network_status` | read | Mainnet chain ID, block, gas price |
+| `get_block` | read | Block by number/hash/latest |
+| `get_latest_blocks` | read | Recent blocks |
+| `get_transaction` | read | Tx + receipt |
+| `get_account` | read | CELO balance, nonce |
+| `get_celo_balances` | read | CELO + ERC-20 balances (default: CELO + USDm) |
+| `get_stablecoin_balances` | read | All registry stablecoins including GoodDollar |
+| `get_token_info` | read | Token metadata |
+| `get_wallet_encryption_public_key` | read | RSA public key for encrypting private keys |
+| `estimate_send` | read* | Gas estimate (*needs encrypted or env key) |
+| `send_token` | write | Send CELO or ERC-20 |
+| `get_swap_quote` | read | Swap preview (routing stub) |
+
+## Adding a new tool
+
+1. Create `src/tools/my-feature.tools.ts` implementing `ToolModule`:
+
+```typescript
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AppContext } from "../context/app-context.js";
+import type { ToolModule } from "./types.js";
+
+export const myFeatureTools: ToolModule = {
+  register(server, ctx) {
+    server.registerTool("my_tool", { /* ... */ }, async (args) => { /* ... */ });
+  },
+};
+```
+
+2. Append to `toolModules` in `src/tools/index.ts`.
+3. Add domain logic in `src/services/` if needed.
+4. Rebuild: `npm run build`.
+
+No changes to `src/index.ts` or server bootstrap required.
+
+## Roadmap
+
+- [ ] Mento / DEX swap routing (`execute_swap`)
+- [ ] Aave lending tools
+- [ ] Self proof verification (`ai.self.xyz`)
+- [ ] Self Agent ID check
+
+## Development
+
+```bash
+npm run dev          # watch TypeScript
+npm run inspect      # MCP Inspector UI (stdio)
+npm run start:http   # HTTP server on PORT (default 10000)
+npm run encrypt-key  # encrypt a private key for write tools
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../build/index.js";

package/build/clients/celo-client.d.ts

@@ -0,0 +1,14 @@
+import { type PublicClient, type WalletClient } from "viem";
+import type { AppConfig } from "../config/env.js";
+export interface CeloClients {
+    public: PublicClient;
+    wallet?: WalletClient;
+    accountAddress?: `0x${string}`;
+}
+export declare class CeloClientFactory {
+    private readonly config;
+    private clients;
+    constructor(config: AppConfig);
+    getClients(): CeloClients;
+    getClientsForAccount(privateKey: `0x${string}`): CeloClients;
+}

package/build/clients/celo-client.js

@@ -0,0 +1,58 @@
+import { createPublicClient, createWalletClient, http, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { CHAIN, DEFAULT_RPC_URL } from "../config/chains.js";
+export class CeloClientFactory {
+    config;
+    clients = null;
+    constructor(config) {
+        this.config = config;
+    }
+    getClients() {
+        if (this.clients) {
+            return this.clients;
+        }
+        const rpcUrl = this.config.rpcUrl ?? DEFAULT_RPC_URL;
+        const transport = http(rpcUrl);
+        const publicClient = createPublicClient({
+            chain: CHAIN,
+            transport,
+        });
+        let wallet;
+        let accountAddress;
+        if (this.config.privateKey) {
+            const account = privateKeyToAccount(this.config.privateKey);
+            accountAddress = account.address;
+            wallet = createWalletClient({
+                account,
+                chain: CHAIN,
+                transport,
+            });
+        }
+        this.clients = {
+            public: publicClient,
+            wallet,
+            accountAddress,
+        };
+        return this.clients;
+    }
+    getClientsForAccount(privateKey) {
+        const rpcUrl = this.config.rpcUrl ?? DEFAULT_RPC_URL;
+        const transport = http(rpcUrl);
+        const publicClient = createPublicClient({
+            chain: CHAIN,
+            transport,
+        });
+        const account = privateKeyToAccount(privateKey);
+        const wallet = createWalletClient({
+            account,
+            chain: CHAIN,
+            transport,
+        });
+        return {
+            public: publicClient,
+            wallet,
+            accountAddress: account.address,
+        };
+    }
+}
+//# sourceMappingURL=celo-client.js.map

package/build/clients/celo-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"celo-client.js","sourceRoot":"","sources":["../../src/clients/celo-client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,IAAI,GAGL,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAQ7D,MAAM,OAAO,iBAAiB;IAGC;IAFrB,OAAO,GAAuB,IAAI,CAAC;IAE3C,YAA6B,MAAiB;QAAjB,WAAM,GAAN,MAAM,CAAW;IAAG,CAAC;IAElD,UAAU;QACR,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,OAAO,CAAC;QACtB,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,eAAe,CAAC;QACrD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/B,MAAM,YAAY,GAAG,kBAAkB,CAAC;YACtC,KAAK,EAAE,KAAK;YACZ,SAAS;SACV,CAAiB,CAAC;QAEnB,IAAI,MAAgC,CAAC;QACrC,IAAI,cAAyC,CAAC;QAE9C,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC5D,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;YACjC,MAAM,GAAG,kBAAkB,CAAC;gBAC1B,OAAO;gBACP,KAAK,EAAE,KAAK;gBACZ,SAAS;aACV,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,OAAO,GAAG;YACb,MAAM,EAAE,YAAY;YACpB,MAAM;YACN,cAAc;SACf,CAAC;QAEF,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,oBAAoB,CAAC,UAAyB;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,eAAe,CAAC;QACrD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/B,MAAM,YAAY,GAAG,kBAAkB,CAAC;YACtC,KAAK,EAAE,KAAK;YACZ,SAAS;SACV,CAAiB,CAAC;QACnB,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;QAEhD,MAAM,MAAM,GAAG,kBAAkB,CAAC;YAChC,OAAO;YACP,KAAK,EAAE,KAAK;YACZ,SAAS;SACV,CAAC,CAAC;QAEH,OAAO;YACL,MAAM,EAAE,YAAY;YACpB,MAAM;YACN,cAAc,EAAE,OAAO,CAAC,OAAO;SAChC,CAAC;IACJ,CAAC;CACF"}