maven-mcp-server

Instructions

Implementation Reference

• src/index.ts:353-442 (handler)

  Executes the list_maven_versions tool: validates input, parses Maven coordinate, queries Maven Central API sorted by timestamp, filters pre-releases if requested, limits to depth, returns formatted list of versions.

  private async handleListVersions(args: unknown) {
    if (!isValidListVersionsArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid Maven dependency format'
      );
    }
  
    const coord = parseMavenCoordinate(args.dependency);
    const depth = args.depth || 15;
    const excludePreReleases = args.excludePreReleases ?? true; // Default to true
  
    try {
      let query = `g:"${coord.groupId}" AND a:"${coord.artifactId}"`;
      if (coord.packaging) {
        query += ` AND p:"${coord.packaging}"`;
      }
  
      const response = await this.axiosInstance.get<MavenSearchResponse>('', {
        params: {
          q: query,
          core: 'gav',
          rows: 100,
          wt: 'json',
          sort: 'timestamp desc',
        },
      });
  
      if (!response.data.response.docs.length) {
        return {
          content: [
            {
              type: 'text',
              text: `No Maven dependency found for ${coord.groupId}:${coord.artifactId}${coord.packaging ? ':' + coord.packaging : ''}`,
            },
          ],
          isError: true,
        };
      }
  
      // Filter versions if needed
      let filteredDocs = response.data.response.docs;
      if (excludePreReleases) {
        filteredDocs = filteredDocs.filter(doc => !isPreReleaseVersion(doc.v));
      }
  
      if (filteredDocs.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: excludePreReleases 
                ? `No stable releases found for ${coord.groupId}:${coord.artifactId}${coord.packaging ? ':' + coord.packaging : ''}. All available versions are pre-releases.`
                : `No Maven dependency found for ${coord.groupId}:${coord.artifactId}${coord.packaging ? ':' + coord.packaging : ''}`,
            },
          ],
          isError: true,
        };
      }
  
      const versions = filteredDocs
        .sort((a, b) => b.timestamp - a.timestamp)
        .slice(0, depth)
        .map(doc => `${doc.v} (${new Date(doc.timestamp).toISOString().split('T')[0]})`);
  
      return {
        content: [
          {
            type: 'text',
            text: versions.join('\n'),
          },
        ],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          content: [
            {
              type: 'text',
              text: `Maven Central API error: ${
                error.response?.data?.error?.msg ?? error.message
              }`,
            },
          ],
          isError: true,
        };
      }
      throw error;
    }
  }

• src/index.ts:163-187 (registration)

  Registers the list_maven_versions tool in the ListTools response, including name, description, and input schema.

  {
    name: 'list_maven_versions',
    description: 'List Maven dependency versions sorted by last updated date (most recent first)',
    inputSchema: {
      type: 'object',
      properties: {
        dependency: {
          type: 'string',
          description: 'Maven coordinate in format "groupId:artifactId[:packaging][:classifier]" (e.g. "org.springframework:spring-core" or "org.springframework:spring-core:jar")',
        },
        depth: {
          type: 'number',
          description: 'Number of versions to return (default: 15)',
          minimum: 1,
          maximum: 100,
        },
        excludePreReleases: {
          type: 'boolean',
          description: 'Whether to exclude pre-release versions (alpha, beta, milestone, RC, snapshot). Default: true',
          default: true,
        },
      },
      required: ['dependency'],
    },
  },

• src/index.ts:197-198 (registration)

  Registers the handler dispatch for list_maven_versions in the CallToolRequest switch statement.

  case 'list_maven_versions':
    return this.handleListVersions(request.params.arguments);

• src/index.ts:83-90 (schema)

  Type guard / validator for list_maven_versions input arguments.

  const isValidListVersionsArgs = (
    args: any
  ): args is { dependency: string; depth?: number; excludePreReleases?: boolean } =>
    typeof args === 'object' &&
    args !== null &&
    typeof args.dependency === 'string' &&
    (args.depth === undefined || (typeof args.depth === 'number' && args.depth > 0)) &&
    (args.excludePreReleases === undefined || typeof args.excludePreReleases === 'boolean');

• src/index.ts:36-52 (helper)

  Helper function to parse Maven coordinate string into structured object, used by list_maven_versions handler.

  const parseMavenCoordinate = (dependency: string): MavenCoordinate => {
    const parts = dependency.split(':');
    if (parts.length < 2) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Invalid Maven coordinate format. Minimum format is "groupId:artifactId"'
      );
    }
  
    return {
      groupId: parts[0],
      artifactId: parts[1],
      version: parts[2],
      packaging: parts[3],
      classifier: parts[4]
    };
  };