maven-central-mcp 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "maven-mcp",
+  "description": "Maven dependency intelligence for Claude Code",
+  "owner": {
+    "name": "kirich1409"
+  },
+  "plugins": [
+    {
+      "name": "maven-mcp",
+      "description": "Maven dependency intelligence — auto-registers MCP server, provides /check-deps and /latest-version skills",
+      "author": {
+        "name": "kirich1409"
+      },
+      "version": "0.2.0",
+      "category": "development",
+      "homepage": "https://github.com/kirich1409/maven-central-mcp",
+      "source": "./plugin"
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,59 @@
+# maven-central-mcp
+
+MCP server for Maven Central dependency intelligence. Provides AI assistants with structured, live dependency data from Maven Central.
+
+Works with any JVM build tool that uses Maven Central coordinates (Maven, Gradle, SBT, etc).
+
+## Quick Start
+
+```bash
+npx maven-central-mcp
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "maven-central": {
+      "command": "npx",
+      "args": ["maven-central-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Create `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "maven-central": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["maven-central-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_latest_version` | Find the latest version with stability-aware selection (STABLE_ONLY / PREFER_STABLE / ALL) |
+| `check_version_exists` | Verify a specific version exists and classify its stability |
+| `check_multiple_dependencies` | Bulk lookup of latest versions for a list of dependencies |
+| `compare_dependency_versions` | Compare current versions against latest, with upgrade type (major/minor/patch) |
+
+## Version Stability
+
+Versions are classified as: `stable`, `rc`, `beta`, `alpha`, `milestone`, or `snapshot`.
+
+## License
+
+MIT

package/dist/discovery/discover.d.ts

@@ -0,0 +1,2 @@
+import type { DiscoveryResult } from "./types.js";
+export declare function discoverRepositories(projectRoot: string): DiscoveryResult;

package/dist/discovery/discover.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseGradleRepositories } from "./gradle-parser.js";
+import { parseMavenRepositories } from "./maven-parser.js";
+const GRADLE_FILES = [
+    "settings.gradle.kts",
+    "settings.gradle",
+    "build.gradle.kts",
+    "build.gradle",
+];
+export function discoverRepositories(projectRoot) {
+    const allRepos = [];
+    const seen = new Set();
+    let buildSystem = "unknown";
+    function addRepos(repos) {
+        for (const repo of repos) {
+            if (!seen.has(repo.url)) {
+                seen.add(repo.url);
+                allRepos.push(repo);
+            }
+        }
+    }
+    // Try Gradle files
+    for (const file of GRADLE_FILES) {
+        const path = join(projectRoot, file);
+        if (existsSync(path)) {
+            buildSystem = "gradle";
+            try {
+                const content = readFileSync(path, "utf-8");
+                addRepos(parseGradleRepositories(content));
+            }
+            catch {
+                console.error(`Failed to parse ${path}`);
+            }
+        }
+    }
+    // Try Maven pom.xml (only if no Gradle files found)
+    if (buildSystem === "unknown") {
+        const pomPath = join(projectRoot, "pom.xml");
+        if (existsSync(pomPath)) {
+            buildSystem = "maven";
+            try {
+                const content = readFileSync(pomPath, "utf-8");
+                addRepos(parseMavenRepositories(content));
+            }
+            catch {
+                console.error(`Failed to parse ${pomPath}`);
+            }
+        }
+    }
+    return {
+        repositories: allRepos,
+        buildSystem,
+        projectRoot,
+    };
+}

package/dist/discovery/gradle-parser.d.ts

@@ -0,0 +1,2 @@
+import type { RepositoryConfig } from "./types.js";
+export declare function parseGradleRepositories(content: string): RepositoryConfig[];

package/dist/discovery/gradle-parser.js

@@ -0,0 +1,38 @@
+import { MAVEN_CENTRAL, GOOGLE_MAVEN, GRADLE_PLUGIN_PORTAL } from "../maven/repository.js";
+const WELL_KNOWN_REPOS = {
+    mavenCentral: { name: MAVEN_CENTRAL.name, url: MAVEN_CENTRAL.url },
+    google: { name: GOOGLE_MAVEN.name, url: GOOGLE_MAVEN.url },
+    gradlePluginPortal: { name: GRADLE_PLUGIN_PORTAL.name, url: GRADLE_PLUGIN_PORTAL.url },
+};
+export function parseGradleRepositories(content) {
+    const repos = [];
+    // Well-known: mavenCentral(), google(), gradlePluginPortal()
+    for (const [funcName, config] of Object.entries(WELL_KNOWN_REPOS)) {
+        const pattern = new RegExp(`\\b${funcName}\\s*\\(\\s*\\)`, "g");
+        if (pattern.test(content)) {
+            repos.push(config);
+        }
+    }
+    // maven("url") or maven('url')
+    const mavenDirectRegex = /\bmaven\s*\(\s*["']([^"']+)["']\s*\)/g;
+    let match;
+    while ((match = mavenDirectRegex.exec(content)) !== null) {
+        repos.push({ name: match[1], url: match[1] });
+    }
+    // maven(url = "url") or maven(url = 'url')
+    const mavenUrlParamRegex = /\bmaven\s*\(\s*url\s*=\s*["']([^"']+)["']\s*\)/g;
+    while ((match = mavenUrlParamRegex.exec(content)) !== null) {
+        repos.push({ name: match[1], url: match[1] });
+    }
+    // maven { url = uri("url") } or maven { url = uri('url') }
+    const mavenBlockUriRegex = /\bmaven\s*\{[^}]*url\s*=\s*uri\s*\(\s*["']([^"']+)["']\s*\)/g;
+    while ((match = mavenBlockUriRegex.exec(content)) !== null) {
+        repos.push({ name: match[1], url: match[1] });
+    }
+    // Groovy: maven { url 'url' } or maven { url "url" }
+    const mavenBlockGroovyRegex = /\bmaven\s*\{[^}]*url\s+["']([^"']+)["']/g;
+    while ((match = mavenBlockGroovyRegex.exec(content)) !== null) {
+        repos.push({ name: match[1], url: match[1] });
+    }
+    return repos;
+}

package/dist/discovery/maven-parser.d.ts

@@ -0,0 +1,2 @@
+import type { RepositoryConfig } from "./types.js";
+export declare function parseMavenRepositories(content: string): RepositoryConfig[];

package/dist/discovery/maven-parser.js

@@ -0,0 +1,14 @@
+export function parseMavenRepositories(content) {
+    const repos = [];
+    const repoBlockRegex = /<repository>([\s\S]*?)<\/repository>/g;
+    let match;
+    while ((match = repoBlockRegex.exec(content)) !== null) {
+        const block = match[1];
+        const url = block.match(/<url>([^<]+)<\/url>/)?.[1]?.trim();
+        if (!url)
+            continue;
+        const id = block.match(/<id>([^<]+)<\/id>/)?.[1]?.trim();
+        repos.push({ name: id ?? url, url });
+    }
+    return repos;
+}

package/dist/discovery/types.d.ts

@@ -0,0 +1,9 @@
+export interface RepositoryConfig {
+    name: string;
+    url: string;
+}
+export interface DiscoveryResult {
+    repositories: RepositoryConfig[];
+    buildSystem: "gradle" | "maven" | "unknown";
+    projectRoot: string;
+}

package/dist/discovery/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { HttpMavenRepository, MAVEN_CENTRAL, GOOGLE_MAVEN, GRADLE_PLUGIN_PORTAL } from "./maven/repository.js";
+import { findProjectRoot } from "./project/find-project-root.js";
+import { discoverRepositories } from "./discovery/discover.js";
+import { getLatestVersionHandler } from "./tools/get-latest-version.js";
+import { checkVersionExistsHandler } from "./tools/check-version-exists.js";
+import { checkMultipleDependenciesHandler } from "./tools/check-multiple-dependencies.js";
+import { compareDependencyVersionsHandler } from "./tools/compare-dependency-versions.js";
+const server = new McpServer({
+    name: "maven-central-mcp",
+    version: "0.2.0",
+});
+let cachedRepos = null;
+function getRepositories() {
+    if (cachedRepos)
+        return cachedRepos;
+    const repos = [];
+    const projectRoot = findProjectRoot(process.cwd());
+    if (projectRoot) {
+        const discovery = discoverRepositories(projectRoot);
+        console.error(`Discovered ${discovery.repositories.length} repositories from ${discovery.buildSystem} project at ${projectRoot}`);
+        for (const config of discovery.repositories) {
+            repos.push(new HttpMavenRepository(config.name, config.url));
+        }
+    }
+    // Add well-known repos as fallback (skip if already discovered)
+    for (const fallback of [GOOGLE_MAVEN, GRADLE_PLUGIN_PORTAL, MAVEN_CENTRAL]) {
+        if (!repos.some((r) => r.url === fallback.url)) {
+            repos.push(fallback);
+        }
+    }
+    cachedRepos = repos;
+    return repos;
+}
+server.tool("get_latest_version", "Find the latest version of a Maven artifact with stability-aware selection", {
+    groupId: z.string().describe("Maven group ID (e.g. io.ktor)"),
+    artifactId: z.string().describe("Maven artifact ID (e.g. ktor-server-core)"),
+    stabilityFilter: z
+        .enum(["STABLE_ONLY", "PREFER_STABLE", "ALL"])
+        .optional()
+        .describe("Version stability filter (default: PREFER_STABLE)"),
+}, async (params) => {
+    const result = await getLatestVersionHandler(getRepositories(), params);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("check_version_exists", "Verify a specific version exists and classify its stability", {
+    groupId: z.string().describe("Maven group ID"),
+    artifactId: z.string().describe("Maven artifact ID"),
+    version: z.string().describe("Version to check"),
+}, async (params) => {
+    const result = await checkVersionExistsHandler(getRepositories(), params);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("check_multiple_dependencies", "Bulk lookup of latest versions for a list of Maven dependencies", {
+    dependencies: z.array(z.object({
+        groupId: z.string().describe("Maven group ID"),
+        artifactId: z.string().describe("Maven artifact ID"),
+    })).describe("List of dependencies to check"),
+}, async (params) => {
+    const result = await checkMultipleDependenciesHandler(getRepositories(), params);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+server.tool("compare_dependency_versions", "Compare current dependency versions against latest available, showing upgrade type (major/minor/patch)", {
+    dependencies: z.array(z.object({
+        groupId: z.string().describe("Maven group ID"),
+        artifactId: z.string().describe("Maven artifact ID"),
+        currentVersion: z.string().describe("Currently used version"),
+    })).describe("Dependencies with current versions to compare"),
+}, async (params) => {
+    const result = await compareDependencyVersionsHandler(getRepositories(), params);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("maven-central-mcp running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/maven/client.d.ts

@@ -0,0 +1,8 @@
+import type { MavenMetadata, MavenSearchResponse } from "./types.js";
+export declare class MavenCentralClient {
+    buildSearchUrl(groupId: string, artifactId: string, rows: number): string;
+    buildMetadataUrl(groupId: string, artifactId: string): string;
+    searchArtifact(groupId: string, artifactId: string): Promise<MavenSearchResponse>;
+    fetchMetadata(groupId: string, artifactId: string): Promise<MavenMetadata>;
+    parseMetadataXml(xml: string, groupId: string, artifactId: string): MavenMetadata;
+}

package/dist/maven/client.js

@@ -0,0 +1,40 @@
+const SEARCH_BASE = "https://search.maven.org/solrsearch/select";
+const REPO_BASE = "https://repo1.maven.org/maven2";
+export class MavenCentralClient {
+    buildSearchUrl(groupId, artifactId, rows) {
+        return `${SEARCH_BASE}?q=g:${groupId}+AND+a:${artifactId}&rows=${rows}&wt=json`;
+    }
+    buildMetadataUrl(groupId, artifactId) {
+        const groupPath = groupId.replace(/\./g, "/");
+        return `${REPO_BASE}/${groupPath}/${artifactId}/maven-metadata.xml`;
+    }
+    async searchArtifact(groupId, artifactId) {
+        const url = this.buildSearchUrl(groupId, artifactId, 1);
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Maven Central search failed: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+    async fetchMetadata(groupId, artifactId) {
+        const url = this.buildMetadataUrl(groupId, artifactId);
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Maven Central metadata fetch failed: ${response.status} ${response.statusText}`);
+        }
+        const xml = await response.text();
+        return this.parseMetadataXml(xml, groupId, artifactId);
+    }
+    parseMetadataXml(xml, groupId, artifactId) {
+        const versions = [];
+        const versionRegex = /<version>([^<]+)<\/version>/g;
+        let match;
+        while ((match = versionRegex.exec(xml)) !== null) {
+            versions.push(match[1]);
+        }
+        const latest = xml.match(/<latest>([^<]+)<\/latest>/)?.[1];
+        const release = xml.match(/<release>([^<]+)<\/release>/)?.[1];
+        const lastUpdated = xml.match(/<lastUpdated>([^<]+)<\/lastUpdated>/)?.[1];
+        return { groupId, artifactId, versions, latest, release, lastUpdated };
+    }
+}

package/dist/maven/repository.d.ts

@@ -0,0 +1,18 @@
+import type { MavenMetadata } from "./types.js";
+export interface MavenRepository {
+    readonly name: string;
+    readonly url: string;
+    fetchMetadata(groupId: string, artifactId: string): Promise<MavenMetadata>;
+}
+export declare class HttpMavenRepository implements MavenRepository {
+    readonly name: string;
+    readonly url: string;
+    constructor(name: string, url: string);
+    buildMetadataUrl(groupId: string, artifactId: string): string;
+    fetchMetadata(groupId: string, artifactId: string): Promise<MavenMetadata>;
+    parseMetadataXml(xml: string, groupId: string, artifactId: string): MavenMetadata;
+}
+export declare const MAVEN_CENTRAL: HttpMavenRepository;
+export declare const GOOGLE_MAVEN: HttpMavenRepository;
+export declare const GRADLE_PLUGIN_PORTAL: HttpMavenRepository;
+export declare const PROXY_TARGET_URLS: Set<string>;

package/dist/maven/repository.js

@@ -0,0 +1,43 @@
+export class HttpMavenRepository {
+    name;
+    url;
+    constructor(name, url) {
+        this.name = name;
+        this.url = url.replace(/\/+$/, "");
+    }
+    buildMetadataUrl(groupId, artifactId) {
+        const groupPath = groupId.replace(/\./g, "/");
+        return `${this.url}/${groupPath}/${artifactId}/maven-metadata.xml`;
+    }
+    async fetchMetadata(groupId, artifactId) {
+        const url = this.buildMetadataUrl(groupId, artifactId);
+        const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+        if (!response.ok) {
+            throw new Error(`Metadata fetch failed from ${this.name}: ${response.status} ${response.statusText}`);
+        }
+        const xml = await response.text();
+        return this.parseMetadataXml(xml, groupId, artifactId);
+    }
+    parseMetadataXml(xml, groupId, artifactId) {
+        const versions = [];
+        const versionRegex = /<version>([^<]+)<\/version>/g;
+        let match;
+        while ((match = versionRegex.exec(xml)) !== null) {
+            versions.push(match[1]);
+        }
+        const latest = xml.match(/<latest>([^<]+)<\/latest>/)?.[1];
+        const release = xml.match(/<release>([^<]+)<\/release>/)?.[1];
+        const lastUpdated = xml.match(/<lastUpdated>([^<]+)<\/lastUpdated>/)?.[1];
+        return { groupId, artifactId, versions, latest, release, lastUpdated };
+    }
+}
+export const MAVEN_CENTRAL = new HttpMavenRepository("Maven Central", "https://repo1.maven.org/maven2");
+export const GOOGLE_MAVEN = new HttpMavenRepository("Google", "https://maven.google.com");
+export const GRADLE_PLUGIN_PORTAL = new HttpMavenRepository("Gradle Plugin Portal", "https://plugins.gradle.org/m2");
+// URLs commonly proxied by corporate repos (Nexus, Artifactory).
+// When a custom repo returns results, these are deprioritized to avoid
+// duplicate/stale metadata. Google Maven and Gradle Plugin Portal are NOT
+// included — they host unique artifacts not typically proxied.
+export const PROXY_TARGET_URLS = new Set([
+    MAVEN_CENTRAL.url,
+]);

package/dist/maven/resolver.d.ts

@@ -0,0 +1,8 @@
+import type { MavenRepository } from "./repository.js";
+import type { MavenMetadata } from "./types.js";
+export interface ResolveFirstResult {
+    metadata: MavenMetadata;
+    repository: MavenRepository;
+}
+export declare function resolveFirst(repos: MavenRepository[], groupId: string, artifactId: string): Promise<ResolveFirstResult | null>;
+export declare function resolveAll(repos: MavenRepository[], groupId: string, artifactId: string): Promise<MavenMetadata>;

package/dist/maven/resolver.js

@@ -0,0 +1,61 @@
+import { PROXY_TARGET_URLS } from "./repository.js";
+export async function resolveFirst(repos, groupId, artifactId) {
+    for (const repo of repos) {
+        try {
+            const metadata = await repo.fetchMetadata(groupId, artifactId);
+            return { metadata, repository: repo };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+export async function resolveAll(repos, groupId, artifactId) {
+    if (repos.length === 0) {
+        throw new Error(`No repositories configured to search for ${groupId}:${artifactId}`);
+    }
+    const results = await Promise.all(repos.map(async (repo) => {
+        try {
+            return await repo.fetchMetadata(groupId, artifactId);
+        }
+        catch {
+            return null;
+        }
+    }));
+    // Custom repos (Nexus, Artifactory) typically proxy Maven Central.
+    // When a custom repo returns results for an artifact, skip Maven Central
+    // results to avoid duplicates and stale metadata from proxy caching.
+    // Google Maven and Gradle Plugin Portal are NOT proxy targets —
+    // they host unique artifacts and always contribute results.
+    const all = results.map((r, i) => ({ result: r, repo: repos[i] }));
+    const hasCustomResult = all.some(({ result, repo }) => result !== null && !PROXY_TARGET_URLS.has(repo.url));
+    const successful = all
+        .filter(({ result, repo }) => result !== null && !(hasCustomResult && PROXY_TARGET_URLS.has(repo.url)))
+        .map(({ result }) => result);
+    if (successful.length === 0) {
+        throw new Error(`Artifact ${groupId}:${artifactId} not found in any repository`);
+    }
+    const orderedVersions = [];
+    const seen = new Set();
+    for (const meta of successful) {
+        for (const v of meta.versions) {
+            if (!seen.has(v)) {
+                seen.add(v);
+                orderedVersions.push(v);
+            }
+        }
+    }
+    // Pick the most recent latest/release across all repos
+    const allLatest = successful.map((m) => m.latest).filter(Boolean);
+    const allRelease = successful.map((m) => m.release).filter(Boolean);
+    const lastVersion = orderedVersions[orderedVersions.length - 1];
+    return {
+        groupId,
+        artifactId,
+        versions: orderedVersions,
+        latest: allLatest.includes(lastVersion) ? lastVersion : allLatest[allLatest.length - 1] ?? lastVersion,
+        release: allRelease.includes(lastVersion) ? lastVersion : allRelease[allRelease.length - 1] ?? lastVersion,
+        lastUpdated: successful[0].lastUpdated,
+    };
+}

package/dist/maven/types.d.ts

@@ -0,0 +1,23 @@
+export interface MavenSearchResponse {
+    response: {
+        numFound: number;
+        docs: MavenArtifact[];
+    };
+}
+export interface MavenArtifact {
+    id: string;
+    g: string;
+    a: string;
+    v: string;
+    latestVersion: string;
+    timestamp: number;
+    versionCount: number;
+}
+export interface MavenMetadata {
+    groupId: string;
+    artifactId: string;
+    versions: string[];
+    latest?: string;
+    release?: string;
+    lastUpdated?: string;
+}

package/dist/maven/types.js

@@ -0,0 +1 @@
+export {};

package/dist/project/find-project-root.d.ts

@@ -0,0 +1,2 @@
+export declare const BUILD_FILE_MARKERS: readonly ["settings.gradle.kts", "settings.gradle", "build.gradle.kts", "build.gradle", "pom.xml"];
+export declare function findProjectRoot(startDir: string): string | null;

package/dist/project/find-project-root.js

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export const BUILD_FILE_MARKERS = [
+    "settings.gradle.kts",
+    "settings.gradle",
+    "build.gradle.kts",
+    "build.gradle",
+    "pom.xml",
+];
+export function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        for (const marker of BUILD_FILE_MARKERS) {
+            if (existsSync(join(current, marker))) {
+                return current;
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}

package/dist/tools/check-multiple-dependencies.d.ts

@@ -0,0 +1,20 @@
+import type { MavenRepository } from "../maven/repository.js";
+interface Dependency {
+    groupId: string;
+    artifactId: string;
+}
+export interface CheckMultipleDependenciesInput {
+    dependencies: Dependency[];
+}
+export interface DependencyResult {
+    groupId: string;
+    artifactId: string;
+    latestVersion: string;
+    stability: string;
+    error?: string;
+}
+export interface CheckMultipleDependenciesResult {
+    results: DependencyResult[];
+}
+export declare function checkMultipleDependenciesHandler(repos: MavenRepository[], input: CheckMultipleDependenciesInput): Promise<CheckMultipleDependenciesResult>;
+export {};

package/dist/tools/check-multiple-dependencies.js

@@ -0,0 +1,26 @@
+import { classifyVersion, findLatestVersion } from "../version/classify.js";
+import { resolveAll } from "../maven/resolver.js";
+export async function checkMultipleDependenciesHandler(repos, input) {
+    const results = await Promise.all(input.dependencies.map(async (dep) => {
+        try {
+            const metadata = await resolveAll(repos, dep.groupId, dep.artifactId);
+            const latest = findLatestVersion(metadata.versions);
+            return {
+                groupId: dep.groupId,
+                artifactId: dep.artifactId,
+                latestVersion: latest,
+                stability: classifyVersion(latest),
+            };
+        }
+        catch (e) {
+            return {
+                groupId: dep.groupId,
+                artifactId: dep.artifactId,
+                latestVersion: "",
+                stability: "",
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }));
+    return { results };
+}

package/dist/tools/check-version-exists.d.ts

@@ -0,0 +1,15 @@
+import type { MavenRepository } from "../maven/repository.js";
+export interface CheckVersionExistsInput {
+    groupId: string;
+    artifactId: string;
+    version: string;
+}
+export interface CheckVersionExistsResult {
+    groupId: string;
+    artifactId: string;
+    version: string;
+    exists: boolean;
+    stability?: string;
+    repository?: string;
+}
+export declare function checkVersionExistsHandler(repos: MavenRepository[], input: CheckVersionExistsInput): Promise<CheckVersionExistsResult>;

package/dist/tools/check-version-exists.js

@@ -0,0 +1,27 @@
+import { classifyVersion } from "../version/classify.js";
+export async function checkVersionExistsHandler(repos, input) {
+    for (const repo of repos) {
+        try {
+            const metadata = await repo.fetchMetadata(input.groupId, input.artifactId);
+            if (metadata.versions.includes(input.version)) {
+                return {
+                    groupId: input.groupId,
+                    artifactId: input.artifactId,
+                    version: input.version,
+                    exists: true,
+                    stability: classifyVersion(input.version),
+                    repository: repo.name,
+                };
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return {
+        groupId: input.groupId,
+        artifactId: input.artifactId,
+        version: input.version,
+        exists: false,
+    };
+}

package/dist/tools/compare-dependency-versions.d.ts

@@ -0,0 +1,31 @@
+import type { MavenRepository } from "../maven/repository.js";
+interface DependencyWithVersion {
+    groupId: string;
+    artifactId: string;
+    currentVersion: string;
+}
+export interface CompareDependencyVersionsInput {
+    dependencies: DependencyWithVersion[];
+}
+export interface CompareResult {
+    groupId: string;
+    artifactId: string;
+    currentVersion: string;
+    latestVersion: string;
+    latestStability: string;
+    upgradeType: string;
+    upgradeAvailable: boolean;
+    error?: string;
+}
+export interface CompareDependencyVersionsResult {
+    results: CompareResult[];
+    summary: {
+        total: number;
+        upgradeable: number;
+        major: number;
+        minor: number;
+        patch: number;
+    };
+}
+export declare function compareDependencyVersionsHandler(repos: MavenRepository[], input: CompareDependencyVersionsInput): Promise<CompareDependencyVersionsResult>;
+export {};

package/dist/tools/compare-dependency-versions.js

@@ -0,0 +1,41 @@
+import { classifyVersion, findLatestVersion } from "../version/classify.js";
+import { getUpgradeType } from "../version/compare.js";
+import { resolveAll } from "../maven/resolver.js";
+export async function compareDependencyVersionsHandler(repos, input) {
+    const results = await Promise.all(input.dependencies.map(async (dep) => {
+        try {
+            const metadata = await resolveAll(repos, dep.groupId, dep.artifactId);
+            const latest = findLatestVersion(metadata.versions);
+            const upgradeType = getUpgradeType(dep.currentVersion, latest);
+            return {
+                groupId: dep.groupId,
+                artifactId: dep.artifactId,
+                currentVersion: dep.currentVersion,
+                latestVersion: latest,
+                latestStability: classifyVersion(latest),
+                upgradeType,
+                upgradeAvailable: upgradeType !== "none",
+            };
+        }
+        catch (e) {
+            return {
+                groupId: dep.groupId,
+                artifactId: dep.artifactId,
+                currentVersion: dep.currentVersion,
+                latestVersion: "",
+                latestStability: "",
+                upgradeType: "none",
+                upgradeAvailable: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    }));
+    const summary = {
+        total: results.length,
+        upgradeable: results.filter((r) => r.upgradeAvailable).length,
+        major: results.filter((r) => r.upgradeType === "major").length,
+        minor: results.filter((r) => r.upgradeType === "minor").length,
+        patch: results.filter((r) => r.upgradeType === "patch").length,
+    };
+    return { results, summary };
+}

package/dist/tools/get-latest-version.d.ts

@@ -0,0 +1,15 @@
+import type { StabilityFilter } from "../version/types.js";
+import type { MavenRepository } from "../maven/repository.js";
+export interface GetLatestVersionInput {
+    groupId: string;
+    artifactId: string;
+    stabilityFilter?: StabilityFilter;
+}
+export interface GetLatestVersionResult {
+    groupId: string;
+    artifactId: string;
+    latestVersion: string;
+    stability: string;
+    allVersionsCount: number;
+}
+export declare function getLatestVersionHandler(repos: MavenRepository[], input: GetLatestVersionInput): Promise<GetLatestVersionResult>;

package/dist/tools/get-latest-version.js

@@ -0,0 +1,17 @@
+import { classifyVersion, findLatestVersion } from "../version/classify.js";
+import { resolveAll } from "../maven/resolver.js";
+export async function getLatestVersionHandler(repos, input) {
+    const metadata = await resolveAll(repos, input.groupId, input.artifactId);
+    const filter = input.stabilityFilter ?? "PREFER_STABLE";
+    const selected = findLatestVersion(metadata.versions, filter);
+    if (!selected) {
+        throw new Error(`No stable version found for ${input.groupId}:${input.artifactId}`);
+    }
+    return {
+        groupId: input.groupId,
+        artifactId: input.artifactId,
+        latestVersion: selected,
+        stability: classifyVersion(selected),
+        allVersionsCount: metadata.versions.length,
+    };
+}

package/dist/version/classify.d.ts

@@ -0,0 +1,3 @@
+import type { StabilityFilter, StabilityType } from "./types.js";
+export declare function classifyVersion(version: string): StabilityType;
+export declare function findLatestVersion(versions: string[], filter?: StabilityFilter): string | undefined;

package/dist/version/classify.js

@@ -0,0 +1,24 @@
+const STABILITY_PATTERNS = [
+    [/[-.]?SNAPSHOT$/i, "snapshot"],
+    [/[-.](?:alpha|a(?=\d|[-.]|$))[-.]?\d*/i, "alpha"],
+    [/[-.](?:beta|b(?=\d|[-.]|$))[-.]?\d*/i, "beta"],
+    [/[-.](?:M|milestone)[-.]?\d*/i, "milestone"],
+    [/[-.](?:RC|CR)[-.]?\d*/i, "rc"],
+];
+export function classifyVersion(version) {
+    for (const [pattern, stability] of STABILITY_PATTERNS) {
+        if (pattern.test(version)) {
+            return stability;
+        }
+    }
+    return "stable";
+}
+export function findLatestVersion(versions, filter = "PREFER_STABLE") {
+    const reversed = [...versions].reverse();
+    if (filter === "ALL")
+        return reversed[0];
+    const stable = reversed.find((v) => classifyVersion(v) === "stable");
+    if (filter === "STABLE_ONLY")
+        return stable;
+    return stable ?? reversed[0];
+}

package/dist/version/compare.d.ts

@@ -0,0 +1,2 @@
+import type { UpgradeType } from "./types.js";
+export declare function getUpgradeType(current: string, latest: string): UpgradeType;

package/dist/version/compare.js

@@ -0,0 +1,22 @@
+function parseSegments(version) {
+    return version
+        .replace(/[-+].*$/, "")
+        .split(".")
+        .map((s) => parseInt(s, 10) || 0);
+}
+export function getUpgradeType(current, latest) {
+    const cur = parseSegments(current);
+    const lat = parseSegments(latest);
+    const maxLen = Math.max(cur.length, lat.length);
+    while (cur.length < maxLen)
+        cur.push(0);
+    while (lat.length < maxLen)
+        lat.push(0);
+    if (lat[0] !== cur[0])
+        return lat[0] > cur[0] ? "major" : "none";
+    if (lat[1] !== cur[1])
+        return lat[1] > cur[1] ? "minor" : "none";
+    if (lat[2] !== cur[2])
+        return lat[2] > cur[2] ? "patch" : "none";
+    return "none";
+}

package/dist/version/types.d.ts

@@ -0,0 +1,7 @@
+export type StabilityType = "stable" | "rc" | "beta" | "alpha" | "milestone" | "snapshot";
+export type StabilityFilter = "STABLE_ONLY" | "PREFER_STABLE" | "ALL";
+export type UpgradeType = "major" | "minor" | "patch" | "none";
+export interface VersionInfo {
+    version: string;
+    stability: StabilityType;
+}

package/dist/version/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "maven-central-mcp",
+  "version": "0.2.0",
+  "description": "MCP server for Maven Central dependency intelligence",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "maven-central-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "maven",
+    "maven-central",
+    "dependencies",
+    "jvm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kirich1409/maven-central-mcp"
+  },
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "plugin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.5",
+    "eslint": "^10.0.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^4.0.18"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "maven-mcp",
+  "version": "0.2.0",
+  "description": "Maven dependency intelligence — auto-registers MCP server, provides /check-deps and /latest-version skills",
+  "mcpServers": {
+    "maven-mcp": {
+      "command": "npx",
+      "args": ["-y", "maven-central-mcp"]
+    }
+  },
+  "skills": "./skills"
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-deps.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/hooks/post-edit-deps.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# Read hook input from stdin
+HOOK_INPUT=$(cat)
+
+# Extract tool name and file path
+TOOL_NAME=$(echo "$HOOK_INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$HOOK_INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only care about Edit and Write tools
+if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+# Check if the file is a build dependency file
+BASENAME=$(basename "$FILE_PATH")
+case "$BASENAME" in
+  build.gradle|build.gradle.kts|settings.gradle|settings.gradle.kts|pom.xml|libs.versions.toml)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Output reminder as JSON systemMessage
+cat <<'EOF'
+{"systemMessage":"Build dependency file was modified. Consider running /check-deps to verify dependency versions are up to date."}
+EOF

package/plugin/skills/check-deps/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: check-deps
+description: Scan current project build files for Maven/Gradle dependencies and check for available updates. Use when user says "check deps", "check dependencies", "outdated dependencies", "update dependencies", or "/check-deps".
+---
+
+# Check Dependencies
+
+Scan the current project for Maven/Gradle dependencies and report available updates.
+
+## Steps
+
+1. Find build dependency files in the project root:
+   - `gradle/libs.versions.toml` (Gradle version catalog)
+   - `build.gradle.kts` or `build.gradle`
+   - `pom.xml`
+
+2. Read the found files and extract all dependencies with their current versions.
+   - For `libs.versions.toml`: parse the `[versions]` and `[libraries]` sections
+   - For Gradle files: find `implementation`, `api`, `compileOnly`, `testImplementation` etc. with group:artifact:version
+   - For `pom.xml`: find `<dependency>` blocks with `<groupId>`, `<artifactId>`, `<version>`
+
+3. Call the `check_multiple_dependencies` MCP tool (from maven-mcp server) with all extracted dependencies.
+
+4. Present results as a markdown table:
+
+   | Artifact | Current | Latest | Upgrade |
+   |----------|---------|--------|---------|
+   | io.ktor:ktor-server-core | 2.3.5 | 2.3.8 | PATCH |
+
+5. If all dependencies are up to date, say so.
+
+## Important
+
+- Always check `libs.versions.toml` first — it's the modern Gradle standard for version management.
+- Dependencies in `libs.versions.toml` may use version references in build files — resolve them.
+- Skip dependencies without explicit versions (e.g., BOM-managed or platform dependencies).

package/plugin/skills/latest-version/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: latest-version
+description: Find the latest version of a Maven artifact. Use when user says "latest version", "find version", "what version", or "/latest-version groupId:artifactId".
+---
+
+# Latest Version
+
+Find the latest version of a specific Maven artifact.
+
+## Arguments
+
+The user provides `groupId:artifactId`, for example:
+- `io.ktor:ktor-server-core`
+- `org.jetbrains.kotlin:kotlin-stdlib`
+- `com.google.dagger:hilt-android`
+
+## Steps
+
+1. Parse the user's input to extract `groupId` and `artifactId` (split by `:`).
+
+2. Call the `get_latest_version` MCP tool (from maven-mcp server) with:
+   - `groupId`: extracted group ID
+   - `artifactId`: extracted artifact ID
+   - `stabilityFilter`: `PREFER_STABLE` (default)
+
+3. Display the result:
+   - Latest stable version
+   - Latest version (if different from stable)
+   - All available versions (abbreviated if more than 10)
+
+## Error Handling
+
+- If the artifact is not found, suggest checking the groupId and artifactId spelling.
+- If the format is wrong (no `:`), ask the user to provide `groupId:artifactId`.