Skip to content

Added Readme #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Shaurya2k06 merged 1 commit into from
Aug 2, 2026
Merged

Added Readme #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
265 changes: 230 additions & 35 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,235 @@
# Cascade
sadsd
Cascade is an iMessage-native governed commerce kernel: message → purchase contract → verified
offer → Prava passkey → checkout → receipt. The TypeScript/PostgreSQL kernel is exposed through an
authenticated Fastify MCP v2 Streamable HTTP adapter and companion web surfaces.

**From a message to a governed purchase, with the smallest safe agent topology.**

Cascade is a governed commerce kernel for agentic buying. A natural-language request becomes an immutable purchase contract; Cascade verifies one offer against approved sources, obtains bounded passkey authority through [Prava](https://prava.space), completes checkout on a tested merchant path, and returns an auditable receipt to the originating conversation or client.

Models propose. Deterministic code owns money and state. No search agent holds a wallet. No AI advances a financial state alone.

The same kernel is reachable through the web companion, authenticated MCP tools, and optional messaging adapters. The distinguishing system is not retrieval — it is the purchase contract, evidence-backed offer normalization, capability narrowing, passkey-bound authority, exact checkout reconciliation, revocation, and audit trail.

Full product and architecture specification: [`context.md`](context.md)

---

## Install Cascade MCP

Cascade exposes governed commerce as **MCP v2 Streamable HTTP**. External agents create missions, inspect offers, request spend, and read audit events **without** receiving Prava secrets, merchant credentials, or payment instruments.

| | |
| --- | --- |
| **Endpoint** | `https://cascade-3mec.onrender.com/mcp` |
| **Local** | `http://127.0.0.1:3001/mcp` (when the API is running) |
| **Auth** | `Authorization: Bearer <token>` |

The server stores **SHA-256 hashes only** (`MCP_AUTH_TOKENS_JSON`). Each token’s `audience` must exactly match `MCP_AUDIENCE` (e.g. `https://cascade-3mec.onrender.com/mcp`). Generate a hash without putting the raw token in config:

```bash
export CASCADE_RAW_TOKEN='replace-with-a-long-random-token'
node -e "console.log(require('node:crypto').createHash('sha256').update(process.env.CASCADE_RAW_TOKEN).digest('hex'))"
unset CASCADE_RAW_TOKEN
```

Local Compose uses bearer `cascade-local-dev-token` (localhost only). Confirm health before connecting clients: `GET /health/mcp`.

### Cursor

`~/.cursor/mcp.json` (or Cursor MCP settings):

```json
{
"mcpServers": {
"cascade": {
"url": "https://cascade-3mec.onrender.com/mcp",
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}
```

For local development, point `url` at `http://127.0.0.1:3001/mcp` and use your local bearer. Reload MCP after saving.

### Claude / ChatGPT

Point a custom connector at `https://<host>/mcp` with:

```text
Authorization: Bearer <your-token>
```

### Tool surface

| Tool | Purpose |
| --- | --- |
| `mission.create` | Create a mission and immutable purchase contract v1 |
| `mission.get` | Read an authorized mission and financial state |
| `mission.get_diagnostics` | Redacted search status / diagnostics |
| `mission.get_offers` | Eligible offers before select / BUY |
| `mission.cancel` | Cancel; release reservations; revoke capabilities |
| `offers.submit` | Validate, normalize, and rank candidate offers |
| `offers.select` | Select one eligible offer bound to the active contract |
| `capability.issue` | Issue a revocable, contract-bound capability |
| `spend.request` | Reserve the selected offer (amounts re-derived server-side) |
| `payment.create_session` | Create a Prava sandbox payment session + checkout URL |
| `spend.get_status` | Reservation / payment / order state |
| `ledger.get_events` | Immutable audit sequence |
| `capture.create_marketplace_mission` | Sandbox marketplace capture → mission (no payment) |

`spend.request` deliberately does not accept amount, currency, merchant, or product identity from the caller — those fields are rebound from the stored offer and active contract.

### Programmatic client

```bash
export CASCADE_MCP_ENDPOINT=https://cascade-3mec.onrender.com/mcp
export CASCADE_MCP_TOKEN=<your-token>

pnpm --filter @cascade/mcp-demo workflow:test -- \
"Find red running shoes size 9 under INR 14000"
```

`@cascade/mcp-demo` wraps `@modelcontextprotocol/client` (Streamable HTTP) with typed helpers for the tools above.

---

## The problem

Online commerce is easy to browse and hard to decide. Buyers translate vague intent into search queries, compare incomplete totals, judge seller trust, re-enter constraints across sites, coordinate money with other people, and still leave the conversation to complete checkout — often without knowing what an AI assistant is actually allowed to spend.

Shopping agents optimize retrieval. Payment products optimize transfer. Group planners optimize discussion. Cascade connects all three with explicit authority boundaries:

1. **Intent becomes a contract.**
2. **Research becomes evidence-backed offers.**
3. **Authority becomes a bounded, revocable capability.**
4. **The purchase becomes a deterministic state machine.**
5. **The receipt returns to where the intent originated.**

---

## Core principles

### Smallest safe topology

Cascade does not run a fixed multi-agent swarm. A deterministic router selects one of four execution modes:

| Mode | When |
| --- | --- |
| **Solo** | Clear, low-risk, one-person purchase |
| **Guarded Cell** | Independent evidence or failure isolation improves the answer |
| **Shared Coordinator** | Open collaboration with shared context |
| **Federated Group** | Private budgets, vetoes, or external personal agents |

A component is a separate agent only when it has a different owner, private context, independent authority, a trust boundary, fault containment needs, or speaks through MCP. “Price agent” and “review agent” are usually functions — not principals.

### Deterministic systems own money and state

Topology routing, contract versioning, policy, reservations, idempotency, Prava gateway, checkout state machine, revocation, and the audit log are **services**, never models. Models may extract intent, search, summarize evidence, or propose a ranking. Typed code validates every financial transition.

### Honest commerce claims

- Final price is confirmed at checkout, not inferred from search.
- Live price and availability come from the merchant path — not from knowledge grounding.
- A Prava payment session grants bounded purchase authority; it is **not** an order.
- “Works at any merchant” is forbidden; only tested adapters and verified Prava/UCP paths.
- Authorization is never silently overspent when a quote drifts.

---

## Product modes

| Mode | Behavior |
| --- | --- |
| **Buy Now** | One ask → verified recommendation (+ alternatives) → BUY → bounded Prava session → checkout → receipt |
| **Group Decision** | Private constraint capsules; coordinator sees only the minimum envelope for a feasible proposal |
| **Watch & Buy** | Arm a quote watch; notify or require a fresh passkey when conditions hold — never unbounded automation |
| **Cascade MCP** | External agents request governed commerce without holding credentials, policy engines, or checkout state |

Signature path:

> Find these red ASICS Gel-Kayano in size 9 under ₹14,000. Prefer delivery before Friday.

Cascade returns one best valid offer, explains why it won, discloses material trade-offs, and presents BUY. Passkey approval scopes merchant and amount. Checkout runs through a tested path; the receipt and audit trail close the mission.

---

## Architecture

```text
Web companion · MCP clients · messaging adapters
│
▼
┌─────────────────────┐
│ Cascade kernel │
│ contracts · policy │
│ ledger · topology │
│ LangGraph orches. │
└─────────┬───────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Merchants Senso Prava
(quotes) (evidence) (passkey auth)
```

One TypeScript monorepo: Fastify API + worker, PostgreSQL ledger, LangGraph for durable orchestration, companion web for approval/audit/demo. Channels are adapters around the same domain services — MCP is the platform boundary, not a slide-only integration.

| Layer | Stack |
| --- | --- |
| Surfaces | Web companion, Cascade MCP (Streamable HTTP), optional Linq messaging |
| Kernel | TypeScript, Fastify, LangGraph, Postgres |
| Commerce | Merchant adapters, Senso grounding, Prava REST / Prava MCP shopping |

### Repository

```text
apps/server API, Cascade MCP, worker
apps/web Landing, chat, demo, payment return
apps/mcp-demo External MCP client + workflow runners
packages/
contracts Shared schemas and MCP tool catalog
domain Deterministic purchase / ledger kernel
agents Orchestration and intent extraction
db Migrations and Postgres access
integrations/ prava · senso · merchants · linq
```

---

## Outbound Prava MCP (shopping)

Cascade’s **outbound** client to Prava shopping MCP is separate from the Cascade MCP server agents connect to. REST `sk_test_*` keys do not authorize Prava MCP.

```bash
corepack enable
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm test:integration
pnpm build
pnpm --filter @cascade/prava mcp:login # one-time OAuth; paste PRAVA_MCP_* into env
pnpm --filter @cascade/prava mcp:refresh # access tokens expire ~10 minutes
```

For the quickest local start, `docker compose up --build` runs PostgreSQL, migrations, and the API.
See [`build.md`](build.md) for environment variables, native commands, container operation, and
Render deploy notes.

### What is implemented

- **Kernel + MCP** — mission, offers, capability, spend, ledger tools with audience/scope enforcement
- **Discovery** — durable jobs, Senso evidence filtering, merchant adapters, Prava MCP shopping quotes,
OpenAI intent extraction, LangGraph workflow
- **Payments** — Prava REST sandbox sessions and Prava MCP payment sessions; `shop_checkout` stays
sandbox-gated until an approved Prava sandbox MCP hostname exists
- **Linq + web** — webhook ingress/outbox, companion mission/audit/payment-return pages, landing
- **Groups + watch** — private capsules, federated/shared coordinators, watch scheduling (mandate
auto-charge remains fail-closed)

Public MCP (whendeployed): `https://cascade-3mec.onrender.com/mcp`.

See [`plan.md`](plan.md) for ownership and Phase 7 launch gates. See
[`docs/LAUNCH_CHECKLIST.md`](docs/LAUNCH_CHECKLIST.md) for operator steps only you can do
(secrets, OAuth, Linq, live rehearsals).
sdaasda
a
sda
Quote path: `shop_search → shop_product → shop_quote`. Keep `PRAVA_MCP_CHECKOUT_ENABLED=false` until an approved sandbox MCP hostname exists; hosted production MCP hosts are rejected for checkout.

---

## Non-negotiables

- SHA-256 of MCP bearer tokens only — never raw tokens in config or git.
- Provider secrets never appear in browser `VITE_*` vars or MCP responses.
- Authorization ≠ order; checkout and receipt are separate states.
- “Verified by Senso” means grounded in approved ingested sources — not a live-price oracle.
- Mandate auto-charge remains fail-closed until a tested provider contract exists.

---

## Further reading

| Document | Contents |
| --- | --- |
| [`context.md`](context.md) | Full product, architecture, contracts, demo scripts, judge Q&A |
| [`build.md`](build.md) | Environment variables, local/deploy runbooks, provider harnesses |
| [`docs/LAUNCH_CHECKLIST.md`](docs/LAUNCH_CHECKLIST.md) | Operator secrets, OAuth, live rehearsals |
| [`plan.md`](plan.md) | Ownership and phase gates |

---

## License

Private repository. All rights reserved unless otherwise noted.
Loading
Loading