@rb2b/rb2b-apis-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RB2B
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @rb2b/rb2b-apis-mcp
+
+MCP (Model Context Protocol) server that exposes [RB2B API's](https://ui.api.rb2b.com) identity resolution and enrichment API as tools for Claude and other MCP-compatible AI assistants.
+
+Resolve IP addresses to companies, look up LinkedIn profiles from emails, find contact information from LinkedIn slugs, and more — all without leaving your AI assistant.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- An [RB2B APIs](https://ui.api.rb2b.com) account and API key. Don't have an account? Get your first 100 credits for just $9.
+
+---
+
+## Quick Start
+
+### 1. Initialize
+
+Run the setup wizard to configure your API key:
+
+```bash
+npx @rb2b/rb2b-apis-mcp init
+```
+
+This will prompt for your RB2B API key, validate it against the API, and store it securely in `~/.rb2b/config.json` (permissions: `600`).
+
+### 2. Add to Claude Desktop
+
+Edit your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "rb2b": {
+      "command": "npx",
+      "args": ["@rb2b/rb2b-apis-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### 3. Add to Claude Code
+
+```bash
+claude mcp add rb2b -- npx @rb2b/rb2b-apis-mcp
+```
+
+---
+
+## Tools
+
+Each API call deducts credits from your account balance. Free tools never consume credits. The server checks your balance before every paid call and will refuse the request if you have insufficient credits.
+
+**Credit warnings** are automatically appended to responses when your balance falls to 500, 200, 100, 50, or 10 credits. Severity levels: `[NOTICE]` (500–51), `[WARNING]` (50–11), `[CRITICAL]` (10 and below).
+
+**Rate limit:** 50 requests/second per endpoint. The server surfaces a clear error if this is exceeded.
+
+### Account
+
+| Tool | Inputs | Cost | Description |
+|------|--------|------|-------------|
+| `help` | — | free | List all available tools with descriptions and costs |
+| `check_credits` | — | free | Check remaining API credits for the account |
+| `set_api_key` | `api_key` | free | Update the stored API key (validates before saving) |
+
+### IP Address Lookup
+
+| Tool | Inputs | Cost | Description |
+|------|--------|------|-------------|
+| `ip_to_company` | `ip_address` | 1 credit | Identify the company associated with an IP address |
+| `ip_to_hem` | `ip_address` | 1 credit | Get hashed emails (MD5 + SHA256) linked to an IP address |
+| `ip_to_maid` | `ip_address` | 1 credit | Get Mobile Advertising IDs (MAIDs) linked to an IP address |
+
+### Email → Identity
+
+| Tool | Inputs | Cost | Description |
+|------|--------|------|-------------|
+| `email_to_linkedin_slug` | `email` | 1 credit | Get the LinkedIn slug for a plain-text email |
+| `email_to_best_linkedin` | `email` | 1 credit | Get the highest-confidence LinkedIn profile URL for an email |
+| `email_to_business_profile` | `email` | 2 credits | Get business/employer profile (title, company, industry) for an email |
+| `email_to_maid` | `email` | 1 credit | Get Mobile Advertising IDs linked to an email |
+
+### Hashed Email (HEM) → Identity
+
+Accepts MD5 hashes of email addresses.
+
+| Tool | Inputs | Cost | Description |
+|------|--------|------|-------------|
+| `hem_to_linkedin_slug` | `md5` | 1 credit | Get the LinkedIn slug for a hashed email |
+| `hem_to_best_linkedin` | `md5` | 1 credit | Get the highest-confidence LinkedIn profile URL for a hashed email |
+| `hem_to_business_profile` | `md5` | 2 credits | Get business/employer profile for a hashed email |
+| `hem_to_maid` | `md5` | 1 credit | Get Mobile Advertising IDs linked to a hashed email |
+
+### LinkedIn → Identity
+
+Accepts LinkedIn vanity URL slugs (e.g. `john-doe-123` from `linkedin.com/in/john-doe-123`).
+
+| Tool | Inputs | Cost | Description |
+|------|--------|------|-------------|
+| `linkedin_to_hashed_emails` | `linkedin_slug` | 1 credit | Get all hashed emails (personal + business, MD5 + SHA256) for a profile |
+| `linkedin_to_best_personal_email` | `linkedin_slug` | 1 credit | Get the highest-confidence personal email for a profile |
+| `linkedin_to_personal_email` | `linkedin_slug` | 1 credit | Get all personal email candidates for a profile |
+| `linkedin_to_mobile_phone` | `linkedin_slug` | 3 credits | Get the mobile phone number for a profile |
+| `linkedin_to_business_profile` | `linkedin_slug` | 4 credits | Get business/employer profile (title, company, industry) for a profile |
+
+---
+
+## Configuration
+
+The API key is stored at `~/.rb2b/config.json` with permissions `600` (owner read/write only):
+
+```json
+{
+  "apiKey": "your-api-key-here"
+}
+```
+
+**To update your API key**, use any of these methods:
+
+- **From Claude:** ask Claude to use the `set_api_key` tool — it validates the key before saving and takes effect immediately, no restart needed
+- **From the terminal:** run `npx @rb2b/rb2b-apis-mcp init` — detects an existing key and prompts for a replacement
+
+---
+
+## Example Usage
+
+Once the server is running, you can ask Claude things like:
+
+- *"Who is visiting my site from IP 203.0.113.42?"*
+- *"Find the LinkedIn profile for jane@example.com"*
+- *"What company does robbclarke work at?"*
+- *"Get the personal email for LinkedIn profile john-doe-123"*
+- *"Check my RB2B credit balance"*
+
+Claude will automatically select and call the appropriate tool.
+
+
+---
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,23 @@
+export declare class RB2BClient {
+    private apiKey;
+    constructor(apiKey: string);
+    setApiKey(apiKey: string): void;
+    private request;
+    checkCredits(): Promise<unknown>;
+    ipToCompany(ip_address: string): Promise<unknown>;
+    hemToBestLinkedin(md5: string): Promise<unknown>;
+    hemToBusinessProfile(md5: string): Promise<unknown>;
+    hemToLinkedinSlug(md5: string): Promise<unknown>;
+    hemToMaid(md5: string): Promise<unknown>;
+    emailToBestLinkedin(email: string): Promise<unknown>;
+    emailToBusinessProfile(email: string): Promise<unknown>;
+    emailToLinkedinSlug(email: string): Promise<unknown>;
+    emailToMaid(email: string): Promise<unknown>;
+    linkedinToBestPersonalEmail(linkedin_slug: string): Promise<unknown>;
+    linkedinToPersonalEmail(linkedin_slug: string): Promise<unknown>;
+    linkedinToMobilePhone(linkedin_slug: string): Promise<unknown>;
+    linkedinToBusinessProfile(linkedin_slug: string): Promise<unknown>;
+    ipToHem(ip_address: string): Promise<unknown>;
+    ipToMaid(ip_address: string): Promise<unknown>;
+    linkedinToHashedEmails(linkedin_slug: string): Promise<unknown>;
+}

package/dist/api.js

@@ -0,0 +1,101 @@
+import { BASE_URL } from "./config.js";
+export class RB2BClient {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    setApiKey(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async request(method, path, body) {
+        const url = `${BASE_URL}${path}`;
+        const headers = {
+            "Api-Key": this.apiKey,
+            "Content-Type": "application/json",
+        };
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new Error(`Unable to reach the RB2B API. Please check your network connection. (${err instanceof Error ? err.message : String(err)})`);
+        }
+        if (res.status === 401) {
+            throw new Error("Invalid API key. Run: npx @rb2b/rb2b-apis-mcp init to update it.");
+        }
+        if (res.status === 404) {
+            throw new Error("No record found for the provided input.");
+        }
+        if (res.status === 429) {
+            throw new Error("Rate limit exceeded (50 requests/second per endpoint). Please wait before retrying.");
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => res.statusText);
+            throw new Error(`RB2B API error ${res.status}: ${text}`);
+        }
+        return res.json();
+    }
+    checkCredits() {
+        return this.request("GET", "/credits");
+    }
+    ipToCompany(ip_address) {
+        return this.request("POST", "/ip_to_company", { ip_address });
+    }
+    hemToBestLinkedin(md5) {
+        return this.request("POST", "/hem_to_best_linkedin", { md5 });
+    }
+    hemToBusinessProfile(md5) {
+        return this.request("POST", "/hem_to_business_profile", { md5 });
+    }
+    hemToLinkedinSlug(md5) {
+        return this.request("POST", "/hem_to_linkedin", { md5 });
+    }
+    hemToMaid(md5) {
+        return this.request("POST", "/hem_to_maid", { md5 });
+    }
+    emailToBestLinkedin(email) {
+        return this.request("POST", "/hem_to_best_linkedin", { email });
+    }
+    emailToBusinessProfile(email) {
+        return this.request("POST", "/hem_to_business_profile", { email });
+    }
+    emailToLinkedinSlug(email) {
+        return this.request("POST", "/hem_to_linkedin", { email });
+    }
+    emailToMaid(email) {
+        return this.request("POST", "/hem_to_maid", { email });
+    }
+    linkedinToBestPersonalEmail(linkedin_slug) {
+        return this.request("POST", "/linkedin_to_best_personal_email", {
+            linkedin_slug,
+        });
+    }
+    linkedinToPersonalEmail(linkedin_slug) {
+        return this.request("POST", "/linkedin_to_personal_email", {
+            linkedin_slug,
+        });
+    }
+    linkedinToMobilePhone(linkedin_slug) {
+        return this.request("POST", "/linkedin_to_mobile_phone", {
+            linkedin_slug,
+        });
+    }
+    linkedinToBusinessProfile(linkedin_slug) {
+        return this.request("POST", "/linkedin_to_business_profile", {
+            linkedin_slug,
+        });
+    }
+    ipToHem(ip_address) {
+        return this.request("POST", "/ip_to_hem", { ip_address });
+    }
+    ipToMaid(ip_address) {
+        return this.request("POST", "/ip_to_maid", { ip_address });
+    }
+    linkedinToHashedEmails(linkedin_slug) {
+        return this.request("POST", "/linkedin_to_hashed_emails", { linkedin_slug });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export interface Config {
+    apiKey: string;
+}
+export declare function loadConfig(): Config | null;
+export declare function saveConfig(config: Config): void;
+export declare const BASE_URL = "https://api.rb2b.com/api/v1";

package/dist/config.js

@@ -0,0 +1,27 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const CONFIG_DIR = join(homedir(), ".rb2b");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+export function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return null;
+    try {
+        const raw = readFileSync(CONFIG_FILE, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.apiKey === "string" && parsed.apiKey.length > 0) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+export const BASE_URL = "https://api.rb2b.com/api/v1";

package/dist/init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/init.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { createInterface } from "readline";
+import { BASE_URL, loadConfig, saveConfig } from "./config.js";
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+function prompt(question) {
+    return new Promise((resolve) => rl.question(question, resolve));
+}
+async function main() {
+    const existing = loadConfig();
+    if (existing) {
+        console.log("RB2B MCP Server — Update API Key");
+        console.log("==================================\n");
+        console.log("A key is already configured. Enter a new key to replace it.\n");
+    }
+    else {
+        console.log("RB2B MCP Server — Initial Setup");
+        console.log("=================================\n");
+    }
+    const apiKey = await prompt("Enter your RB2B API key: ");
+    if (!apiKey.trim()) {
+        console.error("Error: API key cannot be empty.");
+        process.exit(1);
+    }
+    console.log("\nValidating API key...");
+    try {
+        const res = await fetch(`${BASE_URL}/credits`, {
+            headers: { "Api-Key": apiKey.trim() },
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => res.statusText);
+            console.error(`\nError: API key validation failed (${res.status}): ${text}`);
+            process.exit(1);
+        }
+        const data = await res.json();
+        console.log("\nAPI key valid!");
+        console.log("Credits info:", JSON.stringify(data, null, 2));
+        saveConfig({ apiKey: apiKey.trim() });
+        console.log("\nConfiguration saved to ~/.rb2b/config.json");
+        console.log("\nYou can now add the MCP server to your Claude config:\n");
+        console.log(JSON.stringify({
+            mcpServers: {
+                rb2b: {
+                    command: "npx",
+                    args: ["@rb2b/rb2b-apis-mcp"],
+                },
+            },
+        }, null, 2));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`\nError: ${message}`);
+        process.exit(1);
+    }
+    finally {
+        rl.close();
+    }
+}
+main();

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare const CREDIT_COSTS: Record<string, number>;

package/dist/server.js

@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createRequire } from "module";
+import { loadConfig, saveConfig, BASE_URL } from "./config.js";
+import { RB2BClient } from "./api.js";
+import { creditLabel, getCreditWarning } from "./utils.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const config = loadConfig();
+if (!config) {
+    process.stderr.write("RB2B API key not configured. Run: npx @rb2b/rb2b-apis-mcp init\n");
+    process.exit(1);
+}
+// Mutable so set_api_key can update it without a server restart.
+let client = new RB2BClient(config.apiKey);
+// Credit cost per tool. 0 = free, undefined = treated as 0.
+export const CREDIT_COSTS = {
+    help: 0,
+    set_api_key: 0,
+    check_credits: 0,
+    ip_to_company: 1,
+    ip_to_hem: 1,
+    ip_to_maid: 1,
+    email_to_linkedin_slug: 1,
+    email_to_best_linkedin: 1,
+    email_to_business_profile: 2,
+    email_to_maid: 1,
+    hem_to_linkedin_slug: 1,
+    hem_to_best_linkedin: 1,
+    hem_to_business_profile: 2,
+    hem_to_maid: 1,
+    linkedin_to_hashed_emails: 1,
+    linkedin_to_best_personal_email: 1,
+    linkedin_to_personal_email: 1,
+    linkedin_to_mobile_phone: 3,
+    linkedin_to_business_profile: 4,
+};
+const RATE_LIMIT_NOTE = "Rate limit: 50 requests/second per endpoint.";
+const server = new Server({ name: "@rb2b/rb2b-apis-mcp", version }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "set_api_key",
+            description: "Update the RB2B API key. The new key is validated before saving and takes effect immediately. Cost: free.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    api_key: {
+                        type: "string",
+                        description: "The new RB2B API key to save",
+                    },
+                },
+                required: ["api_key"],
+            },
+        },
+        {
+            name: "help",
+            description: "List all available RB2B MCP tools with descriptions, required inputs, and credit costs. Use this to discover what the RB2B MCP server can do. Cost: free.",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+        {
+            name: "check_credits",
+            description: "Check the remaining API credits for the current RB2B account. Use this to verify the API key is valid or monitor usage. Cost: free.",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+        {
+            name: "ip_to_company",
+            description: `Identify the company associated with a given IP address. Useful for de-anonymizing website visitors by their IP. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ip_address: { type: "string", description: "The IPv4 or IPv6 address to look up" },
+                },
+                required: ["ip_address"],
+            },
+        },
+        {
+            name: "linkedin_to_hashed_emails",
+            description: `Retrieve all hashed emails (HEMs) associated with a LinkedIn profile slug. Returns personal and business MD5 and SHA256 arrays. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    linkedin_slug: { type: "string", description: "LinkedIn profile slug / vanity URL (e.g. 'john-doe-123')" },
+                },
+                required: ["linkedin_slug"],
+            },
+        },
+        {
+            name: "ip_to_maid",
+            description: `Retrieve Mobile Advertising IDs (MAIDs) associated with an IP address. Returns a list of device IDs with type (AAID for Android, IDFA for iOS). Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ip_address: { type: "string", description: "The IPv4 or IPv6 address to look up" },
+                },
+                required: ["ip_address"],
+            },
+        },
+        {
+            name: "ip_to_hem",
+            description: `Retrieve hashed emails (HEMs) associated with an IP address. Returns a ranked list of MD5 and SHA256 hashes with confidence scores. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    ip_address: { type: "string", description: "The IPv4 or IPv6 address to look up" },
+                },
+                required: ["ip_address"],
+            },
+        },
+        {
+            name: "hem_to_best_linkedin",
+            description: `Find the best matching LinkedIn profile URL for a hashed email (MD5). Returns the most confident LinkedIn match for the given HEM. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    md5: { type: "string", description: "MD5 hash of the email address (hashed email / HEM)" },
+                },
+                required: ["md5"],
+            },
+        },
+        {
+            name: "hem_to_business_profile",
+            description: `Retrieve the business/company profile associated with a hashed email (MD5), including employer and job title information. Cost: 2 credits. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    md5: { type: "string", description: "MD5 hash of the email address (hashed email / HEM)" },
+                },
+                required: ["md5"],
+            },
+        },
+        {
+            name: "hem_to_linkedin_slug",
+            description: `Look up the LinkedIn profile slug (e.g. 'john-doe-123') for a hashed email (MD5). Returns the LinkedIn vanity URL slug. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    md5: { type: "string", description: "MD5 hash of the email address (hashed email / HEM)" },
+                },
+                required: ["md5"],
+            },
+        },
+        {
+            name: "hem_to_maid",
+            description: `Retrieve the Mobile Advertising ID (MAID) linked to a hashed email (MD5). Useful for cross-device identity resolution. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    md5: { type: "string", description: "MD5 hash of the email address (hashed email / HEM)" },
+                },
+                required: ["md5"],
+            },
+        },
+        {
+            name: "email_to_best_linkedin",
+            description: `Find the best matching LinkedIn profile URL for a plain-text email address. Returns the most confident LinkedIn match. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    email: { type: "string", description: "Plain-text email address to look up" },
+                },
+                required: ["email"],
+            },
+        },
+        {
+            name: "email_to_business_profile",
+            description: `Retrieve the business/company profile associated with a plain-text email address, including employer and job title. Cost: 2 credits. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    email: { type: "string", description: "Plain-text email address to look up" },
+                },
+                required: ["email"],
+            },
+        },
+        {
+            name: "email_to_linkedin_slug",
+            description: `Look up the LinkedIn profile slug for a plain-text email address. Returns the LinkedIn vanity URL slug. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    email: { type: "string", description: "Plain-text email address to look up" },
+                },
+                required: ["email"],
+            },
+        },
+        {
+            name: "email_to_maid",
+            description: `Retrieve the Mobile Advertising ID (MAID) linked to a plain-text email address. Useful for cross-device identity resolution. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    email: { type: "string", description: "Plain-text email address to look up" },
+                },
+                required: ["email"],
+            },
+        },
+        {
+            name: "linkedin_to_best_personal_email",
+            description: `Find the best personal email address for a LinkedIn profile slug. Returns the highest-confidence personal email match. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    linkedin_slug: { type: "string", description: "LinkedIn profile slug / vanity URL (e.g. 'john-doe-123')" },
+                },
+                required: ["linkedin_slug"],
+            },
+        },
+        {
+            name: "linkedin_to_personal_email",
+            description: `Retrieve personal email addresses associated with a LinkedIn profile slug. May return multiple candidate emails. Cost: 1 credit. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    linkedin_slug: { type: "string", description: "LinkedIn profile slug / vanity URL (e.g. 'john-doe-123')" },
+                },
+                required: ["linkedin_slug"],
+            },
+        },
+        {
+            name: "linkedin_to_mobile_phone",
+            description: `Look up the mobile phone number associated with a LinkedIn profile slug. Returns a mobile number when available. Cost: 3 credits. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    linkedin_slug: { type: "string", description: "LinkedIn profile slug / vanity URL (e.g. 'john-doe-123')" },
+                },
+                required: ["linkedin_slug"],
+            },
+        },
+        {
+            name: "linkedin_to_business_profile",
+            description: `Retrieve the business/company profile for a LinkedIn profile slug, including current employer and role details. Cost: 4 credits. ${RATE_LIMIT_NOTE}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    linkedin_slug: { type: "string", description: "LinkedIn profile slug / vanity URL (e.g. 'john-doe-123')" },
+                },
+                required: ["linkedin_slug"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    const a = (args ?? {});
+    try {
+        let result;
+        let remaining = 0;
+        // Pre-flight credit check for all paid tools.
+        const cost = CREDIT_COSTS[name] ?? 0;
+        if (cost > 0) {
+            let creditsData;
+            try {
+                creditsData = await client.checkCredits();
+            }
+            catch (err) {
+                // 401 is already formatted as a friendly message by RB2BClient.
+                throw err;
+            }
+            remaining = creditsData?.credits_remaining ?? 0;
+            if (remaining < cost) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Insufficient credits. "${name}" costs ${cost} credit${cost === 1 ? "" : "s"} but you only have ${remaining} remaining. Top up at https://ui.api.rb2b.com.`,
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        switch (name) {
+            case "set_api_key": {
+                const newKey = a.api_key?.trim();
+                if (!newKey) {
+                    return {
+                        content: [{ type: "text", text: "Error: api_key cannot be empty." }],
+                        isError: true,
+                    };
+                }
+                const res = await fetch(`${BASE_URL}/credits`, {
+                    headers: { "Api-Key": newKey },
+                });
+                if (!res.ok) {
+                    const text = await res.text().catch(() => res.statusText);
+                    return {
+                        content: [{ type: "text", text: `Error: API key validation failed (${res.status}): ${text}` }],
+                        isError: true,
+                    };
+                }
+                saveConfig({ apiKey: newKey });
+                client.setApiKey(newKey);
+                result = {
+                    success: true,
+                    message: "API key updated and active immediately.",
+                };
+                break;
+            }
+            case "help":
+                result = {
+                    description: "RB2B MCP Server — Identity Resolution & Enrichment Tools",
+                    rate_limit: "50 requests/second per endpoint. When processing batches, stay within this limit.",
+                    tools: [
+                        { name: "help", cost: creditLabel(0), input: "none", description: "List all available tools (this command)" },
+                        { name: "set_api_key", cost: creditLabel(0), input: "api_key", description: "Update the RB2B API key (validates before saving, takes effect immediately)" },
+                        { name: "check_credits", cost: creditLabel(0), input: "none", description: "Check remaining API credits" },
+                        { name: "ip_to_company", cost: creditLabel(1), input: "ip_address", description: "Identify the company behind an IP address" },
+                        { name: "ip_to_hem", cost: creditLabel(1), input: "ip_address", description: "Get hashed emails (MD5 + SHA256) for an IP address" },
+                        { name: "ip_to_maid", cost: creditLabel(1), input: "ip_address", description: "Get Mobile Advertising IDs (MAIDs) for an IP address" },
+                        { name: "email_to_linkedin_slug", cost: creditLabel(1), input: "email", description: "Get the LinkedIn slug for a plain-text email" },
+                        { name: "email_to_best_linkedin", cost: creditLabel(1), input: "email", description: "Get the best matching LinkedIn URL for an email" },
+                        { name: "email_to_business_profile", cost: creditLabel(2), input: "email", description: "Get business/company profile for an email" },
+                        { name: "email_to_maid", cost: creditLabel(1), input: "email", description: "Get Mobile Advertising IDs for an email" },
+                        { name: "hem_to_linkedin_slug", cost: creditLabel(1), input: "md5", description: "Get the LinkedIn slug for a hashed email (MD5)" },
+                        { name: "hem_to_best_linkedin", cost: creditLabel(1), input: "md5", description: "Get the best matching LinkedIn URL for a hashed email" },
+                        { name: "hem_to_business_profile", cost: creditLabel(2), input: "md5", description: "Get business/company profile for a hashed email" },
+                        { name: "hem_to_maid", cost: creditLabel(1), input: "md5", description: "Get Mobile Advertising IDs for a hashed email" },
+                        { name: "linkedin_to_hashed_emails", cost: creditLabel(1), input: "linkedin_slug", description: "Get all hashed emails (HEMs) for a LinkedIn profile" },
+                        { name: "linkedin_to_best_personal_email", cost: creditLabel(1), input: "linkedin_slug", description: "Get the best personal email for a LinkedIn profile" },
+                        { name: "linkedin_to_personal_email", cost: creditLabel(1), input: "linkedin_slug", description: "Get all personal emails for a LinkedIn profile" },
+                        { name: "linkedin_to_mobile_phone", cost: creditLabel(3), input: "linkedin_slug", description: "Get the mobile phone number for a LinkedIn profile" },
+                        { name: "linkedin_to_business_profile", cost: creditLabel(4), input: "linkedin_slug", description: "Get business/company profile for a LinkedIn profile" },
+                    ],
+                    examples: [
+                        "Who is visiting my site from IP 203.0.113.42?",
+                        "Find the LinkedIn profile for jane@example.com",
+                        "What company does john-doe-123 work at?",
+                        "Get the personal email for LinkedIn profile john-doe-123",
+                        "What's the mobile number for linkedin.com/in/john-doe-123?",
+                        "Find LinkedIn profiles for all the emails in this spreadsheet",
+                        "Look up the business profile for the MD5 hash abc123...",
+                        "Check my remaining API credits",
+                        "Update my API key to a new value",
+                    ],
+                };
+                break;
+            case "check_credits": {
+                let creditsResult;
+                try {
+                    creditsResult = await client.checkCredits();
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{ type: "text", text: message }],
+                        isError: true,
+                    };
+                }
+                const balance = creditsResult?.credits_remaining ?? 0;
+                const checkWarning = getCreditWarning(balance);
+                const checkContent = [
+                    { type: "text", text: JSON.stringify(creditsResult, null, 2) },
+                ];
+                if (checkWarning) {
+                    checkContent.push({ type: "text", text: checkWarning });
+                }
+                return { content: checkContent };
+            }
+            case "ip_to_company":
+                result = await client.ipToCompany(a.ip_address);
+                break;
+            case "hem_to_best_linkedin":
+                result = await client.hemToBestLinkedin(a.md5);
+                break;
+            case "hem_to_business_profile":
+                result = await client.hemToBusinessProfile(a.md5);
+                break;
+            case "hem_to_linkedin_slug":
+                result = await client.hemToLinkedinSlug(a.md5);
+                break;
+            case "hem_to_maid":
+                result = await client.hemToMaid(a.md5);
+                break;
+            case "email_to_best_linkedin":
+                result = await client.emailToBestLinkedin(a.email);
+                break;
+            case "email_to_business_profile":
+                result = await client.emailToBusinessProfile(a.email);
+                break;
+            case "email_to_linkedin_slug":
+                result = await client.emailToLinkedinSlug(a.email);
+                break;
+            case "email_to_maid":
+                result = await client.emailToMaid(a.email);
+                break;
+            case "linkedin_to_best_personal_email":
+                result = await client.linkedinToBestPersonalEmail(a.linkedin_slug);
+                break;
+            case "linkedin_to_personal_email":
+                result = await client.linkedinToPersonalEmail(a.linkedin_slug);
+                break;
+            case "linkedin_to_mobile_phone":
+                result = await client.linkedinToMobilePhone(a.linkedin_slug);
+                break;
+            case "linkedin_to_business_profile":
+                result = await client.linkedinToBusinessProfile(a.linkedin_slug);
+                break;
+            case "ip_to_hem":
+                result = await client.ipToHem(a.ip_address);
+                break;
+            case "ip_to_maid":
+                result = await client.ipToMaid(a.ip_address);
+                break;
+            case "linkedin_to_hashed_emails":
+                result = await client.linkedinToHashedEmails(a.linkedin_slug);
+                break;
+            default:
+                return {
+                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+        }
+        const content = [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+        ];
+        // Only warn when we actually fetched the balance (paid tools).
+        if (cost > 0) {
+            const warning = getCreditWarning(remaining - cost);
+            if (warning) {
+                content.push({ type: "text", text: warning });
+            }
+        }
+        return { content };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: message }],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare const CREDIT_WARNING_THRESHOLDS: number[];
+export declare function creditLabel(cost: number): string;
+export declare function getCreditWarning(balance: number): string | null;

package/dist/utils.js

@@ -0,0 +1,14 @@
+// Warn at these credit thresholds (checked against post-call balance).
+export const CREDIT_WARNING_THRESHOLDS = [500, 200, 100, 50, 10];
+export function creditLabel(cost) {
+    return cost === 0 ? "free" : `${cost} credit${cost === 1 ? "" : "s"}`;
+}
+export function getCreditWarning(balance) {
+    for (const threshold of CREDIT_WARNING_THRESHOLDS) {
+        if (balance <= threshold) {
+            const level = balance <= 10 ? "CRITICAL" : balance <= 50 ? "WARNING" : "NOTICE";
+            return `[${level}] ${balance} credits remaining. Top up at https://ui.api.rb2b.com.`;
+        }
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@rb2b/rb2b-apis-mcp",
+  "version": "1.1.0",
+  "description": "MCP server exposing RB2B API tools for identity resolution and enrichment",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "rb2b-mcp": "dist/server.js",
+    "rb2b-mcp-init": "dist/init.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/server.js",
+    "init": "node dist/init.js",
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test dist-test/utils.test.js",
+    "prepare": "npm run build"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "rb2b",
+    "identity-resolution",
+    "enrichment",
+    "linkedin",
+    "email",
+    "ip-lookup"
+  ],
+  "author": "RB2B",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robbclarke/RB2B-APIs-MCP.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}