@quantulabs/8004-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quantu Labs
+
+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,370 @@
+# @quantulabs/8004-mcp
+
+Multi-chain MCP server for the ERC-8004 Agent Registry Standard. Supports Solana and EVM chains (Ethereum, Base, Arbitrum, Polygon, Optimism).
+
+## Requirements
+
+- Node.js >= 20.0.0
+- npm or pnpm
+
+## Installation
+
+```bash
+npm install -g @quantulabs/8004-mcp
+```
+
+Or run directly without installing:
+
+```bash
+npx @quantulabs/8004-mcp
+```
+
+## Features
+
+- **Multi-chain**: Solana + EVM (Base, Ethereum, Arbitrum, Polygon, Optimism)
+- **Unified API**: Same tools work across chains with automatic routing
+- **Wallet Management**: Encrypted local storage with auto-lock
+- **Local Cache**: SQLite with FTS5 for fast agent search
+- **ATOM Reputation**: Full integration with Solana's reputation system
+- **IPFS Support**: Pinata, Filecoin, or custom node
+
+## Configuration
+
+The MCP automatically loads a `.env` file from the current directory.
+
+```bash
+cp .env.example .env
+# Edit .env with your values
+npx @quantulabs/8004-mcp
+```
+
+See [.env.example](./.env.example) for all available options.
+
+## Usage with Claude Code
+
+### Quick Start
+
+```bash
+claude mcp add 8004-mcp -- npx @quantulabs/8004-mcp
+```
+
+With configuration:
+
+```bash
+claude mcp add 8004-mcp \
+  -e DEFAULT_CHAIN=sol \
+  -e NETWORK_MODE=testnet \
+  -e PINATA_JWT=your-jwt \
+  -- npx @quantulabs/8004-mcp
+```
+
+### Examples
+
+#### Multi-chain agent search
+
+Search across all blockchains without specifying a chain:
+
+```
+> Find the agent named "DataAnalyst Pro"
+
+Found 2 agents named "DataAnalyst Pro" on Ethereum Sepolia:
+- eth:11155111:461 - Owner: 0xfb49...
+- eth:11155111:460 - Owner: 0x6fd8...
+```
+
+```
+> Search for agents with "Yoda" in the name
+
+Found 4 agents:
+- eth:11155111:523 - "Yoda 27 Jan"
+- eth:11155111:468 - "Yoda 3"
+- eth:11155111:467 - "Yoda Dash 1"
+- eth:11155111:465 - "Yoda PG 2 IPFS"
+All owned by 0xad55...
+```
+
+#### Get agent details
+
+```
+> Show me details about agent eth:11155111:474
+
+Agent: 8004 Test Agent
+- Chain: Ethereum Sepolia
+- Owner: 0x9ca4...
+- Description: This is an explanation of my test agent
+- Created: 2026-01-27
+```
+
+#### Check agent reputation (Solana only)
+
+> Note: Trust tiers and ATOM reputation metrics are only available on Solana.
+
+```
+> What's the reputation of sol:6YMAwDYygQEo1BGDavNaKhhfy52yzZ6SoBsa2wdgXthJ?
+
+Trust Tier: Unrated (0/4)
+Quality Score: 2440
+Total Feedbacks: 29
+Average Score: 24.4
+```
+
+#### Top agents leaderboard (Solana only)
+
+```
+> Show me the top 5 agents by reputation
+
+Top 5 Solana agents:
+1. sol:9j7cTX... - Score: 5586 (34 feedbacks)
+2. sol:5heKjG... - Score: 5544 (35 feedbacks)
+3. sol:HnGRPf... - Score: 3364 (50 feedbacks)
+4. sol:6YMAwD... - Score: 2440 (30 feedbacks)
+5. sol:Arskmk... - Score: 2440 (30 feedbacks)
+```
+
+#### Submit feedback
+
+```
+> Give a score of 90 to agent sol:7xKXtG8vN2... with comment "Fast execution"
+
+First I need to unlock a wallet...
+Feedback submitted! Transaction: 4xR7m...
+```
+
+#### Register a new agent
+
+```
+> Register a new agent called "MyBot" with MCP endpoint https://mybot.com/mcp
+
+1. Uploading registration to IPFS...
+2. Registering on-chain...
+
+Agent registered!
+- ID: sol:NewAgentPubkey...
+- Name: MyBot
+- Transaction: 5tY8n...
+```
+
+#### Manage wallets
+
+```
+> Create a new Solana wallet called "trading-wallet"
+
+Wallet created:
+- Name: trading-wallet
+- Address: 8xM2k...
+- Chain: Solana
+
+Fund this address to start using it for transactions.
+```
+
+#### Switch networks
+
+```
+> Switch to mainnet
+
+Using network_set with mode "mainnet"...
+
+Switched to mainnet. Active chains:
+- Solana: mainnet-beta
+- Base: mainnet (chainId: 8453)
+- Ethereum: mainnet (chainId: 1)
+```
+
+## Tools
+
+See [TOOLS.md](./TOOLS.md) for the complete list of 60+ available tools.
+
+## Global ID Format
+
+Agents are identified using global IDs:
+
+- Solana: `sol:<pubkey>`
+- EVM: `<chain>:<chainId>:<tokenId>`
+
+Examples:
+- `sol:7xKXtG8vN2mPQr...`
+- `base:8453:123`
+- `eth:1:456`
+
+## x402 Protocol Integration
+
+The MCP supports the x402 payment protocol extension for reputation (`8004-reputation`). This allows linking feedback to actual payment transactions, creating verifiable proof-of-payment reputation.
+
+### How it works
+
+1. **Server announces identity**: When returning 402 Payment Required, include agent identity in CAIP-2 format
+2. **Client pays**: Standard x402 payment flow
+3. **Feedback with proof**: Both parties can submit feedback linked to the payment transaction
+
+### Example: Connecting to 8004-mcp
+
+```javascript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { spawn } from 'child_process';
+
+// Start the MCP server
+const server = spawn('npx', ['@quantulabs/8004-mcp'], {
+  stdio: ['pipe', 'pipe', 'inherit'],
+});
+
+const transport = new StdioClientTransport({
+  reader: server.stdout,
+  writer: server.stdin,
+});
+
+const mcpClient = new Client(
+  { name: 'my-app', version: '1.0.0' },
+  { capabilities: {} }
+);
+
+await mcpClient.connect(transport);
+```
+
+### Example: Server-side (announcing identity)
+
+```javascript
+// Build identity for PaymentRequired response
+const result = await mcpClient.callTool({
+  name: 'x402_identity_build',
+  arguments: { agentId: 'sol:AgentPubkey...' }
+});
+
+const identity = JSON.parse(result.content[0].text);
+// Returns: { identity: { agentRegistry: "solana:EtWTRA...:HHCVWc...", agentId: "..." } }
+
+// Add to PaymentRequired headers
+const paymentRequired = {
+  ...standardX402Fields,
+  extensions: {
+    '8004-reputation': identity.identity
+  }
+};
+```
+
+### Example: Client-side (submitting feedback)
+
+```javascript
+// After receiving PaymentResponse, parse the proof
+const proofResult = await mcpClient.callTool({
+  name: 'x402_proof_parse',
+  arguments: { paymentResponse: base64EncodedPaymentResponse }
+});
+
+const proof = JSON.parse(proofResult.content[0].text);
+
+// Option A: Auto-store on IPFS (requires ipfs_configure first)
+await mcpClient.callTool({
+  name: 'x402_feedback_submit',
+  arguments: {
+    agentId: 'sol:AgentPubkey...',
+    score: 85,
+    tag1: 'x402-resource-delivered',
+    tag2: 'exact-svm',
+    endpoint: 'https://agent.example.com/api',
+    proofOfPayment: proof.proofOfPayment,
+    storeOnIpfs: true
+  }
+});
+
+// Option B: Manual storage - build file first, store yourself
+const buildResult = await mcpClient.callTool({
+  name: 'x402_feedback_build',
+  arguments: {
+    agentId: 'base:84532:123',
+    score: 90,
+    tag1: 'x402-resource-delivered',
+    proofOfPayment: proof.proofOfPayment
+  }
+});
+// Store buildResult.feedbackFile on Arweave, your IPFS, etc.
+const myUri = 'ar://abc123...';
+
+// Then submit with your URI
+await mcpClient.callTool({
+  name: 'x402_feedback_submit',
+  arguments: {
+    agentId: 'base:84532:123',
+    score: 90,
+    tag1: 'x402-resource-delivered',
+    proofOfPayment: proof.proofOfPayment,
+    feedbackUri: myUri,
+    storeOnIpfs: false
+  }
+});
+```
+
+### Feedback File Storage
+
+Feedback files **must** be stored for the x402 protocol. Two options:
+
+1. **Auto IPFS** (`storeOnIpfs: true`): Configure IPFS first with `ipfs_configure`, then feedback is automatically stored
+2. **Manual storage** (`feedbackUri`): Use `x402_feedback_build` to get the file, store it yourself (Arweave, your IPFS, HTTP), then pass the URI
+
+Supported URI schemes: `ipfs://`, `ar://`, `https://`, `http://`
+
+Example feedback file structure:
+
+```json
+{
+  "agentRegistry": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1:HHCVWcqs...",
+  "agentId": "AgentPubkey...",
+  "clientAddress": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1:ClientPubkey...",
+  "createdAt": "2026-01-23T12:00:00Z",
+  "score": 85,
+  "tag1": "x402-resource-delivered",
+  "tag2": "exact-svm",
+  "endpoint": "https://agent.example.com/api",
+  "proofOfPayment": {
+    "fromAddress": "ClientPubkey...",
+    "toAddress": "AgentPubkey...",
+    "chainId": "EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+    "txHash": "5xR7mN2k..."
+  }
+}
+```
+
+See [TOOLS.md](./TOOLS.md#x402-protocol-integration) for more details on x402 tools.
+
+## Development
+
+```bash
+git clone https://github.com/QuantuLabs/8004-mcp.git
+cd 8004-mcp
+npm install
+npm run build
+npm test
+```
+
+## Adding Your Registry
+
+> **Note:** Registries supported by the [8004-solana SDK](https://github.com/QuantuLabs/8004-solana) and [agent0-ts SDK](https://github.com/agent0lab/agent0-ts) are automatically included in this MCP. No action needed for those chains.
+
+Want to add your own ERC-8004 compatible registry to the MCP? [Open an issue on GitHub](https://github.com/QuantuLabs/8004-mcp/issues/new?template=registry-request.md) with the following requirements:
+
+### Requirements
+
+1. **Open Source**: Your registry must be public and open source
+   - Provide link to your GitHub repository
+
+2. **Indexer**: Provide an open source indexer or equivalent data access method
+   - We need a way to query agents efficiently
+   - Subgraph, REST API, or RPC-based indexing supported
+
+3. **Documentation**: Complete API documentation including:
+   - All contract methods and events
+   - Data structures and types
+   - Example requests/responses
+
+4. **API Compatibility**: We recommend following the [8004-solana SDK](https://github.com/QuantuLabs/8004-solana) API patterns:
+   - `getAgent(id)` - Get agent details
+   - `agentExists(id)` - Check existence
+   - `searchAgents(params)` - Search with filters
+   - `giveFeedback(input)` - Submit feedback
+   - `getFeedback(agentId, client, index)` - Read feedback
+   - `listFeedbacks(query)` - List feedbacks
+   - `getReputationSummary(id)` - Get reputation
+
+## License
+
+MIT

package/dist/chains/evm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/chains/evm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/chains/evm/index.ts"],"names":[],"mappings":"AAEA,cAAc,eAAe,CAAC"}

package/dist/chains/evm/index.js

@@ -0,0 +1,3 @@
+// EVM chain exports
+export * from './provider.js';
+//# sourceMappingURL=index.js.map

package/dist/chains/evm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/chains/evm/index.ts"],"names":[],"mappings":"AAAA,oBAAoB;AAEpB,cAAc,eAAe,CAAC"}

package/dist/chains/evm/provider.d.ts

@@ -0,0 +1,48 @@
+import { SDK as Agent0SDK } from 'agent0-sdk';
+import type { IChainProvider, IChainConfig, IWriteOptions, ITransactionResult } from '../../core/interfaces/chain-provider.js';
+import type { IAgent, ISearchParams, ISearchResult, ChainType, ChainPrefix } from '../../core/interfaces/agent.js';
+import type { IFeedback, IFeedbackInput, IFeedbackQuery, IFeedbackResult } from '../../core/interfaces/feedback.js';
+import type { IReputationSummary, ILeaderboardOptions, ILeaderboardResult } from '../../core/interfaces/reputation.js';
+export interface IEVMConfig {
+    chainId: number;
+    chainPrefix: ChainPrefix;
+    rpcUrl: string;
+    subgraphUrl?: string;
+    privateKey?: string;
+}
+export declare class EVMChainProvider implements IChainProvider {
+    readonly chainType: ChainType;
+    readonly chainPrefix: ChainPrefix;
+    readonly chainId: string;
+    readonly displayName: string;
+    private readonly config;
+    private _ready;
+    private _sdk?;
+    private _subgraph?;
+    constructor(config: IEVMConfig);
+    private getDisplayName;
+    getSdk(): Agent0SDK;
+    private getSubgraph;
+    invalidateSdk(): void;
+    initialize(): Promise<void>;
+    isReady(): boolean;
+    canWrite(): boolean;
+    getConfig(): IChainConfig;
+    getAgent(agentId: string): Promise<IAgent | null>;
+    agentExists(agentId: string): Promise<boolean>;
+    searchAgents(params: ISearchParams): Promise<ISearchResult>;
+    getFeedback(agentId: string, client: string, index: bigint): Promise<IFeedback | null>;
+    listFeedbacks(query: IFeedbackQuery): Promise<IFeedbackResult>;
+    giveFeedback(input: IFeedbackInput, options?: IWriteOptions): Promise<ITransactionResult>;
+    getReputationSummary(agentId: string): Promise<IReputationSummary | null>;
+    private computeTrustTier;
+    /**
+     * Convert raw value with decimals back to decimal string for SDK encoding
+     * Example: value=9977n, valueDecimals=2 → "99.77"
+     * The SDK's encodeReputationValue() expects decimal strings and will re-encode correctly
+     */
+    private rawToDecimalString;
+    isIndexerAvailable(): Promise<boolean>;
+    getLeaderboard(_options?: ILeaderboardOptions): Promise<ILeaderboardResult>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/chains/evm/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/chains/evm/provider.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,GAAG,IAAI,SAAS,EAIjB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,aAAa,EACb,kBAAkB,EACnB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EACV,MAAM,EACN,aAAa,EACb,aAAa,EACb,SAAS,EACT,WAAW,EACZ,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,qCAAqC,CAAC;AAI7C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,gBAAiB,YAAW,cAAc;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAS;IACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,IAAI,CAAC,CAAY;IACzB,OAAO,CAAC,SAAS,CAAC,CAAiB;gBAEvB,MAAM,EAAE,UAAU;IAO9B,OAAO,CAAC,cAAc;IAYtB,MAAM,IAAI,SAAS;IAkBnB,OAAO,CAAC,WAAW;IASnB,aAAa,IAAI,IAAI;IAKf,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC,OAAO,IAAI,OAAO;IAIlB,QAAQ,IAAI,OAAO;IAInB,SAAS,IAAI,YAAY;IAcnB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAuBjD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK9C,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAwI3D,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA8BtF,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IA0E9D,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAwEzF,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAuB/E,OAAO,CAAC,gBAAgB;IAQxB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAoBpB,kBAAkB,IAAI,OAAO,CAAC,OAAO,CAAC;IAItC,cAAc,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CASlF"}