poc

The poc MCP server is a proof-of-concept that exposes a set of MCP tools to manage and interact with decks of cards via the public Deck of Cards API. It registers tools at a low level using the MCP Server approach to give fine-grained control over tool names, parameters, resources and prompts. Available tools include criar_baralho (create a new deck), embaralhar_baralho (shuffle a deck), comprar_cartas (draw cards from a deck), adicionar_pilha (add cards to a named pile on a deck), and embaralhar_pilha (shuffle a specific pile). A dynamic resource is exposed to list cards from a specific pile via a template like deck://{deckId}/pile/{pileName}/list, and there are prompts to standardize interactions with LLMs (for example explaining rules, suggesting moves, simulating a game, or generating personalized messages).

You can test the setup using the MCP Inspector or the included client. Start the server with npm start (which runs node index.js under the hood). Use the inspector to explore Tools, Resources Templates, and Prompts, or use the client in client/ to drive the server from the command line with an Anthropic Claude-based workflow. The client connects via STDIO and can process natural-language queries that trigger the registered tools.

Example workflows: (1) Crear baralho and comprar cartas: create a new deck, shuffle if desired, then call comprar_cartas with deck_id and count. (2) adicionar_pilha: add cards to a named pile on a deck, e.g., AS,2S into a pile called teste. (3) Use the dynamic resource to list the cards in a pile using resource deck://<deck_id>/pile/<pile_name>/list.

Prerequisites:

• Node.js and npm installed on your system
• Git to clone the repository
• Optional: dotenv support if you want to customize environment variables

Step 1: Clone the repository

git clone <url-do-repo>
cd poc-mcp-server-deck-of-cards

Step 2: Install dependencies

npm install

Step 3: Configure environment (optional but recommended) Create a .env file at the project root and set the base URL for the deck API:

DECK_API_BASE_URL=https://deckofcardsapi.com/api/deck

Step 4: Run the server

npm start

Step 5: (Optional) Run tests

npm test

Step 6: (Optional) If you want to use the MCP Inspector CLI

npx @modelcontextprotocol/inspector node index.js

Notes:

• The server uses dotenv for flexible configuration of the Deck API URL.
• The Tools, Resources, and Prompts are registered using the low-level MCP Server approach for maximum control.

Tips and caveats:

• The project relies on a low-level MCP Server registration approach (Server and setRequestHandler) to retain full control over tools, resources, and prompts. This is suitable for experimentation and debugging but may require more manual maintenance than high-level abstractions.
• If you modify endpoints or add new tools/prompts, ensure the schemas validate inputs correctly (as defined in schemas.js).
• The environment variable DECK_API_BASE_URL is optional but recommended to point to the Deck API base URL; the default in docs is https://deckofcardsapi.com/api/deck.
• The dynamic resource for listing pile cards uses a template like deck://{deckId}/pile/{pileName}/list; make sure to fill deckId and pileName when testing.
• For testing prompts and flows with the MCP Inspector, you can simulate natural-language queries or use the included client in client/ with your Anthropic API key.
• If you encounter cross-origin or network issues, verify that the Deck API is reachable from your runtime environment and that the base URL matches the current API shape.