Jewel MCP Server

A Model Context Protocol (MCP) server that provides access to the Jewel game database, allowing you to search for games and view platform ownership information.

Features

• Game Search: Search for games in the Jewel database by name
• Platform Information: View which platforms you already own the game on
• Multiple Game Support: Search for multiple games in a single query

Prerequisites

• Python 3.12 or higher
• uv package manager (recommended) or pip

Development Setup

1. Clone the repository

git clone https://github.com/ivellios/jewel-mcp-server.git
cd jewel-mcp-server

2. Create and activate virtual environment

Using uv (recommended):

uv venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

3. Install dependencies

Using uv:

uv sync

Using pip:

pip install -e .

4. Set up environment variables

Create a .env file in the project root or set environment variables:

JEWEL_API_BASE_URL=https://your-jewel-api-base-url
JEWEL_API_TOKEN=your-api-token

5. Testing the server

The server runs as a stdio transport, so you can test it directly:

# Run the server (it will wait for stdio input)
python main.py

# Or test with the MCP inspector (if you have it installed)
npx @modelcontextprotocol/inspector python main.py

# Or same node module with
uv run mcp dev main.py

Configuration for Claude Desktop

To add this MCP server to Claude Desktop, add the following configuration to your Claude config file:

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "jewel": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\jewel-mcp-server",
        "run",
        "main.py"
      ],
      "env": {
        "JEWEL_API_BASE_URL": "https://your-jewel-api-base-url",
        "JEWEL_API_TOKEN": "your-api-token"
      }
    }
  }
}

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jewel": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/jewel-mcp-server",
        "run",
        "main.py"
      ],
      "env": {
        "JEWEL_API_BASE_URL": "https://your-jewel-api-base-url",
        "JEWEL_API_TOKEN": "your-api-token"
      }
    }
  }
}

Usage

Once configured in Claude Desktop, you can use the following tool:

search_game

Search for games in the Jewel database.

Parameters:

• query (string): Game name or partial name with intelligent query processing:
  • Single word: Searched as-is (e.g., "witcher" → "witcher")
  • Two words: Searched as-is (e.g., "witcher 3" → "witcher 3")
  • Three+ words: Filters out short words (≤3 chars), splits remaining words (e.g., "the witcher 2" → "witcher")
  • Multiple games: Separate with commas, each processed according to above rules
  • Deduplication: Duplicate keywords are automatically removed

Examples:

"witcher" → searches for: witcher
"witcher 3" → searches for: witcher 3
"the witcher 2" → searches for: witcher
"witcher,cyberpunk,the abyss" → searches for: witcher,cyberpunk,the abyss
"the witcher 2,cyberpunk,the witcher 3" → searches for: witcher,cyberpunk
"LEGO The Skywalkers Saga,PEAK" → searches for: LEGO,Skywalkers,Saga,PEAK

Response: The tool returns a formatted list of matching games with the platforms where you already own them.

API Reference

Environment Variables

Variable	Description	Required
JEWEL_API_BASE_URL	Base URL for the Jewel API	Yes
JEWEL_API_TOKEN	Authentication token for the Jewel API	Yes

Available Tools

search_game(query: str) -> str

Searches for games matching the provided query with intelligent preprocessing.

• query: Search string containing game name(s) with automatic filtering and normalization:
  • Single/two words: used as-is
  • Three+ words: filters out words ≤3 characters, uses remaining words as separate keywords
  • Multiple games: comma-separated, each processed independently
  • Automatic deduplication of keywords
• Returns: Formatted string with game results and platform information.

Development

Running Tests

# Install test dependencies first
uv sync

# Run tests
pytest

# Run tests with coverage
pytest --cov=main --cov-report=term-missing

Code Quality

This project uses pre-commit hooks and GitHub Actions to ensure code quality:

# Install pre-commit hooks (run once)
uv run pre-commit install

# Run pre-commit on all files manually
uv run pre-commit run --all-files

# Run just ruff checks
uv run ruff check .
uv run ruff format .

Continuous Integration

The project uses GitHub Actions for automated testing:

• Code Quality: Runs ruff check and ruff format --check on Python 3.12 and 3.13
• Testing: Executes the full test suite with coverage reporting
• Pre-commit: Validates all pre-commit hooks pass
• Coverage: Publishes coverage reports on pull requests (minimum 80% for green status)

Code Structure

• main.py: Main server implementation with FastMCP 2.0
• make_jewel_request(): HTTP client function for API requests
• normalize_query(): Query preprocessing function that filters and normalizes search terms
• format_games_list(): Game results formatting function
• search_game(): MCP tool for game searching with intelligent query processing

FastMCP 2.0

This project uses FastMCP 2.0, the fast, Pythonic way to build MCP servers. FastMCP provides:

• Simple decorator-based API for defining tools
• Built-in stdio transport (default)
• Production-ready features and enterprise support
• Easy testing with built-in client utilities

Troubleshooting

Common Issues

1. Authentication Error: Ensure JEWEL_API_TOKEN is correctly set and valid.
2. Connection Error: Verify JEWEL_API_BASE_URL is correct and accessible.
3. Module Import Error: Make sure all dependencies are installed in the correct virtual environment.
4. Claude Desktop Not Detecting Server: Check that the path in the config file is absolute and correct.

Debug Mode

To enable debug logging, modify the logging configuration in main.py or set environment variables as needed.

License

Released under the AGPL-3.0 license. See LICENSE file for details.