Skip to content
maveniversePublic

About

Project-aware MCP server for Maven, for coding agents

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

26 Commits

Folders and files

Repository files navigation

Maveniverse Huginn

A project-aware MCP server for Maven, for coding agents. It answers questions about the build the agent is actually editing: that reactor's effective models, its repositories and its resolved dependency graph, rather than an arbitrary GAV on Maven Central.

Built on MIMA, mase (Central search) and the Quarkus MCP server (stdio), on Java 17.

Tools

There are eight tools, all read-only. Every one takes an optional project (any directory or pom.xml inside the reactor; default: the server's working directory) and most take module (path relative to the root, artifactId, or groupId:artifactId). Results are compact JSON.

Tool Answers
describe At the root: modules, inter-module dependencies, repositories in use, maven.config settings. For a module: its effective model, with dependencies, plugins and executions, properties and profiles, and where each version is set: the parent or BOM (version_in) and the property behind it (version_property, property_in). With plugin, that plugin's configuration and executions in the module.
dependencies The resolved tree, as the build sees it, plus conflicts: which version was requested by whom, and which one won. scope is compile, runtime or test; maxDepth caps output on large trees. override=g:a:v answers "what if": it forces that version, as dependencyManagement would, and returns what changes on the classpath.
why Every path that brings an artifact in, including requests that lost a conflict, across all modules by default. One call answers both "why is X here" and "who wants the old X".
versions Upgrade candidates from the project's own repositories: latest, latest within the same major, latest within the same minor; pre-releases skipped unless asked for. Works for plugins too, using the project's plugin repositories. Without an artifact it lists outdated direct dependencies and plugins, each with the POM or property to edit.
search Maven Central search by text or g:/a: query, paged with limit and page. fc:<class> finds which artifact has a class (add g: to narrow); results keep one entry per artifact, at its newest version on the page.
sources Unpacks a dependency's sources jar into ~/.cache/huginn/sources/, or returns one class's source. Without a version, uses the version this project resolves.
plugin A plugin's goals, or one goal's parameters with the user property (-Dx) and default of each, read from the plugin's descriptor. A short name like surefire works; the version is the one the project uses, else the latest release.
extensions Which core extensions are declared in the project (.mvn/extensions.xml), user (~/.m2/extensions.xml) and installation ($MAVEN_HOME/conf/extensions.xml) files, and which useful ones are missing (MWM, Mimir, Nisse, Muninn), each with its latest release from the project's repositories and the exact <extension> snippet to add. Missing ones are proposed user-wide, and Maven 3.10.x is recommended. It changes nothing; applying the snippet is up to the agent.

Builds are deliberately not here. Running mvn with the Muninn extension (which the extensions tool proposes) gives agents a compact JSON report of the build itself; this server covers the questions a shell can't answer cheaply.

How it works

  • Project first: answers come from the reactor's effective models, including dependencyManagement, BOMs, profiles and exclusions, not from a standalone GAV.
  • The project's repositories: repositories declared in the POMs are added to those from settings, and mirrors and authentication from settings apply.
  • Reactor siblings resolve from the working tree: a workspace reader serves modules that were never installed, including their effective models, the same way Maven's ReactorReader does.
  • CI-friendly versions work: -D and -P from .mvn/maven.config apply, with user properties winning as on the command line. MIMA's MavenModelReader deliberately demotes user properties for dependency POMs (MNG-7563), so project models are built separately in ProjectModels.
  • Few tools: eight, because every tool description costs the agent context on every turn.
  • Caching: a loaded reactor is cached and reloaded only when a POM or maven.config changes. Unpacked sources are cached under $XDG_CACHE_HOME/huginn/sources/ (default ~/.cache), and logs go to ~/.cache/huginn/huginn.log, since stdout belongs to the MCP protocol.

Use

With Claude Code, run this from the project directory:

claude mcp add huginn -- jbang --quiet huginn-mcp@maveniverse

Or in an MCP client config:

"mcpServers": {
  "huginn": { "command": "jbang", "args": ["--quiet", "huginn-mcp@maveniverse"] }
}

The first time, jbang asks whether to trust the download origin, with a pop-up dialog that an MCP client can't answer. Trust it once from a terminal:

jbang trust add https://repo.maven.apache.org/maven2/eu/maveniverse/maven/huginn/

The server works on its working directory by default. Set HUGINN_PROJECT to point it elsewhere.

Build

./mvnw clean verify

The project is a parent POM with one module, huginn-mcp, which builds the runnable huginn-mcp/target/huginn-mcp-<version>-runner.jar.

Tests:

  • Unit tests cover the helpers: reactor scanning, maven.config parsing, the workspace reader, tree and conflict rendering, the matcher, version bands, profile activation, extensions.xml reading, JSON output and sources extraction.
  • McpServiceTest runs all tools but search against a generated demo reactor and a file: repository, with real Resolver and MIMA: version conflicts, a managed dependency, a reactor sibling that was never installed, ${revision} from maven.config, plugin versions, extensions proposals, and reload after a POM edit. It runs with a throwaway user.home (huginn-mcp/target/test-home) whose settings.xml mirrors everything to the file repository, so it never touches the network or your ~/.m2.
  • McpServerIT starts the packaged runner jar and talks to it over stdio like an MCP client: tool list, schemas, hints, results and error mapping. It runs in the integration-test phase. Its search tests query Maven Central, so verify needs network access for them.

Status

It needs MIMA 3 with Maven Resolver 2; the POM overrides the Resolver 1.9 pinned by the Quarkus BOM.

Not yet done:

  • Release: 0.1.0 was cut with maven-release-plugin; there is no CI release workflow.

Known gaps:

  • Profile modules: profiles that contribute <modules> follow Maven's activation rules (-P in maven.config, jdk, os, property and file conditions, activeByDefault only when nothing else is active). Properties come from maven.config -D, system properties and env.*; profiles from settings.xml are not consulted, nor are -D flags given only on the real command line.
  • Maven 4: POMs using model version 4.1.0 are not read, because the reader is Maven 3.9's.
  • Search: Central only (its CSC endpoint, which wants an explicit AND between terms, so free text is joined with AND). A class search (fc:) lists every jar containing the class, shaded copies included, sorted by artifactId, so without g: the owning artifact may not be on the first page.
  • Version properties: version_property is read from the line of the <version> start tag, so a version whose value is on the next line shows no property (version_in is still right).
  • Upstream candidates: a "project mode" in MIMA's MavenModelReader, and a standalone reactor locator, would let ProjectModels and the reactor code move upstream.

About

Project-aware MCP server for Maven, for coding agents

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages