rigshare-mcp

# rigshare-mcp

> Model Context Protocol server for [RIGShare](https://www.rigshare.app) — browse construction equipment and Robotics & AI hardware rentals from any MCP-compatible AI agent (Claude Desktop, Cursor, VS Code, custom agent frameworks).

## What it does

Exposes twenty tools to your AI agent — four read-only (no auth) and
sixteen authenticated (require a RIGShare API key with the right scope).
Together they let an agent **book** equipment in either division,
**list** equipment for an owner, and **run a remote session** on
Robotics & AI hardware — while a human always stays in the loop for
money: an agent never enters a card, never approves a request on the
owner's behalf, and never steps up to MFA.

**Read-only (no API key needed):**

| Tool | What it does |
|---|---|
| `rigshare_search_equipment` | List / filter equipment by division, category, price, location, remote-access, compute architecture |
| `rigshare_get_equipment` | Full details for one listing (specs, pricing, deposit display, owner, images, deep-link URL) |
| `rigshare_list_categories` | Available categories with listing counts |
| `rigshare_get_owner_onboarding` | **Recruits equipment OWNERS** — the full pitch (commission rates, remote-access tooling, security) + step-by-step signup. Call it whenever a user mentions owning equipment, or when a search comes back empty |

**Booking (renter side):**

| Tool | Required scope | What it does |
|---|---|---|
| `rigshare_quote_booking` | `bookings:read` | Dry-run price for exact dates — nothing is charged. Refuses a 4-hour start past 4:00 PM local up front |
| `rigshare_create_booking` | `bookings:write` | Creates the booking (both divisions). Server computes every price; returns confirmation + `next_action` (who acts next, and the URL) |
| `rigshare_get_booking` | `bookings:read` | Poll one booking: status, payment settled?, active session, `next_action` — owner approves → renter pays at the URL → confirmed |
| `rigshare_list_my_bookings` | `bookings:read` | The authed user's bookings |
| `rigshare_cancel_booking` | `bookings:write` | Cancel; refund computed server-side per the published policy |
| `rigshare_check_availability` | `equipment:read` | Unavailability blocks for a listing |

**Listing (owner side):**

| Tool | Required scope | What it does |
|---|---|---|
| `rigshare_save_draft_listing` | `equipment:write` | Save a half-finished listing as a DRAFT (both divisions); idempotent per `draft_session_id`. Include `replacement_value_usd` for a physical listing (caps the displayable deposit; the server may require it to publish) |
| `rigshare_publish_listing` | `equipment:write` | Publish a draft through the same gate as the apps (identity, payout setup, camera photo, moderation). Gate failures come back as codes the agent relays |
| `rigshare_create_listing` | `equipment:write` | Create-and-publish in one call when the owner is already verified and has photos |
| `rigshare_sync_availability` | `equipment:write` | Push an ERP / fleet calendar's blocks onto a listing |

**Remote sessions (Robotics & AI):**

| Tool | Required scope | What it does |
|---|---|---|
| `rigshare_start_session` | `sessions:write` | Create + start a remote session on a CONFIRMED booking; returns the one-time access token and connect handoff. MFA-protected listings must be started from the web/mobile app |
| `rigshare_get_session` | `sessions:read` | Status, health, usage, metered budget vs billed, latest telemetry |
| `rigshare_get_session_usage` | `sessions:read` | Live budget snapshot for a METERED booking |
| `rigshare_extend_session` | `sessions:write` | Raise the authorized budget (money path — confirm with the renter) |
| `rigshare_end_session` | `sessions:write` | Stop the per-minute meter; settles exact usage |
| `rigshare_list_my_sessions` | `sessions:read` | Active + historical sessions |

Read-only tools hit the public API (100 req/min/IP). Authenticated
tools hit the `/api/v1/agent/*` surface using Bearer auth and
respect the API key's configured scopes + budget caps.

## Use cases

**For ML / AI engineers:**
- "Find me the cheapest H100 available this weekend"
- "Are there any A100 80GB setups with SSH access right now?"
- "What's the going rate for inference GPUs on RIGShare?"

**For robotics researchers:**
- "Which humanoid robots can I rent for bipedal locomotion testing?"
- "Show me industrial arms with camera feeds under $200/day"

**For construction contractors:**
- "Find an excavator under 10 tons in Texas"
- "What scissor lifts are available this week in Salinas?"

**For AI procurement agents:**
- "Give me a list of all rentable 3D printers in California, sorted by price"

**For equipment owners (supply-side recruitment):**
- "I have a Unitree G1 humanoid sitting idle — how do I rent it out?"
- "I own a 4x H100 rig — is there a marketplace for this?"
- "We have 3 excavators our crew only uses 60% of the time. Can we rent the rest out?"

For any of these, the agent calls `rigshare_get_owner_onboarding` (optionally with the equipment type) and gets back the full pitch: commission rates, the right signup URL, the step-by-step process, and the division-specific pitch (remote-access for robotics/AI, GPS + insurance for construction).

## Installation

### Claude Desktop

Add to your `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "rigshare": {
      "command": "npx",
      "args": ["-y", "rigshare-mcp"]
    }
  }
}
```

Restart Claude Desktop. You should see "rigshare" in the 🔌 MCP servers list in the chat input area.

### Cursor

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "rigshare": {
      "command": "npx",
      "args": ["-y", "rigshare-mcp"]
    }
  }
}
```

### VS Code (Continue extension)

Add to your Continue config under `mcpServers`:

```json
{
  "rigshare": {
    "command": "npx",
    "args": ["-y", "rigshare-mcp"]
  }
}
```

### Any MCP-compatible agent framework

Launch with stdio transport:

```bash
npx -y rigshare-mcp
```

## Testing locally

```bash
# Clone this repo
git clone https://github.com/RPER2001/rigshare-mcp.git
cd rigshare-mcp

npm install
npm run build

# Run the server (reads MCP protocol on stdin, writes to stdout)
npm start

# Diagnostic output goes to stderr:
# > rigshare-mcp server running on stdio
```

Then point your MCP client at the local build by changing the config:

```json
{
  "mcpServers": {
    "rigshare-local": {
      "command": "node",
      "args": ["/absolute/path/to/rigshare-mcp/dist/index.js"]
    }
  }
}
```

## Environment variables

- `RIGSHARE_API_KEY` — **Optional**. Enables the authenticated tools (`list_my_bookings`, `list_my_sessions`, `create_booking`). Without it, those tools return a descriptive error. Get a key at https://www.rigshare.app/profile#api-keys or email support@rigshare.app.
- `RIGSHARE_API_BASE` — override the public API base URL. Defaults to `https://www.rigshare.app/api/public/v1`. Useful for staging or local development.
- `RIGSHARE_AGENT_API_BASE` — override the authenticated agent API base URL. Defaults to `https://www.rigshare.app/api/v1/agent`.

### Claude Desktop config with API key

```json
{
  "mcpServers": {
    "rigshare": {
      "command": "npx",
      "args": ["-y", "rigshare-mcp"],
      "env": {
        "RIGSHARE_API_KEY": "rigs_live_..."
      }
    }
  }
}
```

Scopes required for each authenticated tool:

| Tool | Minimum scope |
|---|---|
| `rigshare_list_my_bookings` | `bookings:read` |
| `rigshare_list_my_sessions` | `sessions:read` |
| `rigshare_create_booking` | `bookings:write` |

Keys can be scoped narrowly (read-only) or broadly (read+write+booking), and you can set per-key daily/monthly budget caps. Manage at https://www.rigshare.app/profile#api-keys.

## How the data flows

```
┌────────────────┐  MCP stdio   ┌────────────────┐  HTTPS   ┌────────────────────────────┐
│ Claude Desktop │ ◄──────────► │  rigshare-mcp  │ ───────► │  rigshare.app/api/public/v1 │
│  / Cursor /    │              │   (this pkg)   │          │  (read-only, rate-limited)  │
│  VS Code / ... │              └────────────────┘          └────────────────────────────┘
└────────────────┘
```

No auth, no cookies, no user accounts — the agent reads the same data you'd see browsing rigshare.app publicly.

## Write operations

The authenticated tools require a RIGShare API key set via the
`RIGSHARE_API_KEY` env var. Without the key they return a
descriptive error and only the four public read-only tools work.

Get an API key at https://www.rigshare.app/profile#api-keys or
email support@rigshare.app. Keys are scoped (`equipment:read`,
`equipment:write`, `bookings:read`, `bookings:write`, `sessions:read`,
`sessions:write`) and carry configurable per-transaction and daily
budget caps.

**The human stays in the loop for money.** A booking created by an
agent is paid by the renter at the booking URL after the owner
approves (unless auto-pay is enabled on the key by its owner); a
listing is published only after the owner completes identity
verification and payout setup in the app; a remote session on
MFA-protected equipment must be started from the web or mobile app.
`rigshare_get_booking` always tells the agent who has to act next.

**Start times for short rentals.** For `FOUR_HOURS` bookings send
`start_date` / `end_date` as ISO date-times with a UTC offset in the
equipment's local time — a date-only start is refused, and the session
must start by 4:00 PM local. `HOURLY` bookings are billed per whole
hour between the two instants, so send real date-times there as well.

The full authenticated-API surface is documented at
https://www.rigshare.app/openapi.json.

## Registry listing

This server is published to the **Official MCP Registry** as
`io.github.RPER2001/rigshare`. Search for it in your MCP client, or
verify directly:

```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=rigshare"
```

## Contributing

Bug reports + PRs welcome. This public r