tniq-mcp 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "tniq",
+  "version": "1.0.0",
+  "description": "MCP server for TNIQ by Ringer — telecom number management, porting, toll-free, messaging, and CNAM APIs",
+  "author": {
+    "name": "Ringer",
+    "url": "https://ringer.tel"
+  },
+  "repository": "https://github.com/Ringer/tniq-mcp",
+  "homepage": "https://ringer.tel",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "tniq",
+    "ringer",
+    "telecom",
+    "porting",
+    "soa",
+    "toll-free",
+    "10dlc",
+    "messaging",
+    "cnam",
+    "npac",
+    "lnp"
+  ],
+  "mcpServers": "./.mcp.json",
+  "userConfig": {
+    "api_token": {
+      "description": "Your TNIQ API token (get one at https://ringer.tel).",
+      "sensitive": true
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "tniq": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
+      "env": {
+        "TNIQ_API_TOKEN": "${user_config.api_token}"
+      }
+    }
+  }
+}

package/README.md

@@ -0,0 +1,57 @@
+# tniq-mcp
+
+MCP server for [TNIQ by Ringer](https://ringer.tel) — telecom number management, porting, toll-free, messaging, and CNAM APIs.
+
+## Quick Start
+
+```bash
+npx tniq-mcp setup
+```
+
+The setup wizard will:
+1. Collect your API key
+2. Detect installed MCP clients (Claude, Cursor, Copilot, Codex, ChatGPT)
+3. Register the server automatically
+
+## Manual Configuration
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "tniq": {
+      "command": "npx",
+      "args": ["-y", "tniq-mcp"],
+      "env": {
+        "TNIQ_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Group | Prefix | Tools | Description |
+|-------|--------|-------|-------------|
+| SOA Operations | `soa_` | 15 | NPAC port request lifecycle |
+| Toll-Free | `tf_` | 37 | Somos TFN Registry integration |
+| ROC | `roc_` | 18 | Responsible Organization Change |
+| Bulk Port | `port_` | 34 | Bulk port order management |
+| Port-Out Release | `port_out_` | 8 | NPAC release management |
+| Messaging / 10DLC | `msg_` | 34 | TCR brand/campaign registration |
+| Number Inventory | `inv_` | 30 | Number search, reserve, assign, audit |
+| CNAM | `cnam_` | 3 | Caller Name ID management |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TNIQ_API_TOKEN` | API bearer token | (from `~/.tniq/config.json`) |
+| `TNIQ_API_BASE_URL` | API base URL | `https://soa-api.ringer.tel` |
+| `TNIQ_REQUEST_TIMEOUT_MS` | Request timeout | `30000` |
+
+## License
+
+MIT

package/dist/annotations.d.ts

@@ -0,0 +1,5 @@
+export declare const READ_ONLY_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: false;
+    readonly destructiveHint: false;
+};

package/dist/annotations.js

@@ -0,0 +1,5 @@
+export const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+};

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+import type { Config } from "./config.js";
+export declare class TniqClient {
+    private baseUrl;
+    private apiToken;
+    private timeoutMs;
+    get isAnonymous(): boolean;
+    constructor(config: Config);
+    get(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<unknown>;
+    post(path: string, body?: unknown): Promise<unknown>;
+    put(path: string, body?: unknown): Promise<unknown>;
+    delete(path: string, params?: Record<string, string | number | boolean | undefined>, body?: unknown): Promise<unknown>;
+    private buildUrl;
+    private request;
+    private authHeaders;
+    private tryParseJson;
+    private describeHttpError;
+}

package/dist/client.js

@@ -0,0 +1,126 @@
+export class TniqClient {
+    baseUrl;
+    apiToken;
+    timeoutMs;
+    get isAnonymous() {
+        return this.apiToken === null;
+    }
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.apiToken = config.apiToken;
+        this.timeoutMs = config.requestTimeoutMs;
+    }
+    async get(path, params) {
+        const url = this.buildUrl(path, params);
+        return this.request(url, { method: "GET" });
+    }
+    async post(path, body) {
+        const url = this.buildUrl(path);
+        return this.request(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    async put(path, body) {
+        const url = this.buildUrl(path);
+        return this.request(url, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json" },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    async delete(path, params, body) {
+        const url = this.buildUrl(path, params);
+        const init = { method: "DELETE" };
+        if (body !== undefined) {
+            init.headers = { "Content-Type": "application/json" };
+            init.body = JSON.stringify(body);
+        }
+        return this.request(url, init);
+    }
+    buildUrl(path, params) {
+        const url = new URL(path, this.baseUrl);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    async request(url, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                ...init,
+                signal: controller.signal,
+                headers: {
+                    ...(init.headers || {}),
+                    ...this.authHeaders(),
+                    Accept: "application/json",
+                },
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                return {
+                    _error: true,
+                    status: response.status,
+                    message: this.describeHttpError(response.status),
+                    body: this.tryParseJson(text),
+                };
+            }
+            return this.tryParseJson(text);
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "AbortError") {
+                return {
+                    _error: true,
+                    status: 0,
+                    message: `Request timed out after ${this.timeoutMs}ms`,
+                };
+            }
+            return {
+                _error: true,
+                status: 0,
+                message: `Network error: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    authHeaders() {
+        if (!this.apiToken)
+            return {};
+        return { Authorization: "Bearer " + this.apiToken };
+    }
+    tryParseJson(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    describeHttpError(status) {
+        switch (status) {
+            case 400:
+                return "Bad request — check parameter format";
+            case 401:
+            case 403:
+                return "Authentication failed — check TNIQ_API_TOKEN";
+            case 404:
+                return "Not found";
+            case 429:
+                return "Rate limit exceeded";
+            case 502:
+            case 503:
+                return "Service temporarily unavailable";
+            default:
+                return `HTTP ${status}`;
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface Config {
+    baseUrl: string;
+    apiToken: string | null;
+    requestTimeoutMs: number;
+}
+declare const CONFIG_DIR: string;
+declare const CONFIG_FILE: string;
+export { CONFIG_DIR, CONFIG_FILE };
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const CONFIG_DIR = join(homedir(), ".tniq");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+export { CONFIG_DIR, CONFIG_FILE };
+function loadTokenFromConfigFile() {
+    try {
+        const raw = readFileSync(CONFIG_FILE, "utf-8");
+        const config = JSON.parse(raw);
+        return typeof config.apiToken === "string" ? config.apiToken : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadConfig() {
+    const apiToken = process.env.TNIQ_API_TOKEN || loadTokenFromConfigFile() || null;
+    return {
+        baseUrl: process.env.TNIQ_API_BASE_URL || "https://soa-api.ringer.tel",
+        apiToken,
+        requestTimeoutMs: parseInt(process.env.TNIQ_REQUEST_TIMEOUT_MS || "30000", 10),
+    };
+}

package/dist/icons.d.ts

@@ -0,0 +1,13 @@
+export declare const ICON_LIGHT_DATA_URI: string;
+export declare const ICON_DARK_DATA_URI: string;
+export declare const ICONS: ({
+    src: string;
+    mimeType: string;
+    sizes: string[];
+    theme: "light";
+} | {
+    src: string;
+    mimeType: string;
+    sizes: string[];
+    theme: "dark";
+})[];

package/dist/icons.js

@@ -0,0 +1,27 @@
+const LIGHT_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" rx="16" fill="#1a1a2e"/>
+  <text x="50" y="62" font-family="system-ui,sans-serif" font-size="28" font-weight="700" fill="#fff" text-anchor="middle">TNIQ</text>
+</svg>`;
+const DARK_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect width="100" height="100" rx="16" fill="#e8e8f0"/>
+  <text x="50" y="62" font-family="system-ui,sans-serif" font-size="28" font-weight="700" fill="#1a1a2e" text-anchor="middle">TNIQ</text>
+</svg>`;
+function toDataUri(svg) {
+    return `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+}
+export const ICON_LIGHT_DATA_URI = toDataUri(LIGHT_SVG);
+export const ICON_DARK_DATA_URI = toDataUri(DARK_SVG);
+export const ICONS = [
+    {
+        src: toDataUri(LIGHT_SVG),
+        mimeType: "image/svg+xml",
+        sizes: ["any"],
+        theme: "light",
+    },
+    {
+        src: toDataUri(DARK_SVG),
+        mimeType: "image/svg+xml",
+        sizes: ["any"],
+        theme: "dark",
+    },
+];

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+const subcommand = process.argv[2];
+if (subcommand === "setup") {
+    const { runSetup } = await import("./setup.js");
+    await runSetup();
+}
+else if (!subcommand && process.stdin.isTTY && !process.env.MCP_CLIENT) {
+    const { VERSION } = await import("./version.js");
+    console.log(`
+  tniq-mcp v${VERSION}
+
+  Usage:
+    tniq-mcp setup    Interactive setup wizard
+    tniq-mcp          MCP server (stdio) — used by MCP clients
+
+  Run 'tniq-mcp setup' to configure your API key and register
+  with your MCP clients (Claude, Cursor, Copilot, Codex, ChatGPT).
+`);
+}
+else {
+    const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+    const { TniqClient } = await import("./client.js");
+    const { loadConfig } = await import("./config.js");
+    const { registerSoaTools } = await import("./tools/soa.js");
+    const { registerTollfreeTools } = await import("./tools/tollfree.js");
+    const { registerRocTools } = await import("./tools/roc.js");
+    const { registerBulkPortTools } = await import("./tools/bulk-port.js");
+    const { registerPortOutTools } = await import("./tools/port-out.js");
+    const { registerMessagingTools } = await import("./tools/messaging.js");
+    const { registerInventoryTools } = await import("./tools/inventory.js");
+    const { registerCnamTools } = await import("./tools/cnam.js");
+    const { registerKnowledge, TNIQ_KNOWLEDGE } = await import("./knowledge.js");
+    const { ICONS } = await import("./icons.js");
+    const { VERSION } = await import("./version.js");
+    const config = loadConfig();
+    const client = new TniqClient(config);
+    const server = new McpServer({
+        name: "tniq",
+        version: VERSION,
+        title: "TNIQ",
+        description: "TNIQ by Ringer — telecom number porting, toll-free, messaging, inventory, and CNAM APIs",
+        icons: ICONS,
+        websiteUrl: "https://ringer.tel",
+    }, {
+        instructions: TNIQ_KNOWLEDGE,
+    });
+    registerSoaTools(server, client);
+    registerTollfreeTools(server, client);
+    registerRocTools(server, client);
+    registerBulkPortTools(server, client);
+    registerPortOutTools(server, client);
+    registerMessagingTools(server, client);
+    registerInventoryTools(server, client);
+    registerCnamTools(server, client);
+    registerKnowledge(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+export {};

package/dist/knowledge.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerKnowledge(server: McpServer): void;
+export declare const TNIQ_KNOWLEDGE = "# TNIQ API Knowledge Base\n\nYou have access to TNIQ tools for managing telecom number operations. NEVER guess carrier names, SPIDs, LRNs, port statuses, or routing data \u2014 always query the API.\n\n---\n\n## Overview\n\nTNIQ by Ringer is a telecom platform providing APIs for:\n- **SOA Operations** \u2014 NPAC port request lifecycle (create, activate, cancel, release, disconnect, conflict, IntraSP)\n- **Number Inventory** \u2014 Search, reserve, assign, release, audit, and report on telephone numbers\n- **Toll-Free** \u2014 Somos TFN Registry integration (templates, search, reserve, activate PTR, disconnect)\n- **Messaging / 10DLC** \u2014 TCR brand and campaign registration, CNP election, number assignment\n- **CNAM** \u2014 Caller Name ID management via TransUnion\n- **ROC** \u2014 Responsible Organization Change workflows for toll-free numbers\n- **Bulk Port Projects** \u2014 Bulk port order management with validation, submission, and lifecycle tracking\n- **Port-Out Releases** \u2014 NPAC release management for numbers leaving your network\n\n---\n\n## Tool Groups\n\n### SOA Operations (soa_*)\nUse for individual number porting operations against NPAC.\n\n- **soa_get_status / soa_get_spid / soa_query** \u2014 Look up current port status, SPID, or detailed query for a TN\n- **soa_get_events** \u2014 Poll for SOA events (new ports, conflicts, etc.)\n- **soa_get_activation_ready** \u2014 Find numbers ready to activate for a given SPID\n- **soa_activate** \u2014 Activate a ported number in NPAC\n- **soa_cancel** \u2014 Cancel a pending port request\n- **soa_release** \u2014 Release (approve) a port-out request\n- **soa_disconnect** \u2014 Disconnect a number from NPAC\n- **soa_create_conflict / soa_remove_conflict** \u2014 Manage port conflicts\n- **soa_intrasp** \u2014 IntraSP transfer (same carrier, different LRN)\n- **soa_create_lrn / soa_remove_lrn** \u2014 Manage LRN records in NPAC\n\n**Common flow:** Query status \u2192 Create port \u2192 Wait for FOC \u2192 Activate\n\n### Bulk Port Projects (port_*)\nUse for managing large-scale porting operations with multiple TNs.\n\n- **port_create_project** \u2014 Start a new bulk port project (requires customer_id, spid, name)\n- **port_get_details** \u2014 View TNs with pagination, filtering by validation/lifecycle status\n- **port_validate** \u2014 Trigger validation for all TNs\n- **port_submit** \u2014 Submit validated TNs to SOA\n- **port_bulk_actions** \u2014 Perform ACTIVATE, CANCEL, SUP_DDD, DELETE, REVALIDATE, SUBMIT, RESUBMIT on selected TNs\n- **port_get_lifecycle_summary** \u2014 Quick overview of where all TNs are in the porting lifecycle\n- **port_get_error_groups** \u2014 Group errors for batch resolution\n- **port_auto_fix** \u2014 Apply automatic fixes for resolvable errors\n\n**Lifecycle states:** DRAFT \u2192 VALIDATING \u2192 READY_FOR_SUBMISSION \u2192 PENDING_FOC \u2192 FOC_RECEIVED \u2192 AWAITING_DUE_DATE \u2192 READY_FOR_ACTIVATION \u2192 ACTIVATING \u2192 ACTIVATED\n\n### Port-Out Releases (port_out_*)\nUse when releasing numbers that are being ported away from your network.\n\n- **port_out_lookup** \u2014 Look up TNs to determine source SPID and subscriber data\n- **port_out_create_project** \u2014 Create a release project with TN subscriber details\n- **port_out_submit** \u2014 Submit releases to NPAC with a due date\n\n### Toll-Free (tf_*)\nUse for Somos TFN Registry operations.\n\n- **Templates** \u2014 tf_create_template, tf_update_template, tf_get_template, etc.\n- **Search & Reserve** \u2014 tf_search_spare, tf_search_and_reserve, tf_reserve\n- **Activate** \u2014 tf_activate (requires template name, effective date, service order number)\n- **Drafts** \u2014 Save work-in-progress templates before pushing to Somos\n- **Sync** \u2014 tf_start_sync to synchronize inventory with Somos\n\n**Template workflow:** Create/update template \u2192 Save draft \u2192 Push to Somos \u2192 Activate TFNs with template\n\n### ROC (roc_*)\nUse for Responsible Organization Changes on toll-free numbers.\n\n- **Outbound ROC:** roc_create_project \u2192 roc_upload_loa/roc_generate_loa \u2192 roc_submit\n- **Inbound ROC:** roc_inbound_checkout \u2192 roc_inbound_process (approve/deny per TFN) \u2192 roc_inbound_checkin\n- **roc_escalate_hdi** \u2014 Escalate stuck ROC to Somos Help Desk\n\n### Messaging / 10DLC (msg_*)\nUse for TCR brand/campaign registration and number assignment.\n\n- **Brands:** msg_create_brand \u2192 msg_get_brand (wait for vetting) \u2192 msg_link_brand (if existing TCR brand)\n- **Campaigns:** msg_create_campaign \u2192 msg_elect_cnp \u2192 msg_assign_numbers\n- **Reference data:** msg_list_verticals, msg_list_use_cases, msg_list_entity_types, msg_list_mnos, msg_list_cnps\n- **NNIDs:** Manage network node IDs for messaging routing\n\n**Brand is required before creating campaigns. Campaign must be approved before assigning numbers.**\n\n### Number Inventory (inv_*)\nUse for managing your telephone number inventory.\n\n- **inv_query** \u2014 Flexible search with query string syntax\n- **inv_aggregate** \u2014 Group and count numbers by field (state, LATA, status, etc.)\n- **inv_get_number** \u2014 Full details for a single TN\n- **inv_reserve_number / inv_assign_number / inv_release_number** \u2014 Lifecycle management\n- **inv_start_audit** \u2014 Compare inventory against NPAC to find discrepancies\n- **inv_get_map_data** \u2014 Geographic visualization data\n\n### CNAM (cnam_*)\nUse for managing Caller Name ID records.\n\n- **cnam_query** \u2014 Look up the CNAM record for a number\n- **cnam_activate** \u2014 Set or update the displayed caller name (max 15 chars)\n- **cnam_delete** \u2014 Remove a CNAM record\n\n---\n\n## Key Concepts\n\n| Term | Definition |\n|------|-----------|\n| TN | Telephone Number \u2014 always 10 digits (NPA + NXX + line) |\n| SPID | Service Provider ID \u2014 4-character alphanumeric code identifying a carrier |\n| LRN | Location Routing Number \u2014 10-digit number used for routing ported calls |\n| NPAC | Number Portability Administration Center \u2014 central database for ported numbers |\n| SOA | Service Order Administration \u2014 interface for submitting port requests to NPAC |\n| FOC | Firm Order Confirmation \u2014 carrier acknowledgment that a port will proceed |\n| DDD | Desired Due Date \u2014 when the port should activate |\n| OCN | Operating Company Number \u2014 identifies the carrier operating a switch |\n| LATA | Local Access and Transport Area \u2014 geographic region for telecom routing |\n| RespOrg | Responsible Organization \u2014 entity managing toll-free numbers in Somos |\n| ROC | Responsible Organization Change \u2014 transferring TFN management to a new RespOrg |\n| TCR | The Campaign Registry \u2014 central registry for 10DLC messaging campaigns |\n| CNP | Connectivity Partner \u2014 messaging aggregator that provides network connectivity |\n| NNID | Network Node ID \u2014 identifier for messaging routing nodes |\n| CNAM | Caller Name \u2014 the name displayed on caller ID |\n| IntraSP | Intra-Service Provider \u2014 moving a number within the same carrier to a new LRN |\n| CPR | Call Processing Record \u2014 routing rules for toll-free numbers |\n| PTR | Pointer Record \u2014 maps a toll-free number to a template/CPR |\n\n---\n\n## Common Mistakes to Avoid\n\n1. **Don't guess SPIDs or carrier names** \u2014 Use soa_get_spid or soa_query to look up the current SPID for a TN\n2. **Don't activate before FOC** \u2014 A port must receive FOC and reach its due date before activation\n3. **Don't skip validation in bulk ports** \u2014 Always run port_validate before port_submit\n4. **Don't confuse TN and LRN** \u2014 The TN is the customer-facing number; the LRN is for routing\n5. **ROC requires LOA** \u2014 Most ROC submissions need a Letter of Authorization uploaded first\n6. **TCR brand before campaign** \u2014 You must create/link a brand before creating a 10DLC campaign\n7. **CNAM is max 15 characters** \u2014 The caller name field has a strict 15-character limit\n8. **Template before toll-free activation** \u2014 TFNs must be activated with a template name and effective date\n9. **Use port_get_lifecycle_summary for quick status** \u2014 Don't fetch all TN details just to count states\n10. **Check port_get_error_groups before manual fixes** \u2014 Many errors have auto-fix available\n";

package/dist/knowledge.js

@@ -0,0 +1,157 @@
+export function registerKnowledge(server) {
+    server.prompt("tniq-guide", "Comprehensive guide to TNIQ APIs — telecom porting, toll-free, messaging, inventory, and CNAM. Load this before answering domain questions.", () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: TNIQ_KNOWLEDGE,
+                },
+            },
+        ],
+    }));
+}
+export const TNIQ_KNOWLEDGE = `# TNIQ API Knowledge Base
+
+You have access to TNIQ tools for managing telecom number operations. NEVER guess carrier names, SPIDs, LRNs, port statuses, or routing data — always query the API.
+
+---
+
+## Overview
+
+TNIQ by Ringer is a telecom platform providing APIs for:
+- **SOA Operations** — NPAC port request lifecycle (create, activate, cancel, release, disconnect, conflict, IntraSP)
+- **Number Inventory** — Search, reserve, assign, release, audit, and report on telephone numbers
+- **Toll-Free** — Somos TFN Registry integration (templates, search, reserve, activate PTR, disconnect)
+- **Messaging / 10DLC** — TCR brand and campaign registration, CNP election, number assignment
+- **CNAM** — Caller Name ID management via TransUnion
+- **ROC** — Responsible Organization Change workflows for toll-free numbers
+- **Bulk Port Projects** — Bulk port order management with validation, submission, and lifecycle tracking
+- **Port-Out Releases** — NPAC release management for numbers leaving your network
+
+---
+
+## Tool Groups
+
+### SOA Operations (soa_*)
+Use for individual number porting operations against NPAC.
+
+- **soa_get_status / soa_get_spid / soa_query** — Look up current port status, SPID, or detailed query for a TN
+- **soa_get_events** — Poll for SOA events (new ports, conflicts, etc.)
+- **soa_get_activation_ready** — Find numbers ready to activate for a given SPID
+- **soa_activate** — Activate a ported number in NPAC
+- **soa_cancel** — Cancel a pending port request
+- **soa_release** — Release (approve) a port-out request
+- **soa_disconnect** — Disconnect a number from NPAC
+- **soa_create_conflict / soa_remove_conflict** — Manage port conflicts
+- **soa_intrasp** — IntraSP transfer (same carrier, different LRN)
+- **soa_create_lrn / soa_remove_lrn** — Manage LRN records in NPAC
+
+**Common flow:** Query status → Create port → Wait for FOC → Activate
+
+### Bulk Port Projects (port_*)
+Use for managing large-scale porting operations with multiple TNs.
+
+- **port_create_project** — Start a new bulk port project (requires customer_id, spid, name)
+- **port_get_details** — View TNs with pagination, filtering by validation/lifecycle status
+- **port_validate** — Trigger validation for all TNs
+- **port_submit** — Submit validated TNs to SOA
+- **port_bulk_actions** — Perform ACTIVATE, CANCEL, SUP_DDD, DELETE, REVALIDATE, SUBMIT, RESUBMIT on selected TNs
+- **port_get_lifecycle_summary** — Quick overview of where all TNs are in the porting lifecycle
+- **port_get_error_groups** — Group errors for batch resolution
+- **port_auto_fix** — Apply automatic fixes for resolvable errors
+
+**Lifecycle states:** DRAFT → VALIDATING → READY_FOR_SUBMISSION → PENDING_FOC → FOC_RECEIVED → AWAITING_DUE_DATE → READY_FOR_ACTIVATION → ACTIVATING → ACTIVATED
+
+### Port-Out Releases (port_out_*)
+Use when releasing numbers that are being ported away from your network.
+
+- **port_out_lookup** — Look up TNs to determine source SPID and subscriber data
+- **port_out_create_project** — Create a release project with TN subscriber details
+- **port_out_submit** — Submit releases to NPAC with a due date
+
+### Toll-Free (tf_*)
+Use for Somos TFN Registry operations.
+
+- **Templates** — tf_create_template, tf_update_template, tf_get_template, etc.
+- **Search & Reserve** — tf_search_spare, tf_search_and_reserve, tf_reserve
+- **Activate** — tf_activate (requires template name, effective date, service order number)
+- **Drafts** — Save work-in-progress templates before pushing to Somos
+- **Sync** — tf_start_sync to synchronize inventory with Somos
+
+**Template workflow:** Create/update template → Save draft → Push to Somos → Activate TFNs with template
+
+### ROC (roc_*)
+Use for Responsible Organization Changes on toll-free numbers.
+
+- **Outbound ROC:** roc_create_project → roc_upload_loa/roc_generate_loa → roc_submit
+- **Inbound ROC:** roc_inbound_checkout → roc_inbound_process (approve/deny per TFN) → roc_inbound_checkin
+- **roc_escalate_hdi** — Escalate stuck ROC to Somos Help Desk
+
+### Messaging / 10DLC (msg_*)
+Use for TCR brand/campaign registration and number assignment.
+
+- **Brands:** msg_create_brand → msg_get_brand (wait for vetting) → msg_link_brand (if existing TCR brand)
+- **Campaigns:** msg_create_campaign → msg_elect_cnp → msg_assign_numbers
+- **Reference data:** msg_list_verticals, msg_list_use_cases, msg_list_entity_types, msg_list_mnos, msg_list_cnps
+- **NNIDs:** Manage network node IDs for messaging routing
+
+**Brand is required before creating campaigns. Campaign must be approved before assigning numbers.**
+
+### Number Inventory (inv_*)
+Use for managing your telephone number inventory.
+
+- **inv_query** — Flexible search with query string syntax
+- **inv_aggregate** — Group and count numbers by field (state, LATA, status, etc.)
+- **inv_get_number** — Full details for a single TN
+- **inv_reserve_number / inv_assign_number / inv_release_number** — Lifecycle management
+- **inv_start_audit** — Compare inventory against NPAC to find discrepancies
+- **inv_get_map_data** — Geographic visualization data
+
+### CNAM (cnam_*)
+Use for managing Caller Name ID records.
+
+- **cnam_query** — Look up the CNAM record for a number
+- **cnam_activate** — Set or update the displayed caller name (max 15 chars)
+- **cnam_delete** — Remove a CNAM record
+
+---
+
+## Key Concepts
+
+| Term | Definition |
+|------|-----------|
+| TN | Telephone Number — always 10 digits (NPA + NXX + line) |
+| SPID | Service Provider ID — 4-character alphanumeric code identifying a carrier |
+| LRN | Location Routing Number — 10-digit number used for routing ported calls |
+| NPAC | Number Portability Administration Center — central database for ported numbers |
+| SOA | Service Order Administration — interface for submitting port requests to NPAC |
+| FOC | Firm Order Confirmation — carrier acknowledgment that a port will proceed |
+| DDD | Desired Due Date — when the port should activate |
+| OCN | Operating Company Number — identifies the carrier operating a switch |
+| LATA | Local Access and Transport Area — geographic region for telecom routing |
+| RespOrg | Responsible Organization — entity managing toll-free numbers in Somos |
+| ROC | Responsible Organization Change — transferring TFN management to a new RespOrg |
+| TCR | The Campaign Registry — central registry for 10DLC messaging campaigns |
+| CNP | Connectivity Partner — messaging aggregator that provides network connectivity |
+| NNID | Network Node ID — identifier for messaging routing nodes |
+| CNAM | Caller Name — the name displayed on caller ID |
+| IntraSP | Intra-Service Provider — moving a number within the same carrier to a new LRN |
+| CPR | Call Processing Record — routing rules for toll-free numbers |
+| PTR | Pointer Record — maps a toll-free number to a template/CPR |
+
+---
+
+## Common Mistakes to Avoid
+
+1. **Don't guess SPIDs or carrier names** — Use soa_get_spid or soa_query to look up the current SPID for a TN
+2. **Don't activate before FOC** — A port must receive FOC and reach its due date before activation
+3. **Don't skip validation in bulk ports** — Always run port_validate before port_submit
+4. **Don't confuse TN and LRN** — The TN is the customer-facing number; the LRN is for routing
+5. **ROC requires LOA** — Most ROC submissions need a Letter of Authorization uploaded first
+6. **TCR brand before campaign** — You must create/link a brand before creating a 10DLC campaign
+7. **CNAM is max 15 characters** — The caller name field has a strict 15-character limit
+8. **Template before toll-free activation** — TFNs must be activated with a template name and effective date
+9. **Use port_get_lifecycle_summary for quick status** — Don't fetch all TN details just to count states
+10. **Check port_get_error_groups before manual fixes** — Many errors have auto-fix available
+`;

package/dist/lib.d.ts

@@ -0,0 +1,15 @@
+export { TniqClient } from "./client.js";
+export type { Config } from "./config.js";
+export { registerSoaTools } from "./tools/soa.js";
+export { registerTollfreeTools } from "./tools/tollfree.js";
+export { registerRocTools } from "./tools/roc.js";
+export { registerBulkPortTools } from "./tools/bulk-port.js";
+export { registerPortOutTools } from "./tools/port-out.js";
+export { registerMessagingTools } from "./tools/messaging.js";
+export { registerInventoryTools } from "./tools/inventory.js";
+export { registerCnamTools } from "./tools/cnam.js";
+export { registerKnowledge, TNIQ_KNOWLEDGE } from "./knowledge.js";
+export { ICONS, ICON_LIGHT_DATA_URI, ICON_DARK_DATA_URI } from "./icons.js";
+export { VERSION } from "./version.js";
+export { READ_ONLY_ANNOTATIONS } from "./annotations.js";
+export type { ToolRegistrar } from "./types.js";

package/dist/lib.js

@@ -0,0 +1,19 @@
+// Library exports for use by remote MCP servers and other consumers
+// Client
+export { TniqClient } from "./client.js";
+// Tool registrars
+export { registerSoaTools } from "./tools/soa.js";
+export { registerTollfreeTools } from "./tools/tollfree.js";
+export { registerRocTools } from "./tools/roc.js";
+export { registerBulkPortTools } from "./tools/bulk-port.js";
+export { registerPortOutTools } from "./tools/port-out.js";
+export { registerMessagingTools } from "./tools/messaging.js";
+export { registerInventoryTools } from "./tools/inventory.js";
+export { registerCnamTools } from "./tools/cnam.js";
+// Knowledge / prompts
+export { registerKnowledge, TNIQ_KNOWLEDGE } from "./knowledge.js";
+// Metadata
+export { ICONS, ICON_LIGHT_DATA_URI, ICON_DARK_DATA_URI } from "./icons.js";
+export { VERSION } from "./version.js";
+// Annotations
+export { READ_ONLY_ANNOTATIONS } from "./annotations.js";

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export declare function runSetup(): Promise<void>;