# Maven Version Server

MCP server for Maven dependency version management using **ONLY** `maven-metadata.xml` from Maven Central (NO Solr search API).

## Features

- **4 Tools** for Maven dependency management
- **Strict stability filtering** - excludes SNAPSHOT, alpha, beta, RC, milestones, etc.
- **Pure metadata approach** - uses only maven-metadata.xml
- **Fast and reliable** - direct XML parsing, no search API dependencies

## Tools

### 1. get_latest_stable_version

Get the latest stable version for a Maven dependency.

**Input:**
```json
{
  "dependency": "io.mockk:mockk"
}
```

**Output:** Plain text version string (e.g., `1.14.7`)

### 2. get_all_versions

List all versions with optional filtering and limits.

**Input:**
```json
{
  "dependency": "com.google.guava:guava",
  "stableOnly": true,
  "limit": 10
}
```

**Output:** Newline-separated version list

### 3. check_version_exists

Verify if a specific version exists and check its stability.

**Input:**
```json
{
  "dependency": "org.springframework:spring-core",
  "version": "6.2.8"
}
```

**Output:** JSON object with exists, isStable fields

### 4. compare_versions

Compare two versions and get upgrade recommendations.

**Input:**
```json
{
  "dependency": "org.springframework:spring-core",
  "currentVersion": "5.3.20",
  "targetVersion": "6.2.8"
}
```

**Output:** JSON object with upgrade type and recommendation

## Stability Filter

Excludes versions containing (case-insensitive):
- `SNAPSHOT` - Development snapshots
- `alpha` / `a` - Alpha releases
- `beta` / `b` - Beta releases
- `RC` - Release candidates
- `M` + digit - Milestones
- `CR` - Candidate releases
- `EA` - Early access
- `preview` - Preview releases
- `dev` - Development versions
- `incubating` - Apache incubator

## Installation

### Via npm (Recommended)

```bash
npm install -g maven-version-server
```

Or use with npx (no installation needed):

```bash
npx maven-version-server
```

### Configure for Claude Code CLI

Add to `~/.claude/mcp_servers.json`:

```json
{
  "mcpServers": {
    "maven-version": {
      "command": "npx",
      "args": ["maven-version-server"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "maven-version": {
      "command": "maven-version-server"
    }
  }
}
```

### Build from source

```bash
git clone https://github.com/krotim/maven-version-server.git
cd maven-version-server
npm install
npm run build
```

## Usage Examples

### Example 1: Get latest stable version

```
User: What's the latest stable version of MockK?
Claude: [Uses get_latest_stable_version with dependency="io.mockk:mockk"]
Result: 1.14.7
```

### Example 2: Compare versions

```
User: Should I upgrade Spring Core from 5.3.20 to 6.2.8?
Claude: [Uses compare_versions]
Result: {
  "currentVersion": "5.3.20",
  "targetVersion": "6.2.8",
  "upgradeType": "major",
  "recommendation": "Caution: Major version upgrade may contain breaking changes. Review migration guide.",
  "isCurrentStable": true,
  "isTargetStable": true
}
```

### Example 3: List recent versions

```
User: Show me the last 5 versions of Guava
Claude: [Uses get_all_versions with limit=5]
Result:
33.5.0-jre
33.4.0-jre
33.3.1-jre
33.3.0-jre
33.2.1-jre
```

## Testing

### Test with MCP Inspector

```bash
npm run inspector
```

### Manual test

```bash
node build/index.js
```

## Technical Details

- **Language:** TypeScript (strict mode)
- **Data Source:** https://repo1.maven.org/maven2/{groupPath}/{artifactId}/maven-metadata.xml
- **Transport:** STDIO (Claude Code CLI)
- **Timeout:** 10 seconds
- **Dependencies:** @modelcontextprotocol/sdk, axios, xml2js

## License

MIT