关键词

Advent of CodeAoC谜题输入LLM工具Python应用

项目简介

'aoc-utils-mcp' 是一个基于 Model Context Protocol (MCP) 构建的服务器，利用 FastMCP 框架实现。它专注于提供与 Advent of Code (AoC) 相关的实用工具，核心功能是让大型语言模型 (LLM) 客户端能够方便地获取特定年份和日期的 AoC 谜题输入数据。该项目也是一个实现 Python 函数 MCP 服务器的优秀示例，并展示了如何将其集成到 Gemini CLI 等 AI 工具中。

主要功能点

  • 获取谜题输入 (get_puzzle_input):
    • 提供 'get_puzzle_input(year: int, day: int)' 工具，允许客户端（如LLM）指定年份和日期来检索对应的 Advent of Code 谜题数据。
    • 该工具需要您提供有效的 AoC 会话 Cookie，以便获取您的个性化谜题输入。
  • 健康检查:
    • 提供 '/health' 端点，用于检查 MCP 服务器的运行状态。

安装步骤

  1. 克隆仓库:

    git clone https://github.com/derailed-dash/aoc-utils-mcp.git
cd aoc-utils-mcp

  2. 创建并激活虚拟环境，安装依赖: 该项目使用 'uv' 进行依赖管理。

    uv sync
source .venv/bin/activate

  3. 获取 AoC 会话密钥: 要获取您的 AoC 谜题数据，需要提供唯一的 AoC 会话密钥。

    • 访问 Advent of Code 网站 并登录。
    • 打开浏览器开发者工具 (F12)。
    • 切换到 'Application' 或 '存储' 标签页，展开 'Cookies'，找到名为 'session' 的 Cookie。
    • 复制该 Cookie 的值。

  4. 设置环境变量: 将复制的会话密钥设置为环境变量 'AOC_SESSION_COOKIE'。

    export AOC_SESSION_COOKIE=<您的会话密钥>

  5. 运行 MCP 服务器: 切换到服务器代码目录并启动服务器。

    cd mcp-server/src
# 默认使用 stdio 传输协议（推荐本地开发）
fastmcp run server.py

# 或者使用 HTTP 传输协议，例如在 9000 端口
fastmcp run server.py --transport http --port 9000

    服务器启动后，即可通过 MCP 客户端进行连接和调用。

服务器配置（供 MCP 客户端使用）

MCP 客户端（如 Gemini CLI）需要配置该服务器才能进行交互。配置信息通常以JSON格式提供，包含以下关键字段：

  • 服务器名称 (Server Name): 用于唯一标识此MCP服务器，例如 'aoc-utils-mcp'。
  • 启动命令 (Command): 执行服务器的命令，通常是 'uv'。
  • 启动参数 (Args): 传递给启动命令的参数列表，例如 'run'、'--with' 'fastmcp'、'fastmcp'、'run' 以及服务器主脚本的完整路径（例如，如果您将仓库克隆到 '/home/user/'，则路径可能为 '/home/user/aoc-utils-mcp/mcp-server/src/server.py'）。
  • 环境变量 (Env): 服务器运行时所需的环境变量，例如 'AOC_SESSION_COOKIE'。在实际配置中，其值应替换为您在步骤4中设置的系统环境变量 '${AOC_SESSION_COOKIE}'。
  • 工作目录 (Cwd): 服务器启动时的工作目录，通常指向服务器脚本所在的目录（例如 '/home/user/aoc-utils-mcp/mcp-server/src'）。

请确保在启动MCP客户端之前，'AOC_SESSION_COOKIE' 环境变量已在您的系统环境中设置。

基本使用方法

一旦 MCP 服务器运行且您的 MCP 客户端（如 Gemini CLI）配置完成，您就可以通过 LLM 客户端与该服务交互。

例如，在 Gemini CLI 中，您可以直接通过自然语言提示来调用 'get_puzzle_input' 工具：

  • 示例提示: "Fetch the input data for AoC 2022 day 1, and save to tmp/aoc_2022_day1_input.txt" (获取 2022 年第 1 天的 AoC 输入数据，并保存到 tmp/aoc_2022_day1_input.txt)

LLM 客户端将识别 'get_puzzle_input' 工具，并根据您的提示提取 'year' 和 'day' 参数，然后调用 MCP 服务器上的该工具来获取数据。

信息

分类

开发者工具

访问项目