Shelem Scorekeeping MCP Server
A local Model Context Protocol server that scores hands of Shelem (شلم), the Persian trick-taking card game. An AI assistant reads the bids and results from conversation, and this server does every score change with deterministic integer arithmetic. The assistant never has to do the maths itself.
The server runs on your machine over STDIO. It has no network access, no database, and no state. It needs nothing hosted.
Features
- One tool,
calculate_shelem_score, with typed input and structured output.
- A scoring engine (
shelem_mcp.scoring) that is independent of MCP, uses only the Python standard library, and never uses floating point.
- Strict validation. A hand that is missing a fact or contradicts itself returns an error naming the field. The server never guesses a score.
- A plain-English
explanation of every hand, generated from the engine result.
- Diagnostics are written to stderr only. stdout carries nothing but MCP messages.
Supported Shelem rules
The full specification, including the contradictions found in the source rules and how each one is resolved, is in docs/scoring-rules.md. The same document in Persian is docs/scoring-rules.fa.md.
- Each hand distributes 165 points. Normal bids run from 100 to 165 in steps of 5.
- The Hakem is the declaring team.
hakem_team and bidding_team name the same team.
- Made bid: the Hakem captured at least the bid and scores
+bid. The defenders score what they captured.
- Mak (مک): the Hakem captured exactly the bid. This is a made bid, not a failure.
- Sweep: the defenders captured nothing, and the Hakem scores
+2 × bid.
- Failed bid: the Hakem captured fewer points than the bid and scores
−bid. If the defenders captured 85 or more, the Hakem scores −2 × bid. The defenders always score what they captured.
- Shelem / sar-shelem (a bid of 165 to take every point):
+330 on success, −330 if the defenders captured 5–80, −660 if they captured 85 or more. sar-shelem scores the same as Shelem.
- A normal bid of 165 is scored by the ordinary rules, so the contract must be stated when the bid is 165.
- 1000-point rule: a defending team that was at 1000 or more before the hand scores 0 when the Hakem makes the bid. If the bid fails, it scores what it captured. A team at or above 1000 that is the Hakem is scored normally.
- Winning: the game ends when exactly one team reaches 1165 or more. Below that the game continues. Scores are not capped, and negative totals are allowed. No tie-break exists, so the server never invents one.
Installation
The package name is shelem-scorekeeping-mcp, and the command it installs has the same name. Python 3.10 or newer is required.
With uvx (recommended)
uv downloads and runs the server in an isolated environment, so there is nothing to install by hand:
With pip
python -m shelem_mcp also starts the server.
From a local checkout (before the package is on PyPI)
Run without arguments, the command starts the MCP server on STDIO and waits for a client. You do not normally run it yourself. Your MCP client launches it.
Options:
--log-level DEBUG|INFO|WARNING|ERROR|CRITICAL sets the level of diagnostics written to stderr. The default is WARNING. The SHELEM_MCP_LOG_LEVEL environment variable does the same.--version prints the version.
MCP client configuration
Claude Desktop
Edit claude_desktop_config.json. On macOS it is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is at %APPDATA%\Claude\claude_desktop_config.json.
Restart Claude Desktop afterwards. If you installed with pip instead, use "command": "shelem-scorekeeping-mcp" with "args": [].
Claude Code
Add --scope user to make it available in every project. Alternatively, commit a project-level .mcp.json:
Cursor and other clients
Any client that launches STDIO servers takes the same command and args. In Cursor, add the Claude Desktop block above to ~/.cursor/mcp.json or to .cursor/mcp.json in a project.
Usage
Tell your assistant about the game in your own words, for example: "We're both on 1000. Team 1 is Hakem, bid 20, and made it exactly (مک)." The assistant expands the spoken bid "20" to 120 and calls the tool:
The server returns this structured result:
The server is stateless. The assistant keeps the running totals and passes the totals from before each hand. To correct an earlier hand, it re-scores every hand from that point on.
Tool reference: calculate_shelem_score
Input
"One of the two" and "one of the three" mean at least one field from that group is required. When several are given, they must agree.
bid_successful alone cannot score a hand. The Hakem's award depends on whether the defenders captured nothing or 85 or more, and the defenders' award is the points they captured. The tool therefore needs the captured points, or outcome, as well.
Output
scoring_rule is one of sweep_double, bid_made, bid_failed, heavy_failure, shelem_made, shelem_failed, or shelem_heavy_failure.
Errors
Invalid input returns an MCP tool result with isError: true and a message that ends in (field: <name>), for example:
No score is returned with an error. The tool refuses to score a hand when either team is already at 1165 or more, because that game is over.
Using the engine without MCP
python -m shelem_mcp.scoring < hand.json scores one hand from JSON on the command line.
Development and testing
The tests cover the following:
tests/test_scoring.py tests the engine alone: every worked example from the source rules, every boundary (999 and 1000, 1160 and 1165, 80 and 85 defensive points), Mak, sweeps, Shelem, validation, a multi-hand game, and the 1000-1000 Mak regression.tests/test_mcp_tools.py tests the MCP layer: tool discovery and schemas, invocation in-process and over a real STDIO subprocess (both the classic initialize handshake and the 2026-07-28 protocol), raw JSON-RPC to check that stdout carries only protocol messages, server.json against the official registry schema, and this README's example against the real output.
To build the distribution:
Publishing
server.json uses the current registry schema, https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json. It is a local PyPI package on STDIO. There is no remote endpoint. The mcp-name comment at the top of this file is the ownership proof PyPI publishing checks.
The current registry guides are:
GitHub Actions
Pushing a tag such as v0.1.0 runs .github/workflows/publish-mcp.yml. The tag, the package version, and both version fields in server.json must be the same number. The workflow tests, builds, publishes shelem-scorekeeping-mcp to PyPI with a repository secret named PYPI_API_TOKEN, then publishes this repository's server.json with mcp-publisher v1.8.6. The binary is verified with its Sigstore bundle before it runs, and it authenticates with GitHub OIDC (login github-oidc). No registry token is stored in the repository.
Create the PyPI token at pypi.org/manage/account/token. Use scope Entire account until the project exists, then add it as the GitHub Actions secret PYPI_API_TOKEN.
Confirm the release:
Manual publish
Install mcp-publisher from the quickstart, publish the package to PyPI first, then:
validate checks server.json against the live registry and does not publish it.
License
MIT. See LICENSE.
