@breaknorm_hu/mcp-server 0.1.2 → 0.1.4

package/dist/index.js

@@ -61,13 +61,14 @@ function str(val) {
 var tools = [
   {
     name: "search_contacts",
-    description: "Search the Breaknorm contact database. Returns contacts matching filters. Use get_search_filters first to discover available filter values. Results paginated (max 25/page). For page 2+, pass searchToken from page 1.",
+    description: "Search contacts with filters. Use suggest_industry_codes FIRST to convert industry descriptions to NAICS codes, then pass them here. NEVER search by company name one by one \u2014 always use filters to get bulk results!",
     schema: z.object({
       q: z.string().optional().describe("Free text search (name, title, company)"),
       industry: z.array(z.string()).optional().describe("Filter by industry names"),
+      naicsCodes: z.array(z.string()).optional().describe("NAICS codes from suggest_industry_codes \u2014 THIS IS THE BEST WAY TO FILTER BY INDUSTRY"),
       city: z.array(z.string()).optional().describe("Filter by city names"),
-      seniority: z.array(z.string()).optional().describe("Filter by seniority: c_level, vp, director, manager, head, senior, founder, partner"),
-      department: z.array(z.string()).optional().describe("Filter by department: sales, marketing, it, hr, finance, engineering, c_suite"),
+      seniority: z.array(z.string()).optional().describe("c_level, vp, director, manager, head, senior, founder, partner"),
+      department: z.array(z.string()).optional().describe("sales, marketing, it, hr, finance, engineering, c_suite"),
       employee_min: z.number().int().optional().describe("Min company employees"),
       employee_max: z.number().int().optional().describe("Max company employees"),
       has_email: z.enum(["yes", "maybe", "no"]).optional().describe("Filter by email availability"),
@@ -79,6 +80,7 @@ var tools = [
       return client.get("/contacts/search", {
         q: str(args.q),
         industry: arrayParam(args.industry),
+        naicsCodes: arrayParam(args.naicsCodes),
         city: arrayParam(args.city),
         seniority: arrayParam(args.seniority),
         department: arrayParam(args.department),
@@ -93,10 +95,11 @@ var tools = [
   },
   {
     name: "search_companies",
-    description: "Search companies in the Breaknorm database.",
+    description: "Search companies with filters. Use suggest_industry_codes FIRST for industry filtering. NEVER search one by one \u2014 use filters!",
     schema: z.object({
       q: z.string().optional().describe("Company name search"),
       industry: z.array(z.string()).optional(),
+      naicsCodes: z.array(z.string()).optional().describe("NAICS codes from suggest_industry_codes \u2014 BEST way to filter by industry"),
       city: z.array(z.string()).optional(),
       employee_min: z.number().int().optional(),
       employee_max: z.number().int().optional(),
@@ -110,6 +113,7 @@ var tools = [
       return client.get("/companies/search", {
         q: str(args.q),
         industry: arrayParam(args.industry),
+        naicsCodes: arrayParam(args.naicsCodes),
         city: arrayParam(args.city),
         employee_min: str(args.employee_min),
         employee_max: str(args.employee_max),
@@ -123,9 +127,47 @@ var tools = [
   },
   {
     name: "get_search_filters",
-    description: "Get all available filter values with counts (industries, cities, seniorities, departments). Call this FIRST before searching.",
-    schema: z.object({}),
-    handler: async (client) => client.get("/search/filters")
+    description: "Get available filter values with counts. Call this FIRST before searching. Returns top values per category (max 50 each to keep response small).",
+    schema: z.object({
+      category: z.enum(["all", "industries", "cities", "counties", "seniorities", "departments", "companyTypes"]).default("all").optional().describe("Which filter category to fetch. Use 'all' for overview (top 20 each) or a specific category for full list (top 50).")
+    }),
+    handler: async (client, args) => {
+      const result = await client.get("/search/filters");
+      const data = result.data;
+      const cat = args.category || "all";
+      const limit = cat === "all" ? 20 : 50;
+      if (cat !== "all" && data[cat]) {
+        return { data: { [cat]: data[cat].slice(0, limit) } };
+      }
+      const trimmed = {};
+      for (const [key, values] of Object.entries(data)) {
+        if (Array.isArray(values)) {
+          trimmed[key] = values.slice(0, limit);
+          if (values.length > limit) {
+            trimmed[`${key}_total`] = values.length;
+            trimmed[`${key}_note`] = `Showing top ${limit} of ${values.length}. Use category="${key}" for more.`;
+          }
+        } else {
+          trimmed[key] = values;
+        }
+      }
+      return { data: trimmed };
+    }
+  },
+  {
+    name: "suggest_industry_codes",
+    description: "IMPORTANT: Use this BEFORE searching by industry. Converts a natural language industry description (e.g. 'marketing \xFCgyn\xF6ks\xE9gek', 'IT szolg\xE1ltat\xF3k') into NAICS codes that the search endpoints understand. Pass the returned codes as the naicsCodes parameter in search_contacts or search_companies. This is how industry filtering works \u2014 do NOT search by company name one by one!",
+    schema: z.object({
+      description: z.string().describe("Industry description in natural language, e.g. 'rekl\xE1m \xE9s m\xE9dia \xFCgyn\xF6ks\xE9gek' or 'IT consulting'"),
+      precision: z.enum(["strict", "balanced", "broad"]).default("balanced").optional().describe("strict = exact match, balanced = recommended, broad = wider results")
+    }),
+    handler: async (client, args) => {
+      const result = await client.post("/search/naics-suggest", {
+        description: args.description,
+        precision: args.precision || "balanced"
+      });
+      return result;
+    }
   },
   {
     name: "get_contact",
@@ -263,33 +305,34 @@ var SERVER_NAME = "breaknorm";
 var SERVER_VERSION = "0.1.0";
 var INSTRUCTIONS = `Breaknorm MCP Server \u2014 B2B contact database for the Hungarian market.
 
-IMPORTANT RULES:
-1. Before ANY paid operation (reveal_contact, bulk_reveal_contacts, score_companies),
-   ALWAYS call estimate_cost first and present the cost to the user for approval.
-   Never execute paid operations without explicit user confirmation.
+CRITICAL RULES \u2014 READ CAREFULLY:
+
+1. NEVER search by company name one by one! ALWAYS use filters to get bulk results.
+   Wrong: search_contacts(q: "Company A"), search_contacts(q: "Company B"), ...
+   Right: suggest_industry_codes("marketing \xFCgyn\xF6ks\xE9gek") \u2192 search_contacts(naicsCodes: [...], seniority: ["c_level"])
 
-2. Recommended workflow for building a lead list:
-   a. get_credits \u2014 check current balance
-   b. get_search_filters \u2014 discover available filter values
-   c. search_companies \u2014 find target companies matching criteria
-   d. search_contacts \u2014 find people at those companies
-   e. estimate_cost \u2014 calculate total cost for reveals
-   f. [Wait for user approval of the cost]
-   g. bulk_reveal_contacts \u2014 get email/phone data
-   h. create_list + add_contacts_to_list \u2014 organize results
-   i. export_list \u2014 export as CSV if needed
+2. INDUSTRY SEARCH WORKFLOW \u2014 this is how it works:
+   a. suggest_industry_codes("rekl\xE1m \xE9s m\xE9dia \xFCgyn\xF6ks\xE9gek") \u2192 returns NAICS codes
+   b. search_companies(naicsCodes: [codes from step a], employee_min: 5) \u2192 returns ALL matching companies at once
+   c. search_contacts(naicsCodes: [same codes], seniority: ["c_level", "director"]) \u2192 returns ALL decision-makers at once
+   This gives you hundreds of results in 2-3 API calls instead of searching one by one!
 
-3. Credit costs:
-   - Email reveal: 1 credit per contact
-   - Phone reveal: 10 credits per contact
-   - Both (email + phone): 11 credits per contact
-   - ICP company scoring: 1 credit per company
+3. Before ANY paid operation (reveal, scoring), call estimate_cost first and get user approval.
 
-4. Search results are paginated (max 25 per page). For page 2+,
-   you must pass the searchToken from the page 1 response.
+4. Recommended workflow for building a lead list:
+   a. get_credits \u2014 check balance
+   b. suggest_industry_codes \u2014 convert industry description to NAICS codes
+   c. search_companies \u2014 find companies with naicsCodes + size + location filters
+   d. search_contacts \u2014 find decision-makers with naicsCodes + seniority + department filters
+   e. estimate_cost \u2014 calculate cost
+   f. [Wait for user approval]
+   g. bulk_reveal_contacts \u2014 get emails (up to 1000 at once!)
+   h. create_list + add_contacts_to_list \u2014 organize
+   i. export_list \u2014 CSV export
 
-5. Bulk operations (reveal, ICP scoring) are async. They return a jobId.
-   Use check_job_status to poll for completion.`;
+5. Credit costs: email=1, phone=10, both=11, ICP scoring=1 per company
+6. Search is FREE and paginated (25/page). Use searchToken for page 2+.
+7. Bulk operations are async \u2014 poll with check_job_status.`;
 async function main() {
   const apiKey = process.env.BREAKNORM_API_KEY;
   if (!apiKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breaknorm_hu/mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Breaknorm MCP Server — AI agent interface for B2B contact database",
   "type": "module",
   "bin": {