# Unblind MCP Skill

## Overview

The **Unblind MCP Skill** exposes the Unblind API as a Model Context Protocol (MCP) server so agents can analyze blockchain transactions and signed messages in natural language.

This document is meant to be fetched and read by external agents (or their operators) to understand how to connect and what tools are available.

## MCP Server

- **Server name**: `unblind-mcp-server`
- **Protocol**: Model Context Protocol (MCP)
- **Transport**: HTTP (streamable)
- **Endpoint**: `https://api.unblind.app/mcp`

> The exact base URL depends on your deployment; replace with your own Unblind API host if different.

### Authentication

All requests to the underlying Unblind HTTP API require an API key:

- Header: `x-api-key: <YOUR_API_KEY>`

For MCP-aware clients:

- If the client supports passing custom headers to the MCP transport, include `x-api-key` there.
- Otherwise, the tools are designed so that the API key can also be passed as a parameter when necessary.

## Tools

The MCP server exposes two tools that mirror the existing Unblind HTTP endpoints:

- `unblind_transaction` → mirrors `POST /unblind/transaction`
- `unblind_message` → mirrors `POST /unblind/message`

Both tools return rich natural-language analysis plus structured warnings about potential risk.

---

### Tool: `unblind_transaction`

**Purpose**

Analyze and translate a blockchain transaction into natural language, explaining what it does and highlighting any risk.

**MCP tool name**

- `unblind_transaction`

**Underlying HTTP endpoint**

- Method: `POST`
- URL: `https://api.unblind.app/unblind/transaction`
- Headers:
  - `Content-Type: application/json`
  - `x-api-key: <YOUR_API_KEY>`

**Parameters (MCP / JSON body)**

The request body matches the Unblind transaction DTO. An example payload:

```json
{
  "from": "0x12876597868b901e1cd194421705c8cf6851addf",
  "data": "0x",
  "gas": "0x5208",
  "to": "0x8d9148b1a44604d64db906493f7e0f376f5f05cc",
  "value": "0x354a6ba7a18000",
  "maxFeePerGas": "0x595e570d",
  "maxPriorityFeePerGas": "0x1dcd6500",
  "chainId": "eip155:1",
  "testInBlock": 22391059
}
```

**Response (HTTP / tool content)**

The underlying Unblind API returns:

```json
{
  "hash": "0x940e5dc22d04b23d81b8a44f633161fdbaba18f4551b4828e5778185b6409ecc",
  "analysis": "You will send 0.015 ETH to 0x8d9148b1a44604d64db906493f7e0f376f5f05cc",
  "warnings": [],
  "messageJSON": "{...}",
  "context": "...",   // may be omitted in production
  "prompt": "..."     // may be omitted in production
}
```

The MCP tool wraps this response in a `CallToolResult`, typically as a single `text` content item containing the JSON result. Agents should parse this JSON and:

- Use `analysis` as the primary human-readable explanation.
- Surface any `warnings` prominently, especially when they indicate financial or security risk.

---

### Tool: `unblind_message`

**Purpose**

Analyze and translate a blockchain message signature request (e.g. EIP‑712 typed data) into natural language, explaining what the user is signing and highlighting risks.

**MCP tool name**

- `unblind_message`

**Underlying HTTP endpoint**

- Method: `POST`
- URL: `https://api.unblind.app/unblind/message`
- Headers:
  - `Content-Type: application/json`
  - `x-api-key: <YOUR_API_KEY>`

**Parameters (MCP / JSON body)**

The request body matches the Unblind message DTO. An example payload:

```json
{
  "from": "0x12876597868b901e1cd194421705c8cf6851addf",
  "data": {
    "types": {
      "PermitBatch": [
        { "name": "details", "type": "PermitDetails[]" },
        { "name": "spender", "type": "address" },
        { "name": "sigDeadline", "type": "uint256" }
      ],
      "PermitDetails": [
        { "name": "token", "type": "address" },
        { "name": "amount", "type": "uint160" },
        { "name": "expiration", "type": "uint48" },
        { "name": "nonce", "type": "uint48" }
      ],
      "EIP712Domain": [
        { "name": "name", "type": "string" },
        { "name": "chainId", "type": "uint256" },
        { "name": "verifyingContract", "type": "address" }
      ]
    },
    "domain": {
      "name": "Permit2",
      "chainId": "1",
      "verifyingContract": "0x000000000022d473030f116ddee9f6b43ac78ba3"
    },
    "primaryType": "PermitBatch",
    "message": {
      "details": [
        {
          "token": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          "amount": "1461501637330902918203684832716283019655932542975",
          "expiration": "1749152649",
          "nonce": "0"
        }
      ],
      "spender": "0xbd216513d74c8cf14cf4747e6aaa6420ff64ee9e",
      "sigDeadline": "1746562449"
    }
  },
  "signatureMethod": "eth_signTypedData_v4",
  "testInBlock": 22426834
}
```

**Response (HTTP / tool content)**

The underlying Unblind API returns:

```json
{
  "hash": "0xf080132ad871d06c7c74a88e4c2dd7fae10284af99ae9036da5d20bbda2631e4",
  "analysis": "You are signing a message for the Permit2 contract to grant spending permission...",
  "warnings": [
    "You are granting unlimited spending permission for your USDT and USDC tokens..."
  ],
  "messageJSON": "{...}"
}
```

The MCP tool wraps this response in a `CallToolResult` (typically as JSON text). Agents should:

- Use `analysis` to explain clearly what the signature authorizes.
- Treat `warnings` as high-priority and present them prominently to users.

---

## Example: Using this MCP server from a TypeScript MCP client

Below is a sketch of how a TypeScript MCP client (e.g. based on `@modelcontextprotocol/sdk`) could connect to the Unblind MCP server:

```ts
import { Client } from '@modelcontextprotocol/sdk/client';

const client = new Client({
  name: 'unblind-client',
  version: '1.0.0',
});

await client.connect({
  url: 'https://api.unblind.app/mcp',
  headers: {
    'x-api-key': process.env.UNBLIND_API_KEY!,
  },
});

// Call the unblind_transaction tool
const txResult = await client.callTool('unblind_transaction', {
  from: '0x...',
  to: '0x...',
  value: '0x...',
  // ...other fields...
});

// Call the unblind_message tool
const msgResult = await client.callTool('unblind_message', {
  from: '0x...',
  data: { /* EIP-712 typed data */ },
  signatureMethod: 'eth_signTypedData_v4',
});
```

## Example: Using from an LLM platform (conceptual)

For MCP-aware LLM platforms (e.g. clients that support a `mcpServers` configuration), configure something like:

```json
{
  "mcpServers": {
    "unblind-mcp-server": {
      "type": "http",
      "url": "https://api.unblind.app/mcp",
      "headers": {
        "x-api-key": "<YOUR_API_KEY>"
      }
    }
  }
}
```

Then call tools:

- `unblind_transaction` when the user shares raw transaction data.
- `unblind_message` when the user shares a message/signature payload (e.g. EIP‑712).

---

## Versioning and Contact

- **Skill document**: `SKILL.md` in the Unblind monorepo.
- **MCP server version**: see the running server’s configuration (`name`/`version` passed to `McpModule.forRoot`).

For updates or issues, refer to the Unblind project repository and documentation.