Metadata-Version: 2.4
Name: humanchain-mcp
Version: 0.17.1
Summary: MCP server for HumanChain — AI agents pause for human expert guidance via the consult() tool.
Project-URL: Homepage, https://humanchain-hub-demo.fly.dev
Project-URL: Documentation, https://humanchain-hub-demo.fly.dev/machine
Project-URL: Repository, https://github.com/M-C-Sigma/humanchain-the-hub
Project-URL: Issues, https://github.com/M-C-Sigma/humanchain-the-hub/issues
Author: HumanChain
License: MIT
Keywords: ai-agents,expert-routing,human-in-the-loop,humanchain,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# humanchain-mcp

> MCP server for HumanChain. AI agents pause for human expert guidance
> via the `consult` tool (and the async `consult_start` / `consult_status` pair).

Wires HumanChain into any MCP-aware coding agent (Claude Desktop, Cursor,
Continue, Claude Code, Cody, …). When your agent hits a question that
needs human judgment, it calls `consult()`; a vetted human answers; the
agent continues with a grounded response. If no human is online, a
single-voice LLM fallback (Groq Llama 3.3 70B) answers in their place.

Full documentation: the `/machine` and `/llms.txt` pages on your configured HumanChain backend.

## Install

```bash
pip install humanchain-mcp
```

Requires Python 3.10+.

## Configure your agent

Mint an API key on the `/developer` page of your HumanChain backend, then add
the server to your agent's MCP config:

```json
{
  "mcpServers": {
    "humanchain": {
      "command": "python",
      "args": ["-m", "humanchain_mcp"],
      "env": {
        "HUMANCHAIN_API_KEY": "hc_your_key_here"
      }
    }
  }
}
```

Restart your agent. The `consult` tool is now available.

## Environment variables

| Variable | Default | Description |
| --- | --- | --- |
| `HUMANCHAIN_API_KEY` | *(required)* | Your account API key. |
| `HUMANCHAIN_BACKEND` | `https://humanchain-hub-demo.fly.dev` | Hub backend URL. Override for self-hosted. |
| `HUMANCHAIN_MODE` | `live` | Set to `sandbox` to return synthetic responses without network calls. |
| `HUMANCHAIN_TIMEOUT_MS` | `5000` | HTTP timeout for Hub calls. (Distinct from `consult.wait_seconds`.) |
| `HUMANCHAIN_LOG_LEVEL` | `INFO` | Server log level. |

## The `consult` tool

The MCP server registers `consult` (blocking) plus the async pair
`consult_start` / `consult_status`. The `consult` signature matches the
documented Python SDK (use the async pair for any consult that waits on a
human, including every `require_human=true` call):

```python
consult(
    question: str,
    domain_tags: list[str] | None = None,
    target_responses: int = 1,
    approval_method: Literal[
        "fastest", "consensus", "best_of_n", "all_must_agree"
    ] = "fastest",
    wait_seconds: int = 60,
    bypass_on_timeout: bool = True,
    require_human: bool = False,
    context_brief: str | None = None,
) -> ConsultResponse
```

See the API reference on your backend's `/machine` page for the full
parameter and response shape, error types, and the `@hc/...` shorthand
mapping.

## Sandbox mode

Set `HUMANCHAIN_MODE=sandbox` and the server returns structurally-valid
synthetic `ConsultResponse` objects without hitting the network. Use
this in CI, agent unit tests, and during integration development —
no credits burned, no humans woken.

## Self-hosted backend

If you're running a self-hosted Hub, set `HUMANCHAIN_BACKEND` to your
deployment URL. The MCP server speaks the same `/api/agent/consult`
contract regardless of where the Hub is hosted.

## Development

```bash
git clone https://github.com/M-C-Sigma/humanchain-the-hub
cd humanchain-the-hub/humanchain-mcp
pip install -e ".[dev]"
pytest
```

## License

MIT.
