ouro-mcp 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# ouro-mcp
+
+[![npm](https://img.shields.io/npm/v/ouro-mcp)](https://www.npmjs.com/package/ouro-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Run HPC compute jobs from any AI agent — paid in USDC on Base via [x402](https://www.x402.org/).
+
+## What is Ouro?
+
+Ouro is an autonomous agent that sells high-performance compute on a Slurm cluster. This MCP server lets any AI agent submit jobs, poll for results, and pay automatically — your wallet signs USDC payments locally via x402, so your private key never leaves your machine.
+
+## Quick Start
+
+You need Node.js 18+ and a wallet with USDC on Base.
+
+```bash
+npx -y ouro-mcp
+```
+
+Add to your MCP client config (works with Cursor, Claude Code, Claude Desktop, VS Code, Windsurf, and any MCP-compatible client):
+
+```json
+{
+  "mcpServers": {
+    "ouro": {
+      "command": "npx",
+      "args": ["-y", "ouro-mcp"],
+      "env": { "WALLET_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+> **Claude Code** also supports: `claude mcp add ouro -- npx -y ouro-mcp`
+
+## Usage Examples
+
+### Run a simple script
+
+```
+User: Run a Python script that computes the first 1000 primes
+
+→ run_job(
+    script: "python3 -c \"primes = []; n = 2\nwhile len(primes) < 1000:\n  if all(n % p for p in primes): primes.append(n)\n  n += 1\nprint(primes)\"",
+    image: "ouro-python"
+  )
+
+← { "job_id": "abc123", "price_usdc": "0.01", "status": "pending" }
+```
+
+### Multi-file project with custom Dockerfile
+
+```
+→ run_job(
+    files: [
+      { "path": "main.py", "content": "import numpy as np\nprint(np.random.rand(3, 3))" },
+      { "path": "Dockerfile", "content": "FROM python:3.12-slim\nRUN pip install numpy\nENTRYPOINT [\"python\", \"main.py\"]" }
+    ],
+    image: "python:3.12-slim",
+    cpus: 2,
+    time_limit_min: 5
+  )
+
+← { "job_id": "def456", "price_usdc": "0.03", "status": "pending" }
+```
+
+### Poll for results
+
+```
+→ get_job_status(job_id: "abc123")
+
+← { "status": "completed", "output": "[2, 3, 5, 7, 11, ...]", "runtime_seconds": 4.2 }
+```
+
+### Check pricing first
+
+```
+→ get_price_quote(cpus: 4, time_limit_min: 10)
+
+← { "price_usdc": "0.12", "breakdown": { "base": 0.01, "cpu_multiplier": 4, ... } }
+```
+
+## Tools
+
+### `run_job`
+
+Submit a compute job and pay automatically. Returns `job_id` when accepted.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `script` | string | One of `script` or `files` | — | Shell script to execute |
+| `files` | array | One of `script` or `files` | — | Array of `{path, content}` objects (can include a Dockerfile) |
+| `image` | string | No | `ouro-ubuntu` | Container image to use |
+| `cpus` | integer | No | `1` | CPU cores (1–8) |
+| `time_limit_min` | integer | No | `1` | Max runtime in minutes |
+| `builder_code` | string | No | — | Builder code for [ERC-8021](https://eips.ethereum.org/EIPS/eip-8021) attribution |
+
+### `get_job_status`
+
+Check the status of a submitted job. Returns output when completed.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `job_id` | string | Yes | Job ID returned by `run_job` |
+
+### `get_price_quote`
+
+Get a price quote without submitting or paying.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `cpus` | integer | No | `1` | CPU cores |
+| `time_limit_min` | integer | No | `1` | Max runtime in minutes |
+| `submission_mode` | string | No | `script` | `script` or `multi_file` |
+
+### `get_allowed_images`
+
+List available container images. No parameters.
+
+## Container Images
+
+**Prebuilt (instant start):**
+- `ouro-ubuntu` — Ubuntu 22.04
+- `ouro-python` — Python 3.12 with pip
+- `ouro-nodejs` — Node.js 20 LTS
+
+**Custom:** Include a `Dockerfile` in your `files` array to use any Docker Hub image:
+```dockerfile
+FROM python:3.12-slim
+RUN pip install numpy pandas
+ENTRYPOINT ["python", "main.py"]
+```
+
+## Pricing
+
+Jobs start at ~$0.01 USDC (1 CPU, 1 minute). Price scales with CPUs and time limit. Ouro uses dynamic pricing — use `get_price_quote` to check the current price before submitting.
+
+Jobs that finish early receive proportional credits for unused compute time, automatically applied to future jobs.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `WALLET_PRIVATE_KEY` | Yes | Hex private key (starting with `0x`) for USDC payment signing |
+| `OURO_API_URL` | No | API base URL (default: `https://api.ourocompute.com`) |
+
+## Security
+
+Your private key **never leaves your machine**. The MCP server runs locally as a stdio process and only uses the key to sign USDC payment authorizations via x402. No keys are sent to any remote server.
+
+## Links
+
+- [Dashboard](https://ourocompute.com) — live P&L, job stats, submit jobs
+- [API Docs](https://github.com/richtan/ouro/blob/main/docs/api-reference.md)
+- [GitHub](https://github.com/richtan/ouro)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { privateKeyToAccount } from "viem/accounts";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+// ---------------------------------------------------------------------------
+// Environment
+// ---------------------------------------------------------------------------
+const WALLET_PRIVATE_KEY = process.env.WALLET_PRIVATE_KEY;
+if (!WALLET_PRIVATE_KEY) {
+    console.error("Error: WALLET_PRIVATE_KEY environment variable is required.\n" +
+        'Set it in your MCP config\'s env section (hex string starting with "0x").');
+    process.exit(1);
+}
+if (!WALLET_PRIVATE_KEY.startsWith("0x")) {
+    console.error("Error: WALLET_PRIVATE_KEY must be a hex string starting with 0x");
+    process.exit(1);
+}
+const API_URL = (process.env.OURO_API_URL || "https://api.ourocompute.com").replace(/\/$/, "");
+// ---------------------------------------------------------------------------
+// Wallet & x402
+// ---------------------------------------------------------------------------
+const account = privateKeyToAccount(WALLET_PRIVATE_KEY);
+const walletAddress = account.address;
+const publicClient = createPublicClient({ chain: base, transport: http() });
+const signer = toClientEvmSigner(account, publicClient);
+const payFetch = wrapFetchWithPaymentFromConfig(fetch, {
+    schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(signer) }],
+});
+const truncAddr = `${walletAddress.slice(0, 6)}...${walletAddress.slice(-4)}`;
+console.error(`Ouro MCP server running · wallet: ${truncAddr}`);
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function apiFetch(path, opts = {}) {
+    const { paid = false, timeout = 30_000, ...init } = opts;
+    const fetchFn = paid ? payFetch : fetch;
+    const url = `${API_URL}${path}`;
+    try {
+        return await fetchFn(url, {
+            ...init,
+            signal: AbortSignal.timeout(timeout),
+        });
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "TimeoutError") {
+            throw new Error(`Request to ${path} timed out after ${timeout}ms`);
+        }
+        throw new Error(`Cannot reach ${API_URL}. Check internet connection. (${err instanceof Error ? err.message : err})`);
+    }
+}
+function errorText(status, body) {
+    switch (status) {
+        case 403:
+            return "Payment verification failed. Check USDC balance on Base.";
+        case 422:
+            try {
+                const parsed = JSON.parse(body);
+                return parsed.detail || parsed.message || body;
+            }
+            catch {
+                return body;
+            }
+        case 429:
+            return "Rate limited or max active jobs reached. Wait and retry.";
+        case 503:
+            return "Payment facilitator temporarily unavailable. Retry shortly.";
+        default:
+            return `API returned ${status}: ${body}`;
+    }
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({ name: "ouro", version: "1.0.0" }, {
+    instructions: `Ouro runs HPC jobs on a Slurm cluster, paid in USDC via x402 on Base.
+Payment is automatic — your wallet signs USDC payments locally.
+
+Typical flow:
+  1. run_job(script="echo hello") → { job_id, price }
+  2. get_job_status(job_id) → poll until status is "completed"
+
+Submission modes:
+  - script: single shell script (simplest)
+  - files: list of {path, content} objects (multi-file workspace, can include a Dockerfile)
+
+Use get_price_quote to check pricing before committing.
+Use get_allowed_images to see available container images.
+
+Prebuilt images (instant): ouro-ubuntu, ouro-python, ouro-nodejs.
+Any Docker Hub image works via Dockerfile (e.g., FROM python:3.12-slim).`,
+});
+// ---------------------------------------------------------------------------
+// Tool: run_job
+// ---------------------------------------------------------------------------
+server.tool("run_job", "Submit a compute job and pay automatically. Returns job_id when accepted.", {
+    script: z.string().optional().describe("Shell script to execute (use this OR files)"),
+    files: z
+        .array(z.object({ path: z.string(), content: z.string() }))
+        .optional()
+        .describe("Array of {path, content} file objects (can include a Dockerfile)"),
+    image: z.string().default("ouro-ubuntu").describe("Container image (default: ouro-ubuntu)"),
+    cpus: z.number().int().min(1).max(8).default(1).describe("CPU cores (1-8)"),
+    time_limit_min: z.number().int().min(1).default(1).describe("Max runtime in minutes"),
+    builder_code: z.string().optional().describe("Builder code for ERC-8021 attribution"),
+}, async (params) => {
+    // Validate: exactly one of script or files
+    if (params.script && params.files) {
+        return { content: [{ type: "text", text: "Provide either script or files, not both." }] };
+    }
+    if (!params.script && !params.files) {
+        return { content: [{ type: "text", text: "Provide either script or files." }] };
+    }
+    const body = {
+        cpus: params.cpus,
+        time_limit_min: params.time_limit_min,
+        image: params.image,
+        submitter_address: walletAddress,
+    };
+    if (params.script)
+        body.script = params.script;
+    if (params.files)
+        body.files = params.files;
+    const headers = { "Content-Type": "application/json" };
+    if (params.builder_code)
+        headers["X-BUILDER-CODE"] = params.builder_code;
+    try {
+        const res = await apiFetch("/api/compute/submit", {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            paid: true,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: errorText(res.status, text) }] };
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }] };
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool: get_job_status
+// ---------------------------------------------------------------------------
+server.tool("get_job_status", "Check the status of a job. Returns output when completed.", {
+    job_id: z.string().describe("Job ID to check"),
+}, async (params) => {
+    try {
+        const res = await apiFetch(`/api/jobs/${params.job_id}`);
+        const text = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: errorText(res.status, text) }] };
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }] };
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool: get_price_quote
+// ---------------------------------------------------------------------------
+server.tool("get_price_quote", "Get a price quote without paying. Check pricing before committing.", {
+    cpus: z.number().int().min(1).max(8).default(1).describe("CPU cores"),
+    time_limit_min: z.number().int().min(1).default(1).describe("Max runtime in minutes"),
+    submission_mode: z
+        .string()
+        .default("script")
+        .describe("Submission mode: script, multi_file"),
+}, async (params) => {
+    try {
+        const qs = new URLSearchParams({
+            cpus: String(params.cpus),
+            time_limit_min: String(params.time_limit_min),
+            submission_mode: params.submission_mode,
+        });
+        const res = await apiFetch(`/api/price?${qs}`);
+        const text = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: errorText(res.status, text) }] };
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }] };
+    }
+});
+// ---------------------------------------------------------------------------
+// Tool: get_allowed_images
+// ---------------------------------------------------------------------------
+server.tool("get_allowed_images", "List available container images for compute jobs.", {}, async () => {
+    try {
+        const res = await apiFetch("/api/capabilities");
+        const text = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: errorText(res.status, text) }] };
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }] };
+    }
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "ouro-mcp",
+  "version": "1.0.0",
+  "description": "Run HPC compute from any AI agent — pay with USDC via x402 on Base",
+  "bin": {
+    "ouro-mcp": "./dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25",
+    "@x402/evm": "^2.6",
+    "@x402/fetch": "^2.6",
+    "viem": "^2.0",
+    "zod": "^3.23"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0",
+    "typescript": "^5.5"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/richtan/ouro"
+  },
+  "keywords": [
+    "mcp",
+    "compute",
+    "x402",
+    "usdc",
+    "base",
+    "hpc",
+    "slurm"
+  ]
+}