npm package: @humandividendprotocol/mcp-server
Description: HDP MCP Server — exposes capture stats and control tools for Claude Desktop
Latest version: 0.1.0

# @hdp/mcp-server

**MCP Server for the Human Dividend Protocol** — gives Claude Desktop (and any MCP-capable AI client) real-time visibility into your HDP capture session and the ability to report usage manually.

## What It Does

The HDP MCP Server is a bridge between your AI assistant and the [HDP Desktop App](../desktop-app/). It exposes three tools and one live resource over the [Model Context Protocol](https://modelcontextprotocol.io/), so Claude can:

- **See your capture stats** — tokens processed, compute units earned, receipts submitted, proof score, GPU info
- **Browse receipt history** — every compute receipt generated during your session
- **Report usage manually** — record token usage from API calls that weren't automatically captured

The server communicates with the HDP Desktop App over a local IPC connection (`127.0.0.1:19876`). It does not make any external network requests — all data stays on your machine.

## Architecture

```
Claude Desktop ──(stdio)──> @hdp/mcp-server ──(HTTP)──> HDP Desktop App (:19876)
                                                              │
                                                         Capture Engine
                                                              │
                                                    Aggregator (on-chain)
```

The MCP server uses **stdio transport** (stdin/stdout), which is the standard way Claude Desktop communicates with MCP servers. It acts as a thin adapter between Claude's MCP protocol and the Desktop App's local HTTP API.

## Installation

```bash
npm install -g @hdp/mcp-server
```

Or run directly with npx:

```bash
npx @hdp/mcp-server
```

## Setup with Claude Desktop

Add the following to your Claude Desktop MCP configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hdp": {
      "command": "npx",
      "args": ["@hdp/mcp-server"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "hdp": {
      "command": "hdp-mcp-server"
    }
  }
}
```

Restart Claude Desktop after editing the config.

## Prerequisites

The HDP Desktop App must be running for the MCP server to return data. If the Desktop App is not running, tools will return a `"status": "disconnected"` response with instructions to launch it.

Download the Desktop App from [humandividendprotocol.com](https://humandividendprotocol.com).

## Tools

### `get_capture_stats`

Returns current capture session statistics.

**Parameters**: None

**Response fields**:
| Field | Type | Description |
|-------|------|-------------|
| `status` | string | `"connected"` or `"disconnected"` |
| `is_active` | boolean | Whether capture is currently active |
| `total_tokens` | number | Total tokens processed this session |
| `total_compute_units` | number | Compute units earned |
| `receipts_submitted` | number | Receipts successfully submitted to aggregator |
| `receipts_pending` | number | Receipts awaiting submission |
| `session_duration_ms` | number | Session uptime in milliseconds |
| `proof_score` | number | Current proof quality score (0-100) |
| `reward_multiplier` | number | HDPT reward multiplier based on tier |
| `gpu_info` | object\|null | Detected GPU hardware info |
| `detected_models` | array | AI models detected running locally |
| `current_telemetry` | object\|null | Live system telemetry |

**Example prompt**: *"How many tokens has HDP captured this session?"*

### `get_receipt_history`

Returns the history of compute receipts generated during the current and past sessions.

**Parameters**: None

**Response fields** (per receipt):
| Field | Type | Description |
|-------|------|-------------|
| `receipt_hash` | string | Unique SHA-256 hash of the receipt |
| `computation_type` | string | Type of computation (`api_call`, `local_inference`, etc.) |
| `input_tokens` | number | Input/prompt tokens |
| `output_tokens` | number | Output/completion tokens |
| `compute_units` | number | Normalized compute units |
| `total_latency_ms` | number | Request latency in milliseconds |
| `provider` | string | AI provider (`anthropic`, `openai`, `google`, etc.) |
| `start` | number | Unix timestamp of request start |
| `end` | number | Unix timestamp of request end |

**Example prompt**: *"Show me my recent HDP compute receipts"*

### `report_usage`

Manually report AI API usage that wasn't automatically captured by the proxy.

**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider` | string | Yes | AI provider name (`"anthropic"`, `"openai"`, `"google"`) |
| `input_tokens` | integer | Yes | Number of input/prompt tokens |
| `output_tokens` | integer | Yes | Number of output/completion tokens |
| `latency_ms` | integer | Yes | Total request latency in milliseconds |

**Example prompt**: *"Report 500 input tokens and 200 output tokens from OpenAI with 3 second latency to HDP"*

## Resources

### `hdp://status`

A subscribable resource that returns the current capture status as JSON. MCP clients can poll this for live updates.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `HDP_IPC_URL` | `http://127.0.0.1:19876` | Override the Desktop App IPC address |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test
```

## How It Fits Into HDP

HDP (Human Dividend Protocol) is a DePIN protocol on Base that rewards machine owners for AI compute work via the $HDPT token. The system has five client applications:

| Client | Capture Method | Tier |
|--------|---------------|------|
| **Desktop App** | Embedded proxy on `:19877` intercepts API calls | Provider (1.0x) |
| **MCP Server** | Reads stats from Desktop App via IPC | — (companion tool) |
| **CLI** | `hdp proxy` or `hdp wrap` commands | Provider (1.0x) |
| **Browser Extension** | Intercepts `fetch()` to AI APIs | Consumer (0.3x) |
| **TypeScript SDK** | `createTrackedClient()` wrapper | Orchestrator (0.6x) |

The MCP Server doesn't capture compute directly — it's a **companion tool** that lets your AI assistant see and interact with the capture data from the Desktop App.

## License

MIT