# **Metacritic MCP Server (MVP)**

---

## 1  Goal

Build a **Model Context Protocol (MCP)** server that exposes Metacritic data (games, movies, TV shows and music) as first-class **MCP tools and resources**. The server will run locally and be started with a single command:

```bash
npx metacritic-mcp --port 3333 --locale en
```

Disable cache:

```bash
npx metacritic-mcp --port 3333 --locale en --no-cache
```

MCP is an open JSON-RPC–based standard that lets LLM hosts (e.g. Claude Desktop) discover **tools**, **resources** and **prompts** declared by a server and invoke them with structured inputs.([modelcontextprotocol.info][1])

---

## 2  Scope

| Component                      | Responsibilities                                                                                                                                                                                         |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Server bootstrap**           | TypeScript 5, Node 18, `npm` scripts; CLI flags `--port`, `--locale`, `--no-cache`.                                                                                                                      |
| **Metacritic adapter**         | Wrap the `chrismichaelps/metacritic` scraper (installed from GitHub), normalise to DTOs for all four content types.                                                                                      |
| **MCP façade**                 | Implement:<br>• `capabilities.tools` & `capabilities.resources` descriptors ([modelcontextprotocol.info][2]) <br>• JSON-RPC handlers for `tools/list`, `tools/call`, `resources/list`, `resources/read`. |
| **In-memory cache (optional)** | Simple `Map` with per-entry TTL (default 1 h) and a 1 s back-off between outbound scrapes.                                                                                                               |
| **Documentation**              | Auto-generated OpenAPI file and a concise README with curl examples.                                                                                                                                     |

*Observability, CI/CD, load testing and deployment tooling are **out of scope** for this MVP.*

---

## 3  Functional Requirements

| ID                         | Capability (exposed as MCP tool/resource)                                                                    | Input → Output |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------- |
| **T-1 `getGameReviews`**   | Get game reviews with optional filters (`filterBy`, `platform`, `sortBy`)                                   | GamesParamsOptions → GameReview[] |
| **T-2 `getMovieReviews`**  | Get movie reviews with optional year filter                                                                  | MoviesParamsOptions → MovieReview[] |
| **T-3 `getTVReviews`**     | Get TV reviews with optional filters (`filterBy`, `sortBy`)                                                  | TVParamsOptions → TVReview[] |
| **T-4 `getMusicReviews`**  | Get music reviews with optional filters (`filterBy`, `sortBy`)                                               | MusicParamsOptions → MusicReview[] |
| **R-1 `reviews/games`**    | Resource for cached game reviews (read-only JSON)                                                            | → GameReview[] |
| **R-2 `reviews/movies`**   | Resource for cached movie reviews (read-only JSON)                                                           | → MovieReview[] |
| **R-3 `reviews/tv`**       | Resource for cached TV reviews (read-only JSON)                                                              | → TVReview[] |
| **R-4 `reviews/music`**    | Resource for cached music reviews (read-only JSON)                                                           | → MusicReview[] |
| **H-1 `health`**           | Lightweight ping returning `{status:"ok", version}`                                                          | → {status: string, version: string} |

All tools must be described with JSON schemas in the `tools/list` response so that LLM hosts can validate parameters at call-time.([modelcontextprotocol.info][2])

---

## 4  High-level Architecture

```mermaid
graph TD
    CLI["npx metacritic-mcp"] --> Server[JSON-RPC MCP Server]
    Server --> Adapter[[Metacritic adapter]]
    Adapter --> Metacritic[metacritic.com]
    Server --> Cache[(TTL Map)]
```

The server communicates with MCP hosts via **stdio transport** (default) or an optional **WebSocket transport** defined in the protocol’s transport layer.([modelcontextprotocol.info][3])

---

## 5  API Surface (JSON-RPC over MCP)

| Method                                                         | Description |
| -------------------------------------------------------------- | ----------- |
| `tools/list` → `{tools[], nextCursor}`                         |             |
| `tools/call` (e.g. `{name:"getGameReviews", args:{filterBy:"new-releases", platform:"ps5"}}`) |             |
| `resources/list` → `{resources[], nextCursor}`                 |             |
| `resources/read` `{uri:"reviews/games"}` → `GameReview[]`        |             |
| `meta/ping` *(utility)*                                        |             |

---

## 6  Task Breakdown & Milestones

| Step                                       | ETA            | Deliverable                                  |
| ------------------------------------------ | -------------- | -------------------------------------------- |
| **0** Confirm statement                    | **T0 + 1 day** | This document signed-off                     |
| **1** Project scaffold & CLI               | T0 + 3 days    | `npm start` prints JSON-RPC handshake        |
| **2** Adapter for games                    | T0 + 6 days    | Tool `getGameReviews` works for games        |
| **3** Extend adapter to movies/shows/music | T0 + 9 days    | Category endpoints complete                  |
| **4** Implement resources tree             | T0 + 11 days   | `resources/list` & `resources/read` functional |
| **5** In-memory cache & scrape delay       | T0 + 12 days   | Config flags verified                        |
| **6** Docs & packaging                     | T0 + 14 days   | Published npm package `metacritic-mcp@0.1.0` |

---

## 7  Acceptance Criteria

1. **Installation**: `npx metacritic-mcp` boots the server with no additional setup.
2. **Correctness**: All functional requirements (T-1 – T-4, R-1 – R-4, H-1) pass unit tests (≥70 % coverage).
3. **Protocol compliance**: Server declares `tools` and `resources` capabilities and answers `tools/list` / `resources/list` per MCP draft spec.
4. **Performance (local dev)**: First uncached call to `getGameReviews` < 750 ms median on a 2020-era laptop.
5. **Docs**: README shows CLI flags, example JSON-RPC calls and expected responses.

---

> **Reference**
> • *Model Context Protocol* specification & quick-start guides for server developers (latest draft, Mar 2025).([modelcontextprotocol.info][3], [modelcontextprotocol.info][4], [modelcontextprotocol.info][2])

[1]: https://modelcontextprotocol.info/specification/ "Specification – Model Context Protocol （MCP）"
[2]: https://modelcontextprotocol.info/specification/draft/server/tools/ "Tools – Model Context Protocol （MCP）"
[3]: https://modelcontextprotocol.info/docs/quickstart/server/ "For Server Developers – Model Context Protocol （MCP）"
[4]: https://modelcontextprotocol.info/specification/draft/server/resources/ "Resources – Model Context Protocol （MCP）"

## 🚀 Quick Start

### 1. Installation & Build

```bash
# Clone the repository
git clone <your-repo-url>
cd mcp-metacritic-wrapper

# Install dependencies and build
npm install
npm run build

# Make server executable (required for Claude Desktop)
chmod +x dist/index.js
```

### 2. Start the MCP Server

The server supports two transport modes:

#### **Stdio Transport (for Claude Desktop)**
```bash
# Default mode - for MCP hosts like Claude Desktop
npm start
# or (after build)
node dist/index.js
```

#### **HTTP Transport (for testing/debugging)**
```bash
# For manual testing and debugging
npm start -- --http --port 3333
# or (after build)
node dist/index.js --http --port 3333
```

### 3. Connect to Claude Desktop

#### **Step 1: Configure Claude Desktop**

Add the MCP server to your Claude Desktop configuration:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "metacritic": {
      "command": "/Users/drwg/src/_exp/mcp-metacritic-wrapper/dist/index.js"
    }
  }
}
```

#### **Step 2: Restart Claude Desktop**

Close and reopen Claude Desktop to load the new MCP server configuration.

#### **Step 3: Verify Connection**

You should see the Metacritic MCP server appear in Claude Desktop's MCP panel. If configured correctly, you'll have access to the `getGameReviews` tool.

### 4. Test the Tools

#### **In Claude Desktop Chat:**

```
Can you search for reviews of "Elden Ring" using the Metacritic tool?
```

#### **Manual Testing (HTTP mode):**

```bash
# Test the tools/list endpoint
curl -X POST http://localhost:3333/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Test the getGameReviews tool
curl -X POST http://localhost:3333/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"getGameReviews","arguments":{"searchTerm":"Elden Ring"}}}'
```

#### **Manual Testing (Stdio mode):**

```bash
# Test via stdio transport
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

# Test getGameReviews tool
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"getGameReviews","arguments":{"searchTerm":"God of War"}}}' | node dist/index.js
```

## 🛠️ Available Tools

### `getGameReviews`

Search for game reviews with optional filters and search capabilities.

**Parameters:**
- `searchTerm` (string, optional): Search for a specific game by name
- `filterBy` (string, optional): Filter games by availability
  - `new-releases` | `coming-soon` | `available`
- `platform` (string, optional): Filter by gaming platform  
  - `ps5` | `ps4` | `xbox-series-x` | `xbox-one` | `pc` | `nintendo-switch`
- `sortBy` (string, optional): Sort results by field
  - `date` | `metascore` | `name` | `userscore`

**Example Usage in Claude Desktop:**
```
Search for "The Last of Us" game reviews
Find new PlayStation 5 game releases
Get reviews for PC games sorted by Metascore
```

**Example Response:**
```
**Elden Ring**
Metascore: 96/100
User Score: 85/100 (positive)
Elden Ring - A game with a Metascore of 96
More info: https://www.metacritic.com/game/elden-ring
---
```

## 🔧 Configuration Options

### CLI Flags

```bash
node dist/index.js [options]
# or
npm start -- [options]

Options:
  -p, --port <port>      Server port (HTTP mode) (default: 3333)
  -l, --locale <locale>  Locale for reviews (default: en)
  --no-cache            Disable caching
  --stdio               Use stdio transport (default)
  --http                Use HTTP transport
  -h, --help            Display help for command
```

### Environment Variables

You can also configure via environment variables:

```bash
export MCP_PORT=3333
export MCP_LOCALE=en
export MCP_CACHE=true
```

## 🧪 Development & Testing

### Run Tests

```bash
# Run unit tests
npm test

# Run tests with coverage
npm run test-coverage
```

### Development Mode

```bash
# Watch for changes and rebuild
npm run dev

# Start in HTTP mode for debugging
npm start -- --http --port 3333
```

### Debugging

Enable debug logging by setting the environment variable:

```bash
DEBUG=metacritic-mcp npm start
```

## 📚 MCP Protocol Details

This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.info/) specification, providing:

- **Tools**: `getGameReviews` for searching and retrieving game review data
- **Resources**: Cached review data accessible via URI endpoints  
- **Transport**: Both stdio (for MCP hosts) and HTTP (for testing)
- **Capabilities**: Tool listing, execution, and resource access

### Supported MCP Methods

- `initialize` - Server initialization and capability negotiation
- `tools/list` - List available tools with schemas
- `tools/call` - Execute tools with parameters
- `resources/list` - List available resources
- `resources/read` - Read resource content
- `ping` / `meta/ping` - Health check endpoint

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Make your changes and add tests
4. Ensure tests pass: `npm test`
5. Build the project: `npm run build`
6. Commit your changes: `git commit -m 'Add new feature'`
7. Push to the branch: `git push origin feature/new-feature`
8. Submit a pull request

## 🐛 Troubleshooting

### Common Issues

**Claude Desktop doesn't show the MCP server:**
- Check the `claude_desktop_config.json` file path and syntax
- Ensure the `cwd` path points to your project directory
- Restart Claude Desktop after configuration changes
- Check Claude Desktop's developer console for error messages

**"Tool not found" errors:**
- Verify the server started successfully with `npm start`
- Check that the build completed without errors: `npm run build`
- Test the server manually: `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js`

**Network/API errors:**
- Check your internet connection
- The Metacritic API may have rate limits or temporary availability issues
- Try again after a short delay

**Permission errors:**
- Ensure you have write permissions in the project directory
- On macOS/Linux, you may need to make the server executable: `chmod +x dist/index.js`

### Debug Mode

Run with debug output to see detailed operation logs:

```bash
# Enable debug logging
DEBUG=* npm start

# Or for specific modules
DEBUG=metacritic-mcp* npm start
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.