boardgame mcp

# Boardgame-MCP 📚🧩

**Boardgame-MCP** is a small MCP‑based system to **find, download, cache, search and summarize** official board game rulebooks from [officialgamerules.org](https://officialgamerules.org).

---

## 🚀 What It Does

Boardgame-MCP employs a fully LLM-driven MCP agent that dynamically orchestrates cache checking, web scraping, PDF download, FAISS-based indexing, and summarization—without any hard-coded if-else logic. It leverages RAG (Retrieval-Augmented Generation) so the summaries are grounded in the actual rulebook text retrieved from the official PDFs.

* **`cache_server`**: checks if a board game rulebook is already cached locally
* **`rulebook_server`**: scrapes the website for a game’s rulebook PDF URL and downloads it, if it doesn't already exist in cache
* **`rag_server`**: chuncks, embeds and indexes rulebook text for fast retrieval, and summarizes results
* **`client`**: an LLM‑driven agent that decides which tools to call in order to fetch or serve a rulebook

---

## ⚙️ Setup

1. **Install Just** (if you don’t have it already)

2. **Clone & run setup**:

   ```bash
   git clone https://github.com/ralucachintoanu/boardgame-mcp.git
   cd boardgame-mcp
   just run-setup
   ```

3. **Add your Anthropic key** (for the client agent):

   ```bash
   echo "ANTHROPIC_API_KEY=sk-..." > .env
   ```

---

## ▶️ Running Everything

### Run all MCP servers

In one terminal, start **all servers** together:

```bash
just run-all-servers
```

You’ll see interleaved logs from each server. Press **Ctrl‑C** to stop them all.

### Run the client agent

In another terminal:

```bash
just run-client
```

Type a question (e.g. `What are the main rules of Settlers of Catan?` or `Summarise Karak rules in 10 short bullet points, based solely on the official rulebook.`) and let the agent orchestrate cache checks, downloads, searches and summarisations.
Type `quit` to exit the client.


## 🐞 Debugging & Manual Steps

#### Start a single server - pick the instruction you need:

```bash
just run-rulebook-server
just run-cache-server
just run-rag-server
```

#### Launch the MCP Inspector

```bash
just run-test-inspector
```

1. Open your browser to `http://127.0.0.1:6274`
2. Choose **Streamable HTTP** transport
3. Enter the server URL (e.g. `http://localhost:3333/mcp` for rulebook-server, `http://localhost:3334/mcp` for cache-server etc; see the complete list in `client/servers.json` file)
4. Connect and interact with individual tools

---

## 🧩 Extensions

Want to add more capabilities? You have two options:

1. **Implement a new MCP server**  
   - Create your server code under a new folder (e.g. `new_tool_server/`), register tools with FastMCP, and run it on a new port.  
   - Add the tool definition to `client/tools.json`.
   - Map the tool to its server URL in `client/servers.json`.  
   - Start the new server (via `just` or directly), and the client agent will automatically pick it up—no client code changes required.

2. **Use an existing MCP service**  
   - If you already have a compliant MCP server (local or remote), simply add its tool definitions to `client/tools.json` and its URL to `client/servers.json`.  
   - As long as the server exposes a valid `/mcp/schema`, you don’t need to write any additional code.

This plug-and-play design makes your system highly extensible without touching the core client logic.

---

Enjoy building with MCP! 🔧✨