hugo-frontmatter-mcp: Tests, CI, and uvx Support

· 2 min read
mcp open-source python hugo

hugo-frontmatter-mcp has been one of my most quietly useful MCP servers. I use it on this blog constantly. Whenever I’m working on posts with Claude, the model doesn’t have to guess at YAML formatting or try to hand-edit frontmatter. It just calls the tools. Tags get added correctly, dates are formatted right, descriptions get set without accidentally nuking the rest of the metadata. It solved a small problem so completely that I stopped thinking about it.

The embarrassing part was that it had essentially no tests. It worked, but “works on my machine” is a bad answer when you’re modifying files.

What Changed

The server now has 32 tests covering all 15 tools. These aren’t mocked-out stubs either. Each test creates real temporary Markdown files with actual frontmatter, runs the tool function, and verifies the file was modified correctly. The batch operations (listing tags across a directory, finding posts by tag, renaming tags, validating dates) use temporary directories with multiple files.

Beyond tests, the project got the same infrastructure I added across all my MCP servers: GitHub Actions CI running lint and tests on Python 3.10-3.12, pre-commit hooks with ruff, a standardized Makefile, and uvx support:

uvx --from git+https://github.com/wdm0006/hugo-frontmatter-mcp hugo-frontmatter-mcp

It’s also still available on Smithery if you prefer one-click installation for Claude Desktop.

What It Does (Quick Refresher)

If you missed the original practical MCP use post, hugo-frontmatter-mcp gives you tools to:

  • Read and update any frontmatter field
  • Set title, date, publishDate, description, and draft status with type validation
  • Add and remove tags and images
  • List all tags across a directory with counts
  • Find all posts matching a specific tag
  • Rename a tag across an entire directory in one call
  • Validate date formats across all posts

I originally built it because models kept writing malformed YAML when editing frontmatter directly. That problem is completely gone now.

Links: