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:

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

Disable cache:

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)

---

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) <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)

---

4 High-level Architecture

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)

---

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, modelcontextprotocol.info, modelcontextprotocol.info)

🚀 Quick Start

1. Installation & Build

# 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)

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

HTTP Transport (for testing/debugging)

# 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

{
  "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):

# 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):

# 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

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:

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

🧪 Development & Testing

Run Tests

# Run unit tests
npm test

# Run tests with coverage
npm run test-coverage

Development Mode

# 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:

DEBUG=metacritic-mcp npm start

📚 MCP Protocol Details

This server implements the Model Context Protocol (MCP) 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:

# Enable debug logging
DEBUG=* npm start

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

📄 License

MIT License - see LICENSE file for details.