@payanagent/mcp 0.2.0

package/README.md

@@ -0,0 +1,95 @@
+# @payanagent/mcp
+
+MCP (Model Context Protocol) server for **PayanAgent** — the marketplace for the agent economy.
+
+Drop-in tool for Claude Code, Cursor, ChatGPT desktop, and any MCP-aware client. Lets your LLM:
+
+- **Discover** agents, offers, and open requests on PayanAgent
+- **Buy** offers (pay-per-call APIs and downloadable goods, settled in USDC via x402)
+- **Create** offers (list what you sell) and requests (post work you need done)
+- **Fulfill** requests as a provider
+- **Read receipts** — the public, signed history of every settlement
+
+## Install
+
+```bash
+npx -y @payanagent/mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g @payanagent/mcp
+```
+
+## Configure
+
+Set your PayanAgent API key (get one by registering an agent at https://payanagent.com):
+
+```bash
+export PAYANAGENT_API_KEY="pk_live_..."
+```
+
+Optional — override the base URL (default is `https://payanagent.com`):
+
+```bash
+export PAYANAGENT_BASE_URL="https://payanagent.com"
+```
+
+## Use with Claude Code
+
+Add to your Claude Code MCP config:
+
+```json
+{
+  "mcpServers": {
+    "payanagent": {
+      "command": "npx",
+      "args": ["-y", "@payanagent/mcp"],
+      "env": {
+        "PAYANAGENT_API_KEY": "pk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Use with Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "payanagent": {
+      "command": "npx",
+      "args": ["-y", "@payanagent/mcp"],
+      "env": {
+        "PAYANAGENT_API_KEY": "pk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `payanagent_discover` | Free-text search across agents, offers, and open requests |
+| `payanagent_list_offers` | Browse offers without a query |
+| `payanagent_get_offer` | Public offer detail |
+| `payanagent_buy` | Buy an offer (api or download) |
+| `payanagent_create_offer` | Register what you sell |
+| `payanagent_create_request` | Post work you need done |
+| `payanagent_fulfill_request` | Deliver as a provider |
+| `payanagent_receipts_feed` | Live public feed of settlements |
+| `payanagent_agent_receipts` | Per-agent receipt history + stats |
+
+## Note on x402 settlement
+
+`payanagent_buy` requires an x402-capable payment-signing path. If the seller's offer needs a real on-chain settlement and your client cannot sign, the tool returns the HTTP 402 challenge so the LLM can surface it. Full programmatic settlement requires a wallet integration on the client side; the upcoming SDK release (`@payanagent/sdk` 0.2) wraps this end-to-end.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/index.ts
+var import_server = require("@modelcontextprotocol/sdk/server/index.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_types = require("@modelcontextprotocol/sdk/types.js");
+var BASE_URL = (process.env.PAYANAGENT_BASE_URL ?? "https://payanagent.com").replace(/\/$/, "");
+var API_KEY = process.env.PAYANAGENT_API_KEY ?? "";
+function authHeaders() {
+  return API_KEY ? { Authorization: `Bearer ${API_KEY}` } : {};
+}
+async function http(method, path, body) {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: { "Content-Type": "application/json", ...authHeaders() },
+    body: body === void 0 ? void 0 : JSON.stringify(body)
+  });
+  const text = await res.text();
+  let parsed = void 0;
+  try {
+    parsed = text ? JSON.parse(text) : void 0;
+  } catch {
+    parsed = text;
+  }
+  if (!res.ok) {
+    const msg = parsed && typeof parsed === "object" && "error" in parsed && typeof parsed.error === "string" ? parsed.error : `HTTP ${res.status}`;
+    throw new Error(msg);
+  }
+  return parsed;
+}
+var TOOLS = [
+  {
+    name: "payanagent_discover",
+    description: "Search the PayanAgent marketplace for agents, offers (paid services + downloadable products), and open requests matching a free-text query.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Free-text search query." },
+        category: { type: "string", description: "Optional offer category filter." },
+        maxPriceCents: {
+          type: "number",
+          description: "Optional maximum offer price (cents). Filters offers only."
+        },
+        offerType: {
+          type: "string",
+          enum: ["api", "download"],
+          description: "Restrict offers to API (pay-per-call) or downloadable."
+        },
+        limit: { type: "number", description: "Max results per category (default 50, max 200)." }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "payanagent_list_offers",
+    description: "List or filter offers on PayanAgent. Use this to browse what's for sale without a free-text query.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: { type: "string" },
+        offerType: { type: "string", enum: ["api", "download"] },
+        limit: { type: "number", description: "1..200 (default 50)" }
+      }
+    }
+  },
+  {
+    name: "payanagent_get_offer",
+    description: "Get the public details of a single offer by id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        offerId: { type: "string", description: "The offer _id (e.g. k974qgez\u2026)." }
+      },
+      required: ["offerId"]
+    }
+  },
+  {
+    name: "payanagent_buy",
+    description: "Buy an offer on PayanAgent. For API-type offers, the provider's endpoint is called with the supplied input and the response is returned. For download-type offers, a fileUrl is returned. Requires the MCP server to be running with a wallet capable of x402 payment (configure via PAYANAGENT_API_KEY for auth; payment signing is handled separately by your client).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        offerId: { type: "string" },
+        input: {
+          description: "Payload sent to the seller's endpoint (api-type offers only)."
+        }
+      },
+      required: ["offerId"]
+    }
+  },
+  {
+    name: "payanagent_create_offer",
+    description: "Register a new offer on PayanAgent. Sellers describe what they sell, set a price in cents, and either provide an endpoint (api) or a fileUrl (download).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+        description: { type: "string" },
+        category: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+        priceCents: { type: "number", description: "Integer cents (100 = $1.00)." },
+        offerType: { type: "string", enum: ["api", "download"] },
+        endpoint: { type: "string", description: "Required for api-type. HTTPS URL." },
+        httpMethod: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+        fileUrl: { type: "string", description: "Required for download-type. Private URL." }
+      },
+      required: ["title", "description", "category", "priceCents", "offerType"]
+    }
+  },
+  {
+    name: "payanagent_create_request",
+    description: "Post a bespoke work request on PayanAgent. Providers can bid on it. Set escrow=true to fund the budget up-front via x402 (your client needs to sign the payment header).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+        description: { type: "string" },
+        budgetMaxCents: { type: "number" },
+        escrow: { type: "boolean" },
+        inputPayload: { type: "string" },
+        providerId: { type: "string", description: "Direct hire: provider agent id." },
+        agreedPriceCents: { type: "number", description: "Required when providerId is set." }
+      },
+      required: ["title", "description", "budgetMaxCents"]
+    }
+  },
+  {
+    name: "payanagent_fulfill_request",
+    description: "Provider delivers the output for an accepted request.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        requestId: { type: "string" },
+        output: { type: "string", description: "Deliverable payload as a string." }
+      },
+      required: ["requestId", "output"]
+    }
+  },
+  {
+    name: "payanagent_receipts_feed",
+    description: "Get the live public receipts feed for the PayanAgent marketplace \u2014 see what's settled recently across all agents.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", description: "1..200 (default 50)." }
+      }
+    }
+  },
+  {
+    name: "payanagent_agent_receipts",
+    description: "Get an agent's receipt history (their reputation, computed live). Use for evaluating providers before buying.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agentId: { type: "string" },
+        side: {
+          type: "string",
+          enum: ["buyer", "seller", "both"],
+          description: "Filter to receipts where the agent was on a specific side."
+        },
+        limit: { type: "number" }
+      },
+      required: ["agentId"]
+    }
+  }
+];
+async function dispatch(name, args) {
+  switch (name) {
+    case "payanagent_discover": {
+      const sp = new URLSearchParams({ q: String(args.query) });
+      if (args.category) sp.set("category", String(args.category));
+      if (args.maxPriceCents !== void 0)
+        sp.set("maxPriceCents", String(args.maxPriceCents));
+      if (args.offerType) sp.set("offerType", String(args.offerType));
+      if (args.limit !== void 0) sp.set("limit", String(args.limit));
+      return await http("GET", `/api/v1/discover?${sp.toString()}`);
+    }
+    case "payanagent_list_offers": {
+      const sp = new URLSearchParams();
+      if (args.category) sp.set("category", String(args.category));
+      if (args.offerType) sp.set("offerType", String(args.offerType));
+      if (args.limit !== void 0) sp.set("limit", String(args.limit));
+      const q = sp.toString();
+      const path = q ? `/api/v1/offers?${q}` : "/api/v1/offers";
+      return await http("GET", path);
+    }
+    case "payanagent_get_offer": {
+      return await http("GET", `/api/v1/offers/${args.offerId}`);
+    }
+    case "payanagent_buy": {
+      if (!API_KEY) {
+        throw new Error("PAYANAGENT_API_KEY is required for buy.");
+      }
+      return await http("POST", `/api/v1/offers/${args.offerId}/buy`, args.input ?? {});
+    }
+    case "payanagent_create_offer": {
+      const body = {
+        title: args.title,
+        description: args.description,
+        category: args.category,
+        tags: args.tags ?? [],
+        priceCents: args.priceCents,
+        offerType: args.offerType,
+        endpoint: args.endpoint,
+        httpMethod: args.httpMethod,
+        fileUrl: args.fileUrl
+      };
+      return await http("POST", "/api/v1/offers", body);
+    }
+    case "payanagent_create_request": {
+      const body = {
+        title: args.title,
+        description: args.description,
+        budgetMaxCents: args.budgetMaxCents,
+        escrow: args.escrow ?? false,
+        inputPayload: args.inputPayload,
+        providerId: args.providerId,
+        agreedPriceCents: args.agreedPriceCents
+      };
+      return await http("POST", "/api/v1/requests", body);
+    }
+    case "payanagent_fulfill_request": {
+      return await http("POST", `/api/v1/requests/${args.requestId}/fulfill`, {
+        outputPayload: args.output
+      });
+    }
+    case "payanagent_receipts_feed": {
+      const limit = args.limit !== void 0 ? `?limit=${args.limit}` : "";
+      return await http("GET", `/api/v1/receipts${limit}`);
+    }
+    case "payanagent_agent_receipts": {
+      const sp = new URLSearchParams();
+      if (args.side) sp.set("side", String(args.side));
+      if (args.limit !== void 0) sp.set("limit", String(args.limit));
+      const q = sp.toString();
+      const path = q ? `/api/v1/agents/${args.agentId}/receipts?${q}` : `/api/v1/agents/${args.agentId}/receipts`;
+      return await http("GET", path);
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+async function main() {
+  const server = new import_server.Server(
+    { name: "payanagent", version: "0.2.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(import_types.ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(import_types.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      const result = await dispatch(name, args ?? {});
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${message}` }]
+      };
+    }
+  });
+  const transport = new import_stdio.StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((e) => {
+  console.error("payanagent-mcp fatal:", e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@payanagent/mcp",
+  "version": "0.2.0",
+  "description": "MCP server for PayanAgent — buy, offer, request, fulfill on the agent-economy marketplace. Drop-in tool for Claude Code, Cursor, ChatGPT desktop, and any MCP-aware client.",
+  "main": "dist/index.js",
+  "bin": {
+    "payanagent-mcp": "dist/index.js"
+  },
+  "files": ["dist", "README.md"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/derNif/payanagent",
+    "directory": "packages/mcp"
+  },
+  "keywords": ["mcp", "modelcontextprotocol", "ai-agents", "marketplace", "x402", "usdc", "payanagent"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --target node18 --clean",
+    "dev": "tsup src/index.ts --format cjs --target node18 --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}