MCP Server RubyGems

Instructions

Implementation Reference

• src/tools/search_rubygems.ts:33-54 (handler)

  Core handler function that executes the tool logic: fetches search results from RubyGems API, validates with Zod schema, applies limit, and returns results.

  async function searchRubyGems(
    query: string,
    limit?: number
  ): Promise<RubyGemSearchResult[]> {
    const response = await fetch(
      `https://rubygems.org/api/v1/search.json?query=${encodeURIComponent(query)}`
    );
  
    if (!response.ok) {
      throw new Error(`Failed to search RubyGems: ${response.statusText}`);
    }
  
    const data = await response.json();
    const results = z.array(RubyGemSearchResultSchema).parse(data);
  
    // Apply limit if provided
    if (limit && limit > 0) {
      return results.slice(0, limit);
    }
  
    return results;
  }

• src/tools/search_rubygems.ts:21-30 (schema)

  Input schema for the search_rubygems tool using Zod, defining query and optional limit parameters.

  const SearchRubyGemsInputSchema = z.object({
    query: z.string().min(1).describe('Search query for finding RubyGems'),
    limit: z
      .number()
      .int()
      .positive()
      .max(30)
      .optional()
      .describe('Maximum number of results to return (default: 10, max: 30)'),
  });

• src/tools/search_rubygems.ts:7-16 (schema)

  Schema for individual RubyGem search results used for response validation.

  const RubyGemSearchResultSchema = z.object({
    name: z.string(),
    version: z.string(),
    downloads: z.number(),
    info: z.string(),
    homepage_uri: z.string().nullable(),
    source_code_uri: z.string().nullable(),
    documentation_uri: z.string().nullable(),
    bug_tracker_uri: z.string().nullable(),
  });

• src/tools/search_rubygems.ts:57-84 (registration)

  Exports the McpTool object for search_rubygems, including name, description, inputSchema, and wrapper handler that parses args, calls core function, formats response or error.

  export const searchRubyGemsTool: McpTool = {
    name: 'search_rubygems',
    description:
      'Search for RubyGems matching a query string. The search matches against gem names and descriptions. Returns up to 10 results by default (customizable with limit parameter), ordered by relevance. Example queries: "authentication", "rails middleware", "aws sdk"',
    inputSchema: {
      type: 'object',
      properties: zodToJsonSchema(SearchRubyGemsInputSchema),
    },
    handler: async (args: Record<string, unknown> | undefined) => {
      const { query, limit } = SearchRubyGemsInputSchema.parse(args || {});
      const resultLimit = limit || 10; // Default to 10 if not specified
  
      try {
        const results = await searchRubyGems(query, resultLimit);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(results, null, 2),
            },
          ],
        };
      } catch (error: unknown) {
        // Return error context instead of throwing an error
        return createErrorResponse(error, 'Failed to search RubyGems');
      }
    },
  };

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

  Registers searchRubyGemsTool in the server's tools array for use in MCP server.

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