@breaknorm_hu/mcp-server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/api-client.ts
+var BreakNormClient = class {
+  baseUrl;
+  apiKey;
+  constructor(apiKey, baseUrl) {
+    this.apiKey = apiKey;
+    this.baseUrl = (baseUrl || "https://breaknorm.com").replace(/\/$/, "");
+  }
+  async request(method, path, options) {
+    const url = new URL(`/api/v1${path}`, this.baseUrl);
+    if (options?.params) {
+      for (const [key, value] of Object.entries(options.params)) {
+        if (value !== void 0 && value !== "") {
+          url.searchParams.set(key, value);
+        }
+      }
+    }
+    const res = await fetch(url.toString(), {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": "@breaknorm/mcp-server"
+      },
+      body: options?.body ? JSON.stringify(options.body) : void 0
+    });
+    const json = await res.json();
+    if (!res.ok) {
+      const errorMsg = json?.error?.message || json?.error || `API error ${res.status}`;
+      throw new Error(`Breaknorm API error (${res.status}): ${errorMsg}`);
+    }
+    return json;
+  }
+  async get(path, params) {
+    return this.request("GET", path, { params });
+  }
+  async post(path, body) {
+    return this.request("POST", path, { body });
+  }
+  async delete(path, body) {
+    return this.request("DELETE", path, { body });
+  }
+};
+
+// src/tools.ts
+function arrayParam(val) {
+  if (Array.isArray(val) && val.length > 0) return val.join(",");
+  return void 0;
+}
+function str(val) {
+  if (val === void 0 || val === null || val === "") return void 0;
+  return String(val);
+}
+var tools = [
+  // ── Search ─────────────────────────────────
+  {
+    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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Free text search (name, title, company)" },
+        industry: { type: "array", items: { type: "string" }, description: "Filter by industry names" },
+        city: { type: "array", items: { type: "string" }, description: "Filter by city names" },
+        county: { type: "array", items: { type: "string" }, description: "Filter by county (megye)" },
+        country: { type: "string", description: "2-letter country code (default: HU)" },
+        seniority: {
+          type: "array",
+          items: { type: "string", enum: ["c_level", "vp", "director", "manager", "head", "senior", "entry", "intern", "founder", "partner", "managing_director", "individual_contributor"] },
+          description: "Filter by seniority level"
+        },
+        department: {
+          type: "array",
+          items: { type: "string", enum: ["sales", "marketing", "it", "hr", "finance", "operations", "legal", "engineering", "product", "customer_success", "c_suite", "design", "other"] }
+        },
+        employee_min: { type: "integer", description: "Minimum company employee count" },
+        employee_max: { type: "integer", description: "Maximum company employee count" },
+        revenue_min: { type: "number", description: "Minimum annual revenue (HUF)" },
+        revenue_max: { type: "number", description: "Maximum annual revenue (HUF)" },
+        has_email: { type: "string", enum: ["yes", "maybe", "no"], description: "Filter by email availability" },
+        has_phone: { type: "string", enum: ["yes", "maybe", "no"] },
+        title: { type: "string", description: "Job title keyword search" },
+        page: { type: "integer", default: 1 },
+        limit: { type: "integer", default: 25, maximum: 25 },
+        searchToken: { type: "string", description: "Required for page 2+. From page 1 response." }
+      }
+    },
+    handler: async (client, args) => {
+      return client.get("/contacts/search", {
+        q: str(args.q),
+        industry: arrayParam(args.industry),
+        city: arrayParam(args.city),
+        county: arrayParam(args.county),
+        country: str(args.country),
+        seniority: arrayParam(args.seniority),
+        department: arrayParam(args.department),
+        employee_min: str(args.employee_min),
+        employee_max: str(args.employee_max),
+        revenue_min: str(args.revenue_min),
+        revenue_max: str(args.revenue_max),
+        has_email: str(args.has_email),
+        has_phone: str(args.has_phone),
+        title: str(args.title),
+        page: str(args.page),
+        limit: str(args.limit),
+        searchToken: str(args.searchToken)
+      });
+    }
+  },
+  {
+    name: "search_companies",
+    description: "Search companies in the Breaknorm database. Returns companies matching filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: { type: "string", description: "Free text company name search" },
+        industry: { type: "array", items: { type: "string" } },
+        city: { type: "array", items: { type: "string" } },
+        county: { type: "array", items: { type: "string" } },
+        country: { type: "string" },
+        employee_min: { type: "integer" },
+        employee_max: { type: "integer" },
+        revenue_min: { type: "number" },
+        revenue_max: { type: "number" },
+        has_website: { type: "boolean" },
+        page: { type: "integer", default: 1 },
+        limit: { type: "integer", default: 25, maximum: 25 },
+        sort: { type: "string", enum: ["relevance", "name", "employee_count", "revenue", "icp_score"], default: "relevance" },
+        searchToken: { type: "string" }
+      }
+    },
+    handler: async (client, args) => {
+      return client.get("/companies/search", {
+        q: str(args.q),
+        industry: arrayParam(args.industry),
+        city: arrayParam(args.city),
+        county: arrayParam(args.county),
+        country: str(args.country),
+        employee_min: str(args.employee_min),
+        employee_max: str(args.employee_max),
+        revenue_min: str(args.revenue_min),
+        revenue_max: str(args.revenue_max),
+        has_website: str(args.has_website),
+        page: str(args.page),
+        limit: str(args.limit),
+        sort: str(args.sort),
+        searchToken: str(args.searchToken)
+      });
+    }
+  },
+  {
+    name: "get_search_filters",
+    description: "Get all available filter values with counts (industries, cities, counties, seniorities, departments, etc.). Call this FIRST before searching to understand what filter values are available.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async (client) => client.get("/search/filters")
+  },
+  // ── Contacts ───────────────────────────────
+  {
+    name: "get_contact",
+    description: "Get details of a single contact (public fields, no revealed data).",
+    inputSchema: {
+      type: "object",
+      properties: { contactId: { type: "string", description: "Contact UUID" } },
+      required: ["contactId"]
+    },
+    handler: async (client, args) => client.get(`/contacts/${args.contactId}`)
+  },
+  // ── Cost Estimation ────────────────────────
+  {
+    name: "estimate_cost",
+    description: "IMPORTANT: Call this BEFORE any paid operation (reveal, ICP scoring). Returns exact credit cost, current balance, and whether you can afford it. Present the cost to the user for approval before proceeding.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        operations: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              type: { type: "string", enum: ["reveal", "icp_score"] },
+              contactIds: { type: "array", items: { type: "string" }, description: "For reveal operations" },
+              revealType: { type: "string", enum: ["email", "phone", "all"], description: "For reveal: what to reveal" },
+              companyIds: { type: "array", items: { type: "string" }, description: "For icp_score operations" },
+              icpProfileId: { type: "string", description: "For icp_score: specific profile ID (optional)" }
+            },
+            required: ["type"]
+          },
+          description: "List of operations to estimate"
+        }
+      },
+      required: ["operations"]
+    },
+    handler: async (client, args) => client.post("/estimate", { operations: args.operations })
+  },
+  // ── Reveal ─────────────────────────────────
+  {
+    name: "reveal_contact",
+    description: "Reveal email and/or phone for a single contact. Costs credits (email=1, phone=10, all=11). ALWAYS call estimate_cost first and get user approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contactId: { type: "string", description: "Contact UUID" },
+        type: { type: "string", enum: ["email", "phone", "all"], description: "What to reveal" }
+      },
+      required: ["contactId", "type"]
+    },
+    handler: async (client, args) => client.post(`/contacts/${args.contactId}/reveal`, { type: args.type })
+  },
+  {
+    name: "bulk_reveal_contacts",
+    description: "Reveal data for multiple contacts at once. Creates an async job. Returns jobId \u2014 use check_job_status to poll progress. ALWAYS call estimate_cost first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contactIds: { type: "array", items: { type: "string" }, description: "Contact UUIDs (max 1000)" },
+        type: { type: "string", enum: ["email", "phone", "all"] },
+        idempotencyKey: { type: "string", description: "UUID to prevent duplicate charges on retry" }
+      },
+      required: ["contactIds", "type"]
+    },
+    handler: async (client, args) => client.post("/contacts/bulk-reveal", {
+      contactIds: args.contactIds,
+      type: args.type,
+      idempotencyKey: args.idempotencyKey
+    })
+  },
+  // ── Jobs ───────────────────────────────────
+  {
+    name: "check_job_status",
+    description: "Check the status of an async job (bulk reveal, export, ICP scoring). Returns progress (processedItems/totalItems) and status (pending/processing/completed/failed).",
+    inputSchema: {
+      type: "object",
+      properties: { jobId: { type: "string", description: "Job UUID" } },
+      required: ["jobId"]
+    },
+    handler: async (client, args) => client.get(`/jobs/${args.jobId}`)
+  },
+  // ── Credits ────────────────────────────────
+  {
+    name: "get_credits",
+    description: "Check current credit balance and subscription tier.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async (client) => client.get("/credits")
+  },
+  // ── Lists ──────────────────────────────────
+  {
+    name: "list_saved_lists",
+    description: "List all saved contact lists.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        page: { type: "integer", default: 1 },
+        limit: { type: "integer", default: 20, maximum: 100 },
+        sort: { type: "string", enum: ["name", "created_at", "contact_count"], default: "created_at" }
+      }
+    },
+    handler: async (client, args) => client.get("/lists", { page: str(args.page), limit: str(args.limit), sort: str(args.sort) })
+  },
+  {
+    name: "create_list",
+    description: "Create a new saved contact list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "List name (1-200 chars)" },
+        description: { type: "string", description: "Optional description (max 1000 chars)" }
+      },
+      required: ["name"]
+    },
+    handler: async (client, args) => client.post("/lists", { name: args.name, description: args.description })
+  },
+  {
+    name: "add_contacts_to_list",
+    description: "Add contacts to an existing list. Duplicates are automatically skipped.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        listId: { type: "string", description: "List UUID" },
+        contactIds: { type: "array", items: { type: "string" }, description: "Contact UUIDs (max 500)" }
+      },
+      required: ["listId", "contactIds"]
+    },
+    handler: async (client, args) => client.post(`/lists/${args.listId}/contacts`, { contactIds: args.contactIds })
+  },
+  {
+    name: "export_list",
+    description: "Export a saved list as CSV. Creates async job \u2014 use check_job_status to poll.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        listId: { type: "string", description: "List UUID" }
+      },
+      required: ["listId"]
+    },
+    handler: async (client, args) => client.post(`/lists/${args.listId}/export`)
+  },
+  // ── ICP ────────────────────────────────────
+  {
+    name: "list_icp_profiles",
+    description: "List user's ICP (Ideal Customer Profile) definitions.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async (client) => client.get("/icp-profiles")
+  },
+  {
+    name: "create_icp_profile",
+    description: "Create an ICP profile from a natural language description. This defines what your ideal customer looks like, used for AI scoring.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Profile name (e.g., 'SaaS c\xE9gek Budapest')" },
+        description: {
+          type: "string",
+          description: "Detailed ICP description in natural language (1-2000 chars). Example: 'IT \xE9s SaaS c\xE9gek, 10-200 alkalmazott, Budapest, \xE9ves bev\xE9tel 100M-1B HUF, akt\xEDv LinkedIn jelenl\xE9t'"
+        },
+        isDefault: { type: "boolean", description: "Set as default profile for scoring", default: false }
+      },
+      required: ["name", "description"]
+    },
+    handler: async (client, args) => client.post("/icp-profiles", {
+      name: args.name,
+      description: args.description,
+      isDefault: args.isDefault
+    })
+  },
+  {
+    name: "score_companies",
+    description: "Score companies against an ICP profile using AI. Creates async job. Costs 1 credit per company. ALWAYS call estimate_cost first.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        companyIds: { type: "array", items: { type: "string" }, description: "Company UUIDs (max 500)" },
+        icpProfileId: { type: "string", description: "ICP profile UUID (uses default if omitted)" },
+        idempotencyKey: { type: "string", description: "UUID to prevent duplicate charges" }
+      },
+      required: ["companyIds"]
+    },
+    handler: async (client, args) => client.post("/icp-scores/bulk", {
+      companyIds: args.companyIds,
+      icpProfileId: args.icpProfileId,
+      idempotencyKey: args.idempotencyKey
+    })
+  }
+];
+
+// src/index.ts
+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.
+
+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
+
+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
+
+4. Search results are paginated (max 25 per page). For page 2+,
+   you must pass the searchToken from the page 1 response.
+
+5. Bulk operations (reveal, ICP scoring) are async. They return a jobId.
+   Use check_job_status to poll for completion.`;
+async function main() {
+  const apiKey = process.env.BREAKNORM_API_KEY;
+  if (!apiKey) {
+    console.error("Error: BREAKNORM_API_KEY environment variable is required.");
+    console.error("Get your API key at https://breaknorm.com/app/settings/developers");
+    process.exit(1);
+  }
+  const baseUrl = process.env.BREAKNORM_BASE_URL || "https://breaknorm.com";
+  const client = new BreakNormClient(apiKey, baseUrl);
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION
+  }, {
+    instructions: INSTRUCTIONS
+  });
+  for (const tool of tools) {
+    server.tool(
+      tool.name,
+      tool.description,
+      tool.inputSchema,
+      async (args) => {
+        try {
+          const result = await tool.handler(client, args);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2)
+              }
+            ]
+          };
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true
+          };
+        }
+      }
+    );
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@breaknorm_hu/mcp-server",
+  "version": "0.1.0",
+  "description": "Breaknorm MCP Server — AI agent interface for B2B contact database",
+  "type": "module",
+  "bin": {
+    "breaknorm-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "breaknorm",
+    "ai",
+    "agents",
+    "b2b",
+    "leads"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}