{
  "markdown": "# The Aoc-Utils MCP Server and Gemini Extension\n\nThis repo contains an extension and MCP server that exposes handy Advent of Code (AoC) utilities, e.g.\n\n- The `get_puzzle_input(year: int, day: int)` retrieves your puzzle data for a given specific year and day.\n\nIt also acts as a useful example of how to implement a FastMCP server for Python functions, and explains how to integrate the MCP server into an AI tool like Gemini CLI.\n\n## Useful Links\n\n- [Advent of Code](https://adventofcode.com/)\n- [Dazbo's Advent of Code Walkthroughs](https://aoc.just2good.co.uk/)\n- [FastMCP Quickstart](https://gofastmcp.com/getting-started/quickstart)\n- [FastMCP Cloud](https://gofastmcp.com/deployment/fastmcp-cloud)\n- [Gemini CLI with FastMCP](https://developers.googleblog.com/en/gemini-cli-fastmcp-simplifying-mcp-server-development/)\n- [FastMCP Gemini Integration](https://gofastmcp.com/integrations/gemini-cli)\n- [Dazbo's Advent of Code Solutions Repo](https://github.com/derailed-dash/advent-of-code)\n\n## Demo from Gemini CLI\n\nMy prompt to Gemini CLI: \n\n_Fetch the input data for AoC 2022 day 1, and save to tmp/aoc_2022_day1_input.txt_\n\n![Get AoC Input](/docs/media/get-aoc-input.png)\n\nAnd it has saved the file!\n\n![File Saved](/docs/media/file-saved.png)\n\n## Development\n\n### Running the MCP Server\n\n#### Pre-Reqs for Local Development and Testing\n\nStart by loading your dependencies into the virtual environment:\n\n```bash\n# Create venv and activate\nuv sync\nsource .venv/bin/activate\n```\n\nThen retrieve your AoC session key:\n\nThis AoC MCP server is designed to retrieve your specific AoC input data. To do so, you'll need to supply your unique AoC session key. This is easy to get. Open the [Advent of Code](https://adventofcode.com/) website and ensure you are logged in. Then open developer tools in your browser (F12), open the `Application` tab, then expand Cookies and find the cookie called `session`. Copy the value against this cookie.\n\n#### Running the Server\n\nNow we can launch the server.\n\nNote that the `fastmcp` CLI automatically integrates with `uv` to manage\nenvironments and dependencies.\n\n```bash\ncd mcp-server/src\n\n# PRE-REQ: Ensure AOC_SESSION_COOKIE is set as env var\nexport AOC_SESSION_COOKIE=<session key>\n\n# View FastMCP CLI help\nfastmcp \n\n# To launch the server with default stdio transport\nfastmcp run server.py\n\n# Or to run with HTTP transport:\nfastmcp run server.py --transport http --port 9000\n\n# Or if we just configure using the `fastmcp.json`, we don't need any parameters:\nfastmcp run # If fastmcp.json is in the cwd\nfastmcp run path/to/fastmcp.json\nfastmcp run prod.fastmcp.json # use a specific json\n```\n\nNote that command-line arguments override the `fastmcp.json` configuration.\n\n### Testing\n\nWe can test a few ways:\n\n#### Unit Testing\n\nUse the `make test` shortcut to run unit tests. These tests do not the actual MCP server.\n\n#### Checking the Server is Healthy\n\nIf we've started the MCP server, we can check it's [healthy](http://127.0.0.1:8000/health).\n\n#### With the Sample Client\n\nIf the MCP server is running, we can test from a separate terminal session:\n\n```bash\n# Activate the venv\nuv sync\nsource .venv/bin/activate\n\n# Launch a client with Python - requires server to be HTTP\npython3 tests/a_client.py --port 8000\n```\n\n## Installing into Gemini CLI\n\n### Installing as an Extension\n\n```bash\n# Install from the GitHub URL\ngemini extensions install https://github.com/derailed-dash/aoc-utils-mcp\n```\n\nNote that you can enable and disable extensions at global (user) and workspace level. This is configured in `~/.gemini/extensions/extension-enablement.json`. For example, to enable this extension only in a specific workspace:\n\n```json\n{\n  \"adk-docs-ext\": {\n    \"overrides\": [\n      \"/home/darren/*\"\n    ]\n  },\n  \"gcloud\": {\n    \"overrides\": [\n      \"/home/darren/*\"\n    ]\n  },\n  \"aoc-utils\": {\n    \"overrides\": [\n      \"!/home/darren/*\",\n      \"/home/darren/localdev/python/advent-of-code/*\"\n    ]\n  }\n}\n```\n\nWe can see that the `aoc-utils` extension is disabled (`!`) at global level, but enabled in the `advent-of-code` workspace.\n\n### Installing the MCP Server Only\n\nI struggled to install with either of these approaches:\n\n```bash\n# Using FastMCP CLI, which automatically calls the Gemini CLI MCP management system\n# It runs gemini mcp add for you\nfastmcp install gemini-cli server.py \\\n  --project /path/to/your/project \\\n  --env AOC_SESSION_COOKIE=$AOC_SESSION_COOKIE\n\n# Using `gemini mcp add`\ngemini mcp add aoc-utils-mcp \\\n  uv -- run --project /path/to/project --with fastmcp fastmcp run server.py \\\n  -e AOC_SESSION_COOKIE=$AOC_SESSION_COOKIE\n```\n\nSo instead, I just create this entry in my `settings.json`, in my AoC project:\n\n```json\n{\n  \"mcpServers\": {\n    \"aoc-utils-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--with\",\n        \"fastmcp\",\n        \"fastmcp\",\n        \"run\",\n        \"/home/darren/localdev/python/aoc-utils-mcp/mcp-server/src/server.py\"\n      ],\n      \"env\": {\n        \"AOC_SESSION_COOKIE\": \"${AOC_SESSION_COOKIE}\"\n      },\n      \"cwd\": \"/home/darren/localdev/python/aoc-utils-mcp/mcp-server/src\"\n    }\n  }\n}\n```\n\nNote: **You need to ensure your AOC_SESSION_COOKIE environment is set before launching Gemini CLI.**\n\nWe can check the MCP server is running in Gemini CLI:\n\n![MCP server running](/docs/media/mcp-running-in-gemini.png)\n\n## Appendix\n\n### Deploying to FastMCP Cloud\n\nWe can optionally deploy the sever to FastMCP Cloud to make it publicly accessible.\nNote that FastMCP Cloud automatically detects and uses `pyproject.toml`.\n\n### Troubleshooting\n\n#### Terminating the Background Process\n\nIf we're having trouble closing the background process...\n\n```bash\npgrep -f \"fastmcp\"\nkill <PID>\n```",
  "bytes": 5693,
  "sha": "de8df73a2ef5bdd5506ab6ab327eba73ae133824b35e3f1bfc9611213490431e",
  "repo_slug": "derailed-dash/aoc-utils-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_derailed_dash_aoc_utils_mcp_8aea04b6/readme"
}