Aoc Utils MCP

Aoc-Utils MCP 服务器和 Gemini 扩展

这个仓库包含一个扩展和一个MCP服务器，它们提供了方便的Advent of Code（AoC）实用工具，例如：。

• 这个 get_puzzle_input(year: int, day: int) 检索特定年份和日期的您的拼图数据。

它还作为一个有用的示例，展示了如何为Python函数实现一个FastMCP服务器，并解释了如何将MCP服务器集成到像Gemini CLI这样的AI工具中。

有用链接

• “Advent of Code”翻译为中文是“编码的降临”或更常译为“编程之日历挑战”（但通常直接保留原名以体现其特色，因为这是一个特定的编程挑战活动名称）。在实际使用中，人们可能会直接使用“Advent of Code”这个英文原名，因为它已经广为人知。如果需要一个中文解释性名称，可以称之为“编程挑战季”或“编程日历挑战”，但具体翻译还需根据上下文和使用场景来确定。在这里，为了简洁明了，我们通常直接使用“Advent of Code”
• Dazbo的《Advent of Code》解题指南
• FastMCP 快速入门
• FastMCP Cloud（可译为“FastMCP云端”或根据具体语境简化为“FastMCP云”）
• 带有FastMCP的Gemini命令行界面（CLI）
• FastMCP Gemini 集成
• Dazbo的《Advent of Code》解决方案仓库

来自Gemini CLI的演示

我给Gemini CLI的提示：

_获取2022年AOC（Advent of Code，编程挑战赛）第1天的输入数据，并保存到tmp/aoc_2022_day1_input.txt文件中_

Get AoC Input

并且它已经保存了文件！

File Saved

发展

运行MCP服务器

本地开发和测试的先决条件

首先，将你的依赖项加载到虚拟环境中：

# Create venv and activate
uv sync
source .venv/bin/activate

然后获取您的AoC会话密钥：

这个《帝国时代》（AoC）MCP服务器旨在获取您特定的《帝国时代》输入数据。为此，您需要提供您唯一的《帝国时代》会话密钥。这很容易获取。打开 “Advent of Code”翻译成中文是“编程挑战日历”或“编码冒险之旅”。这个活动通常指的是每年在圣诞节前夕举办的一系列编程挑战，旨在通过解决一系列有趣的编程问题来锻炼编程技能 登录网站并确保您已登录。然后在您的浏览器中打开开发者工具（F12），打开 Application 按Tab键，然后展开“Cookies”并找到名为 session复制此cookie对应的值。

运行服务器

现在我们可以启动服务器了。

请注意 fastmcp CLI 自动集成到 uv 管理 环境和依赖项。

cd mcp-server/src

# PRE-REQ: Ensure AOC_SESSION_COOKIE is set as env var
export AOC_SESSION_COOKIE=

# View FastMCP CLI help
fastmcp 

# To launch the server with default stdio transport
fastmcp run server.py

# Or to run with HTTP transport:
fastmcp run server.py --transport http --port 9000

# Or if we just configure using the `fastmcp.json`, we don't need any parameters:
fastmcp run # If fastmcp.json is in the cwd
fastmcp run path/to/fastmcp.json
fastmcp run prod.fastmcp.json # use a specific json

请注意，命令行参数会覆盖（之前的设置/配置） fastmcp.json 配置。

测试

我们可以尝试几种方法：

单元测试

使用 make test 运行单元测试的快捷方式。这些测试不涉及实际的MCP服务器。

检查服务器是否正常运行

如果我们已经启动了MCP服务器，我们可以检查它是否 健康的。

使用示例客户端

如果MCP服务器正在运行，我们可以在另一个终端会话中进行测试：

# Activate the venv
uv sync
source .venv/bin/activate

# Launch a client with Python - requires server to be HTTP
python3 tests/a_client.py --port 8000

安装到Gemini CLI中

作为扩展程序进行安装

# Install from the GitHub URL
gemini extensions install https://github.com/derailed-dash/aoc-utils-mcp

请注意，您可以在全局（用户）和工作区级别启用和禁用扩展。这是在以下位置进行配置的： ~/.gemini/extensions/extension-enablement.json例如，仅在特定工作区中启用此扩展：

{
  "adk-docs-ext": {
    "overrides": [
      "/home/darren/*"
    ]
  },
  "gcloud": {
    "overrides": [
      "/home/darren/*"
    ]
  },
  "aoc-utils": {
    "overrides": [
      "!/home/darren/*",
      "/home/darren/localdev/python/advent-of-code/*"
    ]
  }
}

我们可以看到 aoc-utils 扩展已禁用（!在全球范围内（这一功能）并未启用，但在（某处/某些情况下）已启用 advent-of-code 工作区。

仅安装MCP服务器

我尝试用这两种方法安装，但都遇到了困难：

# Using FastMCP CLI, which automatically calls the Gemini CLI MCP management system
# It runs gemini mcp add for you
fastmcp install gemini-cli server.py \
  --project /path/to/your/project \
  --env AOC_SESSION_COOKIE=$AOC_SESSION_COOKIE

# Using `gemini mcp add`
gemini mcp add aoc-utils-mcp \
  uv -- run --project /path/to/project --with fastmcp fastmcp run server.py \
  -e AOC_SESSION_COOKIE=$AOC_SESSION_COOKIE

所以，相反，我只是在我的（记录/文件/系统中）创建了这个条目 settings.json在我的AoC项目中：

{
  "mcpServers": {
    "aoc-utils-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/home/darren/localdev/python/aoc-utils-mcp/mcp-server/src/server.py"
      ],
      "env": {
        "AOC_SESSION_COOKIE": "${AOC_SESSION_COOKIE}"
      },
      "cwd": "/home/darren/localdev/python/aoc-utils-mcp/mcp-server/src"
    }
  }
}

注： 在启动 Gemini CLI 之前，您需要确保已设置 AOC_SESSION_COOKIE 环境变量。

我们可以在Gemini CLI中检查MCP服务器是否正在运行：

MCP server running

附录

部署到FastMCP云

我们可以选择将服务器部署到FastMCP云上，以使其公开可访问。 请注意，FastMCP Cloud会自动检测并使用 pyproject.toml。

故障排除

终止后台进程

如果我们无法成功关闭后台进程。。。

pgrep -f "fastmcp"
kill