arc-market-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BABA Capital
+
+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,118 @@
+# Arc Market MCP
+
+An [MCP](https://modelcontextprotocol.io) server that reads **live market state on Arc** — Circle's L1
+(chainId `5042`) — through the BABA Capital Arc Data API.
+
+Circle publishes an Arc MCP, but it serves **documentation**. This one reads **chain state**:
+
+- **`arc_launchpads`** — launchpad concentration (HHI), pools created, v3 vs v4 launch counts, distinct
+  deployer callers, and per-launchpad share / graduations / dead-on-arrival.
+- **`arc_lp_apr`** — realised range-APR for LP pools from the latest scan (filter by pair / venue / range).
+- **`arc_rpc_consensus`** — how many of Arc's four public RPCs agree this block, before you trust a figure.
+- **`arc_token_screen`** — cheap gate on a launched token: its USDC pool, fee, swap count, decoy verdict.
+- **`arc_token_sellsim`** — a **live honeypot test**: buy-then-sell simulated against current chain state,
+  reporting the round-trip fraction recovered. Not a heuristic — an actual simulation.
+- **`arc_pool_decoy`** — is this v4 poolId the real venue for its token, or a high-fee decoy?
+- **`arc_rpc_consensus`**, **`arc_health`**, **`arc_agent_card`** — trust, liveness, and identity.
+
+### Agent Directory — who is actually on Arc
+
+~137 agents are registered in the ERC-8004 registry on Arc and nothing else lets you see who they
+are. Circle builds the rails; this is the phone book.
+
+- **`arc_agents_list`** — every registered agent: agentId, owner, agentURI, host, name, skills,
+  validation status, and how concentrated its host and owner are.
+- **`arc_agent_get`** — one agent in full, including the **raw card as served** and a validation
+  report giving the evidence for every flag, so you can check the directory rather than trust it.
+- **`arc_agents_search`** — *"find me an Arc agent that does X and that I can pay."*
+- **`arc_agents_stats`** — the registry's shape in one call.
+
+Two things worth knowing, both measured rather than assumed:
+
+- **`x402=true` is much narrower than `payment=true`.** Most of this registry prices in USDC via
+  ERC-8183 settlement, which is *not* x402. Each match carries the exact key and value that prove it.
+- **The registry is extremely concentrated.** One host holds **115 of 137 ids (83.9%)** and one owner
+  holds 100 (73%). The directory publishes those counts and lets you draw the conclusion — it attaches
+  no label or rating to any agent, because a directory that editorialises is worth nothing.
+
+A card that will not resolve is listed as `UNRESOLVED`, never quietly dropped; a partial crawl comes
+back `NO_DATA` with `coverage` naming the ids it could not reach. **BABA Capital operates agentIds 135
+and 136**; they are listed on the same terms as everyone else and get no ranking advantage.
+
+## Honesty model (read this)
+
+Every data route returns one envelope:
+
+```json
+{ "chain": "arc", "chainId": 5042, "asof": "…", "head": 123, "status": "OK|NO_DATA|REFUSED",
+  "coverage": {…}, "rpc_consensus": true, "data": {…}, "warnings": [], "source": "…", "version": "…" }
+```
+
+- **`NO_DATA` is never a zero.** A missing or partial reading returns `status: "NO_DATA"`, not an
+  empty success. Absence of a signal is stated, never disguised as a value of the signal.
+- **`REFUSED`** means the API declined (e.g. fewer than 2 of 4 RPCs agreed). The reading was not cross-checked; weigh it accordingly.
+- This server passes the envelope through **unchanged**. It never unwraps `data` and hides the status.
+
+This is a **read-only** client. It holds no private key, signs nothing, and moves no funds.
+This is a software tool that reports chain reads. A passing sell-simulation is a snapshot at one block, not a guarantee.
+
+## Install
+
+Runs over stdio via `npx` — no global install needed.
+
+```bash
+npx arc-market-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "arc-market": {
+      "command": "npx",
+      "args": ["-y", "arc-market-mcp"]
+    }
+  }
+}
+```
+
+### Configuration
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `ARC_API_BASE` | `https://api.babacapital.app` | Base for the `/arc/*` routes. |
+| `ARC_AGENT_CARD_BASE` | `https://babacapital.app` | Base for `/.well-known/agents/<name>.json`. |
+| `ARC_API_TIMEOUT_MS` | `20000` | Per-request timeout (the sellsim route runs a live simulation). |
+
+## Pricing
+
+The Arc Data API's **free tier is 20 calls/day/IP**. Paid calls settle in **USDC over Circle Gateway
+x402** on Arc (`eip155:5042`). This package is the reader; payment, when required, is negotiated by the
+API's `402` response. The reader never holds funds or keys.
+
+## Identity (ERC-8004)
+
+BABA Capital's Arc agents publish [ERC-8004](https://eips.ethereum.org/) agent-cards at
+`https://babacapital.app/.well-known/agents/` — `baba-arc-data` and `baba-arc-yield`. Fetch one with
+`arc_agent_card`. `agentId` is `null` until on-chain registration completes.
+
+## Build from source
+
+```bash
+npm install
+npm run build
+npm test
+node dist/index.js
+```
+
+## Provenance
+
+This repository is standalone. Its git history begins on **2026-09-17**; it shares no history with any
+other BABA Capital repository.
+
+## License
+
+MIT © 2026 BABA Capital

package/dist/arc.js

@@ -0,0 +1,84 @@
+/**
+ * Thin, honest client for the BABA Capital Arc Data API (the `/arc/*` routes).
+ *
+ * Two rules carried from the API's own doctrine and preserved here verbatim:
+ *   1. Every `/arc` route returns the §3.5 envelope
+ *      { chain, chainId, asof, head, status, coverage, rpc_consensus, data, warnings, source, version }.
+ *      This client passes that envelope through UNCHANGED. It never unwraps `data` and presents it as
+ *      the whole answer, because a caller must be able to see `status` and `coverage`.
+ *   2. NO_DATA is never silently turned into a zero or an empty success. A NO_DATA envelope, a network
+ *      failure, and a non-200 are three distinct, visible outcomes — none is dressed up as data.
+ *
+ * This client holds no keys. The Arc Data API's free tier is 20 calls/day/IP; paid calls settle in
+ * USDC over Gateway x402 (chainId 5042). Reading is free within the tier; this package never signs.
+ */
+/** Where the `/arc/*` routes live. Override with ARC_API_BASE for staging or a self-host. */
+export const ARC_API_BASE = (process.env.ARC_API_BASE || "https://api.babacapital.app").replace(/\/+$/, "");
+/** Where the ERC-8004 agent-cards live (`/.well-known/agents/<name>.json`). Usually the site apex. */
+export const AGENT_CARD_BASE = (process.env.ARC_AGENT_CARD_BASE || "https://babacapital.app").replace(/\/+$/, "");
+/** Per-request ceiling. The heavy routes (sellsim) run a live simulation server-side. */
+const TIMEOUT_MS = Number(process.env.ARC_API_TIMEOUT_MS || 20000);
+const UA = "arc-market-mcp/0.1.0 (+https://babacapital.app)";
+async function getJson(url) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { accept: "application/json", "user-agent": UA },
+            signal: ctrl.signal,
+        });
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // A non-JSON body is a failure to be shown, not data to be guessed at.
+            return { ok: false, httpStatus: res.status, body: null, url,
+                error: `non-JSON response (${res.status}): ${text.slice(0, 200)}` };
+        }
+        return { ok: res.ok, httpStatus: res.status, body, url };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? (e.name === "AbortError" ? `timeout after ${TIMEOUT_MS}ms` : e.message) : String(e);
+        return { ok: false, httpStatus: 0, body: null, url, error: msg };
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+function qs(params) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null && `${v}`.length > 0)
+            p.set(k, `${v}`);
+    }
+    const s = p.toString();
+    return s ? `?${s}` : "";
+}
+/** A launched-token contract address, loosely validated before it ever reaches the network. */
+export function isAddress(x) {
+    return /^0x[0-9a-fA-F]{40}$/.test(x.trim());
+}
+/** A v4 poolId is a bytes32. */
+export function isPoolId(x) {
+    return /^0x[0-9a-fA-F]{64}$/.test(x.trim());
+}
+export const arc = {
+    health: () => getJson(`${ARC_API_BASE}/arc/health`),
+    launchpads: () => getJson(`${ARC_API_BASE}/arc/launchpads`),
+    lpApr: (o = {}) => getJson(`${ARC_API_BASE}/arc/pools/lp-apr${qs(o)}`),
+    rpcConsensus: () => getJson(`${ARC_API_BASE}/arc/rpc/consensus`),
+    tokenScreen: (ca) => getJson(`${ARC_API_BASE}/arc/token/${ca}/screen`),
+    tokenSellsim: (ca) => getJson(`${ARC_API_BASE}/arc/token/${ca}/sellsim`),
+    poolDecoy: (poolId) => getJson(`${ARC_API_BASE}/arc/pools/${poolId}/decoy`),
+    agentCard: (name) => getJson(`${AGENT_CARD_BASE}/.well-known/agents/${name}.json`),
+    // ── Arc Agent Directory ────────────────────────────────────────────────────────────────────────
+    // ~137 agents are registered in the ERC-8004 registry on Arc and nothing else lets you see who
+    // they are. These read a validated hourly crawl: facts and their evidence, never a verdict.
+    agentsList: (o = {}) => getJson(`${ARC_API_BASE}/arc/agents${qs(o)}`),
+    agentGet: (agentId) => getJson(`${ARC_API_BASE}/arc/agents/${agentId}`),
+    agentsSearch: (o = {}) => getJson(`${ARC_API_BASE}/arc/agents/search${qs(o)}`),
+    agentsStats: () => getJson(`${ARC_API_BASE}/arc/agents/stats`),
+};

package/dist/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Arc Market MCP — read live Arc (chainId 5042) market state through the BABA Capital Arc Data API.
+ *
+ * Circle ships an Arc MCP, but it serves documentation. This one reads chain state: which launchpads
+ * are concentrating flow, what an LP range actually yielded, whether Arc's RPCs agree this block, and
+ * whether a freshly launched token is a honeypot (a live sell-simulation, not a heuristic).
+ *
+ * It is a stateless HTTP client of a public API. It holds no private key, signs nothing, and moves no
+ * funds. Paid calls settle in USDC over Gateway x402; the free tier is 20 calls/day/IP.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { arc, isAddress, isPoolId, ARC_API_BASE } from "./arc.js";
+/**
+ * Turn an ArcResult into MCP content WITHOUT laundering its meaning. Three outcomes stay three:
+ *   - transport failure  -> isError, the reason shown
+ *   - NO_DATA / REFUSED  -> not an error, but the status is stated first so it can't be mistaken for data
+ *   - OK                 -> the full §3.5 envelope, so status/coverage/warnings travel with the data
+ */
+function present(r) {
+    if (r.error) {
+        return { isError: true, content: [{ type: "text",
+                    text: `REQUEST FAILED (${r.url})\n${r.error}\n\nThis is a transport failure, not a market signal. Nothing about Arc is implied.` }] };
+    }
+    const body = r.body;
+    const status = body && typeof body === "object" ? body["status"] : undefined;
+    const pretty = JSON.stringify(body, null, 2);
+    if (r.httpStatus >= 400 && status !== "NO_DATA") {
+        return { isError: true, content: [{ type: "text", text: `HTTP ${r.httpStatus} from ${r.url}\n${pretty}` }] };
+    }
+    let header = "";
+    if (status === "NO_DATA")
+        header = "STATUS: NO_DATA — the API has no complete reading to return. This is not zero and not an error; do not treat absence as a value.\n\n";
+    else if (status === "REFUSED")
+        header = "STATUS: REFUSED — the API declined to answer (e.g. RPCs did not agree). The reading was not cross-checked.\n\n";
+    return { content: [{ type: "text", text: header + pretty }] };
+}
+const server = new McpServer({ name: "arc-market-mcp", version: "0.1.0" });
+server.tool("arc_health", "Liveness of the Arc Data API and the list of routes it serves. Returns the §3.5 envelope. Call this first to confirm the API base and see which live routes are wired.", {}, async () => present(await arc.health()));
+server.tool("arc_launchpads", "Launchpad concentration on Arc over the recent window: HHI, pools created, v3 vs v4 launch counts, distinct deployer callers, and per-launchpad share/graduations/dead-on-arrival. NO_DATA until an hourly reading has been written; partial windows are NO_DATA, never a false zero.", {}, async () => present(await arc.launchpads()));
+server.tool("arc_lp_apr", "Realised range-APR for Arc LP pools from the latest scan. Optional filters: pair (e.g. 'usdc/weth'), venue (e.g. 'aero-lite'), range_pct. APR assumes price stayed in range over the window; the warning states this. NO_DATA if no scan has been written.", {
+    pair: z.string().optional().describe("Filter by pair, case-insensitive, e.g. 'usdc/weth'."),
+    venue: z.string().optional().describe("Filter by venue, case-insensitive, e.g. 'aero-lite'."),
+    range_pct: z.number().optional().describe("Filter to rows computed at this range width in percent."),
+}, async ({ pair, venue, range_pct }) => present(await arc.lpApr({ pair, venue, range_pct })));
+server.tool("arc_rpc_consensus", "How many of Arc's four public RPCs agreed at the last reading (of 4), and the head they agreed on. Below 2 the status is REFUSED — treat any Arc figure as not cross-checked until they agree again. A cheap trust gate before acting on other Arc data.", {}, async () => present(await arc.rpcConsensus()));
+server.tool("arc_token_screen", "Screen a launched Arc token by contract address: its USDC-paired pool, fee, recent swap count, and the decoy-pool verdict (a fee above the cap, or a dynamic pool whose swaps charged above the cap, is refused). A cheap gate — it does NOT run a live buy/sell. NO_DATA if the token has not traded in the API's discovery window.", { ca: z.string().describe("The token contract address (0x…40 hex).") }, async ({ ca }) => {
+    if (!isAddress(ca))
+        return { isError: true, content: [{ type: "text", text: `'${ca}' is not a contract address (expected 0x + 40 hex).` }] };
+    return present(await arc.tokenScreen(ca.trim()));
+});
+server.tool("arc_token_sellsim", "Honeypot test for an Arc token: a LIVE sell-simulation (buy then sell in one simulated transaction against current chain state) reporting the round-trip fraction recovered. Below ~0.9 the token is likely a honeypot or a punitive-tax trap. This is a heavy, paid-tier route. NO_DATA if the pool cannot be simulated (it is never scored zero on a failed simulation).", { ca: z.string().describe("The token contract address (0x…40 hex).") }, async ({ ca }) => {
+    if (!isAddress(ca))
+        return { isError: true, content: [{ type: "text", text: `'${ca}' is not a contract address (expected 0x + 40 hex).` }] };
+    return present(await arc.tokenSellsim(ca.trim()));
+});
+server.tool("arc_pool_decoy", "Decoy-pool verdict for a specific v4 poolId: whether this pool is the real venue for its token or a high-fee decoy that a naive buyer would route into. Explains the refusal reason. NO_DATA if the poolId is unknown to the API.", { poolId: z.string().describe("The v4 poolId (bytes32, 0x…64 hex).") }, async ({ poolId }) => {
+    if (!isPoolId(poolId))
+        return { isError: true, content: [{ type: "text", text: `'${poolId}' is not a poolId (expected 0x + 64 hex).` }] };
+    return present(await arc.poolDecoy(poolId.trim()));
+});
+server.tool("arc_agent_card", "Fetch a BABA Capital ERC-8004 agent-card (the /.well-known/agents/<name>.json identity document). Known names: 'baba-arc-data', 'baba-arc-yield'. Shows the agent's registry, agentId (null until registered), and x402 payment network.", { name: z.enum(["baba-arc-data", "baba-arc-yield"]).describe("Which agent-card to fetch.") }, async ({ name }) => present(await arc.agentCard(name)));
+// ── Arc Agent Directory ──────────────────────────────────────────────────────────────────────────
+// Discovery is the unclaimed position on Arc: Circle ships the rails, and nobody ships the phone
+// book. These tools answer "who is actually on this chain, and which of them can I pay?"
+server.tool("arc_agents_list", "List the ERC-8004 agents registered on Arc, from a validated hourly crawl. Each row carries agentId, owner, agentURI, host, name, skills, status (OK | UNRESOLVED | INVALID), whether it declares x402, and how concentrated its host and owner are. Optional filters: status, host, owner. Paged. An agent whose card will not resolve is listed as UNRESOLVED, never silently dropped.", {
+    status: z.enum(["OK", "UNRESOLVED", "INVALID", "SKIPPED_ROBOTS"]).optional()
+        .describe("Only agents with this validation status."),
+    host: z.string().optional().describe("Only agents whose agentURI is on this host, e.g. 'stubly.org'."),
+    owner: z.string().optional().describe("Only agents owned by this address."),
+    limit: z.number().optional().describe("Page size (default 50, max 200)."),
+    offset: z.number().optional().describe("Page offset."),
+}, async (o) => present(await arc.agentsList(o)));
+server.tool("arc_agent_get", "Full record for one Arc agent by agentId: its on-chain owner and agentURI, the RAW card as served, and a validation report showing the evidence behind every flag (which key supplied the name, which supplied the skills, the exact key and value that prove an x402 or payment declaration, redirects, robots handling, and any fetch error). Use this to check the directory's claims yourself rather than trusting them.", { agentId: z.number().int().min(0).describe("The ERC-8004 agentId (an ERC-721 tokenId on the registry).") }, async ({ agentId }) => present(await arc.agentGet(agentId)));
+server.tool("arc_agents_search", "Find an Arc agent that does something, and optionally one you can pay. `q` matches name, host and skills; `skill` matches skill ids/names/tags. IMPORTANT: `x402=true` means the card declares x402 SPECIFICALLY — it is a much smaller set than `payment=true`, which includes other settlement schemes (most of this registry prices in USDC via ERC-8183, which is not x402). `resolvable=true` restricts to agents whose card actually fetched.", {
+    q: z.string().optional().describe("Free text over name, host and skills, e.g. 'translate'."),
+    skill: z.string().optional().describe("Match a skill id, name or tag."),
+    x402: z.enum(["true", "false"]).optional().describe("Declares x402 specifically."),
+    payment: z.enum(["true", "false"]).optional().describe("Declares any payment/pricing/settlement."),
+    resolvable: z.enum(["true", "false"]).optional().describe("Card actually resolved on the last crawl."),
+    limit: z.number().optional().describe("Page size (default 50, max 200)."),
+    offset: z.number().optional().describe("Page offset."),
+}, async (o) => present(await arc.agentsSearch(o)));
+server.tool("arc_agents_stats", "Shape of Arc's ERC-8004 agent registry in one call: total ids, distinct owners, distinct hosts, how many resolve, how many declare x402 vs payment generally, status counts, and the most concentrated hosts and owners with their share of the registry. Facts only — the concentration numbers are stated so you can draw your own conclusion.", {}, async () => present(await arc.agentsStats()));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is the MCP transport and must carry nothing but protocol frames.
+    process.stderr.write(`arc-market-mcp connected (API base: ${ARC_API_BASE})\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`fatal: ${e instanceof Error ? e.stack || e.message : String(e)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "arc-market-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Arc (Circle's L1, chainId 5042). Reads live chain state: the ERC-8004 agent directory with every card fetched and checked, launchpad concentration, LP range-APR, RPC consensus, and sell simulation. Circle's own Arc MCP is docs-only; this one reads the chain.",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "arc",
+    "circle",
+    "erc-8004",
+    "x402",
+    "defi",
+    "onchain",
+    "launchpad",
+    "honeypot",
+    "agent-directory",
+    "agents"
+  ],
+  "license": "MIT",
+  "author": "BABA Capital",
+  "type": "module",
+  "bin": {
+    "arc-market-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "start": "node dist/index.js",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "@types/node": "^20.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/babaanalytix-commits/arc-market-mcp.git"
+  },
+  "homepage": "https://babacapital.app"
+}