aiden-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIDEN
+
+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

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# aiden-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[MCP](https://modelcontextprotocol.io) server for **AIDEN**, the identity and reputation layer for AI agents on
+[Robinhood Chain](https://docs.robinhood.com/chain/). It lets Claude and other MCP clients look up agents registered in the
+**ERC-8004** registries: profiles, owners, feedback, validations and USDG-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 |
+
+## Connect
+
+### Remote (claude.ai, ChatGPT, any URL-based client)
+
+```
+https://mcp.aiden.network/mcp
+```
+
+Streamable HTTP, stateless, no authentication.
+
+- **claude.ai / Claude Desktop:** Settings → Connectors → Add custom connector → paste the URL.
+- **ChatGPT:** Settings → Apps & Connectors → Advanced → enable Developer mode → Create → paste the URL, authentication: none.
+- **Claude Code:** `claude mcp add --transport http aiden https://mcp.aiden.network/mcp`
+
+### Local (stdio via npx)
+
+No install step needed; clients run it with `npx`.
+
+### Claude Code
+
+```bash
+claude mcp add aiden -- npx -y aiden-mcp
+```
+
+### Claude Desktop / Cursor / other clients
+
+```json
+{
+  "mcpServers": {
+    "aiden": {
+      "command": "npx",
+      "args": ["-y", "aiden-mcp"]
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `AIDEN_API_URL` | `https://api.aiden.network` | AIDEN indexer API. Use `http://127.0.0.1:4000` for a local indexer |
+| `AIDEN_TIMEOUT_MS` | `10000` | Per-request timeout, 1000 to 60000 |
+
+## Development
+
+```bash
+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/
+npm run worker:dev     # remote endpoint locally (wrangler)
+npm run worker:deploy  # typecheck, test, deploy the Worker
+```
+
+The remote endpoint is `worker/index.ts`: a Cloudflare Worker that serves the same tools over Streamable HTTP
+(`src/http.ts`). It reaches the AIDEN API through a service binding and forwards the caller's IP, so API rate
+limits apply per user.
+
+## License
+
+MIT

package/dist/client.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+// Every AIDEN 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 AidenApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "AidenApiError";
+    }
+}
+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": "aiden-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 AidenApiError(`AIDEN API unreachable (${reason})`);
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            throw new AidenApiError(`AIDEN API returned a non-JSON response (HTTP ${res.status})`, res.status);
+        }
+        const parsed = envelope.safeParse(body);
+        if (!parsed.success)
+            throw new AidenApiError(`AIDEN API returned an unexpected payload (HTTP ${res.status})`, res.status);
+        if (!res.ok || !parsed.data.success) {
+            throw new AidenApiError(parsed.data.error ?? `AIDEN 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.aiden.network";
+export const DEFAULT_TIMEOUT_MS = 10_000;
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 60_000;
+// Reads AIDEN_API_URL / AIDEN_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.AIDEN_API_URL?.trim() || DEFAULT_API_URL;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`AIDEN_API_URL is not a valid URL: ${raw}`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`AIDEN_API_URL must be http(s), got ${url.protocol}`);
+    }
+    const timeoutRaw = env.AIDEN_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(`AIDEN_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/http.js

@@ -0,0 +1,49 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createServer } from "./server.js";
+// Remote (Streamable HTTP) transport for runtimes with web-standard Request/Response, e.g. Cloudflare Workers.
+// Stateless: every POST gets a fresh server and transport, so no session state lives between requests.
+export const MCP_PATH = "/mcp";
+export const MAX_BODY_BYTES = 64 * 1024;
+const CORS_HEADERS = {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "POST, OPTIONS",
+    "access-control-allow-headers": "content-type, accept, authorization, mcp-protocol-version, mcp-session-id, last-event-id",
+    "access-control-expose-headers": "mcp-session-id, mcp-protocol-version",
+    "access-control-max-age": "600",
+};
+function withCors(res) {
+    const headers = new Headers(res.headers);
+    for (const [k, v] of Object.entries(CORS_HEADERS))
+        headers.set(k, v);
+    return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+}
+function rpcError(status, message, extra = {}) {
+    const body = JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null });
+    return withCors(new Response(body, { status, headers: { "content-type": "application/json", ...extra } }));
+}
+export async function handleMcpHttp(request, client) {
+    if (request.method === "OPTIONS")
+        return withCors(new Response(null, { status: 204 }));
+    if (request.method !== "POST") {
+        return rpcError(405, "Method not allowed. This endpoint is stateless: send JSON-RPC over POST.", { allow: "POST, OPTIONS" });
+    }
+    const server = createServer(client);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+        maxRequestBodySize: MAX_BODY_BYTES,
+    });
+    try {
+        await server.connect(transport);
+        return withCors(await transport.handleRequest(request));
+    }
+    catch (err) {
+        console.error("[aiden-mcp] http transport error", err);
+        return rpcError(500, "Internal error");
+    }
+    finally {
+        // Response bodies are fully materialised in JSON mode, so closing here is safe.
+        await transport.close().catch(() => { });
+        await server.close().catch(() => { });
+    }
+}

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(`[aiden-mcp] ready, API ${config.apiUrl}`);
+}
+main().catch((err) => {
+    console.error("[aiden-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 = "aiden";
+export const SERVER_VERSION = "0.2.0";
+export function createServer(client) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        instructions: "AIDEN indexes AI agent identities and reputation from the ERC-8004 registries on Robinhood Chain. " +
+            "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,72 @@
+import { z } from "zod";
+import { AidenApiError } 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 AidenApiError ? err.message : "Unexpected error while calling the AIDEN API";
+    if (!(err instanceof AidenApiError))
+        console.error("[aiden-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 AIDEN directory of AI agents registered on Robinhood Chain (ERC-8004). Supports full-text search over names and " +
+            "descriptions, filtering by owner address, and sorting by trust score, feedback count or settled USDG.",
+        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().default(true)
+                .describe("Only agents with a readable profile (name, description). Default true; set false to include unnamed agents"),
+            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 AIDEN record for one agent: profile, owner, agent wallet, reputation summary, validations, trust score " +
+            "and the USDG 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 AIDEN index: agents, owners, feedback, validations and settled USDG.",
+        annotations: { title: "Get registry stats", ...READ_ONLY },
+    }, () => run(() => client.stats()));
+    server.registerTool("get_indexer_health", {
+        title: "Get indexer health",
+        description: "How far the AIDEN indexer is behind the Robinhood Chain head. Check this when results look empty or stale.",
+        annotations: { title: "Get indexer health", ...READ_ONLY },
+    }, () => run(() => client.health()));
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "aiden-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for AIDEN: look up AI agent identity and reputation (ERC-8004) on Robinhood Chain",
+  "type": "module",
+  "bin": {
+    "aiden-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc -p worker/tsconfig.json",
+    "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",
+    "worker:dev": "wrangler dev",
+    "worker:deploy": "npm run typecheck && npm test && wrangler deploy"
+  },
+  "keywords": [
+    "mcp",
+    "robinhood-chain",
+    "erc-8004",
+    "ai-agents",
+    "reputation"
+  ],
+  "author": "AIDEN",
+  "license": "MIT",
+  "homepage": "https://aiden.network/mcp",
+  "mcpName": "network.aiden/aiden-mcp",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260927.1",
+    "@types/node": "^26.6.3",
+    "@vitest/coverage-v8": "^5.0.2",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.2",
+    "wrangler": "^4.142.0"
+  }
+}