Maven Artifacts

A TypeScript-based Model Context Protocol (MCP) server that provides Maven2 module version resolution capabilities with caching and logging.

Features

• Latest stable version resolution from Maven Central
• Pre-release filtering (excludes preview, RC, alpha, beta, snapshot, milestone versions)
• 5-minute in-memory cache with automatic cleanup
• Request/response logging
• Error handling and input validation

Installation from Source

npm install
npm run build

Usage

Stdio Mode (Default)

For MCP clients like Cursor:

npm start

Remote HTTP Server Mode

Run as a standalone network service:

# Start HTTP server on port 3001
npm run start:http

# Or with custom port
npm run dev:http -- --port 8080

Development Mode

# Stdio mode
npm run dev

# HTTP mode
npm run dev:http

Setup

Stdio Mode (Recommended for Cursor)

Add to your .cursor-settings.json:

{
  "mcp": {
    "mcpServers": {
      "maven-resolver": {
        "command": "npx",
        "args": ["maven-artifacts-mcp", "--stdio"],
        "env": {
          "CACHE_TTL_MINUTES": "5",
          "MAVEN_API_TIMEOUT": "10000"
        }
      }
    }
  }
}

Remote HTTP Mode

Start the server: npm run start:http, then configure:

{
  "mcp": {
    "mcpServers": {
      "maven-resolver-remote": {
        "command": "http",
        "args": ["http://localhost:3001/sse"],
        "env": {
          "CACHE_TTL_MINUTES": "5",
          "MAVEN_API_TIMEOUT": "10000"
        }
      }
    }
  }
}

HTTP Endpoints:

• GET /sse - MCP Server-Sent Events endpoint
• GET /health - Health check endpoint
• GET /tools - List available MCP tools and capabilities

Example /tools response:

curl http://localhost:3001/tools

{
  "service": "maven-mcp-server",
  "tools": [{"name": "latest_version", "description": "Get the latest stable version of a Maven artifact"}],
  "features": ["Filters out pre-release versions", "In-memory caching with 5-minute TTL"],
  "endpoints": {"health": "/health", "sse": "/sse", "tools": "/tools"}
}

Other environment variables like

    "HTTPS_PROXY": "http://myorg.proxy:8080",
    "HTTP_PROXY": "http://myorg.proxy:8080",
    "NO_PROXY": "localhost,127.0.0.1,.local"
    "LOG_LEVEL": "debug",
    "NODE_ENV": "development"       

can also be provided.

MCP Tool: latest_version

Retrieves the latest version information for a Maven artifact.

Parameters

Parameter	Type	Required	Description
groupId	string	Yes	Maven group ID (e.g., "org.springframework")
artifactId	string	Yes	Maven artifact ID (e.g., "spring-core")

Example Usage

{
  "tool": "latest_version",
  "arguments": {
    "groupId": "org.springframework",
    "artifactId": "spring-core"
  }
}

Response includes latest version, last updated timestamp, repository, cache status, and excluded pre-release versions.

Version Filtering

Automatically filters out pre-release versions:

• Preview versions (e.g., 6.1.0-preview)
• Release candidates (e.g., 6.1.0-RC1)
• Alpha/Beta versions (e.g., 6.1.0-alpha)
• Snapshots (e.g., 6.1.0-SNAPSHOT)
• Milestones (e.g., 7.0.0-M1)

Configuration

Environment Variables

Variable	Default	Description
MAVEN_API_TIMEOUT	10000	API request timeout in milliseconds
CACHE_TTL_MINUTES	5	Cache TTL in minutes
LOG_LEVEL	info	Logging verbosity level

Npm Tasks

• npm run build - Compile TypeScript
• npm start - Start the server
• npm run dev - Build and start in development mode
• npm test - Run test suite
• npm run test:coverage - Run tests with coverage

License

Apache 2.0 License