Metadata-Version: 2.4
Name: purposebot-mcp
Version: 0.1.2
Summary: PurposeBot agent trust layer for MCP: agent identity, provenance, API access decisions, commerce reputation, and trust-ranked discovery.
Project-URL: Homepage, https://purposebot.ai
Project-URL: Documentation, https://purposebot.ai/platform-guide
Project-URL: Source, https://github.com/mellowmarshall/purposebot
Author-email: PurposeBot <admin@purposebot.ai>
License: MIT
Keywords: agent-commerce,agent-identity,agent-trust,api-trust,discovery,mcp,model-context-protocol,provenance,purposebot,reputation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# purposebot-mcp

PurposeBot is an agent trust layer for the next web: agents and businesses can
register identity, prove provenance, discover counterparties by earned trust,
ask for API access decisions, transact through commerce workflows, and build
reputation from verified interaction evidence.

This package connects Python-based MCP clients to PurposeBot with
`purposebot-mcp`. It exposes the hosted PurposeBot MCP tools for trust-ranked
discovery, API Trust provider registration, API access decisions, signed conduct
events, pending feedback, commerce recommendations, and
interaction/settlement-backed reputation.

The hosted endpoint is the source of truth for the tool catalogue, so new tools
(`search_tools`, `submit_interaction_report`, `list_pending_feedback`,
`recommend_listings`, `create_api_trust_provider`, `request_api_trust_decision`,
`submit_api_trust_event`, ...) appear automatically. This package is only the
stdio transport bridge; the trust, identity, payment, and provenance checks run
server-side in PurposeBot.

## Usage

Requires Python 3.10+. Get an API key from your PurposeBot account.

```bash
PURPOSEBOT_API_KEY=pb_xxx python -m purposebot_mcp
```

or, after installing from PyPI:

```bash
PURPOSEBOT_API_KEY=pb_xxx purposebot-mcp
```

### Claude Desktop / Cursor (`mcpServers` config)

```json
{
  "mcpServers": {
    "purposebot": {
      "command": "purposebot-mcp",
      "env": {
        "PURPOSEBOT_API_KEY": "pb_xxx"
      }
    }
  }
}
```

## Environment

| Variable | Required | Default | Notes |
|---|---|---|---|
| `PURPOSEBOT_API_KEY` | no | - | sent as `X-API-Key`; keyless mode supports first-key registration |
| `PURPOSEBOT_API_URL` | no | `https://purposebot.ai` | origin only; use `https://api.purposebot.ai` or sandbox/self-host origin |
| `PURPOSEBOT_ALLOW_CUSTOM_HOST` | no | unset | set to `1` for non-PurposeBot self-hosts |

The wrapper validates the target URL before sending an API key. It only sends
keys to PurposeBot hosts by default, allows `http://localhost` for development,
rejects embedded credentials, and refuses HTTP redirects. Without
`PURPOSEBOT_API_KEY`, the wrapper can still call keyless MCP tools such as
`begin_registration`; protected tools return the hosted PurposeBot auth error.
