docs/mcp_guide.md

# MCP Server Guide

This application functions as an **MCP (Model Context Protocol) Server**.
External LLMs can connect to this server and use game management tools.

## Connection URL

```
https://mcp-1st-birthday-unpredictable-lord.hf.space/gradio_api/mcp/
```

For local development:

```
http://localhost:7860/gradio_api/mcp/
```

## How to Connect

Add the following to your MCP settings configuration.

### VS Code

```json
{
  "servers": {
    "unpredictable-lord": {
      "url": "https://mcp-1st-birthday-unpredictable-lord.hf.space/gradio_api/mcp/"
      "type": "http"
    }
  },
  "inputs": []
}
```

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "unpredictable-lord": {
      "url": "https://mcp-1st-birthday-unpredictable-lord.hf.space/gradio_api/mcp/"
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `init_game` | Initialize a new game session. Returns a session_id and available advice options. |
| `get_game_state` | Get the current game state for a session. |
| `list_available_advice` | Get all available advice options for execute_turn. |
| `execute_turn` | Execute a turn with the given advice. Returns whether advice was adopted and results. |

## Usage Flow

1. Call `init_game(<personality>)` to start a new game session
2. User gives advice to the Lord AI
3. Lord AI interprets advice and calls `execute_turn(session_id, advice)`
4. Lord AI explains the result to the user (adopted/rejected, action taken, effects)
5. Repeat from step 2 until game over