Erick Wendel Contributions MCP

Instructions

Implementation Reference

• src/tools/talks.ts:64-143 (handler)

  The primary handler function for the 'get_talks' tool. It processes input parameters, calls GraphQL queries via helpers, handles special cases like year filtering and grouping, and returns formatted MCP response.

  handler: async (params: TalksParams): Promise<McpResponse> => {
    try {
      const { id, title, language, city, country, year, skip, limit, count_only, group_by } = params;
      
      // Handle year-specific filtering
      if (year) {
        const allTalks = await fetchTalksByYear({ id, title, language, city, country, year });
        
        if (count_only) {
          let response = `Total talks in ${year}: ${allTalks.length}`;
          
          if (group_by) {
            const counts = calculateGroupCounts(allTalks, group_by);
            response += formatGroupCounts(counts, group_by);
          }
  
          const content: McpTextContent = {
            type: "text",
            text: response
          };
  
          return {
            content: [content],
          };
        }
  
        // Apply pagination to filtered results
        const paginatedTalks = allTalks.slice(skip || 0, (skip || 0) + (limit || 10));
  
        const content: McpTextContent = {
          type: "text",
          text: `Talks Results for ${year}:\n\n${JSON.stringify({ 
            totalCount: allTalks.length,
            retrieved: paginatedTalks.length,
            talks: paginatedTalks 
          }, null, 2)}`
        };
  
        return {
          content: [content],
        };
      }
  
      // Regular query without year filtering
      const result = await fetchTalks({ id, title, language, city, country, skip, limit, count_only });
  
      if (!result.getTalks) {
        throw new Error('No results returned from API');
      }
  
      if (count_only) {
        let response = `Total talks: ${result.getTalks.totalCount}`;
        
        if (group_by && result.getTalks.talks) {
          const counts = calculateGroupCounts(result.getTalks.talks, group_by);
          response += formatGroupCounts(counts, group_by);
        }
  
        const content: McpTextContent = {
          type: "text",
          text: response
        };
  
        return {
          content: [content],
        };
      }
  
      const content: McpTextContent = {
        type: "text",
        text: `Talks Results:\n\n${JSON.stringify(result.getTalks, null, 2)}`
      };
  
      return {
        content: [content],
      };
    } catch (error) {
      throw new Error(`Failed to fetch talks: ${error.message}`);
    }
  }

• src/tools/talks.ts:52-63 (schema)

  Zod-based input schema defining all parameters for the get_talks tool, including filters, pagination, and grouping options.

  parameters: {
    id: z.string().optional().describe("Filter talks by ID"),
    title: z.string().optional().describe("Filter talks by title"),
    language: z.string().optional().describe("Filter talks by language (e.g., 'spanish', 'english', 'portuguese' or direct codes like 'es', 'en', 'pt-br')"),
    city: z.string().optional().describe("Filter talks by city"),
    country: z.string().optional().describe("Filter talks by country"),
    year: z.number().optional().describe("Filter talks by year"),
    skip: z.number().optional().default(0).describe("Number of talks to skip"),
    limit: z.number().optional().default(10).describe("Maximum number of talks to return"),
    count_only: z.boolean().optional().default(false).describe("If true, returns only the count without talk details"),
    group_by: z.string().optional().describe("Group counts by a specific field (language, country, city)"),
  },

• src/index.ts:21-26 (registration)

  Registration of the get_talks tool with the MCP server using the tool() method, passing name, description, parameters, and handler.

  server.tool(
    getTalksTool.name,
    getTalksTool.description,
    getTalksTool.parameters,
    getTalksTool.handler
  );

• src/services/api.ts:14-68 (helper)

  Core helper function that executes the GraphQL query to fetch talks data from the API, used by the tool handler.

  export async function fetchTalks(params: {
    id?: string;
    title?: string;
    language?: string;
    city?: string;
    country?: string;
    skip?: number;
    limit?: number;
    count_only?: boolean;
  }): Promise<TalksResponse> {
    const { id, title, language, city, country, skip, limit, count_only } = params;
    const languageCode = getLanguageCode(language);
  
    return await client.query({
      getTalks: {
        __args: {
          _id: id,
          title,
          language: languageCode,
          city,
          country,
          skip,
          limit: count_only ? 0 : limit,
        },
        totalCount: true,
        retrieved: true,
        processedIn: true,
        talks: count_only ? {
          language: true,
          location: {
            country: true,
            city: true,
          }
        } : {
          _id: true,
          title: true,
          abstract: true,
          type: true,
          event: {
            link: true,
            name: true,
          },
          slides: true,
          video: true,
          tags: true,
          location: {
            country: true,
            city: true,
          },
          language: true,
          date: true,
        },
      },
    }) as TalksResponse;
  }

• src/tools/talks.ts:9-33 (helper)

  Utility function to calculate counts of talks grouped by language, country, or city.

  function calculateGroupCounts(talks: Talk[], groupBy: string): Map<string, number> {
    const counts = new Map<string, number>();
    
    talks.forEach(talk => {
      if (!talk) return;
      
      let value = '';
      switch(groupBy) {
        case 'language':
          value = talk.language || 'unknown';
          break;
        case 'country':
          value = talk.location?.country || 'unknown';
          break;
        case 'city':
          value = talk.location?.city || 'unknown';
          break;
        default:
          return;
      }
      counts.set(value, (counts.get(value) || 0) + 1);
    });
  
    return counts;
  }