receipts-mcp 0.1.1__tar.gz

receipts_mcp-0.1.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include receipts_mcp/upstreams.json.example
+include receipts_mcp/README.md

receipts_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: receipts-mcp
+Version: 0.1.1
+Summary: MCP proxy that records and cryptographically signs AI agent tool calls
+Author-email: Shreyansh <shreyanshkanojia104@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Shreyansh-Kanojiaa/receipts
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.2.0
+
+# Receipts MCP Proxy
+
+`receipts_mcp/` is a stdio MCP server that sits between an MCP client and one or more upstream MCP servers.
+
+For each tool call:
+
+1. The client calls the Receipts proxy.
+2. The proxy forwards the call to the real upstream MCP server.
+3. The real output is captured.
+4. The proxy POSTs that result to `POST /tools/record` on the Receipts backend.
+5. The real result is returned to the client even if receipting fails.
+
+Upstream tools are namespaced as `<server>__<tool>` so collisions do not clobber each other.
+
+If no upstream config file exists, the proxy falls back to the built-in demo tools:
+
+- `write_file`
+- `http_fetch`
+- `db_query`
+
+Those demo tools are forwarded to the backend's `/tools/call` endpoint.
+
+## Setup
+
+```bash
+pip install receipts-mcp
+cp upstreams.json.example upstreams.json
+```
+
+## Configuration
+
+`receipts_mcp/config.py` reads environment variables and an upstreams JSON file.
+
+Environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `RECEIPTS_URL` | `http://localhost:8000` | Receipts backend URL |
+| `RECEIPTS_API_KEY` | empty | Proxy-role API key used for `/tools/record` |
+| `UPSTREAMS_PATH` | `receipts_mcp/upstreams.json` | Path to upstream config |
+| `TOOL_TIMEOUT_SECONDS` | `60` | Max time for an upstream tool call |
+| `RECORD_TIMEOUT_SECONDS` | `5` | Max time for backend receipting |
+
+The upstreams file supports:
+
+- `stdio`
+- `sse`
+- `streamable_http`
+
+`${ENV_VAR}` references inside `env` and `headers` are expanded from the process environment.
+
+Example:
+
+```json
+{
+  "include_demo_tools": false,
+  "upstreams": {
+    "github": {
+      "transport": "stdio",
+      "command": "/path/to/github-mcp",
+      "args": [],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Claude Code / Cursor config
+
+Add this to `~/.claude/claude_mcp_config.json` or the equivalent Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "receipts": {
+      "command": "/home/shreyansh/receipts/.venv/bin/python3",
+      "args": ["-m", "receipts_mcp.server"],
+      "cwd": "/home/shreyansh/receipts",
+      "env": {
+        "RECEIPTS_URL": "http://localhost:8000",
+        "RECEIPTS_API_KEY": "<proxy-key>",
+        "UPSTREAMS_PATH": "receipts_mcp/upstreams.json",
+        "PYTHONPATH": "/home/shreyansh/receipts"
+      }
+    }
+  }
+}
+```
+
+Restart the MCP client after changing the config.
+
+## Runtime behavior
+
+- One proxy process gets one `mcp-<hex>` session ID.
+- All tool calls from that process share that session so they can be reconciled together.
+- If the backend is unreachable, the tool result still returns and the receipt is skipped.
+- If the backend rejects the API key, the proxy logs it as a configuration error.
+
+## Run
+
+```bash
+python3 -m receipts_mcp
+```
+
+or
+
+```bash
+python3 -m receipts_mcp.server
+```

receipts_mcp-0.1.1/README.md

@@ -0,0 +1,334 @@
+# Receipts
+
+Receipts is a verification layer between an AI agent and the tools it uses.
+
+Flow:
+
+`Agent -> Receipts MCP proxy -> upstream MCP server(s) -> Receipts backend -> dashboard`
+
+The proxy forwards real tool calls to real upstream MCP servers, captures the real output, and sends that result to the backend to be signed as a receipt. The backend stores receipts, verifies signatures, reconciles agent claims against stored output, and tracks session state. The React dashboard shows the ledger, sessions, reconciliation flow, alert rules, help, and settings in real time.
+
+The repo also includes a built-in demo path so a fresh checkout works without any external MCP server. In demo mode the backend executes three mock tools, and the proxy can fall back to those same tools when no upstreams are configured.
+
+![Live Ledger](docs/live-ledger-2.png)
+
+## What is in the repo
+
+- `backend/` — FastAPI API, SQLite persistence, auth, signing, verification, alert delivery (webhook/email/Slack), structured logging, rate limiting, and demo tool execution
+- `receipts_mcp/` — stdio MCP proxy that fronts upstream MCP servers and records receipts
+- `frontend/` — React + Vite dashboard (single SPA, sidebar navigation, dark theme)
+- `tests/` — backend verification, session lifecycle, auth, and MCP proxy integration tests
+- `demo_agent.py` — CLI demo client that exercises all three verdict modes
+- `test_mcp.py` — smoke test against a live backend
+
+## Stack
+
+- Backend: Python 3.12, FastAPI, SQLite, Pydantic v2, slowapi (rate limiting)
+- Frontend: React 19, Vite 8, Tailwind 3 (CSS utilities only — the dashboard is inline-styled)
+- MCP proxy: `mcp` Python SDK, `httpx`
+- Signing: HMAC-SHA256 over canonical receipt fields (`json.dumps(sort_keys=True)`)
+- Auth: bearer API keys with `viewer`, `proxy`, and `admin` roles (SHA-256 hashed in DB)
+- Logging: structured JSON logs via stdlib logging (configurable level and format)
+
+## Quick start
+
+```bash
+# 1. Install Python dependencies from the repo root
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# Or install just the MCP proxy from PyPI
+pip install receipts-mcp
+
+# 2. Start the backend in development mode
+cd backend
+RECEIPT_SECRET=dev-secret \
+API_KEYS="dashboard:viewer:devviewer,proxy:proxy:devproxy" \
+python3 -m uvicorn main:app --reload
+
+# 3. Start the frontend in another terminal
+cd frontend
+npm install
+echo "VITE_RECEIPTS_VIEWER_KEY=devproxy" > .env.local
+npm run dev
+```
+
+- Backend: http://localhost:8000
+- API docs: http://localhost:8000/docs
+- Frontend: http://localhost:5173
+
+`VITE_RECEIPTS_VIEWER_KEY` should point at a `proxy` role key during local development because the dashboard can run reconciliation, which uses write endpoints.
+
+## Configuration
+
+The main environment variables live in [`.env.example`](.env.example).
+
+Important ones:
+
+| Variable | Purpose |
+|---|---|
+| `ENVIRONMENT` | `development` or `production` |
+| `RECEIPT_SECRET` | HMAC signing key, required in production (≥16 chars) |
+| `DATABASE_URL` | SQLite URL today (`sqlite:///./receipts.db`), Postgres-ready form |
+| `API_KEYS` | comma-separated `label:role:rawkey` bootstrap entries |
+| `ENABLE_DEMO_TOOLS` | enables the mock `/tools/call` path |
+| `CORS_ORIGINS` | allowed frontend origin(s), `*` for dev |
+| `LOG_LEVEL` | logging level (`INFO`, `DEBUG`, etc.) |
+| `LOG_JSON` | `true` for structured JSON log output |
+| `RATE_LIMIT` | global per-IP rate limit (e.g. `120/minute`) |
+| `RECEIPTS_URL` | backend URL for the MCP proxy |
+| `RECEIPTS_API_KEY` | proxy-role key for the MCP proxy |
+| `UPSTREAMS_PATH` | upstream MCP server config for the proxy |
+| `VITE_BACKEND_URL` | frontend build-time backend URL |
+| `VITE_RECEIPTS_VIEWER_KEY` | frontend dev-time API key |
+| `RECEIPTS_PROXY_KEY` | nginx-injected key for the production frontend container |
+
+## Backend
+
+### Modules
+
+| File | Purpose |
+|---|---|
+| `main.py` | FastAPI routes, lifespan startup, timeout loop, alerts, demo run |
+| `database.py` | SQLite schema, CRUD, session state, alert rules, API keys |
+| `signer.py` | canonical hashing, HMAC signing, receipt assembly |
+| `verifier.py` | claim verification and session verdict derivation |
+| `auto_verify.py` | signature-only verification for session close / inactivity |
+| `alerts.py` | webhook, email (SMTP/STARTTLS), and Slack alert delivery |
+| `auth.py` | bearer / X-API-Key auth, role hierarchy, bootstrap key seeding |
+| `settings.py` | pydantic-settings env-based config with production safety checks |
+| `tools.py` | built-in demo tools (`write_file`, `http_fetch`, `db_query`) |
+| `models.py` | Pydantic v2 request / response schemas |
+| `logging_config.py` | structured JSON logging with context fields |
+| `Dockerfile` | production container with healthcheck |
+
+### Endpoints
+
+| Endpoint | Auth | Description |
+|---|---|---|
+| `POST /tools/record` | proxy | sign and store an already-executed tool call |
+| `POST /tools/call` | proxy | demo-only mock tool execution (gated by `ENABLE_DEMO_TOOLS`) |
+| `POST /verify` | proxy | compare claimed outputs against stored receipts |
+| `GET /sessions` | viewer | list sessions |
+| `GET /sessions/{id}` | viewer | session detail |
+| `POST /sessions/{id}/close` | proxy | close a session and schedule auto-verify |
+| `POST /sessions/{id}/verify-claim` | proxy | full-claim reconciliation with verdict persistence |
+| `GET /receipts/all` | viewer | all receipts (paginated by limit) |
+| `GET /receipts/{session_id}` | viewer | receipts for a session |
+| `GET /stats` | viewer | aggregate receipt and session counts |
+| `GET /alerts` | viewer | list alert rules |
+| `POST /alerts` | proxy | create an alert rule |
+| `GET /alerts/{id}` | viewer | get an alert rule |
+| `PATCH /alerts/{id}` | proxy | update an alert rule |
+| `DELETE /alerts/{id}` | proxy | delete an alert rule |
+| `POST /alerts/{id}/test` | proxy | send a test alert |
+| `POST /demo/run` | proxy | run a built-in demo scenario |
+| `GET /healthz` | none | liveness probe |
+| `GET /readyz` | none | readiness probe (checks DB) |
+
+### Verification
+
+Verification has two scopes:
+
+- **`signature_only`** — automatic on session close or 30-second inactivity sweep. Checks receipt HMAC integrity only. Can detect `TAMPERED` but cannot tell whether the agent lied about the tool output.
+- **`full_claim`** — manual reconciliation or `/demo/run`. Compares agent claims against stored receipts and can return `VERIFIED`, `CONTRADICTED`, `UNVERIFIED`, or `TAMPERED`.
+
+A `full_claim` verdict is never overwritten by a later `signature_only` sweep. The `verify-claim` endpoint has a guard: if a full_claim verdict already exists, it returns the stored verdict instead of re-running (which would use stored receipts as the claim source and always collapse to VERIFIED). Pass `?force=true` to override this guard.
+
+Sessions are auto-closed by a background timeout loop (configurable via `INACTIVITY_TIMEOUT_SECONDS`). Closed sessions are then auto-verified, and the dashboard labels signature-only verdicts as such.
+
+### Auth
+
+Three roles with a hierarchy: `viewer` < `proxy` < `admin`. A key satisfies any requirement at or below its level.
+
+- `viewer` — read-only dashboard access (stats, receipts, sessions, alert listing)
+- `proxy` — record receipts, run verification, manage alerts
+- `admin` — everything
+
+Keys are presented as `Authorization: Bearer <key>` or `X-API-Key: <key>`. Only SHA-256 hashes are stored in the `api_keys` table; raw keys live only in the operator's env/secret store.
+
+Bootstrap keys from the `API_KEYS` env var are seeded on first startup when the table is empty.
+
+### Alerts
+
+Alert rules fire on verdict events. Each rule specifies a trigger (`CONTRADICTED`, `TAMPERED`, `UNVERIFIED`, or `ANY`) and a delivery channel:
+
+![Slack alert channel receiving CONTRADICTED verdicts in real time](docs/slack-alerts.png)
+
+![Email alert for a CONTRADICTED session — includes session ID, tool, receipt ID, and HMAC signature](docs/email-alert.png)
+
+- **Webhook** — POST a JSON payload to a URL
+- **Email** — SMTP/STARTTLS delivery (Gmail App Passwords, Alertmanager, etc.)
+- **Slack** — POST to an Incoming Webhook URL with Block Kit formatting
+
+### Rate limiting
+
+Global per-client-IP rate limiting via slowapi (default: `120/minute`, configurable via `RATE_LIMIT`).
+
+## Dashboard
+
+The frontend is a single dashboard SPA with a fixed sidebar. It has these views:
+
+| View | Description |
+|---|---|
+| **Live Ledger** | Real-time receipt stream with stats, filtering (verdict/time/search), pagination, and new-row highlighting |
+| **Sessions** | Session registry with status, scope, duration, receipt count, and verdict |
+| **Reconciliation** | Full-claim verification interface — select a session, run validation, view per-receipt cards with field-level match status |
+| **Alerts** | CRUD for alert rules — multi-step creation wizard, enable/disable toggle, test delivery, delete |
+| **Help** | Setup guides for Claude Code, Cursor, Slack, Gmail, Alertmanager, and custom webhooks |
+| **Settings** | System config display and raw hash toggle |
+
+The Live Ledger polls `/stats`, `/receipts/all`, and `/sessions` every 3 seconds. Reconciliation can be launched from the ledger or sessions view, and the dashboard can export a JSON audit report.
+
+Design: dark theme with JetBrains Mono + Inter fonts, monochrome surfaces, color-coded status indicators (green=verified, amber=contradicted, red=tampered/unverified, blue=open/active), no emojis. JSON code blocks in Help are syntax-highlighted (keys blue, string values green, numbers amber).
+
+## Demo agent
+
+```bash
+python3 demo_agent.py --mode normal
+python3 demo_agent.py --mode lying
+python3 demo_agent.py --mode replit
+```
+
+- `normal` — claims match receipts, so the run is `VERIFIED`
+- `lying` — claims are fabricated, so the run is `UNVERIFIED`
+- `replit` — the claim does not match what actually ran, so the run is `CONTRADICTED`
+
+The demo agent uses `RECEIPTS_URL` (default `http://localhost:8000`) and `RECEIPTS_API_KEY` (default `devproxy`).
+
+## MCP proxy
+
+```bash
+pip install receipts-mcp
+```
+
+`receipts_mcp/` is a stdio MCP server that aggregates upstream MCP servers, namespaces tools as `<server>__<tool>`, forwards calls to the real upstream, and posts the real output to `/tools/record`.
+
+If `receipts_mcp/upstreams.json` does not exist, the proxy falls back to the built-in demo tools:
+
+- `write_file`
+- `http_fetch`
+- `db_query`
+
+Supported upstream transports: `stdio`, `sse`, `streamable_http`.
+
+`${ENV_VAR}` references inside upstream configs are expanded from the process environment at runtime.
+
+Each proxy process uses one `mcp-<hex>` session ID.
+
+The real result is ALWAYS returned to the agent, even if receipting fails — a backend outage must not break the agent's tools. A 401 (misconfigured key) is logged loudly.
+
+### Example upstream config
+
+See [`receipts_mcp/upstreams.json.example`](receipts_mcp/upstreams.json.example):
+
+```json
+{
+  "upstreams": {
+    "filesystem": {
+      "transport": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
+      "env": {}
+    },
+    "github": {
+      "transport": "streamable_http",
+      "url": "https://mcp.internal.example.com/github",
+      "headers": { "Authorization": "Bearer ${GITHUB_MCP_TOKEN}" }
+    }
+  },
+  "include_demo_tools": false
+}
+```
+
+### Claude Code / Cursor config
+
+![Receipts MCP server connected in Cursor — write_file, http_fetch, db_query tools visible](docs/cursor-mcp.png)
+
+```json
+{
+  "mcpServers": {
+    "receipts": {
+      "command": "/home/shreyansh/receipts/.venv/bin/python3",
+      "args": ["-m", "receipts_mcp.server"],
+      "cwd": "/home/shreyansh/receipts",
+      "env": {
+        "RECEIPTS_URL": "http://localhost:8000",
+        "RECEIPTS_API_KEY": "<proxy-key>",
+        "UPSTREAMS_PATH": "receipts_mcp/upstreams.json",
+        "PYTHONPATH": "/home/shreyansh/receipts"
+      }
+    }
+  }
+}
+```
+
+### Proxy settings
+
+| Variable | Default | Description |
+|---|---|---|
+| `RECEIPTS_URL` | `http://localhost:8000` | Backend base URL |
+| `RECEIPTS_API_KEY` | none | Proxy-role key for `/tools/record` |
+| `UPSTREAMS_PATH` | `receipts_mcp/upstreams.json` | Upstream config file |
+| `RECORD_TIMEOUT_SECONDS` | `5.0` | Backend POST timeout |
+| `TOOL_TIMEOUT_SECONDS` | `60.0` | Upstream tool-call timeout |
+
+## Tests
+
+```bash
+python -m pytest
+```
+
+The test suite covers:
+
+- **`tests/test_verification.py`** — verification logic, session lifecycle, auto-verify (VERIFIED/TAMPERED/empty), session timeout detection, explicit close endpoint, `/tools/record` signing, and auth enforcement (401/403/200 per role)
+- **`tests/test_proxy.py`** — real upstream MCP server via `tests/fixtures/mock_upstream.py`, proxy forwarding and receipting, namespacing, error handling
+- **`test_mcp.py`** — smoke test against a live backend (receipting path, session visibility, auth enforcement)
+
+Tests use isolated temporary SQLite databases via `tmp_path` fixtures.
+
+## Docker
+
+The repo includes `docker-compose.yml` for a production-style single-tenant deployment:
+
+- **backend** on port `8000` — Python 3.12, uvicorn, SQLite in a Docker volume, healthcheck on `/healthz`
+- **frontend** on port `8080` — Node 20 build stage, nginx 1.27 serving stage with API reverse proxy; nginx injects the `PROXY_KEY` header so the JS bundle never contains credentials
+
+```bash
+# Copy and fill in secrets
+cp .env.example .env
+# Edit .env: set RECEIPT_SECRET, API_KEYS, RECEIPTS_PROXY_KEY
+
+docker compose up --build
+```
+
+SQLite data is persisted in the `receipts-data` Docker volume.
+
+## Architecture
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌──────────────────┐
+│  AI Agent   │────▶│  Receipts MCP    │────▶│  Upstream MCP    │
+│ (Claude,    │     │  Proxy (stdio)   │     │  Server(s)       │
+│  Cursor)    │     │                  │     │  (real tools)    │
+└─────────────┘     └──────┬───────────┘     └──────────────────┘
+                           │ POST /tools/record
+                    ┌──────▼───────────┐
+                    │  Receipts        │
+                    │  Backend         │
+                    │  (FastAPI)       │
+                    │  ┌────────────┐  │
+                    │  │  SQLite    │  │
+                    │  │  receipts  │  │
+                    │  │  sessions  │  │
+                    │  │  api_keys  │  │
+                    │  │  alerts    │  │
+                    │  └────────────┘  │
+                    └──────┬───────────┘
+                           │ /stats, /receipts, /sessions
+                    ┌──────▼───────────┐
+                    │  Dashboard       │
+                    │  (React SPA)     │
+                    └──────────────────┘
+```

receipts_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "receipts-mcp"
+version = "0.1.1"
+description = "MCP proxy that records and cryptographically signs AI agent tool calls"
+readme = "receipts_mcp/README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Shreyansh", email = "shreyanshkanojia104@gmail.com" }]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic-settings>=2.2.0",
+]
+
+[project.scripts]
+receipts-mcp = "receipts_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/Shreyansh-Kanojiaa/receipts"
+
+[tool.setuptools.packages.find]
+include = ["receipts_mcp*"]
+
+[tool.setuptools.package-data]
+receipts_mcp = ["upstreams.json.example"]

receipts_mcp-0.1.1/receipts_mcp/README.md

@@ -0,0 +1,111 @@
+# Receipts MCP Proxy
+
+`receipts_mcp/` is a stdio MCP server that sits between an MCP client and one or more upstream MCP servers.
+
+For each tool call:
+
+1. The client calls the Receipts proxy.
+2. The proxy forwards the call to the real upstream MCP server.
+3. The real output is captured.
+4. The proxy POSTs that result to `POST /tools/record` on the Receipts backend.
+5. The real result is returned to the client even if receipting fails.
+
+Upstream tools are namespaced as `<server>__<tool>` so collisions do not clobber each other.
+
+If no upstream config file exists, the proxy falls back to the built-in demo tools:
+
+- `write_file`
+- `http_fetch`
+- `db_query`
+
+Those demo tools are forwarded to the backend's `/tools/call` endpoint.
+
+## Setup
+
+```bash
+pip install receipts-mcp
+cp upstreams.json.example upstreams.json
+```
+
+## Configuration
+
+`receipts_mcp/config.py` reads environment variables and an upstreams JSON file.
+
+Environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `RECEIPTS_URL` | `http://localhost:8000` | Receipts backend URL |
+| `RECEIPTS_API_KEY` | empty | Proxy-role API key used for `/tools/record` |
+| `UPSTREAMS_PATH` | `receipts_mcp/upstreams.json` | Path to upstream config |
+| `TOOL_TIMEOUT_SECONDS` | `60` | Max time for an upstream tool call |
+| `RECORD_TIMEOUT_SECONDS` | `5` | Max time for backend receipting |
+
+The upstreams file supports:
+
+- `stdio`
+- `sse`
+- `streamable_http`
+
+`${ENV_VAR}` references inside `env` and `headers` are expanded from the process environment.
+
+Example:
+
+```json
+{
+  "include_demo_tools": false,
+  "upstreams": {
+    "github": {
+      "transport": "stdio",
+      "command": "/path/to/github-mcp",
+      "args": [],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Claude Code / Cursor config
+
+Add this to `~/.claude/claude_mcp_config.json` or the equivalent Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "receipts": {
+      "command": "/home/shreyansh/receipts/.venv/bin/python3",
+      "args": ["-m", "receipts_mcp.server"],
+      "cwd": "/home/shreyansh/receipts",
+      "env": {
+        "RECEIPTS_URL": "http://localhost:8000",
+        "RECEIPTS_API_KEY": "<proxy-key>",
+        "UPSTREAMS_PATH": "receipts_mcp/upstreams.json",
+        "PYTHONPATH": "/home/shreyansh/receipts"
+      }
+    }
+  }
+}
+```
+
+Restart the MCP client after changing the config.
+
+## Runtime behavior
+
+- One proxy process gets one `mcp-<hex>` session ID.
+- All tool calls from that process share that session so they can be reconciled together.
+- If the backend is unreachable, the tool result still returns and the receipt is skipped.
+- If the backend rejects the API key, the proxy logs it as a configuration error.
+
+## Run
+
+```bash
+python3 -m receipts_mcp
+```
+
+or
+
+```bash
+python3 -m receipts_mcp.server
+```

receipts_mcp-0.1.1/receipts_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Receipts MCP proxy — cryptographic receipting for AI agent tool calls."""
+
+__version__ = "0.1.1"

receipts_mcp-0.1.1/receipts_mcp/__main__.py

@@ -0,0 +1,3 @@
+from receipts_mcp.server import main
+
+main()

receipts_mcp-0.1.1/receipts_mcp/config.py

@@ -0,0 +1,79 @@
+"""Configuration for the Receipts MCP proxy.
+
+Two inputs:
+  1. Environment (via pydantic-settings): where the Receipts backend is and the API
+     key to authenticate to it.
+  2. An upstreams file (JSON): the company's real MCP servers to front. Format mirrors
+     the familiar ``mcpServers`` convention. ``${ENV_VAR}`` references inside ``env`` and
+     ``headers`` are expanded from the process environment so upstream secrets are never
+     committed to the file.
+"""
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from mcp.client.stdio import StdioServerParameters
+from mcp.client.session_group import SseServerParameters, StreamableHttpParameters
+
+_ENV_REF = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+class ProxySettings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore", case_sensitive=False)
+
+    receipts_url: str = "http://localhost:8000"
+    receipts_api_key: str | None = None          # proxy-role key for /tools/record
+    upstreams_path: str = "receipts_mcp/upstreams.json"
+    record_timeout_seconds: float = 5.0          # backend POST timeout
+    tool_timeout_seconds: float = 60.0           # upstream tool-call timeout
+
+
+def _expand(value: Any) -> Any:
+    """Recursively expand ${ENV_VAR} references in strings."""
+    if isinstance(value, str):
+        return _ENV_REF.sub(lambda m: os.environ.get(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: _expand(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand(v) for v in value]
+    return value
+
+
+def load_upstreams(path: str) -> tuple[dict[str, Any], bool]:
+    """Load and validate the upstreams file.
+
+    Returns ``(server_params_by_key, include_demo_tools)`` where each value is an
+    SDK params object ready for ``ClientSessionGroup.connect_to_server``.
+    """
+    p = Path(path)
+    if not p.exists():
+        return {}, False
+    data = json.loads(p.read_text())
+    include_demo = bool(data.get("include_demo_tools", False))
+
+    result: dict[str, Any] = {}
+    for key, spec in (data.get("upstreams") or {}).items():
+        spec = _expand(spec)
+        transport = (spec.get("transport") or "stdio").lower()
+        if transport == "stdio":
+            result[key] = StdioServerParameters(
+                command=spec["command"],
+                args=spec.get("args", []),
+                env={**os.environ, **spec.get("env", {})} if spec.get("env") else None,
+                cwd=spec.get("cwd"),
+            )
+        elif transport == "sse":
+            result[key] = SseServerParameters(
+                url=spec["url"], headers=spec.get("headers"),
+            )
+        elif transport in ("streamable_http", "http"):
+            result[key] = StreamableHttpParameters(
+                url=spec["url"], headers=spec.get("headers"),
+            )
+        else:
+            raise ValueError(f"upstream '{key}': unknown transport '{transport}'")
+    return result, include_demo