# Examples

This page keeps the longer prompt and workflow examples out of the main README while preserving the practical usage patterns.

## Important Boundary

Maven Tools MCP provides dependency intelligence, not standalone product judgment.

That means:

- the server can supply current coordinates, stability signals, upgrade classifications, and project-health data
- the calling model still has to reason about tradeoffs when you ask broader questions like "which library should I choose?"
- the best results usually come when the client combines Maven Tools MCP with the raw Context7 tools exposed by the default image and, if the client supports it, web search for ecosystem context that is outside Maven metadata

In practice, library-choice prompts work well when the model uses this server to stay current and grounded, then uses documentation and general research to justify the recommendation.

## Everyday Prompts

### Version and upgrade checks

- "Check all latest versions of the dependencies in my `pom.xml`."
- "Compare my current Spring Boot stack with the latest stable releases."
- "Show me which of these dependencies are patch-only upgrades vs major upgrades."

### POM-aware analysis

- "Here's my `pom.xml` — what version does it actually resolve to for each dependency? Walk the parent chain and BOMs."
- "What can I safely bump in this `pom.xml`? Give me only the deterministic edits."
- "Here's a child module's `pom.xml` plus its parent (snapshot, not on Central). Resolve it as if it were built."

### Dependency selection

- "I need caching for a Spring Boot service at moderate throughput. Compare Redis and Caffeine."
- "I am adding JSON, HTTP, and time-series support to a new service. What libraries should I consider?"

### Health and compliance

- "Give me a health assessment for my key dependencies."
- "Scan these dependencies for CVEs and call out license risks."

## Richer Example Flows

### Starting a new feature

Ask:

> I'm building a REST API for IoT data ingestion. I need high-throughput JSON parsing, time-series data structures, and an async HTTP client. What libraries fit well with Spring Boot?

Expected value when the client uses Maven Tools MCP well:

- current Maven coordinates for suitable libraries
- guidance on what is already covered by Spring Boot
- version and stability awareness
- useful follow-up documentation targets when deeper library docs matter

### Choosing between alternatives

Ask:

> Should I use Redis or Caffeine for caching around 10k req/min in Spring Boot?

Useful output here includes:

- current versions
- comparative tradeoffs
- whether one option is overkill for the stated workload
- suggested dependency coordinates for the recommended path

This kind of answer depends on model reasoning. Maven Tools MCP provides the current dependency facts; the recommendation quality improves when the client also reads Context7 docs and falls back to web search when it needs performance, adoption, or framework-guidance context.

### Reviewing upgrade work

Ask:

> I want to upgrade Spring Boot. What will change, and what should I check before touching code?

Useful output here includes:

- whether the next step is a patch/minor/major move
- which related dependencies may also need attention
- whether the client should consult Context7 for migration docs
- clear separation of safe updates vs changes that need manual review

## Advanced Analysis Examples

### Dependency age

A response from `analyze_dependency_age` may look like:

```json
{
  "dependency": "org.springframework.boot:spring-boot-starter",
  "age_classification": "current",
  "days_since_release": 45,
  "recommendation": "Actively maintained - consider updating if needed"
}
```

### Release pattern analysis

A response from `analyze_release_patterns` may look like:

```json
{
  "dependency": "com.fasterxml.jackson.core:jackson-core",
  "maintenance_level": "active",
  "release_velocity": 1.2,
  "next_release_prediction": "Expected in 3 weeks"
}
```

### Project health

A response from `analyze_project_health` may look like:

```json
{
  "overall_health": "good",
  "average_health_score": 78,
  "age_distribution": {
    "fresh": 2,
    "current": 8,
    "aging": 3,
    "stale": 1
  }
}
```

### POM-aware: effective versions from raw XML

`analyze_pom_dependencies` takes a whole `<project>...</project>` and returns the resolved view. For a Spring Boot 3.5 app that doesn't pin Jackson but uses it transitively, you'll see:

```json
{
  "dependencies": [
    {
      "groupId": "com.fasterxml.jackson.core",
      "artifactId": "jackson-databind",
      "effectiveVersion": "2.19.2",
      "source": "MANAGED",
      "managedBy": {
        "groupId": "com.fasterxml.jackson",
        "artifactId": "jackson-bom",
        "version": "2.19.2"
      },
      "conflicts": []
    }
  ],
  "parentChain": [
    {"artifactId": "spring-boot-starter-parent", "version": "3.5.14"},
    {"artifactId": "spring-boot-dependencies", "version": "3.5.14"}
  ],
  "rootImportedBoms": [],
  "warnings": []
}
```

Read this as: "I didn't declare a Jackson version — Spring Boot's BOM transitively imports jackson-bom, which pinned me to 2.19.2." `EXPLICIT` would mean I declared the version inline; `EXPLICIT_OVERRIDE` would mean I declared a version *and* a BOM also manages it — useful for spotting deliberate pins.

When two BOMs at the same level disagree on a coordinate, `conflicts[]` lists every losing candidate version so the caller can see all the alternatives and decide whether to pin.

### POM-aware: deterministic upgrade plan

`recommend_pom_upgrades` builds on the analyzer and splits the result so a non-LLM agent can act on `deterministic_actions[]` while a human or LLM judges `needs_attention[]`:

```json
{
  "deterministicActions": [
    {
      "kind": "explicit_bump",
      "groupId": "org.apache.maven",
      "artifactId": "maven-artifact",
      "current": "3.9.14",
      "target": "3.9.15",
      "updateType": "patch"
    },
    {
      "kind": "bom_bump",
      "groupId": "org.springframework.boot",
      "artifactId": "spring-boot-starter-parent",
      "current": "3.5.13",
      "target": "3.5.14",
      "updateType": "patch"
    }
  ],
  "needsAttention": [
    {
      "kind": "major_available",
      "groupId": "org.springframework.boot",
      "artifactId": "spring-boot-starter-parent",
      "current": "3.5.14",
      "currentMajorLatest": "3.5.14",
      "latestStable": "4.0.6",
      "source": "MANAGED"
    }
  ],
  "warnings": []
}
```

`explicit_bump` edits a declared `<version>`; `bom_bump` edits the `<version>` of a user-controllable BOM (direct `<parent>` or root `<dependencyManagement>` import). Transitively-imported BOMs are intentionally absent — there's nothing for an agent to edit in your own POM.

`needs_attention[]` carries `latestOnCentral` on every entry so the reviewing model has full context in one round-trip and doesn't need to fan out per-coordinate `compare_dependency_versions` calls.

### POM-aware: multi-module with `sideloadedPoms`

If the parent isn't published yet (snapshot or local-only), pass it in the bundle:

```jsonc
analyze_pom_dependencies({
  pomXml: "<child module pom.xml>",
  sideloadedPoms: [
    "<root parent pom.xml>",
    "<sibling module that also needs to resolve>"
  ]
})
```

The resolver indexes each sideloaded POM by its self-declared `groupId:artifactId:version`, tries the bundle first, and only falls back to Maven Central if a coordinate isn't in the bundle. This makes the tool work in a fresh monorepo checkout before any `mvn install` has run.

## Example Commands And Prompts

These files are kept here as example entry points and showcase material.

They are useful for demonstrating how someone might ask for Maven Tools MCP-driven analysis in Claude Code or GitHub Copilot, but they are not the canonical source of orchestration behavior.

Use this split when thinking about maintenance:

- local `.claude/commands/` and `.github/prompts/` are illustrative examples
- the [`maven-tools` skill in the separate `agent-skills` repository](https://github.com/arvindand/agent-skills/tree/main/skills/maven-tools) gives agents general guidance for using Maven Tools MCP across varied use cases
- the local dependency agent described in [`dogfooding.md`](dogfooding.md) defines this repository's automation policy: direct MCP for deterministic minor/patch updates, Copilot SDK only for major-review mode

### Claude Code slash commands

The repository includes command helpers in `.claude/commands/`:

| Command | Purpose |
|---------|---------|
| `/deps-check` | Quick version lookup for specific dependencies |
| `/deps-health` | Health audit with security and license analysis |
| `/deps-upgrade` | Upgrade recommendations with breaking-change awareness |
| `/deps-age` | Freshness and maintenance activity analysis |

Examples:

```bash
/deps-check org.springframework:spring-core,com.google.guava:guava
/deps-health
/deps-upgrade org.springframework:spring-core:6.0.0,junit:junit:4.13.2
```

### GitHub Copilot prompts

The repository includes prompt templates in `.github/prompts/`:

| Prompt | Purpose |
|--------|---------|
| `dependency-audit.prompt.md` | Dependency audit with health scoring |
| `security-scan.prompt.md` | CVE scanning and remediation guidance |
| `upgrade-plan.prompt.md` | Phased upgrade planning |

If you want broader agent guidance that can adapt across projects and prompts, prefer the `maven-tools` skill in the separate `agent-skills` repository. If you need deterministic repo automation, prefer the explicit policy in the local dependency agent instead of copying these example prompts into CI.

## FAQ

### Does this replace Renovate or Dependabot?

For Maven Central-based JVM projects, it can. Maven Tools MCP provides the dependency intelligence, and an agent workflow built on top of it can use that context to make safer update decisions than a blind version-bump bot.

That is already how this repository's weekly self-update workflow works:

- it checks real current vs available versions
- it auto-applies stable minor and patch updates through direct MCP calls
- it avoids auto-applying major upgrades and reserves Copilot SDK usage for manual major-review runs
- it opens a single reviewable PR and relies on normal CI

It is still not a universal drop-in replacement across every package ecosystem, but for Maven Central-driven JVM projects it is a realistic replacement for routine dependency bot PRs.

### Does it work offline?

Not fully. It depends on live Maven Central access for uncached queries. Cached results can still help for previously queried dependencies.

### Does it support non-Maven build tools?

Yes for JVM projects that use Maven Central data. The tool speaks Maven coordinates, which are shared across Maven, Gradle, SBT, and Mill.

## Related Docs

- [`tools.md`](tools.md)
- [`setup.md`](setup.md)
- [`dogfooding.md`](dogfooding.md)