Metadata-Version: 2.4
Name: heed-mcp
Version: 0.1.0
Summary: MCP server for Heed — human approval as a native agent tool
Project-URL: Homepage, https://heed.run
Project-URL: Documentation, https://heed.run/docs/claude-code
Author-email: Heed <hello@getheed.ai>
License: MIT
Keywords: ai-agents,claude,cursor,heed,hitl,human-in-the-loop,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: heed>=0.1.0
Requires-Dist: mcp>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Heed MCP Server

Human approval as a native agent tool. Exposes the [Heed](../README.md)
HITL API over [MCP](https://modelcontextprotocol.io) so Claude Code, Cursor, and any
MCP-compatible agent can pause for human sign-off before risky actions.

## Install

```bash
pip install heed-mcp
```

Or without installing globally:

```bash
uvx heed-mcp
```

## Tools

| Tool | Purpose |
|------|---------|
| `request_approval(action, summary, context?, priority?, mode?, grace_seconds?)` | Submit an action for approval. Returns `{status: "approved", auto_approved: true}` when no policy matches, else `{status: "pending"\|"grace_pending", poll_url, expires_at}`. |
| `check_approval(request_id)` | Poll a submitted request until a human decides (or the grace window auto-approves). |

## Configuration

| Env var | Required | Description |
|---------|----------|-------------|
| `HEED_API_KEY` | ✅ | Tenant API key (`hd_live_...` / `hd_test_...`) — from https://heed.run/signup |
| `HEED_BASE_URL` | ☑️ | API base URL (default `https://heed.run`) |
| `HEED_AGENT_ID` | ☑️ | Agent identifier shown in the dashboard (default `mcp-agent`) |

## Claude Code setup

```bash
pip install heed-mcp
claude mcp add heed \
  -e HEED_API_KEY=hd_live_your_key_here \
  -e HEED_BASE_URL=https://heed.run \
  -- heed-mcp
```

Or add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "heed": {
      "command": "heed-mcp",
      "env": {
        "HEED_API_KEY": "hd_live_your_key_here",
        "HEED_BASE_URL": "https://heed.run"
      }
    }
  }
}
```

## Development

From the monorepo (install SDK first):

```bash
make install
HEED_API_KEY=hd_test_... HEED_BASE_URL=http://localhost:8000 venv/bin/heed-mcp
```

> Install `heed-mcp` into its **own** virtualenv (or use `uvx`). Installing into the API venv can upgrade `starlette` past what the pinned FastAPI version supports.

## Publish

```bash
./scripts/publish.sh
```

Requires `build` and `twine`, plus PyPI token in `TWINE_PASSWORD`.
