MTG

A minimal MCP Python server exposing health.check and mtg.card_lookup with Day-1 fake data and Day-2 real API integration

python

0

GitHub Stars

python

Language

3 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jabelk-mtg-mcp": {
      "command": "python",
      "args": [
        "src/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

This MCP server provides two tools for a minimal Magic: The Gathering card lookup workflow. It includes a health endpoint that reports version and uptime, plus a card lookup tool that starts with a fake response for Day 1 and can switch to a real API (Scryfall) for Day 2. It is designed to be run locally and wired to a client that can call these tools through the MCP protocol.

How to use

To use this MCP server, run it in your environment and connect your MCP client to the stdio transport provided by the server. You will access two tools: health.check to verify the server is responsive and to observe the current learning streak counter, and mtg.card_lookup to search for card data by name. The server returns structured results that your client can display, log, or chain into other actions.

Typical usage pattern involves starting the server, then invoking health.check to confirm the server is up and to observe the health payload, followed by calling mtg.card_lookup with a card name such as Atraxa to retrieve card data. If the name is not found in the fake Day-1 implementation, you will receive a friendly error suggesting you try a different name or verify spelling.

How to install

Prerequisites: you need Python installed on your system. It is recommended to use a virtual environment to isolate dependencies.

Step 1: Create and activate a virtual environment.

python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows
.\venv\Scripts\activate

Step 2: Upgrade the Python packaging tools.

pip install --upgrade pip

Step 3: Install MCP dependencies. You can optionally install uvloop for improved event loops on platforms that support it.

pip install mcp uvloop

Step 4: Run the MCP server over stdio. This starts the server and waits for client connections.

python src/server.py

Configuration notes

The server exposes two tools under the MCP namespace. The health.check tool returns a payload with version, current UTC time, and a learning streak counter that persists to a local file named streak.json. The mtg.card_lookup tool accepts a name parameter and returns card data. Day 1 uses a fake response to prove wiring; Day 2 switches to a real HTTP call to Scryfall while preserving the same return structure.

Troubleshooting and notes

If you encounter issues connecting from your MCP client, ensure you are providing input through the stdio channel and that the server process is running without errors. Check the logs under logs/week1.log for runtime messages and errors.

If the card lookup returns a not_found error, verify that the input name is non-empty and correctly spelled. The server will guide you toward a different name or spell-check as needed.

Available tools

health.check

Returns server version, current time in UTC, and a persistent learning streak counter stored locally.

mtg.card_lookup

Fuzzy-lookup for a Magic card by name. Day-1 returns a fake, wired response; Day-2 switches to a real HTTP call to Scryfall while preserving the same return structure.