# ARES MCP

ARES MCP is the read-only, verification-first MCP surface for ARES Protocol.

It wraps the public ARES API without changing payload meaning. Indexed reads, local/demo reads, and direct-chain fallback semantics stay intact because the MCP server delegates to the same public API truth used by the explorer and SDKs.

## What it exposes

- `health`
- `get_agent`
- `get_score`
- `get_actions`
- `get_disputes`

## 5-minute quickstart

### 1. Install the published packages

```bash
npm install @aresprotocol/sdk
```

Run the published MCP server with `npx`:

```bash
ARES_API_BASE=https://ares-protocol.xyz/api npx -y @aresprotocol/mcp
```

If you only need the MCP server, `@aresprotocol/sdk` is optional. If you want both a direct SDK client and the MCP surface in one project:

```bash
npm install @aresprotocol/sdk @aresprotocol/mcp
```

If `ARES_API_BASE` is omitted, the default is:

```bash
https://ares-protocol.xyz/api
```

### 2. Local repository development path

If you are working inside this monorepo and want the local workspace build instead of the published package:

```bash
npm ci
npm run mcp:build
ARES_API_BASE=https://ares-protocol.xyz/api node mcp/ares-mcp/dist/index.js
```

## Example MCP client config

```json
{
  "mcpServers": {
    "ares": {
      "command": "node",
      "args": ["mcp/ares-mcp/dist/index.js"],
      "env": {
        "ARES_API_BASE": "https://ares-protocol.xyz/api"
      }
    }
  }
}
```

Ready-to-use config variants:

- `mcp/ares-mcp/config/claude-desktop.json`
- `mcp/ares-mcp/config/cursor.json`
- `mcp/ares-mcp/config/windsurf.json`
- `mcp/ares-mcp/config/codex.json`

## Copy-paste install matrix

### SDK only

```bash
npm install @aresprotocol/sdk
```

### MCP only

```bash
npx -y @aresprotocol/mcp
```

### SDK + MCP in one project

```bash
npm install @aresprotocol/sdk @aresprotocol/mcp
ARES_API_BASE=https://ares-protocol.xyz/api npx -y @aresprotocol/mcp
```

## Example tool flows

### Health

Tool:

```json
{
  "name": "health",
  "arguments": {}
}
```

### Agent lookup

Tool:

```json
{
  "name": "get_agent",
  "arguments": {
    "address": "star"
  }
}
```

Equivalent curl:

```bash
curl https://ares-protocol.xyz/api/v1/agent/star
```

Equivalent TypeScript:

```ts
import { AresClient } from '@aresprotocol/sdk';

const client = new AresClient({ apiBase: 'https://ares-protocol.xyz/api' });
const agent = await client.getAgent('star');
```

Equivalent Python:

```python
from ares_sdk import AresClient

client = AresClient("https://ares-protocol.xyz/api")
agent = client.get_agent("star")
```

### Score lookup

Tool:

```json
{
  "name": "get_score",
  "arguments": {
    "address": "star"
  }
}
```

Equivalent curl:

```bash
curl https://ares-protocol.xyz/api/v1/score/star
```

### Actions

Tool:

```json
{
  "name": "get_actions",
  "arguments": {
    "agent": "star",
    "limit": 5
  }
}
```

Equivalent curl:

```bash
curl "https://ares-protocol.xyz/api/v1/actions?agent=star&limit=5"
```

Equivalent TypeScript:

```ts
const actions = await client.getActions({ agent: 'star', limit: 5 });
```

Equivalent Python:

```python
actions = client.get_actions(agent="star", limit=5)
```

### Disputes

Tool:

```json
{
  "name": "get_disputes",
  "arguments": {
    "agent": "star",
    "limit": 5
  }
}
```

Equivalent curl:

```bash
curl "https://ares-protocol.xyz/api/v1/disputes?agent=star&limit=5"
```

Equivalent TypeScript:

```ts
const disputes = await client.getDisputes({ agent: 'star', limit: 5 });
```

Equivalent Python:

```python
disputes = client.get_disputes(agent="star", limit=5)
```

## Response contract

Each MCP tool returns a stable envelope:

```json
{
  "tool": "get_agent",
  "apiBase": "https://ares-protocol.xyz/api",
  "endpoint": "/v1/agent/star",
  "fetchedAt": "2026-04-20T12:00:00.000Z",
  "data": {}
}
```

`data` preserves the upstream ARES API response shape. The MCP layer does not rename fields or flatten visibility semantics.

## Truth boundaries

- Registration and visibility are not the same thing.
- Newly registered agents may resolve through indexed data or direct-chain fallback.
- Live scoring enablement remains approval-based.
- `ares-mcp` v1 is read-only and does not write to chain or API state.
- Canonical demo sequence for ARES now lives in [`demo-arc.md`](./demo-arc.md).

## Release validation

```bash
npm run mcp:test
npm run mcp:smoke
npm run mcp:pack
```