# iCafeCloud MCP

A remote [MCP](https://modelcontextprotocol.io) server that wraps the **iCafeCloud** internet-cafe
management API and plugs into **claude.ai as a custom connector** — so you can run your cafe from a
normal Claude chat on web, desktop, or mobile.

```
claude.ai  →  Anthropic cloud  →  this server (VPS, static IP)  →  api.icafecloud.com
```

Hosting on the VPS solves iCafeCloud's IP-bound token: every upstream call originates from that one
static IP. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).

## Quick start

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env          # fill in credentials
icafecloud-mcp                # runs Streamable HTTP on :8080
npx @modelcontextprotocol/inspector   # poke at the tools
```

## MVP tools

`list_pcs` · `pc_status` · `send_pc_command` · `get_member` · `revenue_report` (`topup_member` optional).

## Docs

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — diagrams: request path, security model, modules.
- [`docs/DEVELOPMENT_PLAN.md`](docs/DEVELOPMENT_PLAN.md) — SDLC flow + decomposed task backlog.
- [`CLAUDE.md`](CLAUDE.md) — guidance for Claude Code working in this repo.

## Stack

Python 3.11+ · [FastMCP](https://github.com/jlowin/fastmcp) · httpx · Streamable HTTP transport
(SSE intentionally unused — it is being phased out).