MCP Server RubyGems

Instructions

Implementation Reference

• src/tools/get_gem_versions.ts:67-83 (handler)

  The handler function for the MCP tool 'get_gem_versions'. It parses the input arguments using the schema, calls the getGemVersions helper, formats the response as text content, or returns an error response.

  handler: async (args: Record<string, unknown> | undefined) => {
    const { gem_name, limit } = GetGemVersionsInputSchema.parse(args || {});
  
    try {
      const versions = await getGemVersions(gem_name, limit);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(versions, null, 2),
          },
        ],
      };
    } catch (error: unknown) {
      return createErrorResponse(error, 'Failed to fetch gem versions');
    }
  },

• src/tools/get_gem_versions.ts:19-30 (schema)

  Zod schema defining the input parameters for the get_gem_versions tool: required 'gem_name' string and optional 'limit' positive integer.

  const GetGemVersionsInputSchema = z.object({
    gem_name: z
      .string()
      .min(1)
      .describe('Name of the RubyGem to fetch versions for'),
    limit: z
      .number()
      .int()
      .positive()
      .optional()
      .describe('Maximum number of versions to return'),
  });

• src/tools/get_gem_versions.ts:33-57 (helper)

  Helper function that performs the HTTP fetch to RubyGems API for versions of a gem, handles errors, parses and validates the JSON response using Zod's GemVersionSchema, and slices to limit if specified.

  async function getGemVersions(
    gemName: string,
    limit?: number
  ): Promise<GemVersion[]> {
    const response = await fetch(
      `https://rubygems.org/api/v1/versions/${gemName}.json`
    );
  
    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`RubyGem '${gemName}' not found`);
      }
      throw new Error(`Failed to fetch versions: ${response.statusText}`);
    }
  
    const data = await response.json();
    let versions = z.array(GemVersionSchema).parse(data);
  
    // Apply limit if provided
    if (limit && limit > 0) {
      versions = versions.slice(0, limit);
    }
  
    return versions;
  }

• src/tools/get_gem_versions.ts:7-14 (schema)

  Zod schema for individual RubyGem version objects, used to validate the API response data.

  const GemVersionSchema = z.object({
    number: z.string(),
    created_at: z.string(),
    summary: z.string().nullable(),
    platform: z.string(),
    downloads_count: z.number(),
    prerelease: z.boolean().optional(),
  });

• src/index.ts:20-27 (registration)

  Registration of the get_gem_versions tool (as getGemVersionsTool) in the MCP server's tools array, which is used for listing tools and dispatching tool calls.

  const tools: readonly McpTool[] = [
    getRubyGemInfoTool,
    searchRubyGemsTool,
    getGemVersionsTool,
    getGemReverseDependenciesTool,
    getOwnerGemsTool,
    getGemOwnersTool,
  ] as const;