mingle-mcp

Instructions

Implementation Reference

• src/index.ts:122-150 (handler)

  The handler function for search_matches tool that executes the core logic: constructs query parameters, makes API call to /api/matches/{agentId}, handles errors, and returns formatted JSON response with match results including matchId, person, score, mutual status, and explanation.

  async (args) => {
    try {
      const params = new URLSearchParams();
      if (args.min_score) params.set("minScore", String(args.min_score));
      if (args.max_results) params.set("max", String(args.max_results));
      const result = await api(`/api/matches/${agentId}?${params}`);
  
      if (result.error) return { content: [{ type: "text" as const, text: result.error }], isError: true };
  
      return {
        content: [{
          type: "text" as const,
          text: JSON.stringify({
            matchCount: result.matchCount,
            totalPeople: result.totalCandidates,
            matches: (result.matches || []).map((m: any) => ({
              matchId: m.matchId,
              person: m.agentA === agentId ? m.agentB : m.agentA,
              score: m.score,
              mutual: m.mutual,
              explanation: m.explanation,
            })),
          }, null, 2),
        }],
      };
    } catch (e: any) {
      return { content: [{ type: "text" as const, text: `Network error: ${e.message}` }], isError: true };
    }
  }

• src/index.ts:118-121 (schema)

  Input schema definition for search_matches using Zod validation. Defines two optional parameters: min_score (number) for minimum relevance score filtering, and max_results (number) to limit the number of results returned.

  {
    min_score: z.number().optional().describe("Minimum relevance score (default: 0)"),
    max_results: z.number().optional().describe("Max results (default: 10)"),
  },

• src/index.ts:115-151 (registration)

  Registration of the search_matches tool with the MCP server using server.tool(). Includes the tool name, description, input schema, and handler function.

  server.tool(
    "search_matches",
    "Find people relevant to you on the Mingle network. Returns ranked matches based on how well your needs align with their offers and vice versa.",
    {
      min_score: z.number().optional().describe("Minimum relevance score (default: 0)"),
      max_results: z.number().optional().describe("Max results (default: 10)"),
    },
    async (args) => {
      try {
        const params = new URLSearchParams();
        if (args.min_score) params.set("minScore", String(args.min_score));
        if (args.max_results) params.set("max", String(args.max_results));
        const result = await api(`/api/matches/${agentId}?${params}`);
  
        if (result.error) return { content: [{ type: "text" as const, text: result.error }], isError: true };
  
        return {
          content: [{
            type: "text" as const,
            text: JSON.stringify({
              matchCount: result.matchCount,
              totalPeople: result.totalCandidates,
              matches: (result.matches || []).map((m: any) => ({
                matchId: m.matchId,
                person: m.agentA === agentId ? m.agentB : m.agentA,
                score: m.score,
                mutual: m.mutual,
                explanation: m.explanation,
              })),
            }, null, 2),
          }],
        };
      } catch (e: any) {
        return { content: [{ type: "text" as const, text: `Network error: ${e.message}` }], isError: true };
      }
    }
  );

• src/index.ts:19-30 (helper)

  Helper function 'api' used by search_matches handler to make HTTP requests. Adds authentication headers (X-Agent-Id, X-Public-Key) and returns JSON response from the Mingle API.

  async function api(path: string, opts?: RequestInit): Promise<any> {
    const res = await fetch(`${API}${path}`, {
      ...opts,
      headers: {
        "Content-Type": "application/json",
        "X-Agent-Id": agentId,
        "X-Public-Key": keys.publicKey,
        ...opts?.headers,
      },
    });
    return res.json();
  }