# ERC-8004 MCP Server

An MCP (Model Context Protocol) server for querying ERC-8004 AI agent identities. It queries The Graph subgraph for on-chain data and fetches IPFS metadata for full off-chain details.

## Features

- **Search agents** by name with optional protocol filtering (MCP/A2A)
- **List agents** with pagination, sorting, and protocol filtering
- **Get full agent details** including contract state, services, identity, and statistics
- **Get feedback/reviews** with scores, tags, review text, and MCP/A2A context
- **Get engagement stats** with tag analysis and score distribution
- **Get full metadata** including off-chain IPFS attributes (certifications, model info, social links, pricing, etc.)

## Tools

| Tool | Description |
|------|-------------|
| `search_agents` | Search agents by name with optional protocol filter |
| `list_agents` | Browse agents with pagination and sorting |
| `get_agent` | Get full details for an agent by ID |
| `get_agent_feedback` | Get all feedback/reviews for an agent |
| `get_agent_stats` | Get engagement metrics and score breakdown |
| `get_agent_metadata` | Get full on-chain + off-chain metadata (IPFS) |

## Setup

```bash
yarn install
```

## Usage

### stdio mode (Claude Desktop, Cursor, etc.)

```bash
yarn dev
```

### HTTP mode (Streamable HTTP)

```bash
yarn dev:http
```

The server starts on `http://localhost:3100/mcp` by default. Set the `PORT` environment variable to change it.

### Production

```bash
yarn build
yarn start          # stdio
yarn start:http     # HTTP
```

## Configuration with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "erc-8004-agents": {
      "command": "npx",
      "args": ["tsx", "/path/to/erc-8004-mcp-server/src/index.ts"]
    }
  }
}
```

Or with the compiled version:

```json
{
  "mcpServers": {
    "erc-8004-agents": {
      "command": "node",
      "args": ["/path/to/erc-8004-mcp-server/dist/index.js"]
    }
  }
}
```

## Configuration with Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "erc-8004-agents": {
      "command": "npx",
      "args": ["tsx", "/path/to/erc-8004-mcp-server/src/index.ts"]
    }
  }
}
```

Or for the HTTP transport:

```json
{
  "mcpServers": {
    "erc-8004-agents": {
      "url": "http://localhost:3100/mcp"
    }
  }
}
```

## Example queries

Once connected, you can ask your AI assistant:

- "Search for fitness agents on ERC-8004"
- "List the most recently created agents with MCP support"
- "Get details for agent 11155111:1213"
- "Show me all the feedback for Larry the Lobster"
- "What are the full metadata attributes for agent 11155111:1213?"
- "Show me the stats and score breakdown for this agent"

## Data Sources

- **On-chain data**: [ERC-8004 Subgraph](https://thegraph.com/hosted-service/) on Sepolia testnet
- **Off-chain metadata**: IPFS via public gateways (ipfs.io, cloudflare-ipfs.com, dweb.link)