arcid-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArcID
+
+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,62 @@
+# arcid-mcp
+
+[MCP](https://modelcontextprotocol.io) server for **ArcID**, the identity and reputation layer for AI agents on
+[Arc](https://arc.network). It lets Claude and other MCP clients look up agents registered in the
+**ERC-8004** registries: profiles, owners, feedback, validations and USDC-weighted trust scores.
+
+Read-only. No wallet or API key needed.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_agents` | Full-text search, owner filter, sort by `newest` / `score` / `feedback` / `settled` / `relevance` |
+| `get_agent` | Full record: profile, reputation, validations, trust score, settlement evidence |
+| `get_agent_feedback` | Reputation Registry feedback, newest first, classified and normalised |
+| `get_agent_validations` | Latest 100 Validation Registry entries |
+| `get_registry_stats` | Index totals |
+| `get_indexer_health` | How far the indexer is behind the chain head |
+
+## Install
+
+No install step needed; clients run it with `npx`.
+
+### Claude Code
+
+```bash
+claude mcp add arcid -- npx -y arcid-mcp
+```
+
+### Claude Desktop / Cursor / other clients
+
+```json
+{
+  "mcpServers": {
+    "arcid": {
+      "command": "npx",
+      "args": ["-y", "arcid-mcp"]
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `ARCID_API_URL` | `https://api.arcusid.com` | ArcID indexer API. Use `http://127.0.0.1:4000` for a local indexer |
+| `ARCID_TIMEOUT_MS` | `10000` | Per-request timeout, 1000 to 60000 |
+
+## Development
+
+```bash
+git clone https://github.com/arcusid/arcid-mcp.git && cd arcid-mcp && npm install
+npm run dev            # run from source (tsx)
+npm test               # vitest
+npm run test:coverage  # 80% threshold enforced
+npm run inspect        # MCP Inspector against dist/
+```
+
+## License
+
+MIT

package/dist/client.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+// Every ArcID endpoint answers with this envelope.
+const envelope = z.object({
+    success: z.boolean(),
+    data: z.unknown(),
+    error: z.string().nullable(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+export class ArcIdApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "ArcIdApiError";
+    }
+}
+export function createClient(config, fetchImpl = fetch) {
+    async function get(path, query = {}) {
+        const url = new URL(config.apiUrl + path);
+        for (const [k, v] of Object.entries(query))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        let res;
+        try {
+            res = await fetchImpl(url, {
+                headers: { accept: "application/json", "user-agent": "arcid-mcp" },
+                signal: AbortSignal.timeout(config.timeoutMs),
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error && err.name === "TimeoutError" ? `timed out after ${config.timeoutMs} ms` : "network error";
+            throw new ArcIdApiError(`ArcID API unreachable (${reason})`);
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new ArcIdApiError(`ArcID API returned a non-JSON response (HTTP ${res.status})`, res.status);
+        }
+        const parsed = envelope.safeParse(body);
+        if (!parsed.success)
+            throw new ArcIdApiError(`ArcID API returned an unexpected payload (HTTP ${res.status})`, res.status);
+        if (!res.ok || !parsed.data.success) {
+            throw new ArcIdApiError(parsed.data.error ?? `ArcID API error (HTTP ${res.status})`, res.status);
+        }
+        return { data: parsed.data.data, ...(parsed.data.meta ? { meta: parsed.data.meta } : {}) };
+    }
+    return Object.freeze({
+        health: () => get("/health"),
+        stats: () => get("/v1/stats"),
+        listAgents: (p) => get("/v1/agents", { ...p }),
+        getAgent: (id) => get(`/v1/agents/${id}`),
+        listFeedback: (id, page, limit) => get(`/v1/agents/${id}/feedback`, { page, limit }),
+        listValidations: (id) => get(`/v1/agents/${id}/validations`),
+    });
+}

package/dist/config.js

@@ -0,0 +1,25 @@
+export const DEFAULT_API_URL = "https://api.arcusid.com";
+export const DEFAULT_TIMEOUT_MS = 10_000;
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 60_000;
+// Reads ARCID_API_URL / ARCID_TIMEOUT_MS. Fails fast on bad values so a misconfigured
+// client sees the problem at startup instead of on the first tool call.
+export function loadConfig(env = process.env) {
+    const raw = env.ARCID_API_URL?.trim() || DEFAULT_API_URL;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`ARCID_API_URL is not a valid URL: ${raw}`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`ARCID_API_URL must be http(s), got ${url.protocol}`);
+    }
+    const timeoutRaw = env.ARCID_TIMEOUT_MS?.trim();
+    const timeoutMs = timeoutRaw ? Number(timeoutRaw) : DEFAULT_TIMEOUT_MS;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < MIN_TIMEOUT_MS || timeoutMs > MAX_TIMEOUT_MS) {
+        throw new Error(`ARCID_TIMEOUT_MS must be an integer between ${MIN_TIMEOUT_MS} and ${MAX_TIMEOUT_MS}`);
+    }
+    return Object.freeze({ apiUrl: url.origin + url.pathname.replace(/\/+$/, ""), timeoutMs });
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createClient } from "./client.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    const config = loadConfig();
+    const server = createServer(createClient(config));
+    await server.connect(new StdioServerTransport());
+    // stdout carries the MCP protocol, so logs go to stderr.
+    console.error(`[arcid-mcp] ready, API ${config.apiUrl}`);
+}
+main().catch((err) => {
+    console.error("[arcid-mcp] failed to start:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,13 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+export const SERVER_NAME = "arcid";
+export const SERVER_VERSION = "0.1.0";
+export function createServer(client) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        instructions: "ArcID indexes AI agent identities and reputation from the ERC-8004 registries on Arc. " +
+            "Use search_agents to find agents, then get_agent for the full record. If results are empty, " +
+            "call get_indexer_health: the indexer may still be catching up with the chain.",
+    });
+    registerTools(server, client);
+    return server;
+}

package/dist/tools.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { ArcIdApiError } from "./client.js";
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const agentId = z.number().int().min(0).max(999_999_999_999_999).describe("ERC-8004 agent ID (token ID in the Identity Registry)");
+const page = z.number().int().min(1).max(10_000).optional().describe("Page number, starting at 1");
+const limit = z.number().int().min(1).max(100).optional();
+export function toResult(result) {
+    const payload = result.meta ? { data: result.data, meta: result.meta } : { data: result.data };
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+export function toError(err) {
+    const message = err instanceof ArcIdApiError ? err.message : "Unexpected error while calling the ArcID API";
+    if (!(err instanceof ArcIdApiError))
+        console.error("[arcid-mcp]", err);
+    return { isError: true, content: [{ type: "text", text: message }] };
+}
+async function run(call) {
+    try {
+        return toResult(await call());
+    }
+    catch (err) {
+        return toError(err);
+    }
+}
+export function registerTools(server, client) {
+    server.registerTool("search_agents", {
+        title: "Search agents",
+        description: "Search the ArcID directory of AI agents registered on Arc (ERC-8004). Supports full-text search over names and " +
+            "descriptions, filtering by owner address, and sorting by trust score, feedback count or settled USDC.",
+        inputSchema: {
+            query: z.string().trim().max(120).optional().describe("Full-text search (prefix match on words)"),
+            owner: z.string().regex(/^0x[0-9a-fA-F]{40}$/, "owner must be a 0x address").optional().describe("Owner wallet address"),
+            readable_only: z.boolean().optional().describe("Only agents whose profile could be parsed"),
+            sort: z.enum(["newest", "score", "feedback", "settled", "relevance"]).optional()
+                .describe("Default: relevance when a query is given, otherwise newest"),
+            page,
+            limit: limit.describe("Results per page, 1-100 (default 24)"),
+        },
+        annotations: { title: "Search agents", ...READ_ONLY },
+    }, ({ query, owner, readable_only, sort, page, limit }) => run(() => client.listAgents({ q: query, owner, readable: readable_only, sort, page, limit })));
+    server.registerTool("get_agent", {
+        title: "Get agent",
+        description: "Full ArcID record for one agent: profile, owner, agent wallet, reputation summary, validations, trust score " +
+            "and the USDC settlement evidence behind it.",
+        inputSchema: { agent_id: agentId },
+        annotations: { title: "Get agent", ...READ_ONLY },
+    }, ({ agent_id }) => run(() => client.getAgent(agent_id)));
+    server.registerTool("get_agent_feedback", {
+        title: "Get agent feedback",
+        description: "Feedback left for an agent in the ERC-8004 Reputation Registry, newest first. Each entry is classified " +
+            "(receipt, rating, metric, self, revoked) with a normalised 0-100 rating where applicable.",
+        inputSchema: { agent_id: agentId, page, limit: limit.describe("Results per page, 1-100 (default 50)") },
+        annotations: { title: "Get agent feedback", ...READ_ONLY },
+    }, ({ agent_id, page, limit }) => run(() => client.listFeedback(agent_id, page, limit)));
+    server.registerTool("get_agent_validations", {
+        title: "Get agent validations",
+        description: "The latest 100 validation requests and responses for an agent from the ERC-8004 Validation Registry.",
+        inputSchema: { agent_id: agentId },
+        annotations: { title: "Get agent validations", ...READ_ONLY },
+    }, ({ agent_id }) => run(() => client.listValidations(agent_id)));
+    server.registerTool("get_registry_stats", {
+        title: "Get registry stats",
+        description: "Totals across the ArcID index: agents, owners, feedback, validations and settled USDC.",
+        annotations: { title: "Get registry stats", ...READ_ONLY },
+    }, () => run(() => client.stats()));
+    server.registerTool("get_indexer_health", {
+        title: "Get indexer health",
+        description: "How far the ArcID indexer is behind the Arc chain head. Check this when results look empty or stale.",
+        annotations: { title: "Get indexer health", ...READ_ONLY },
+    }, () => run(() => client.health()));
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "arcid-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ArcID: look up AI agent identity and reputation (ERC-8004) on Arc",
+  "type": "module",
+  "bin": {
+    "arcid-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "arc",
+    "erc-8004",
+    "ai-agents",
+    "reputation"
+  ],
+  "author": "arcusid",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcusid/arcid-mcp.git"
+  },
+  "homepage": "https://github.com/arcusid/arcid-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/arcusid/arcid-mcp/issues"
+  },
+  "mcpName": "io.github.arcusid/arcid-mcp",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@vitest/coverage-v8": "^5.0.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.2"
+  }
+}