telique-mcp 1.0.9 → 1.0.11

package/dist/icons.d.ts

@@ -0,0 +1,11 @@
+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,22 @@
+// Optimized, cropped SVGs of the Ringer logomark as data URIs.
+// Light: black left link + teal right link (for light backgrounds)
+// Dark: white left link + teal right link (for dark backgrounds)
+const LIGHT_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="280 250 230 115"><path d="M422.4,300.6c-4.6,4.6-12.2,4.6-16.8,0l-15.4-15.4c-3.7-3.7-8.8-5.8-14-5.8-5.3,0-10.3,2.1-14,5.8l-57.9,57.9c-4.6,4.6-12.2,4.6-16.8,0-4.6-4.6-4.6-12.2,0-16.8l57.9-57.9c8.2-8.2,19.3-12.8,30.8-12.8,11.6,0,22.7,4.6,30.8,12.8l15.4,15.4C427,288.4,427,296,422.4,300.6"/><path fill="#59C5C7" d="M369.6,311.4c4.6-4.6,12.2-4.6,16.8,0l15.4,15.4c3.7,3.7,8.8,5.8,14,5.8,5.3,0,10.3-2.1,14-5.8l57.9-57.9c4.6-4.6,12.2-4.6,16.8,0,4.6,4.6,4.6,12.2,0,16.8l-57.9,57.9c-8.2,8.2-19.3,12.8-30.8,12.8-11.6,0-22.7-4.6-30.8-12.8l-15.4-15.4C365,323.6,365,316,369.6,311.4"/></svg>`;
+const DARK_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="280 250 230 115"><path fill="#FFF" d="M422.4,300.6c-4.6,4.6-12.2,4.6-16.8,0l-15.4-15.4c-3.7-3.7-8.8-5.8-14-5.8-5.3,0-10.3,2.1-14,5.8l-57.9,57.9c-4.6,4.6-12.2,4.6-16.8,0-4.6-4.6-4.6-12.2,0-16.8l57.9-57.9c8.2-8.2,19.3-12.8,30.8-12.8,11.6,0,22.7,4.6,30.8,12.8l15.4,15.4C427,288.4,427,296,422.4,300.6"/><path fill="#59C5C7" d="M369.6,311.4c4.6-4.6,12.2-4.6,16.8,0l15.4,15.4c3.7,3.7,8.8,5.8,14,5.8,5.3,0,10.3-2.1,14-5.8l57.9-57.9c4.6-4.6,12.2-4.6,16.8,0,4.6,4.6,4.6,12.2,0,16.8l-57.9,57.9c-8.2,8.2-19.3,12.8-30.8,12.8-11.6,0-22.7-4.6-30.8-12.8l-15.4-15.4C365,323.6,365,316,369.6,311.4"/></svg>`;
+function toDataUri(svg) {
+    return `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+}
+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.js

@@ -31,13 +31,22 @@ else {
     const { registerCnamTools } = await import("./tools/cnam.js");
     const { registerLergTools } = await import("./tools/lerg.js");
     const { registerGraphqlTools } = await import("./tools/graphql.js");
+    const { registerKnowledge, TELIQUE_KNOWLEDGE } = await import("./knowledge.js");
     const { registerCompositeTools } = await import("./tools/composite.js");
+    const { ICONS } = await import("./icons.js");
+    const { VERSION } = await import("./version.js");
     const config = loadConfig();
     const client = new TeliqueClient(config);
     setAnonymousMode(client.isAnonymous);
     const server = new McpServer({
         name: "telique",
-        version: "1.0.0",
+        version: VERSION,
+        title: "Telique",
+        description: "Telecom data APIs — LRN, CNAM, DNO, LERG (27 tables), RouteLink toll-free routing, and LSMS/LERG GraphQL",
+        icons: ICONS,
+        websiteUrl: "https://telique.ringer.tel",
+    }, {
+        instructions: TELIQUE_KNOWLEDGE,
     });
     registerRoutelinkTools(server, client);
     registerLrnTools(server, client);
@@ -45,6 +54,7 @@ else {
     registerLergTools(server, client);
     registerGraphqlTools(server, client);
     registerCompositeTools(server, client);
+    registerKnowledge(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

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 TELIQUE_KNOWLEDGE = "# Telique Telecom API Knowledge Base\n\nYou have access to 13 Telique tools for querying live telecom data. NEVER guess carrier names, LRNs, routing data, or CNAM \u2014 always query the API.\n\n---\n\n## CRITICAL: LERG vs LSMS \u2014 Two Different Databases\n\n**LERG** = Static telecom infrastructure reference (updated monthly from iconectiv BIRRDS)\n- NPA-NXX assignments, switches, tandems, homing arrangements, rate centers, LATAs, carrier names by OCN\n- 27 tables. NO individual phone number data.\n- Query with: `lerg_query`, `lerg_complex_query`, `lerg_tandem`, `lerg_table_info`, or `graphql_query(service=\"lerg\")`\n\n**LSMS** = Live NPAC porting data (refreshed within minutes)\n- Phone number ownership (SPID), LRN assignments, porting state\n- NO routing infrastructure (no tandems, switches, homing, rate centers, OCN names)\n- Query with: `lrn_lookup`, `lrn_relationship_query`, or `graphql_query(service=\"lsms\")`\n\n| Data Type | Database | Tool |\n|-----------|----------|------|\n| Tandem switches | **LERG** | `lerg_tandem` |\n| Switch/CLLI details | **LERG** | `lerg_query` on lerg_7 |\n| Homing arrangements | **LERG** | `lerg_query` on lerg_7_sha |\n| NPA-NXX routing (OCN, switch, LATA, rate center) | **LERG** | `lerg_query` on lerg_6 |\n| Carrier/OCN names | **LERG** | `lerg_query` on lerg_1 |\n| Current TN ownership (SPID) | **LSMS** | `lrn_lookup` |\n| Current LRN for a TN | **LSMS** | `lrn_lookup` |\n| Porting state | **LSMS** | `lrn_relationship_query` or GraphQL |\n\n---\n\n## CRITICAL: Always Dip the LRN First\n\nA ported phone number's NPA-NXX often differs from its LRN's NPA-NXX. For ANY routing question about a specific phone number:\n\n1. **`lrn_lookup`** \u2192 get the LRN and SPID\n2. Extract NPA-NXX from the **LRN** (first 3 digits = NPA, next 3 = NXX)\n3. Use the **LRN's** NPA-NXX for all LERG lookups\n\n**Example:** TN 303-629-8301\n- WRONG: Look up 303-629 in LERG \u2192 returns the original carrier's data (before porting)\n- CORRECT: `lrn_lookup(\"3036298301\")` \u2192 LRN = 7207081999 \u2192 look up 720-708 in LERG \u2192 returns current carrier\n\nThis applies to: tandem, switch, LATA, OCN, rate center \u2014 anything keyed by NPA-NXX.\n\n### The Golden Pattern for Routing Questions\n\n```\nStep 1: lrn_lookup({phone_number}) \u2192 get LRN and SPID\nStep 2: Extract NPA (first 3 digits of LRN) and NXX (next 3 digits of LRN)\nStep 3: Use LRN's NPA-NXX for LERG queries:\n  - lerg_tandem({npa, nxx})           \u2192 tandem switch\n  - lerg_query(\"lerg_6\", ..., \"npa={npa}&nxx={nxx}\")  \u2192 OCN, switch, LATA, rate center\n  - lerg_query(\"lerg_7\", ..., \"switch={clli}\")         \u2192 switch details\n```\n\nOr use `lookup_tn` for a quick consolidated view (dips LRN + CNAM + DNO + LERG in parallel).\n\n---\n\n## LERG Table Reference\n\n### Big 4 \u2014 Cover ~80% of Queries\n\n**lerg_1** \u2014 OCN/carrier directory\n- Fields: ocn_num, ocn_name, abbre_ocn_name, ocn_state, category, overall_ocn\n- Use: Look up carrier name by OCN. Join from lerg_6 `ocn` \u2192 lerg_1 `ocn_num`.\n- Example: `lerg_query(\"lerg_1\", \"ocn_num,ocn_name,ocn_state\", \"ocn_num=567G\")`\n\n**lerg_6** \u2014 NPA-NXX block assignments (the workhorse)\n- Fields: npa, nxx, block_id, lata, lata_name, loc_state, ocn, aocn, switch, sha_indicator, rc_abbre, rc_type, coc_type, eff_date, status\n- Has LATA + state + NPA + NXX + OCN + switch + rate center all on one row.\n- BLOCK=\"A\" = full NXX assignment; numeric 0-9 = thousands-block pooling.\n- Example: `lerg_query(\"lerg_6\", \"npa,nxx,loc_name,loc_state,ocn,switch,lata\", \"npa=720&nxx=708\")`\n\n**lerg_7_sha** \u2014 Switch homing arrangements\n- Fields: switch, sha_indicator, h_trm_d_tdm (FGD tandem), host, ocn\n- Match `switch` + `sha_indicator` from lerg_6 to find the correct tandem.\n- Or use `lerg_tandem` which does the join automatically.\n\n**lerg_12** \u2014 LRN registry\n- Fields: lrn, lata, lata_name, switch, ocn, status, eff_date\n- Which company/switch established each LRN.\n\n### Supporting Tables\n\n| Table | Purpose |\n|-------|---------|\n| lerg_3 | NPA (area code) metadata \u2014 state, effective date |\n| lerg_5 | NPA/LATA cross-reference \u2014 which NPAs exist in a LATA |\n| lerg_7 | Switch/CLLI details \u2014 address, coordinates, equipment type |\n| lerg_8 | Rate center details \u2014 geography, V&H coordinates |\n| lerg_8_loc | Localities (towns) \u2192 rate centers |\n| lerg_8_pst | ZIP codes \u2192 localities (US only) |\n| lerg_9 | Homing by tandem \u2014 \"top-down\" view of which NPA-NXXs subtend a tandem |\n| lerg_4 | SS7 point codes |\n| lerg_10 | NPA-NXX \u2192 operator services ATC |\n| lerg_11 | Locality \u2192 operator services ATC |\n| lerg_16 | IP capability by LRN |\n| lerg_17 | IP capability by NPA-NXX |\n\nUse `lerg_table_info` to list all tables or get the schema for a specific one.\n\n---\n\n## LERG Query Syntax\n\nREST queries use path-based filters with `&` joining multiple conditions:\n- Single filter: `lerg_query(\"lerg_1\", \"ocn_num,ocn_name\", \"ocn_state=CO\")`\n- Multiple filters: `lerg_query(\"lerg_6\", \"npa,nxx,loc_name,ocn\", \"npa=303&nxx=629\")`\n\nFor complex queries with JOINs and advanced operators, use `lerg_complex_query`:\n```json\n{\n  \"table\": \"lerg_6\",\n  \"fields\": [\"npa\", \"nxx\", \"ocn\", \"loc_name\"],\n  \"filters\": [{\"field\": \"npa\", \"operator\": \"eq\", \"value\": 720}],\n  \"join\": {\n    \"table\": \"lerg_1\",\n    \"on\": [{\"left_field\": \"ocn\", \"right_field\": \"ocn_num\"}],\n    \"fields\": [\"ocn_name\", \"ocn_state\"]\n  }\n}\n```\n\nFilter operators: eq, ne, gt, gte, lt, lte, like, in, isnull, isnotnull.\n\n---\n\n## CNAM (Caller Name)\n\n`cnam_lookup` queries TransUnion's LIDB for the caller name associated with a phone number.\n\n- Returns: calling_name (up to 15 chars), calling_name_status (available/unavailable), presentation_indicator (allowed/restricted)\n- Results cached server-side for 24 hours\n- \"WIRELESS CALLER\" typically means the carrier hasn't provisioned a specific CNAM entry\n\n---\n\n## DNO (Do Not Originate)\n\n`dno_check` checks if a phone number should never appear as a caller ID.\n\n- DNO numbers belong to entities that only receive calls (IRS, major banks, government agencies)\n- If is_dno=true, the number appearing as caller ID indicates **spoofing/fraud**\n- Supports prefix matching: 3-digit (NPA), 6-digit (NPA-NXX), 7-digit, or 10-digit patterns\n- Response includes: is_dno, matched_pattern, source\n\n---\n\n## RouteLink \u2014 Toll-Free Number Routing\n\n### ROR (Responsible Organization)\n`routelink_lookup` with lookup_type=\"ror\" returns the RespOrg managing a toll-free number.\n- RespOrg is a 5-char code (e.g., \"NEX01\", \"TZN99\")\n- Only needs the CRN (toll-free number), no ANI/LATA required\n\n### CIC (Carrier Identification Code)\n`routelink_lookup` with lookup_type=\"cic\" or \"cicror\" returns which carrier handles calls to a toll-free number FROM a specific caller (ANI) in a specific LATA.\n- Requires: crn, ani (10-digit), lata (3-digit)\n- Common carrier codes: 0288 (AT&T), 0222 (MCI/Verizon), 0333 (Sprint), 0432 (Lumen)\n\n### CPR (Call Processing Record)\n`routelink_cpr` retrieves the full routing decision tree for a toll-free number.\n\n**Decision tree node types:**\n| Node | Description |\n|------|-------------|\n| [LATA] | Routes by caller's LATA |\n| [NPA] | Routes by caller's area code |\n| [NXX] | Routes by caller's exchange |\n| [STATE] | Routes by caller's state |\n| [DAY_OF_WEEK] | Routes by day (1-7, Sunday=1) |\n| [TIME_OF_DAY] | Routes by time (15-min intervals) |\n| [PERCENT] | Percentage-based load balancing |\n| [ANI] | Routes by specific caller number |\n\n**Action types:** Carrier XXXX (4-digit carrier code), Template XXXXXXXXXX (reference to template CRN), Routing XXXXX, NMC X (Network Management Class)\n\n**Common patterns:**\n- Simple: All calls \u2192 one carrier \u2192 one termination number\n- Time-of-day: Business hours \u2192 office, after hours \u2192 answering service\n- Geographic: Different terminations per LATA/state/NPA\n- Percentage: Load balancing across call centers (e.g., 60%/40%)\n\nUse `expand=true` (default) to recursively resolve template references into their full decision trees.\n\n---\n\n## GraphQL\n\nUse `graphql_query` for complex queries not possible with REST:\n- Cross-table relationship joins (lerg6 \u2192 carrier, lerg6 \u2192 switchInfo, lerg7Sha \u2192 tandemSwitch)\n- Filtering by fields not in REST endpoints\n- Multiple related data points in one query\n\n**LERG GraphQL** (`service=\"lerg\"`): All 27 tables with camelCase names (lerg1, lerg6, lerg7Sha, etc.)\n- FilterInput operators: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, IS_NULL, IS_NOT_NULL\n- All field values are nullable strings\n\n**LSMS GraphQL** (`service=\"lsms\"`): 5 tables\n- subscriptionVersions (514M rows \u2014 MUST filter by phone_number, lrn, or spid)\n- numberBlocks, serviceProviders, locationRoutingNumbers, npanxx\n- Safety limits: max 1000 results, depth 5, complexity 200, 10-second timeout\n\n---\n\n## Key Telecom Concepts\n\n| Term | Definition |\n|------|-----------|\n| **LRN** | Location Routing Number \u2014 identifies the switch serving a ported number |\n| **SPID** | Service Provider ID \u2014 identifies the carrier that owns a number |\n| **OCN** | Operating Company Number \u2014 4-char carrier identifier (often same as SPID) |\n| **NPA** | Numbering Plan Area \u2014 3-digit area code |\n| **NXX** | Exchange code \u2014 next 3 digits after area code |\n| **LATA** | Local Access Transport Area \u2014 geographic region for call routing |\n| **CLLI** | Common Language Location Identifier \u2014 8-11 char switch/building code |\n| **CRN** | Call Routing Number \u2014 a toll-free number in RouteLink context |\n| **ROR/RespOrg** | Responsible Organization \u2014 entity managing a toll-free number's routing |\n| **CIC** | Carrier Identification Code \u2014 identifies which carrier handles a toll-free call |\n| **CPR** | Call Processing Record \u2014 routing decision tree for a toll-free number |\n| **Rate Center** | Geographic area defining local calling boundaries |\n| **Tandem** | A switching office that connects local switches to the long-distance network |\n| **Homing** | The relationship between a local switch and its tandem |\n\n---\n\n## Common Mistakes to Avoid\n\n1. **Never guess carrier names** \u2014 always query lerg_1 by OCN\n2. **Never skip the LRN dip** \u2014 ported TNs have different NPA-NXX than their LRN\n3. **Never look for tandem/switch data in LSMS** \u2014 LSMS has no infrastructure data\n4. **Never look for TN-level data in LERG** \u2014 LERG has no per-phone-number data\n5. **Never query LSMS subscriptionVersions without a filter** \u2014 514M rows will timeout\n6. **Always use the LRN's NPA-NXX** (not the TN's) for LERG routing lookups\n";

package/dist/knowledge.js

@@ -0,0 +1,250 @@
+export function registerKnowledge(server) {
+    server.prompt("telique-guide", "Comprehensive guide to Telique telecom APIs — LERG vs LSMS data boundary, routing lookup patterns, LERG table reference, CPR interpretation, CNAM, DNO, and common mistakes to avoid. Load this before answering telecom questions.", () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: TELIQUE_KNOWLEDGE,
+                },
+            },
+        ],
+    }));
+}
+export const TELIQUE_KNOWLEDGE = `# Telique Telecom API Knowledge Base
+
+You have access to 13 Telique tools for querying live telecom data. NEVER guess carrier names, LRNs, routing data, or CNAM — always query the API.
+
+---
+
+## CRITICAL: LERG vs LSMS — Two Different Databases
+
+**LERG** = Static telecom infrastructure reference (updated monthly from iconectiv BIRRDS)
+- NPA-NXX assignments, switches, tandems, homing arrangements, rate centers, LATAs, carrier names by OCN
+- 27 tables. NO individual phone number data.
+- Query with: \`lerg_query\`, \`lerg_complex_query\`, \`lerg_tandem\`, \`lerg_table_info\`, or \`graphql_query(service="lerg")\`
+
+**LSMS** = Live NPAC porting data (refreshed within minutes)
+- Phone number ownership (SPID), LRN assignments, porting state
+- NO routing infrastructure (no tandems, switches, homing, rate centers, OCN names)
+- Query with: \`lrn_lookup\`, \`lrn_relationship_query\`, or \`graphql_query(service="lsms")\`
+
+| Data Type | Database | Tool |
+|-----------|----------|------|
+| Tandem switches | **LERG** | \`lerg_tandem\` |
+| Switch/CLLI details | **LERG** | \`lerg_query\` on lerg_7 |
+| Homing arrangements | **LERG** | \`lerg_query\` on lerg_7_sha |
+| NPA-NXX routing (OCN, switch, LATA, rate center) | **LERG** | \`lerg_query\` on lerg_6 |
+| Carrier/OCN names | **LERG** | \`lerg_query\` on lerg_1 |
+| Current TN ownership (SPID) | **LSMS** | \`lrn_lookup\` |
+| Current LRN for a TN | **LSMS** | \`lrn_lookup\` |
+| Porting state | **LSMS** | \`lrn_relationship_query\` or GraphQL |
+
+---
+
+## CRITICAL: Always Dip the LRN First
+
+A ported phone number's NPA-NXX often differs from its LRN's NPA-NXX. For ANY routing question about a specific phone number:
+
+1. **\`lrn_lookup\`** → get the LRN and SPID
+2. Extract NPA-NXX from the **LRN** (first 3 digits = NPA, next 3 = NXX)
+3. Use the **LRN's** NPA-NXX for all LERG lookups
+
+**Example:** TN 303-629-8301
+- WRONG: Look up 303-629 in LERG → returns the original carrier's data (before porting)
+- CORRECT: \`lrn_lookup("3036298301")\` → LRN = 7207081999 → look up 720-708 in LERG → returns current carrier
+
+This applies to: tandem, switch, LATA, OCN, rate center — anything keyed by NPA-NXX.
+
+### The Golden Pattern for Routing Questions
+
+\`\`\`
+Step 1: lrn_lookup({phone_number}) → get LRN and SPID
+Step 2: Extract NPA (first 3 digits of LRN) and NXX (next 3 digits of LRN)
+Step 3: Use LRN's NPA-NXX for LERG queries:
+  - lerg_tandem({npa, nxx})           → tandem switch
+  - lerg_query("lerg_6", ..., "npa={npa}&nxx={nxx}")  → OCN, switch, LATA, rate center
+  - lerg_query("lerg_7", ..., "switch={clli}")         → switch details
+\`\`\`
+
+Or use \`lookup_tn\` for a quick consolidated view (dips LRN + CNAM + DNO + LERG in parallel).
+
+---
+
+## LERG Table Reference
+
+### Big 4 — Cover ~80% of Queries
+
+**lerg_1** — OCN/carrier directory
+- Fields: ocn_num, ocn_name, abbre_ocn_name, ocn_state, category, overall_ocn
+- Use: Look up carrier name by OCN. Join from lerg_6 \`ocn\` → lerg_1 \`ocn_num\`.
+- Example: \`lerg_query("lerg_1", "ocn_num,ocn_name,ocn_state", "ocn_num=567G")\`
+
+**lerg_6** — NPA-NXX block assignments (the workhorse)
+- Fields: npa, nxx, block_id, lata, lata_name, loc_state, ocn, aocn, switch, sha_indicator, rc_abbre, rc_type, coc_type, eff_date, status
+- Has LATA + state + NPA + NXX + OCN + switch + rate center all on one row.
+- BLOCK="A" = full NXX assignment; numeric 0-9 = thousands-block pooling.
+- Example: \`lerg_query("lerg_6", "npa,nxx,loc_name,loc_state,ocn,switch,lata", "npa=720&nxx=708")\`
+
+**lerg_7_sha** — Switch homing arrangements
+- Fields: switch, sha_indicator, h_trm_d_tdm (FGD tandem), host, ocn
+- Match \`switch\` + \`sha_indicator\` from lerg_6 to find the correct tandem.
+- Or use \`lerg_tandem\` which does the join automatically.
+
+**lerg_12** — LRN registry
+- Fields: lrn, lata, lata_name, switch, ocn, status, eff_date
+- Which company/switch established each LRN.
+
+### Supporting Tables
+
+| Table | Purpose |
+|-------|---------|
+| lerg_3 | NPA (area code) metadata — state, effective date |
+| lerg_5 | NPA/LATA cross-reference — which NPAs exist in a LATA |
+| lerg_7 | Switch/CLLI details — address, coordinates, equipment type |
+| lerg_8 | Rate center details — geography, V&H coordinates |
+| lerg_8_loc | Localities (towns) → rate centers |
+| lerg_8_pst | ZIP codes → localities (US only) |
+| lerg_9 | Homing by tandem — "top-down" view of which NPA-NXXs subtend a tandem |
+| lerg_4 | SS7 point codes |
+| lerg_10 | NPA-NXX → operator services ATC |
+| lerg_11 | Locality → operator services ATC |
+| lerg_16 | IP capability by LRN |
+| lerg_17 | IP capability by NPA-NXX |
+
+Use \`lerg_table_info\` to list all tables or get the schema for a specific one.
+
+---
+
+## LERG Query Syntax
+
+REST queries use path-based filters with \`&\` joining multiple conditions:
+- Single filter: \`lerg_query("lerg_1", "ocn_num,ocn_name", "ocn_state=CO")\`
+- Multiple filters: \`lerg_query("lerg_6", "npa,nxx,loc_name,ocn", "npa=303&nxx=629")\`
+
+For complex queries with JOINs and advanced operators, use \`lerg_complex_query\`:
+\`\`\`json
+{
+  "table": "lerg_6",
+  "fields": ["npa", "nxx", "ocn", "loc_name"],
+  "filters": [{"field": "npa", "operator": "eq", "value": 720}],
+  "join": {
+    "table": "lerg_1",
+    "on": [{"left_field": "ocn", "right_field": "ocn_num"}],
+    "fields": ["ocn_name", "ocn_state"]
+  }
+}
+\`\`\`
+
+Filter operators: eq, ne, gt, gte, lt, lte, like, in, isnull, isnotnull.
+
+---
+
+## CNAM (Caller Name)
+
+\`cnam_lookup\` queries TransUnion's LIDB for the caller name associated with a phone number.
+
+- Returns: calling_name (up to 15 chars), calling_name_status (available/unavailable), presentation_indicator (allowed/restricted)
+- Results cached server-side for 24 hours
+- "WIRELESS CALLER" typically means the carrier hasn't provisioned a specific CNAM entry
+
+---
+
+## DNO (Do Not Originate)
+
+\`dno_check\` checks if a phone number should never appear as a caller ID.
+
+- DNO numbers belong to entities that only receive calls (IRS, major banks, government agencies)
+- If is_dno=true, the number appearing as caller ID indicates **spoofing/fraud**
+- Supports prefix matching: 3-digit (NPA), 6-digit (NPA-NXX), 7-digit, or 10-digit patterns
+- Response includes: is_dno, matched_pattern, source
+
+---
+
+## RouteLink — Toll-Free Number Routing
+
+### ROR (Responsible Organization)
+\`routelink_lookup\` with lookup_type="ror" returns the RespOrg managing a toll-free number.
+- RespOrg is a 5-char code (e.g., "NEX01", "TZN99")
+- Only needs the CRN (toll-free number), no ANI/LATA required
+
+### CIC (Carrier Identification Code)
+\`routelink_lookup\` with lookup_type="cic" or "cicror" returns which carrier handles calls to a toll-free number FROM a specific caller (ANI) in a specific LATA.
+- Requires: crn, ani (10-digit), lata (3-digit)
+- Common carrier codes: 0288 (AT&T), 0222 (MCI/Verizon), 0333 (Sprint), 0432 (Lumen)
+
+### CPR (Call Processing Record)
+\`routelink_cpr\` retrieves the full routing decision tree for a toll-free number.
+
+**Decision tree node types:**
+| Node | Description |
+|------|-------------|
+| [LATA] | Routes by caller's LATA |
+| [NPA] | Routes by caller's area code |
+| [NXX] | Routes by caller's exchange |
+| [STATE] | Routes by caller's state |
+| [DAY_OF_WEEK] | Routes by day (1-7, Sunday=1) |
+| [TIME_OF_DAY] | Routes by time (15-min intervals) |
+| [PERCENT] | Percentage-based load balancing |
+| [ANI] | Routes by specific caller number |
+
+**Action types:** Carrier XXXX (4-digit carrier code), Template XXXXXXXXXX (reference to template CRN), Routing XXXXX, NMC X (Network Management Class)
+
+**Common patterns:**
+- Simple: All calls → one carrier → one termination number
+- Time-of-day: Business hours → office, after hours → answering service
+- Geographic: Different terminations per LATA/state/NPA
+- Percentage: Load balancing across call centers (e.g., 60%/40%)
+
+Use \`expand=true\` (default) to recursively resolve template references into their full decision trees.
+
+---
+
+## GraphQL
+
+Use \`graphql_query\` for complex queries not possible with REST:
+- Cross-table relationship joins (lerg6 → carrier, lerg6 → switchInfo, lerg7Sha → tandemSwitch)
+- Filtering by fields not in REST endpoints
+- Multiple related data points in one query
+
+**LERG GraphQL** (\`service="lerg"\`): All 27 tables with camelCase names (lerg1, lerg6, lerg7Sha, etc.)
+- FilterInput operators: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, IS_NULL, IS_NOT_NULL
+- All field values are nullable strings
+
+**LSMS GraphQL** (\`service="lsms"\`): 5 tables
+- subscriptionVersions (514M rows — MUST filter by phone_number, lrn, or spid)
+- numberBlocks, serviceProviders, locationRoutingNumbers, npanxx
+- Safety limits: max 1000 results, depth 5, complexity 200, 10-second timeout
+
+---
+
+## Key Telecom Concepts
+
+| Term | Definition |
+|------|-----------|
+| **LRN** | Location Routing Number — identifies the switch serving a ported number |
+| **SPID** | Service Provider ID — identifies the carrier that owns a number |
+| **OCN** | Operating Company Number — 4-char carrier identifier (often same as SPID) |
+| **NPA** | Numbering Plan Area — 3-digit area code |
+| **NXX** | Exchange code — next 3 digits after area code |
+| **LATA** | Local Access Transport Area — geographic region for call routing |
+| **CLLI** | Common Language Location Identifier — 8-11 char switch/building code |
+| **CRN** | Call Routing Number — a toll-free number in RouteLink context |
+| **ROR/RespOrg** | Responsible Organization — entity managing a toll-free number's routing |
+| **CIC** | Carrier Identification Code — identifies which carrier handles a toll-free call |
+| **CPR** | Call Processing Record — routing decision tree for a toll-free number |
+| **Rate Center** | Geographic area defining local calling boundaries |
+| **Tandem** | A switching office that connects local switches to the long-distance network |
+| **Homing** | The relationship between a local switch and its tandem |
+
+---
+
+## Common Mistakes to Avoid
+
+1. **Never guess carrier names** — always query lerg_1 by OCN
+2. **Never skip the LRN dip** — ported TNs have different NPA-NXX than their LRN
+3. **Never look for tandem/switch data in LSMS** — LSMS has no infrastructure data
+4. **Never look for TN-level data in LERG** — LERG has no per-phone-number data
+5. **Never query LSMS subscriptionVersions without a filter** — 514M rows will timeout
+6. **Always use the LRN's NPA-NXX** (not the TN's) for LERG routing lookups
+`;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.0.9";
+export declare const VERSION = "1.0.11";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "1.0.9";
+export const VERSION = "1.0.11";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telique-mcp",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "MCP server for Telique telecom APIs (RouteLink, LRN, CNAM, LERG)",
   "type": "module",
   "main": "dist/index.js",