# BorrowRelay

A community lending desk that automatically offers returned items to the next person in line. A working **MCP 2025-11-25 server over Streamable HTTP**, with an operator console to inspect and exercise the same tools.

Submitted to the Alexa+ track and Open Source mini challenge of Build, Ship, Shape: Amazon Developer Hackathon on September 9, 2026: [Devpost entry](https://devpost.com/software/borrowrelay). Submission does not imply selection or an award. This project has no affiliation with Amazon and has not been tested with a live Alexa+ account.

[Watch the public demonstration](https://youtu.be/znf1J0xLYEY). The captioned video records actual local MCP responses using synthetic data. Its complete source is in `walkthrough.html`; generated video binaries are kept in the local submission package.

## Run locally

Requires Python 3.11 or newer. No cloud account, API key, paid model, device, or payment is needed.

```sh
python -m venv .venv
# Activate your environment (Windows: .venv\Scripts\activate)
# macOS/Linux: source .venv/bin/activate
python -m pip install -r requirements.txt
python server.py
```

Open http://127.0.0.1:8765/. The MCP endpoint is http://127.0.0.1:8765/mcp. The operator console itself uses JSON-RPC tool calls over this endpoint; it does not bypass the lending engine.

The database defaults to `data/demo.sqlite3`. To use a separate database, set `BORROWRELAY_DB` to a new path before starting. `BORROWRELAY_PORT` changes the loopback port. Preserve the database to keep requests and the activity log between restarts.

## A two-person walkthrough

1. Select Noa and Cordless drill. Request to borrow. Noa gets an **offer**, not a recorded pickup.
2. Click **Confirm physical pickup**. This is a demo operator confirmation using synthetic data.
3. Select Eli and Cordless drill. Request to borrow. Eli joins the queue; the drill is not double-booked.
4. Click **Confirm physical return** for Noa. The same transaction records the return and creates Eli's offer.
5. Inspect the activity log and MCP exchange. No message is sent and Eli has not automatically checked out the drill.

## Connect an agent

Point an MCP host supporting Streamable HTTP at the endpoint. `lending_board` and `activity_log` read state. `request_item`, `confirm_pickup`, `record_return`, and `cancel_request` mutate it. Schemas and usage guidance are discoverable through `tools/list`; mutation calls require an operation key.

Example intent: “Noa wants the drill. When it comes back, offer it to Eli.” An agent can call `request_item` for each member and inspect the queue. It must ask the desk operator before using `confirm_pickup` or `record_return`: an intent to borrow or return does not prove a physical handover.

The server provides the workflow tools. The local UI is a deterministic operator console, not a conversational model or a claimed Alexa integration. No LLM is bundled. A live Alexa+ connection, public deployment, voice input, email delivery and real users are not demonstrated.

## Why these state transitions matter

- A SQLite `BEGIN IMMEDIATE` transaction covers each mutation and queue promotion.
- A unique partial index permits at most one offer or borrower per item. A separate index rejects duplicate active member/item requests.
- FIFO order uses persisted request sequence, not client timestamps.
- Operation keys store both payload fingerprints and responses. Retries return the original response; reusing a key for a different operation fails.
- A return can only follow a pickup. Cancelling a borrowed item cannot silently free it.
- The next member receives an **offer awaiting pickup confirmation**. No physical custody or delivery is invented.

## Validation

```sh
python -m unittest test_domain -v
python -m unittest test_mcp -v
```

The domain tests use isolated databases and exercise simultaneous requests, FIFO promotion, failed transitions, retries and persistence. The transport test starts a temporary loopback server on port 8767, uses the official SDK client, and writes `evidence/mcp-verification.json`. Keep that port free when testing. Browser walkthrough results are recorded separately in the submission package.

## Deployment boundary

This is a single-operator local prototype with synthetic inventory and member names. It deliberately binds to loopback and uses the SDK's transport origin checks. It has no authentication or per-member authorization. Do not expose it to a network or load real personal records without implementing authentication, authorization, retention and operator access controls. The activity log is an application record, not tamper-proof evidence.

Next practical work would include real member onboarding, item condition checks, an offer expiry policy and an authenticated host integration. These are not implemented features.

## Development and rights

Created during the hackathon window with OpenAI Codex assistance under the account owner's direction. All project-specific code and visual styling were written for this entry. Synthetic people and inventory were created for the demo. The MCP Python SDK and dependencies are third-party software, installed from PyPI; see `THIRD_PARTY.md`. No sponsor funding, AWS credits, paid APIs or purchased assets were used.

MIT license. No warranties.