@ramestta/agent-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,55 @@
+# @ramestta/agent-mcp-server
+
+**Give your AI a wallet it can't abuse.** An MCP server that exposes a booted
+[Ramestta](https://agents.ramestta.com) AI agent's on-chain capabilities as tools —
+so Claude, Cursor, or any MCP client can pay, schedule on-chain work, and message other
+agents, every action bounded by the agent's **on-chain spend limits**.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `ramestta_agent_info` | The agent's `.rama` name, wallet address, and RAMA balance |
+| `ramestta_remaining_quota` | Sponsored (gas-free) transactions left this month |
+| `ramestta_send_payment` | Send RAMA to an address or `.rama` name — respects on-chain spend limits |
+| `ramestta_schedule_task` | Schedule a recurring on-chain call, run by the keeper market (no server) |
+| `ramestta_list_tasks` | List the agent's scheduled task ids |
+| `ramestta_send_message` | Send an end-to-end-encrypted message to another agent by `.rama` name |
+
+## Setup
+
+First [boot an agent](https://agents.ramestta.com) to get a `.rama` name and its controller
+key. Then add the server to your MCP client.
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ramestta": {
+      "command": "npx",
+      "args": ["-y", "@ramestta/agent-mcp-server"],
+      "env": {
+        "AGENT_KEY": "0xYOUR_CONTROLLER_KEY",
+        "AGENT_NAME": "yieldhunter",
+        "RAMESTTA_NETWORK": "testnet"
+      }
+    }
+  }
+}
+```
+
+| Env var | Required | Notes |
+|---|---|---|
+| `AGENT_KEY` | ✅ | Controller private key. Used locally to sign; never sent anywhere but the RPC. |
+| `AGENT_NAME` | ✅ | Your agent's `.rama` name without the suffix. |
+| `RAMESTTA_NETWORK` | — | `mainnet` or `testnet` (default `testnet`). |
+
+## Safety
+
+Every value-moving tool goes through the agent's on-chain `AgentPermissions` layer —
+per-tx / per-day / per-month spend caps, allow-lists, and a human approval inbox. The
+controller can pause or revoke the agent at any time. Start on testnet with small amounts;
+Ramestta mainnet is a guarded beta pending external audit.
+
+Docs: **https://agents.ramestta.com** · Built on [@ramestta/agent-kit](https://www.npmjs.com/package/@ramestta/agent-kit)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ramestta/agent-mcp-server",
+  "version": "0.2.0",
+  "description": "MCP server exposing a Ramestta AI agent's on-chain capabilities as tools",
+  "license": "MIT",
+  "bin": {
+    "ramestta-agent-mcp": "server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md",
+    "server.json",
+    "smithery.yaml"
+  ],
+  "dependencies": {
+    "@ramestta/agent-kit": "^0.2.0",
+    "ethers": "^6.13.0"
+  },
+  "keywords": [
+    "ramestta",
+    "ai-agents",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "evm",
+    "web3",
+    "blockchain",
+    "agent",
+    "wallet"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ramestta/agent-kit.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://agents.ramestta.com",
+  "author": "Ramestta",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/server.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Ramestta Agent OS — MCP server (stdio, JSON-RPC 2.0, newline-delimited).
+ *
+ * Exposes a booted agent's capabilities as MCP tools so any MCP client
+ * (Claude Desktop, Claude Code, etc.) can drive an on-chain agent:
+ *   ramestta_agent_info, ramestta_remaining_quota, ramestta_send_payment,
+ *   ramestta_schedule_task, ramestta_list_tasks, ramestta_send_message
+ *
+ * Config via env: AGENT_KEY, AGENT_NAME, RAMESTTA_NETWORK (default testnet).
+ * Every value-moving tool still passes the on-chain AgentPermissions layer.
+ *
+ * Register in an MCP client, e.g. Claude Code:
+ *   claude mcp add ramestta -- node /path/to/mcp-server/server.js
+ * (with AGENT_KEY / AGENT_NAME in the environment)
+ */
+const { Agent } = require("@ramestta/agent-kit");
+const { Wallet } = require("ethers");
+
+const TOOLS = [
+  { name: "ramestta_agent_info", description: "Get the agent's .rama name, wallet address and RAMA balance.", schema: { type: "object", properties: {} } },
+  { name: "ramestta_remaining_quota", description: "Sponsored (gas-free) transactions left this month.", schema: { type: "object", properties: {} } },
+  { name: "ramestta_send_payment", description: "Send RAMA to an address or .rama agent name (respects on-chain spend limits).", schema: { type: "object", properties: { to: { type: "string" }, amountRama: { type: "string" } }, required: ["to", "amountRama"] } },
+  { name: "ramestta_schedule_task", description: "Schedule a recurring on-chain call, executed by the keeper market (no server needed).", schema: { type: "object", properties: { targetAddress: { type: "string" }, callDataHex: { type: "string" }, everySeconds: { type: "number" } }, required: ["targetAddress", "callDataHex", "everySeconds"] } },
+  { name: "ramestta_list_tasks", description: "List the agent's scheduled task ids.", schema: { type: "object", properties: {} } },
+  { name: "ramestta_send_message", description: "Send an end-to-end encrypted message to another agent by .rama name.", schema: { type: "object", properties: { toName: { type: "string" }, message: { type: "string" } }, required: ["toName", "message"] } },
+];
+
+let agentPromise;
+function getAgent() {
+  if (!agentPromise) {
+    const signer = new Wallet(process.env.AGENT_KEY);
+    agentPromise = Agent.connect(process.env.AGENT_NAME, signer, process.env.RAMESTTA_NETWORK || "testnet");
+  }
+  return agentPromise;
+}
+
+async function callTool(name, args) {
+  const { ramesttaTools } = await import("@ramestta/agent-kit/langchain");
+  const agent = await getAgent();
+  const tools = await ramesttaTools(agent);
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) throw new Error(`unknown tool ${name}`);
+  return tool.invoke(args || {});
+}
+
+// ─── MCP JSON-RPC over stdio ────────────────────────────────────────────────
+function send(msg) { process.stdout.write(JSON.stringify(msg) + "\n"); }
+
+async function handle(req) {
+  const { id, method, params } = req;
+  try {
+    if (method === "initialize") {
+      return { jsonrpc: "2.0", id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "ramestta-agent-os", version: "0.2.0" } } };
+    }
+    if (method === "tools/list") {
+      return { jsonrpc: "2.0", id, result: { tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.schema })) } };
+    }
+    if (method === "tools/call") {
+      const out = await callTool(params.name, params.arguments);
+      return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text: String(out) }] } };
+    }
+    if (method === "notifications/initialized" || method?.startsWith("notifications/")) return null;
+    return { jsonrpc: "2.0", id, error: { code: -32601, message: `method not found: ${method}` } };
+  } catch (e) {
+    return { jsonrpc: "2.0", id, error: { code: -32000, message: e.shortMessage || e.message } };
+  }
+}
+
+let buf = "";
+process.stdin.on("data", async (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let req;
+    try { req = JSON.parse(line); } catch { continue; }
+    const res = await handle(req);
+    if (res) send(res);
+  }
+});
+
+process.stderr.write(`ramestta MCP server ready (agent ${process.env.AGENT_NAME || "?"}.rama, ${process.env.RAMESTTA_NETWORK || "testnet"})\n`);

package/server.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.ramestta/agent-mcp-server",
+  "description": "Give an AI model its own on-chain body on Ramestta: a .rama identity, a smart wallet with spend limits, sponsored gas, server-less scheduled execution, and end-to-end-encrypted agent-to-agent messaging.",
+  "repository": {
+    "url": "https://github.com/ramestta/agent-kit",
+    "source": "github",
+    "subfolder": "mcp-server"
+  },
+  "version": "0.2.0",
+  "websiteUrl": "https://agents.ramestta.com",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@ramestta/agent-mcp-server",
+      "version": "0.2.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "AGENT_KEY",
+          "description": "Controller private key (0x...) of your booted agent. Used locally to sign; never transmitted anywhere but the RPC.",
+          "isRequired": true,
+          "isSecret": true
+        },
+        {
+          "name": "AGENT_NAME",
+          "description": "Your booted agent's .rama name without the suffix (e.g. yieldhunter).",
+          "isRequired": true
+        },
+        {
+          "name": "RAMESTTA_NETWORK",
+          "description": "mainnet | testnet",
+          "isRequired": false,
+          "default": "testnet"
+        }
+      ]
+    }
+  ]
+}

package/smithery.yaml

@@ -0,0 +1,37 @@
+# Smithery config — lists the Ramestta Agent MCP server so any MCP client
+# (Claude Desktop, Cursor, etc.) can install and drive a Ramestta AI agent.
+# https://smithery.ai/docs
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required: ["agentKey", "agentName"]
+    properties:
+      agentKey:
+        type: string
+        title: Agent controller key
+        description: "The controller private key (0x...) of your booted agent. Kept locally; never sent anywhere but the RPC you sign with."
+      agentName:
+        type: string
+        title: Agent .rama name
+        description: "Your booted agent name without the .rama suffix (e.g. \"yieldhunter\")."
+      network:
+        type: string
+        title: Network
+        enum: ["mainnet", "testnet"]
+        default: "testnet"
+        description: "Ramestta network. Start on testnet."
+  commandFunction: |
+    (config) => ({
+      command: "node",
+      args: ["server.js"],
+      env: {
+        AGENT_KEY: config.agentKey,
+        AGENT_NAME: config.agentName,
+        RAMESTTA_NETWORK: config.network || "testnet"
+      }
+    })
+  exampleConfig:
+    agentKey: "0xYOUR_CONTROLLER_PRIVATE_KEY"
+    agentName: "yieldhunter"
+    network: "testnet"