AI导哈

纸牌游戏API集成服务

一个概念验证的MCP服务器，用于集成deckofcardsapi.com API，提供创建、洗牌、抽牌、管理牌堆和通过提示交互的功能。

  • by lucianoyamane
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 lucianoyamane/poc-mcp-server

使用说明

poc-mcp服务器

描述

该项目是模型上下文协议（MCP）服务器的概念验证，该服务器集成了deckofcardsapi.com公共API以创建，混淆，购买纸牌，操作堆栈并通过提示进行交互。该设计是模块化的，以方便维护和扩展。

关于MCP手动（低级）方法的评论

注： 本项目使用 API 低级别 做MCP SDK(Server e setRequestHandler（而不是高层次的抽象）McpServer, server.tool等）。这是为了确保完全控制工具、资源、模板和提示符的日志，以及与 Inspector 和其他 MCP 客户端的兼容性。这种方法非常适合需要高级定制的概念验证、调试和场景。

有关详细信息，请参阅文件 docs/plano-refatoracao.md.

项目结构

  • index.jsMCP 服务器的入口点。记录工具、动态资源和提示。
  • handlers.js包含实现每个工具逻辑的处理器。
  • schemas.js: 使用 Zod 定义参数验证方案。
  • toolsMeta.js集中化工具名称和描述。
  • .env环境变量文件（例如：块 API 基础 URL）。
  • test.js自动化测试脚本来验证工具。
  • client/MCP CLI 客户端与服务器交互。
  • docs/文档和已知问题。

安装

  1. 克隆仓库 ：
    git clone <url-do-repo>
cd poc-mcp-server-deck-of-cards
  2. 安装依赖关系 ：
    npm install
  3. 创建文件 .env 工程根（ 可选） ：
    DECK_API_BASE_URL=https://deckofcardsapi.com/api/deck

如何运行服务器

npm start

或MCP服务器将启动并等待通过STDIO传输的命令。

如何运行测试

npm test

O脚本 test.js 将 ：

  • 创建棋盘
  • 购买纸牌
  • 模拟提示符逻辑作为工具

如何运作

  • 工具（工具), 资源 e 鼓励 使用MCP服务器的低级模型手动注册。
  • 处理器实现了与 deckofcardsapi.com API 的集成逻辑。
  • 模式保证了接收到的参数的验证。
  • 该项目使用dotenv灵活配置API基础URL。

可用工具

  • criar_baralho创建一个新的牌组。
  • embaralhar_baralho包装一个现有的牌。
  • comprar_cartas：从纸牌上买牌。
  • adicionar_pilha将卡片添加到一堆牌中（如果不存在，则创建该堆）。
  • embaralhar_pilha: 将特定的电池堆放在纸板上。

工具使用示例 adicionar_pilha

{
  "deck_id": "c7ji4ar6dxti",
  "pile_name": "teste",
  "cards": "AS,2S"
}

动态资源

服务器会暴露一个动态资源来列出特定牌池中的卡：

  • 模板： deck://{deckId}/pile/{pileName}/list
  • 如何使用：
    • 填写参数 deckId e pileName 要挂载 URI，例如：
      • deck://c7ji4ar6dxti/pile/teste/list
    • 通过 MCP 客户端或检查器查看此资源。

提示MCP

服务器显示提示符以标准化交互并促进与LLM的对话流。可用的提示是：

  • 解释规则解释纸牌游戏的规则。
    • 论据： jogo （纸牌游戏名称）
    • 例如： { "jogo": "pôquer" }
  • 建议 游戏：根据所提供的卡片建议最佳游戏。
    • 论据： cartas （例如：“AS、KD、10H、9C”）
    • 例如： { "cartas": "AS, KD, 10H, 9C" }
  • 模拟器部分： 模拟 N 位玩家的纸牌游戏。
    • 论据： jogo, jogadores
    • 例如： { "jogo": "blackjack", "jogadores": 3 }
  • 自定义消息为玩家生成欢迎或祝贺消息。
    • 论据： nome, tipo （例如：“欢迎”，“恭喜”）
    • 例如： { "nome": "João", "tipo": "boas-vindas" }

如何测试提示

  • 不 MCP检查员进入标签页 提示.
  • 选择提示符，填写参数，然后查看生成的消息。
  • 您可以将提示集成到LLM流中，以标准化问题和答案。

使用 MCP Inspector 进行测试

您可以测试服务器及其功能 MCP检查员:

npx @modelcontextprotocol/inspector node index.js

或者，如果你喜欢，使用已经定义的脚本 package.json:

npm run inspector
  • 进入标签页 工具 测试可用的工具。
  • 进入标签页 资源模板 通过填写必要的参数来测试动态资源。
  • 进入标签页 提示 测试提示和生成自定义消息。

客户端MCP（CLI）

该项目在文件夹中包含Node.js中的MCP客户端 client它允许通过命令行与MCP服务器交互，使用Claude（Anthropic）模型来处理自然语言并触发服务器工具。

安装客户端依赖关系

cd client
npm install

配置

创建文件 .env 意大利面 client 使用您的 Anthropic API 密钥：

ANTHROPIC_API_KEY=sua-chave-aqui

如何运行客户端

当 MCP 服务器运行时，通过 MCP 服务器脚本路径运行客户端（例如： ../index.js):

node index.js <caminho_para_o_servidor_MCP>

例如：

node index.js ../index.js

操作

  • 客户端通过 STDIO 传输连接到 MCP 服务器。
  • 允许发送自然语言查询，由Claude处理。
  • 要退出，请键入 quit 没有提示。
  • 要列出可用的工具，请键入 resources 欧点 tools （取决于执行的命令）。
  • 要使用动态资源，请键入：
    resource deck://<deck_id>/pile/<pile_name>/list

使用范例

$ node index.js ../index.js
MCP Client Started!
Type your queries, 'resources' to listar resources, or 'quit' to exit.

Query: Quero criar um baralho e comprar 5 cartas.
[resposta do modelo com o resultado das operações]

Query: resource deck://c7ji4ar6dxti/pile/teste/list
[resposta com as cartas da pilha 'teste']

Obs： 客户端可以根据需要适应其他模型或接口。

关于prompt的评论

  • 实际提示的支持依赖于具有人工界面（聊天，网络等）的MCP客户端。
  • 目前，提示符逻辑被模拟为促进自动化测试的工具。

主要依赖关系

  • @modelcontextprotocol/sdk
  • dotenv
  • node-fetch
  • zod

自定义

  • 要添加新工具或提示，请在 index.js.
  • 要更改 API URL，请编辑文件 .env.

已知问题

吃意大利面 docs/ 已知问题和解决方案。

如果您有疑问或想要扩展项目，请随时贡献！

使用示例：模拟扑克游戏

下面是一个使用MCP服务器模拟德州扑克扑克游戏的自然语言提示示例：

我想模拟一个4名玩家的德州扑克游戏，每名玩家收到两张牌，并在桌子上显示5张社区牌。

此提示将请求 MCP 服务器：

  • 创建新牌
  • 装载纸板
  • 向4名玩家分发2张牌
  • 在桌子上显示5张社区卡（如德州扑克）

预期的响应将是一个JSON对象，其中包含每个玩家的牌和桌子的牌，例如：

{
  "jogadores": {
    "jogador_1": ["AS", "KD"],
    "jogador_2": ["10H", "9C"],
    "jogador_3": ["2D", "7S"],
    "jogador_4": ["JC", "5H"]
  },
  "mesa": ["3C", "8D", "QS", "4H", "6S"]
}

Obs： 您可以根据需要调整自然语言提示符，更改玩家数量或游戏格式。

相关 MCP