xkcd-mcp

# xkcd-mcp — LLM corpus

Curated reference for agents and indexers. **Version** tracks `pyproject.toml` / `xkcd_mcp.__version__`.

## Tools (Discrete Surface v0.2.0)

All tools provide **Prefab UI (Rich In-Chat Comics)** support when the `apps` extra is installed (`uv sync --extra apps`) and `XKCD_PREFAB_APPS` is not `0`. The rich view includes a high-res image, alt text, and interactive links.

### `xkcd_latest`
**Description:** Fetch the most recent comic metadata and image.
**Arguments:** None.

### `xkcd_get`
**Description:** Fetch a specific xkcd comic by its number.
**Arguments:**
- `comic_number` (`int`): Required. Valid comic index (1 ... latest).

### `xkcd_random`
**Description:** Fetch a random surprise comic from the collection.
**Arguments:** None.

### `xkcd_help`
**Description:** Interactive usage guide and system configuration.
**Arguments:** None.
**Returns:** Text help + a rich Prefab card with port assignments and links.

**Behavior:** Calls xkcd’s official JSON API only (`https://xkcd.com/.../info.0.json`). `random` uses the current comic to bound the range.
**Success response:** `ToolResult` containing `text` summary and optional `structured_content` (PrefabApp).
**Errors:** `ToolResult` with `is_error=True` and descriptive error message.

## Environment

| Variable | Default | Purpose |
|----------|---------|---------|
| `XKCD_MCP_HOST` | `127.0.0.1` | HTTP bind address (`--serve`). |
| `XKCD_MCP_PORT` | `10778` | HTTP port (fleet backend). |
| `XKCD_MCP_HTTP_PATH` | `/mcp` | Path where MCP HTTP app is mounted. |
| `MCP_TRANSPORT` | (empty) | If `http` or `streamable`, can select HTTP mode when used by wrappers. |

Stdio: `uv run xkcd-mcp` or `uv run xkcd-mcp --stdio` (implicit without `--serve`).

## Run

**HTTP + MCP (recommended for IDE HTTP clients):**

```powershell
uv run xkcd-mcp --serve
```

**Stdio (Claude Desktop / Cursor stdio):**

```powershell
uv run xkcd-mcp
```

**Web UI (clears 10778/10779, starts backend + Vite):**

```powershell
powershell -ExecutionPolicy Bypass -File .\web_sota\start.ps1
```

Or from repo root: `just web` (see `justfile`).

**Health:**

```powershell
Invoke-WebRequest -Uri http://127.0.0.1:10778/health -UseBasicParsing
```

(`just health` uses `curl.exe` if available.)

## Architecture

- **`xkcd_mcp.server`** — FastMCP instance + four discrete tools (`xkcd_latest`, `xkcd_get`, `xkcd_random`, `xkcd_help`).
- **`xkcd_mcp.app`** — FastAPI: `/health`, `/`, `POST /api/comic`, mounts MCP app at `XKCD_MCP_HTTP_PATH`.
- **`xkcd_mcp.xkcd_api`** — httpx async client, User-Agent string, no scraping.
- **`xkcd_mcp.__main__`** — CLI: `--serve` → uvicorn; else `mcp.run_stdio_async()`.
- **`web_sota/`** — Vite + React; dev server proxies `/api` and `/health` to `127.0.0.1:10778`.

## MCP client snippets

**HTTP (Streamable HTTP):** base URL `http://127.0.0.1:10778`, MCP path `/mcp` (default).

**Stdio:**

```json
{
  "mcpServers": {
    "xkcd": {
      "command": "uv",
      "args": ["run", "xkcd-mcp"],
      "cwd": "D:/Dev/repos/xkcd-mcp"
    }
  }
}
```

Adjust `cwd` to your clone path.

## Troubleshooting

1. **Connection refused on 10778** — Start backend first: `uv run xkcd-mcp --serve`.
2. **404 on comic number** — Number may not exist; verify on xkcd.com.
3. **Frontend can’t reach API** — Ensure Vite proxy targets `127.0.0.1:10778` (see `web_sota/vite.config.ts`).
4. **Port already in use** — `web_sota/start.ps1` attempts to stop processes on 10778 and 10779; or change `XKCD_MCP_PORT` and matching Vite/proxy ports consistently.
5. **Rate limits / timeouts** — httpx timeout is 20s; transient network errors retry at the client.

## Fleet / related docs

Local **MCP Central Docs** clone: fleet standards (`SOTA_REQUIREMENTS`, `WEBAPP_STANDARDS`, `PACKAGING_STANDARDS`) live under `mcp-central-docs` in the same workspace layout as other sandraschi MCP servers.