# LabLoop MCP (demo)

<!-- mcp-name: io.github.lorkorblaq/labloop-mcp -->

An **unofficial, fictional** [Model Context Protocol](https://modelcontextprotocol.io) server that
demonstrates a complete, multi-step booking flow for medical lab tests:

**search → compare prices → quote → confirm booking → escalate to a human**

> **Everything here is fake.** Tests, test centers, prices ("credits"), bookings, profiles, and
> escalation tickets are fictional and held in memory. The server makes **no network calls**,
> needs **no credentials**, and never books, charges, or messages anyone. It is not medical
> advice and is not affiliated with any real healthcare provider.

## Why this exists

This server is a reference for designing tools that LLMs can chain reliably:

- **Rules live next to arguments.** Guidance like "strip filler words before searching" or "use
  the exact id from a prior lookup" sits in each parameter's description instead of a long
  system prompt.
- **Two-step writes.** The booking tool returns a full quote first (`needs_confirmation`) and only
  books when it is called again with `confirm=true` after the user agrees. A quote leaves no state
  behind.
- **Actionable non-happy paths.** Results carry a `status` (`ambiguous`, `not_found`,
  `needs_info` with a `missing` list, `invalid_test_id`) plus a message telling the model what to
  do next, instead of a bare error.
- **Graceful degradation.** Each test in a multi-test order falls back to its cheapest center
  when the preferred one doesn't offer it (flagged with `providerFallback`), and tests that can't
  be resolved are reported in `skipped_tests` without failing the whole order.
- **Small surface.** The only runtime dependencies are `mcp` and `pydantic`.

## Tools

| Tool | What it does | Read-only |
|---|---|---|
| `labloop_list_tests` | List the full catalog (id, name, abbreviation, category) | yes |
| `labloop_find_test` | Find a test by name or abbreviation; handles ambiguous matches and fuzzy suggestions | yes |
| `labloop_get_test_providers` | Test centers and prices for one test, cheapest first | yes |
| `labloop_quote_or_book_collection` | Quote (`confirm=false`) or book (`confirm=true`) a home sample collection for one or more tests | no |
| `labloop_get_user_profile` | Read saved demo contact details | yes |
| `labloop_update_user_profile` | Save demo contact details for reuse in later bookings | no |
| `labloop_escalate_to_human` | Simulated hand-off to a human agent; logs a ticket in memory | no |

## Install and run

Requires Python 3.10+. The server speaks MCP over stdio.

```bash
pip install labloop-mcp        # or: uvx labloop-mcp
labloop-mcp
```

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "labloop": { "command": "uvx", "args": ["labloop-mcp"] }
  }
}
```

With Claude Code: `claude mcp add labloop -- uvx labloop-mcp`

### Try it with MCP Inspector

```bash
npx @modelcontextprotocol/inspector uvx labloop-mcp
```

## Example conversation flow

1. *"How much is a thyroid test?"* → `labloop_find_test(name="thyroid")` → `labloop_get_test_providers(test_id="tst-thyroid")`
2. *"Book it with a lipid panel for next Monday at 9am, 12 Willow Ave."*
   → `labloop_quote_or_book_collection(test_ids=["tst-thyroid","tst-lipid-panel"], user_id="demo-user-1", date_time="…", address="12 Willow Ave", phone_number="+15550000001")`
   → returns `needs_confirmation` with the combined quote
3. *"Yes, go ahead."* → the same call with `confirm=true` → `successful`, with simulated `collectionId`/`schedulingId`
4. *"This is wrong, I want a person."* → `labloop_escalate_to_human(...)`

## Security and privacy

- No secrets, API keys, or environment variables are required or read.
- No outbound network access. All state is in process memory and is cleared on restart.
- Every input is validated by Pydantic before it reaches the tool logic (E.164 phone numbers, email
  format, length limits).
- Don't enter real personal data; this is a demo.

## Development

```bash
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest
python scripts/smoke_test.py      # drives the server over stdio end-to-end
```

## License

MIT