agentdeals

Instructions

Implementation Reference

• src/server.ts:33-100 (handler)

  The handler function for the search_deals tool which performs the search, fetches vendor details, or lists categories depending on the input parameters.

  async ({ query, category, vendor, eligibility, sort, since, limit, offset }) => {
    try {
      recordToolCall("search_deals");
  
      // Mode: list categories
      if (category === "list") {
        const categories = getCategories();
        logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { category: "list" }, result_count: categories.length, session_id: getSessionId?.() });
        return {
          content: [{ type: "text" as const, text: JSON.stringify(categories, null, 2) }],
        };
      }
  
      // Mode: vendor details
      if (vendor) {
        const result = getOfferDetails(vendor, true);
        if ("error" in result) {
          const msg = result.suggestions.length > 0
            ? `${result.error} Did you mean: ${result.suggestions.join(", ")}?`
            : `${result.error} No similar vendors found.`;
          logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { vendor }, result_count: 0, session_id: getSessionId?.() });
          return {
            isError: true,
            content: [{ type: "text" as const, text: msg }],
          };
        }
        logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { vendor }, result_count: 1, session_id: getSessionId?.() });
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result.offer, null, 2) }],
        };
      }
  
      // Mode: recent deals (since param)
      if (since && !query && !category) {
        const result = getNewestDeals({ since, limit, category: undefined });
        logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { since, limit }, result_count: result.total, session_id: getSessionId?.() });
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
        };
      }
  
      // Mode: search/browse
      const allResults = searchOffers(query, category, eligibility, sort);
      const total = allResults.length;
      const effectiveOffset = offset ?? 0;
      const effectiveLimit = limit ?? 20;
  
      // If since is provided alongside search, filter by date
      let filtered = allResults;
      if (since) {
        const sinceDate = new Date(since);
        filtered = allResults.filter(o => new Date(o.verifiedDate) >= sinceDate);
      }
  
      const paged = filtered.slice(effectiveOffset, effectiveOffset + effectiveLimit);
      const results = enrichOffers(paged);
      logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { query, category, eligibility, sort, limit: effectiveLimit, offset: effectiveOffset, since }, result_count: results.length, session_id: getSessionId?.() });
      return {
        content: [{ type: "text" as const, text: JSON.stringify({ results, total: since ? filtered.length : total, limit: effectiveLimit, offset: effectiveOffset }, null, 2) }],
      };
    } catch (err) {
      console.error("search_deals error:", err);
      return {
        isError: true,
        content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
      };
    }
  }

• src/server.ts:17-101 (registration)

  Tool registration for search_deals including its input schema and description.

  server.registerTool(
    "search_deals",
    {
      description:
        "Find free tiers, credits, and discounts for 1,500+ developer tools. Search by keyword, browse categories, or get full vendor details with alternatives. Covers AWS, Vercel, Supabase, Cloudflare, and more.",
      inputSchema: {
        query: z.string().optional().describe("Keyword search (vendor names, descriptions, tags)"),
        category: z.string().optional().describe("Filter by category. Pass \"list\" to get all categories with counts."),
        vendor: z.string().optional().describe("Get full details for a specific vendor (fuzzy match). Returns alternatives in the same category."),
        eligibility: z.enum(["public", "accelerator", "oss", "student", "fintech", "geographic", "enterprise"]).optional().describe("Filter by eligibility type"),
        sort: z.enum(["vendor", "category", "newest"]).optional().describe("Sort: vendor (A-Z), category, newest (recently verified first)"),
        since: z.string().optional().describe("ISO date (YYYY-MM-DD). Only return deals verified/added after this date."),
        limit: z.number().optional().describe("Max results (default: 20)"),
        offset: z.number().optional().describe("Pagination offset (default: 0)"),
      },
    },
    async ({ query, category, vendor, eligibility, sort, since, limit, offset }) => {
      try {
        recordToolCall("search_deals");
  
        // Mode: list categories
        if (category === "list") {
          const categories = getCategories();
          logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { category: "list" }, result_count: categories.length, session_id: getSessionId?.() });
          return {
            content: [{ type: "text" as const, text: JSON.stringify(categories, null, 2) }],
          };
        }
  
        // Mode: vendor details
        if (vendor) {
          const result = getOfferDetails(vendor, true);
          if ("error" in result) {
            const msg = result.suggestions.length > 0
              ? `${result.error} Did you mean: ${result.suggestions.join(", ")}?`
              : `${result.error} No similar vendors found.`;
            logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { vendor }, result_count: 0, session_id: getSessionId?.() });
            return {
              isError: true,
              content: [{ type: "text" as const, text: msg }],
            };
          }
          logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { vendor }, result_count: 1, session_id: getSessionId?.() });
          return {
            content: [{ type: "text" as const, text: JSON.stringify(result.offer, null, 2) }],
          };
        }
  
        // Mode: recent deals (since param)
        if (since && !query && !category) {
          const result = getNewestDeals({ since, limit, category: undefined });
          logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { since, limit }, result_count: result.total, session_id: getSessionId?.() });
          return {
            content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
          };
        }
  
        // Mode: search/browse
        const allResults = searchOffers(query, category, eligibility, sort);
        const total = allResults.length;
        const effectiveOffset = offset ?? 0;
        const effectiveLimit = limit ?? 20;
  
        // If since is provided alongside search, filter by date
        let filtered = allResults;
        if (since) {
          const sinceDate = new Date(since);
          filtered = allResults.filter(o => new Date(o.verifiedDate) >= sinceDate);
        }
  
        const paged = filtered.slice(effectiveOffset, effectiveOffset + effectiveLimit);
        const results = enrichOffers(paged);
        logRequest({ ts: new Date().toISOString(), type: "mcp", endpoint: "search_deals", params: { query, category, eligibility, sort, limit: effectiveLimit, offset: effectiveOffset, since }, result_count: results.length, session_id: getSessionId?.() });
        return {
          content: [{ type: "text" as const, text: JSON.stringify({ results, total: since ? filtered.length : total, limit: effectiveLimit, offset: effectiveOffset }, null, 2) }],
        };
      } catch (err) {
        console.error("search_deals error:", err);
        return {
          isError: true,
          content: [{ type: "text" as const, text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
        };
      }
    }
  );