Metadata-Version: 2.5
Name: roost-mcp
Version: 0.2.2
Summary: Model Context Protocol server for Roost — credit underwriting and per-spend decisioning for AI agents.
Project-URL: Homepage, https://roostcapital.ai
Project-URL: Documentation, https://roostcapital.ai/docs
Project-URL: Repository, https://github.com/roostcapital/roost
Author-email: Roost <developers@roostcapital.ai>
License: Apache-2.0
Keywords: ai-agents,credit,mcp,model-context-protocol,roost,underwriting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: cryptography>=42
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: pydantic>=2
Provides-Extra: credit
Requires-Dist: roost-sdk>=0.1.0; extra == 'credit'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Provides-Extra: keychain
Requires-Dist: keyring>=24; extra == 'keychain'
Description-Content-Type: text/markdown

# Roost MCP

Model Context Protocol server for Roost. Plug it into any MCP-aware client (Claude Desktop, Claude Code, Cursor, Cline, Zed) and your agent gets shadow-era advisory decisioning plus the credit lifecycle, without any framework-specific glue.

## What it exposes

Shadow-era tools — advisory only; nothing here moves money, touches credit rails, or changes any credit-era behavior:

| Tool | What it does |
| --- | --- |
| `roost_decide` | Get an advisory pay / wait / finance verdict for a prospective payment. Call BEFORE proposing or scheduling one. |
| `roost_review_pending` | List advisory decisions awaiting human review. |
| `roost_explain_decision` | Fetch the full evidence pack behind one advisory decision. |
| `roost_resolve` | Record a human's judgment (approved / rejected / modified) on a decision. The acting identity is fixed to the server's configured operator — never an argument the calling agent supplies. |

Credit-era tools — the underwriting lifecycle:

| Tool | What it does |
| --- | --- |
| `roost_pay` | Ask Roost to approve / deny / queue-for-review a payment intent. The hot path — call before every external spend. |
| `credit_apply` | Open a credit application for the configured agent. |
| `credit_status` | Read the current credit account (status, limit, available, outstanding, terms). |
| `offer_get_active` | Fetch the latest non-expired offer. |
| `offer_accept` | Accept an offer and activate the credit line. |
| `offer_decline` | Decline an offer. |
| `roost_about` | Identify this server + surface docs / OpenAPI / llms.txt URLs (includes the list of shadow tools). |

## Install

```bash
pip install roost-mcp
# or (for ephemeral / per-invocation install):
uvx roost-mcp
```

## Configure

The server reads `ROOST_SDK_*` env vars at startup. One instance acts on behalf of one `(operator, agent)` pair — install once per agent if the operator has multiple.

Required:

- `ROOST_SDK_API_BASE` — defaults to `https://api.roostcapital.ai`.
- `ROOST_SDK_OPERATOR_API_KEY` — the operator's API credential, sent as a bearer token. For shadow-era use (`roost_decide` and the oversight tools) this is a **Personal Access Token** (`roost_pat_...`), issued via `backend/scripts/issue_api_token.py --email <operator-email>` — the raw token is printed once, to stderr; only its hash is stored server-side, so save it immediately. A PAT authenticates the shadow surface only (`/v1/decisions*`, `/v1/scoreboard`) — it is rejected on credit-era, admin, account, and auth endpoints.
- `ROOST_SDK_AGENT_ID` — agent UUID the server will act for.

Optional:

- `ROOST_SDK_OPERATOR_ID` — operator UUID. Needed for credit-era agent-direct (Ed25519-signed) calls; not required for shadow-era tools.
- `ROOST_SDK_PRIVATE_KEY_PEM` — Ed25519 private key, PEM format, used only for credit-era signing (agent-direct calls to `/roost/pay` and the credit lifecycle). The matching public key must be registered for this `(operator, agent)` pair. Not used by the shadow tools.
- `ROOST_SDK_ACTOR_LABEL` — human-readable label identifying this server instance as an actor. Used to build the pinned actor string (`mcp:<label>`) recorded on every `roost_resolve` call. Defaults to `mcp-operator`.

### Claude Desktop / Claude Code

Add to `claude_desktop_config.json` (Desktop) or your `.mcp.json` (Claude Code):

```json
{
  "mcpServers": {
    "roost": {
      "command": "uvx",
      "args": ["roost-mcp"],
      "env": {
        "ROOST_SDK_OPERATOR_API_KEY": "roost_pat_...",
        "ROOST_SDK_AGENT_ID": "8c64...",
        "ROOST_SDK_ACTOR_LABEL": "claude-desktop"
      }
    }
  }
}
```

Add `ROOST_SDK_OPERATOR_ID` and `ROOST_SDK_PRIVATE_KEY_PEM` only if you also plan to use the credit-era, agent-direct tools.

### Cursor / Cline / Zed

Each editor has its own MCP config UI, but the shape is identical — a command (`uvx roost-mcp`) plus the `ROOST_SDK_*` env vars.

## CFO oversight from Claude

A typical human-in-the-loop session: an agent has already been calling `roost_decide` before its payments, and a human wants to check what's outstanding.

```
Human:  What payment decisions are waiting on me?
Claude: [calls roost_review_pending] -> 3 decisions, including a $1,250
        payment to "New Vendor Co" with verdict "wait" (low confidence
        on vendor reputation).
Human:  Show me why it said wait.
Claude: [calls roost_explain_decision(decision_id)] -> evidence pack +
        summary: "Verdict: wait. Vendor reputation unknown. Resolution:
        unresolved."
Human:  Approve it, I've vetted this vendor separately.
Claude: [calls roost_resolve(decision_id, "approved")] -> recorded.
        The acting identity is this server's configured operator, not
        anything Claude supplied — an agent can record a human's
        judgment, but it can never claim to *be* a different human.
```

## Verify

The fastest sanity check is to call `roost_about` from your MCP client — it returns the configured `(operator, agent)` pair, the doc URLs, and the list of shadow tools. If the env vars aren't wired, the first tool call surfaces the actual config error.

## Local development

```bash
# From the repo root:
pip install -e sdk/python      # roost-sdk in editable mode
pip install -e mcp-server[dev] # roost-mcp + test deps
pytest mcp-server/tests
```

## Evidence you can open, Roost can't read

Commit each document your agent relied on with `roost_commit_evidence` before
`roost_decide`, and pass the entries as `evidence`. Roost stores only a keyed hash
and a locator sealed with your evidence key, inside the decision's signed record.
Roost can tell when two decisions cite the same document (the keyed hash is the same),
and it sees each entry's kind and time. `roost_verify_chain` detects altered, deleted or
reordered records; it cannot detect a chain cut short at the end.
Later, `roost_open_record` decrypts the locators on your machine so a person can
open the exact invoice, PO or email, and `roost_verify_evidence` confirms each one
matches. `roost_verify_chain` checks your whole record chain against Roost's
published keys.

Set up the evidence key once (32 random bytes, base64):

    python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"

Then either export it as `ROOST_EVIDENCE_KEY`, or install `roost-mcp[keychain]` and
store it in the OS keychain: `keyring set roost-evidence <your ROOST_SDK_ACTOR_LABEL>`.
Back it up: without it, locators can't be opened (commitments still verify against
a document you find another way).

## Why MCP

We ship `roost-sdk` for Python and `@roost/sdk` for TypeScript — those work standalone. MCP is the single integration point that buys the broadest surface: every MCP-aware agent runtime discovers the toolset without any framework-specific code. If your agent doesn't speak MCP yet, use the SDKs directly or wait — the framework-specific adapters (OpenAI Agents SDK, Vercel AI SDK, LangChain, CrewAI) are next on the roadmap.

## Links

- [API & SDK reference](https://roostcapital.ai/docs)
- [Markdown / agent-readable docs](https://roostcapital.ai/docs.md)
- [OpenAPI specification](https://api.roostcapital.ai/openapi.json)
- [llms.txt index](https://roostcapital.ai/llms.txt)
