MCP sellers and agents

npm install @modelcontextprotocol/sdk@^1.15.1 \
  @openx402/bazaar-sdk \
  @x402/core@2.20.0 \
  @x402/mcp@2.20.0 \
  express zod zod-to-json-schema

import { randomUUID } from "node:crypto";
import express from "express";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { x402ResourceServer } from "@x402/core/server";
import { HTTPFacilitatorClient } from "@x402/core/http";
import type { PaymentRequirements } from "@x402/core/types";
import { createPaymentWrapper } from "@x402/mcp";
import { bazaar } from "@openx402/bazaar-sdk";

const TOOL_NAME = "sentiment_analysis";
const PORT = Number(process.env.PORT ?? 4711);
const FACILITATOR_URL = process.env.FACILITATOR_URL ?? "http://localhost:4022";
const NETWORK = (process.env.SELLER_NETWORK ?? "stellar:testnet") as
  "stellar:testnet" | "stellar:pubnet";
const ASSET = process.env.SELLER_ASSET ?? "";
const PAY_TO = process.env.SELLER_PAY_TO ?? "";
const AMOUNT = process.env.SELLER_AMOUNT ?? "10000";

if (!ASSET || !PAY_TO) {
  throw new Error("SELLER_ASSET and SELLER_PAY_TO are required");
}

const inputShape = {
  text: z.string().min(1).max(2_000).describe("Text to analyze."),
};
const inputSchema = z.object(inputShape);
const inputJsonSchema = zodToJsonSchema(inputSchema, {
  name: undefined,
  $refStrategy: "none",
}) as Record<string, unknown>;

const positiveWords = ["great", "good", "excellent", "love", "amazing", "happy", "positive"];
const negativeWords = ["bad", "terrible", "hate", "awful", "sad", "negative", "poor"];

function score(text: string) {
  const words = text.toLowerCase().split(/\W+/).filter(Boolean);
  const value = words.filter(word => positiveWords.includes(word)).length
    - words.filter(word => negativeWords.includes(word)).length;
  return {
    label: value > 0 ? "positive" : value < 0 ? "negative" : "neutral",
    score: value,
  };
}

const accepts: PaymentRequirements[] = [{
  scheme: "exact",
  network: NETWORK,
  asset: ASSET,
  amount: AMOUNT,
  payTo: PAY_TO,
  maxTimeoutSeconds: 60,
  extra: { areFeesSponsored: true },
}];

const metadata = bazaar.mcp({
  toolName: TOOL_NAME,
  description: "Deterministic keyword-based sentiment analysis of a short text.",
  transport: "streamable-http",
  serviceName: "Example Sentiment Tool",
  tags: ["nlp", "sentiment", "example"],
  inputSchema: inputJsonSchema,
  example: { text: "This is a great day" },
  output: { type: "json", example: { label: "positive", score: 1 } },
});

const resourceServer = new x402ResourceServer(
  new HTTPFacilitatorClient({ url: FACILITATOR_URL }),
);
const paid = createPaymentWrapper(resourceServer, {
  accepts,
  resource: {
    url: process.env.SELLER_PUBLIC_URL ?? `http://localhost:${PORT}/mcp`,
    ...metadata.resource,
  },
  extensions: metadata.extensions,
});

function buildServer(): McpServer {
  const server = new McpServer(
    { name: "openx402-example-seller", version: "0.1.0" },
    { capabilities: { tools: {} } },
  );
  server.tool(
    TOOL_NAME,
    "Deterministic keyword-based sentiment analysis of a short text. Paid via x402.",
    inputShape,
    paid(async args => ({
      content: [{ type: "text", text: JSON.stringify(score(args.text)) }],
    })),
  );
  return server;
}

const app = express();
app.use(express.json());
const transports = new Map<string, StreamableHTTPServerTransport>();

app.post("/mcp", async (req, res) => {
  const sessionId = req.headers["mcp-session-id"];
  const existing = typeof sessionId === "string" ? transports.get(sessionId) : undefined;
  if (existing) {
    await existing.handleRequest(req, res, req.body);
    return;
  }

  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => randomUUID(),
    onsessioninitialized: id => { transports.set(id, transport); },
    onsessionclosed: id => { transports.delete(id); },
  });
  const server = buildServer();
  await server.connect(transport as Parameters<typeof server.connect>[0]);
  await transport.handleRequest(req, res, req.body);
});

app.listen(PORT, () => {
  console.log(`example seller listening on :${PORT}, tool=${TOOL_NAME}`);
});

FACILITATOR_URL=https://facilitator-production-8430.up.railway.app \
SELLER_NETWORK=stellar:testnet \
SELLER_ASSET=C... \
SELLER_PAY_TO=G... \
SELLER_AMOUNT=10000 \
SELLER_PUBLIC_URL=https://your-seller.example/mcp \
npm start

{
  "mcpServers": {
    "openx402": {
      "url": "https://mcp-production-e242.up.railway.app/mcp"
    }
  }
}

{
  "query": "weather API",
  "type": "http",
  "network": "stellar:testnet",
  "scheme": "exact",
  "limit": 10
}

{
  "ref": "<ref returned by x402_search_resources>",
  "expectedVersionHash": "<versionHash returned by search>"
}

{
  "ref": "v1....",
  "expectedVersionHash": "...",
  "arguments": {
    "text": "This is a great day"
  },
  "network": "stellar:testnet",
  "scheme": "exact",
  "asset": "C...",
  "maxAtomicAmount": "1000000"
}

resolve stable ref against active catalog
-> connect to the cataloged MCP endpoint
-> call once without payment
-> validate both PaymentRequired copies
-> compare live URL, tool, schema, transport, and selected terms to catalog
-> reserve the local budget
-> create one payment identifier and signed payload
-> retry the same tool once with payment
-> validate the settlement response
-> return paid content plus an openx402 receipt

{
  "schemaVersion": 1,
  "code": "RESOURCE_STALE",
  "message": "human-readable text may change",
  "retryable": true,
  "details": {}
}