telique-mcp 1.0.27 → 1.0.29

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ringer
+
+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

@@ -4,12 +4,27 @@ Telecom data tools for AI assistants. Query LRN, CNAM, DNO, LERG routing tables,
 
 ## Install
 
+Pick **one** install surface.
+
+### Recommended — Hosted connector
+
+OAuth-authenticated. Works on claude.ai, Claude Desktop, Claude Code, and Claude mobile. No local Node runtime.
+
+- **URL:** `https://mcp.telique.ringer.tel`
+- Add it as a custom MCP connector in your Claude client's settings.
+
+### npm stdio — advanced / offline
+
+For CI, local development, or clients that don't support remote MCP. Stores a long-lived `tlq_…` token at `~/.telique/config.json`.
+
 ```bash
 npm install -g telique-mcp
 telique-mcp setup
 ```
 
-The setup wizard detects your installed AI clients and registers automatically.
+The setup wizard detects installed AI clients and registers automatically.
+
+> ⚠️ **Install only one surface.** Running both exposes the same tools under overlapping namespaces and causes confusing shadowing of tool results.
 
 ## What You Get
 

package/dist/knowledge.d.ts

@@ -1,3 +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- Example: `lerg_query(\"lerg_6\", \"npa,nxx,block_id,loc_name,loc_state,ocn,switch,lata\", \"npa=720&nxx=708\")`\n\n**CRITICAL: Understanding block_id and NPA-NXX ownership:**\n- `block_id=\"A\"` = the **Code Holder** \u2014 the original LERG owner of the entire NPA-NXX. This is THE owner of the NPA-NXX.\n- `block_id=\"0\"` through `\"9\"` = **Block Holders** \u2014 carriers who received a pooled 1,000-number block (thousands-block pooling). Each block covers numbers x000-x999 within the NXX.\n- When asked \"who owns NPA-NXX 720-708?\", the answer is the OCN on the `block_id=\"A\"` row.\n- A query for `npa=720&nxx=708` may return multiple rows \u2014 one for block_id=\"A\" (the Code Holder) and additional rows for pooled blocks (0-9). Always filter or identify the \"A\" row for ownership questions.\n- To find which carrier serves a specific phone number within a pooled NXX, use the LRN dip pattern instead (the block_id approach only tells you who holds the block, not who currently serves an individual ported number).\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, notin, isnull, isnotnull.\nUse `*` as the fields value to return all fields from a table.\nNote: REST `like` is **case-insensitive** (in-memory matching), unlike GraphQL LIKE which is case-sensitive (PostgreSQL).\n\n---\n\n## When to Use REST vs GraphQL\n\n| Use Case | Best Tool | Why |\n|----------|-----------|-----|\n| Single LRN/SPID for a phone number | `lrn_lookup` (REST) | Sub-millisecond, in-memory |\n| Carrier name by OCN | `lerg_query` (REST) | Simple single-field lookup |\n| NPA-NXX routing info | `lerg_query` (REST) | Fast, straightforward |\n| Tandem routing | `lerg_tandem` (REST) | Pre-built JOIN, optimized |\n| NPA-NXX + carrier name + switch in one call | `graphql_query` (LERG) | Nested relationships avoid multiple round trips |\n| Filter by fields not in REST (e.g., all switches for an OCN) | `graphql_query` (LERG) | FilterInput supports any field |\n| Cross-table JOIN with arbitrary conditions | `graphql_query` (LERG dynamicJoin) | Only way to do ad-hoc joins |\n| All phone numbers for an LRN (paginated with totalCount) | `graphql_query` (LSMS) | SVConnection returns totalCount + hasMore |\n| Quick profile of a phone number | `lookup_tn` (composite) | Parallel dip across LRN + CNAM + DNO + LERG |\n\n**Rule of thumb:** Use REST for simple lookups (one table, one or two filters). Use GraphQL when you need joins, relationship traversal, or fields not exposed by REST endpoints.\n\n---\n\n## LSMS / LRN REST Endpoints\n\nThe LRN API serves live NPAC porting data from an in-memory Judy Array store (500M+ records, sub-millisecond) backed by a PostgreSQL LSMS database.\n\n### LRN Lookup (`lrn_lookup` tool)\n\n`GET /v1/telique/lrn/{phone_number}?format=json`\n\nReturns the current LRN and carrier for a phone number. This is the fastest lookup \u2014 served from in-memory store, not PostgreSQL.\n\n**JSON response shape:**\n```json\n{\n  \"phone_number\": \"3036298301\",\n  \"lrn\": \"7207081999\",\n  \"status\": \"success\",\n  \"timestamp\": \"2025-08-07T02:30:00Z\",\n  \"metadata\": {\n    \"spid\": \"567G\",\n    \"lnp_type\": \"lspp\",\n    \"activation_timestamp\": \"2024-01-15T10:30:00Z\",\n    \"last_updated\": \"2025-08-07T01:30:00Z\"\n  }\n}\n```\n\nDefault format is plain text (`LRN;SPID`, e.g., `7207081999;567G`). Use `?format=json` for structured response.\n\n### LSMS Relationship Queries (`lrn_relationship_query` tool)\n\nQuery relationships between phone numbers, LRNs, and SPIDs from the LSMS PostgreSQL database. These hit the database directly and have higher latency than the in-memory LRN lookup.\n\n**6 query types and their endpoints:**\n\n| query_type | Endpoint | Description |\n|------------|----------|-------------|\n| `phones_by_lrn` | `GET /v1/telique/lsms/list/phone_number?lrn={value}` | All phone numbers for a given LRN |\n| `phones_by_spid` | `GET /v1/telique/lsms/list/phone_number?spid={value}` | All phone numbers for a given SPID |\n| `spid_by_lrn` | `GET /v1/telique/lsms/list/spid?lrn={value}` | All SPIDs associated with a given LRN |\n| `spid_by_phone` | `GET /v1/telique/lsms/list/spid?phone_number={value}` | All SPIDs for a given phone number |\n| `lrn_by_spid` | `GET /v1/telique/lsms/list/lrn?spid={value}` | All LRNs for a given SPID |\n| `lrn_by_phone` | `GET /v1/telique/lsms/list/lrn?phone_number={value}` | All LRNs for a given phone number |\n\n**Constraints:**\n- Exactly ONE query parameter per request (multiple parameters return a validation error)\n- Results are filtered to active records only\n- Phone numbers and LRNs are returned as strings\n\n**Example response (phones_by_lrn):**\n```json\n{\n  \"phone_numbers\": [\"3036298301\", \"3039982743\", \"3033334444\"],\n  \"count\": 3,\n  \"query\": { \"lrn\": \"7207081999\", \"spid\": null, \"phone_number\": null }\n}\n```\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- Phone numbers are auto-normalized: E.164 (+12003456789), domestic (12003456789), and international (0012003456789) formats all accepted\n\n---\n\n## RouteLink \u2014 Toll-Free Number Routing\n\n**What is a toll-free number?** A phone number with an 8XX NPA (area code) that is free for the caller \u2014 the called party pays. Toll-free NPAs: **800, 888, 877, 866, 855, 844, 833, 822**. Any 10-digit number starting with one of these NPAs is a toll-free number (also called TFN or CRN in RouteLink context).\n\nToll-free numbers are managed by the **Somos TFN Registry**, not NPAC/LSMS. They have their own routing system (CPR decision trees) and their own management hierarchy (RespOrgs, not SPIDs). Use the RouteLink tools for toll-free lookups \u2014 do NOT use `lrn_lookup` for toll-free numbers (they don't have LRNs).\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\"`)\n\n**CRITICAL naming rules:**\n- **Query names** are camelCase: `lerg1`, `lerg6`, `lerg7Sha`, `lerg7ShaIns`, `lerg12`, etc.\n- **Return fields** MUST be camelCase: `ocnName`, `locState`, `locName`, `shaIndicator`, `hTrmDTdm`\n- **Filter field names** accept BOTH camelCase (`ocnName`) and snake_case (`ocn_name`)\n- **All values are strings** \u2014 even numeric fields. Always quote: `value: \"720\"` not `value: 720`\n- **GraphQL LIKE is case-sensitive (SQL)** \u2014 LERG data is stored UPPERCASE, so patterns must be uppercase: `%VERIZON%` not `%verizon%`. (The REST `like` operator is case-insensitive \u2014 this only applies to GraphQL.)\n\n**FilterInput:**\n```graphql\n{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }   # partial match (UPPERCASE!)\n{ field: \"npa\", op: EQ, value: \"720\" }                # exact match\n{ field: \"npa\", op: IN, values: [\"212\", \"646\", \"917\"] } # IN uses 'values' (plural), not 'value'\n```\n\nOperators: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, IS_NULL, IS_NOT_NULL\n\n**Predefined relationships** (avoid N+1 \u2014 use these instead of separate queries):\n- `lerg6` \u2192 `carrier` (joins to lerg1 via OCN), `switchInfo` (\u2192 lerg7), `homingArrangements` (\u2192 lerg7Sha)\n- `lerg7` \u2192 `carrier` (\u2192 lerg1)\n- `lerg7Sha` \u2192 `tandemSwitch` (\u2192 lerg7)\n\n**Example \u2014 find all Verizon OCNs:**\n```graphql\n{\n  lerg1(\n    filters: [{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }]\n    pagination: { limit: 10 }\n  ) {\n    ocnNum\n    ocnName\n    ocnState\n    category\n  }\n}\n```\n\n**Example \u2014 NPA-NXX with carrier and switch in one query:**\n```graphql\n{\n  lerg6(\n    filters: [{ field: \"npa\", op: EQ, value: \"303\" }, { field: \"nxx\", op: EQ, value: \"629\" }]\n    pagination: { limit: 1 }\n  ) {\n    npa nxx ocn locName switch\n    carrier { ocnNum ocnName ocnState }\n    switchInfo { switch eqpType swCity swState }\n    homingArrangements {\n      shaIndicator hTrmDTdm\n      tandemSwitch { switch swCity swState }\n    }\n  }\n}\n```\n\n**dynamicJoin** \u2014 for arbitrary cross-table SQL joins (returns raw JSON):\n```graphql\n{\n  dynamicJoin(input: {\n    table: \"lerg_6\"\n    fields: [\"npa\", \"nxx\", \"ocn\", \"locName\"]\n    filters: [{ field: \"locName\", op: LIKE, value: \"%DENVER%\" }]\n    join: {\n      table: \"lerg_1\"\n      fields: [\"ocnName\", \"category\"]\n      on: [{ leftField: \"ocn\", rightField: \"ocnNum\" }]\n      joinType: \"INNER\"\n    }\n    pagination: { limit: 10 }\n  })\n}\n```\nNote: dynamicJoin uses snake_case table IDs (lerg_6, lerg_1, lerg_7_sha) and returns raw PostgreSQL column names (UPPERCASE with spaces, e.g., `\"OCN_NAME\"`, `\"LOC NAME\"`, `\"EFF DATE\"`), NOT GraphQL camelCase.\n\n### LSMS GraphQL (`service=\"lsms\"`)\n\nThe LSMS GraphQL API is a **completely separate implementation** from LERG GraphQL. It has different query patterns, different field naming, and different schema design. Do NOT use LERG-style FilterInput syntax with LSMS.\n\n**5 tables:**\n\n| Table | ~Rows | Requires Filter? |\n|-------|-------|------------------|\n| subscriptionVersions | 514M | Yes (phoneNumber, lrn, or spid) |\n| numberBlocks | 751K | Yes (npanxxx, spid, or lrn) |\n| serviceProviders | 5.2K | No |\n| locationRoutingNumbers | 56K | No |\n| npanxx | 192K | No |\n\n**Query patterns (NOT FilterInput \u2014 uses typed named parameters):**\n```graphql\n# Single phone number lookup\n{ subscriptionVersion(phoneNumber: \"3036298301\") { phoneNumber lrn spid serviceProvider { name } } }\n\n# Paginated list by LRN (returns totalCount, hasMore)\n{ subscriptionVersionsByLrn(lrn: \"7207081999\", limit: 10) { totalCount hasMore items { phoneNumber spid } } }\n\n# Paginated list by SPID\n{ subscriptionVersionsBySpid(spid: \"567G\", limit: 10) { totalCount hasMore items { phoneNumber lrn } } }\n\n# Number block lookup (single)\n{ numberBlock(npanxxx: \"3035551\") { npanxxx lrn spid serviceProvider { name } } }\n\n# Number blocks by SPID or LRN (paginated \u2014 at least one filter required)\n{ numberBlocks(spid: \"567G\", limit: 10) { totalCount hasMore items { npanxxx lrn spid } } }\n\n# Single carrier lookup (note: composite PK \u2014 same SPID may exist in multiple regions)\n{ serviceProvider(spid: \"567G\") { spid name npacRegion status contactInfo } }\n\n# List carriers (paginated)\n{ serviceProviders(limit: 20) { spid name npacRegion } }\n\n# LRN metadata\n{ locationRoutingNumber(lrn: \"7207081999\") { lrn ocn regionId status switchInfo } }\n\n# NPA-NXX single lookup\n{ npanxx(npa: \"303\", nxx: \"629\") { npa nxx spid effectiveTimestamp serviceProvider { name } } }\n\n# NPA-NXX codes for a carrier (paginated)\n{ npanxxBySpid(spid: \"567G\", limit: 50) { npa nxx effectiveTimestamp } }\n\n# Database statistics\n{ lsmsStats { activeSubscriptionVersions activeNumberBlocks totalServiceProviders totalLocationRoutingNumbers activeNpanxx } }\n```\n\n**Relationships** (use DataLoader batching \u2014 no N+1):\n- subscriptionVersion \u2192 `serviceProvider`, `lrnMetadata`\n- numberBlock \u2192 `serviceProvider`, `lrnMetadata`\n- npanxx \u2192 `serviceProvider`\n\n**Safety limits:** max 1000 results, depth 5, complexity 200, 10-second statement timeout\n**Auto-filters:** Soft-deletable records filter to is_active = true automatically\n**Note:** Phone numbers/LRNs are strings (stored as BIGINT but GraphQL Int is 32-bit). SPIDs are auto-trimmed (stored as CHAR(4) with trailing spaces).\n**Note:** Service providers have a composite PK of (spid, npac_region) \u2014 the same SPID may appear in multiple NPAC regions.\n\n---\n\n## REST Paths for Direct API Access\n\nThe MCP tools wrap these HTTP endpoints. Use this table when calling the Telique API directly with `curl` or another HTTP client. Base URL: `https://api-dev.ringer.tel`. Authentication: `-H \"x-api-token: tlq_\u2026\"` (per-request header, never in query string).\n\n| Tool | Method | Path | Notes |\n|------|--------|------|-------|\n| `lrn_lookup` | GET | `/v1/telique/lrn/{phone_number}` | Add `?format=json` for structured response; default is `LRN;SPID` plain text |\n| `cnam_lookup` | GET | `/v1/telique/cnam/{phone_number}` | Returns calling_name, presentation_indicator |\n| `dno_check` | GET | `/v1/telique/dno/{phone_number}` | Add `?format=json` for details; default is `true`/`false` text |\n| `lrn_relationship_query` | GET | `/v1/telique/lsms/list/{resource}?{filter}={value}` | `resource` \u2208 {phone_number, spid, lrn}; filter \u2208 {lrn, spid, phone_number}; exactly one filter |\n| `lerg_table_info` | GET | `/v1/telique/lerg/tables` or `/v1/telique/lerg/tables/{table_name}` | No args = list all tables |\n| `lerg_query` | GET | `/v1/telique/lerg/{table_name}/{fields}/{query}` | Example: `/lerg/lerg_6/npa,nxx,ocn/npa=303&nxx=629` |\n| `lerg_complex_query` | POST | `/v1/telique/lerg/query` | JSON body with table, fields, filters, join, limit, offset |\n| `lerg_tandem` | GET | `/v1/telique/lerg/tandem?npa={npa}&nxx={nxx}` | Pre-joined tandem lookup |\n| `routelink_lookup` (ror) | GET | `/v1/telique/ror/{crn}` | Responsible Organization for a toll-free number |\n| `routelink_lookup` (cic/cicror) | GET | `/v1/telique/{cic\\|cicror}/{crn}/{ani}/{lata}` | CIC or CIC+ROR for a toll-free call |\n| `routelink_ror_query` | GET | `/v1/telique/ror/{ror}/{tfns\\|cprs}` | List TFNs or CPRs for a ROR; paginated `?limit=&offset=` |\n| `routelink_cpr` | GET | `/v1/telique/cpr/{crn}` | Call Processing Record; add `?expand=true` to inline templates |\n| `graphql_query` (lerg) | POST | `/v1/telique/lerg/gql` | JSON body `{\"query\":\"...\"}`; GET returns GraphiQL playground HTML |\n| `graphql_query` (lsms) | POST | `/v1/telique/lsms/gql` | JSON body `{\"query\":\"...\"}`; GET returns GraphiQL playground HTML |\n| `lookup_tn` | \u2014 | (composite) | Not a single endpoint \u2014 fans out to `/lrn/`, `/cnam/`, `/dno/`, `/lerg/\u2026` in parallel |\n\n**Note on RouteLink paths**: there is NO `/routelink/` segment. The public OpenAPI spec at `https://telique.ringer.tel/docs/api-reference` historically listed `/v1/telique/routelink/cpr/{crn}` etc. \u2014 those paths return 404. The real paths are bare (`/v1/telique/cpr/{crn}`) as shown above.\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\n7. **GraphQL return fields must be camelCase** \u2014 `ocnName` not `ocn_name`, `locState` not `loc_state`\n8. **GraphQL LIKE patterns must be UPPERCASE** \u2014 LERG data is uppercase in PostgreSQL, so `%VERIZON%` works but `%verizon%` returns nothing. (REST `like` is case-insensitive \u2014 this only applies to GraphQL.)\n9. **IN operator uses `values` (plural)** \u2014 `{ field: \"npa\", op: IN, values: [\"212\", \"646\"] }` not `value`\n";
+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- Example: `lerg_query(\"lerg_6\", \"npa,nxx,block_id,loc_name,loc_state,ocn,switch,lata\", \"npa=720&nxx=708\")`\n\n**CRITICAL: Understanding block_id and NPA-NXX ownership:**\n- `block_id=\"A\"` = the **Code Holder** \u2014 the original LERG owner of the entire NPA-NXX. This is THE owner of the NPA-NXX.\n- `block_id=\"0\"` through `\"9\"` = **Block Holders** \u2014 carriers who received a pooled 1,000-number block (thousands-block pooling). Each block covers numbers x000-x999 within the NXX.\n- When asked \"who owns NPA-NXX 720-708?\", the answer is the OCN on the `block_id=\"A\"` row.\n- A query for `npa=720&nxx=708` may return multiple rows \u2014 one for block_id=\"A\" (the Code Holder) and additional rows for pooled blocks (0-9). Always filter or identify the \"A\" row for ownership questions.\n- To find which carrier serves a specific phone number within a pooled NXX, use the LRN dip pattern instead (the block_id approach only tells you who holds the block, not who currently serves an individual ported number).\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, notin, isnull, isnotnull.\nUse `*` as the fields value to return all fields from a table.\nNote: REST `like` is **case-insensitive** (in-memory matching), unlike GraphQL LIKE which is case-sensitive (PostgreSQL).\n\n---\n\n## When to Use REST vs GraphQL\n\n| Use Case | Best Tool | Why |\n|----------|-----------|-----|\n| Single LRN/SPID for a phone number | `lrn_lookup` (REST) | Sub-millisecond, in-memory |\n| Carrier name by OCN | `lerg_query` (REST) | Simple single-field lookup |\n| NPA-NXX routing info | `lerg_query` (REST) | Fast, straightforward |\n| Tandem routing | `lerg_tandem` (REST) | Pre-built JOIN, optimized |\n| NPA-NXX + carrier name + switch in one call | `graphql_query` (LERG) | Nested relationships avoid multiple round trips |\n| Filter by fields not in REST (e.g., all switches for an OCN) | `graphql_query` (LERG) | FilterInput supports any field |\n| Cross-table JOIN with arbitrary conditions | `graphql_query` (LERG dynamicJoin) | Only way to do ad-hoc joins |\n| All phone numbers for an LRN (paginated with totalCount) | `graphql_query` (LSMS) | SVConnection returns totalCount + hasMore |\n| Quick profile of a phone number | `lookup_tn` (composite) | Parallel dip across LRN + CNAM + DNO + LERG |\n\n**Rule of thumb:** Use REST for simple lookups (one table, one or two filters). Use GraphQL when you need joins, relationship traversal, or fields not exposed by REST endpoints.\n\n---\n\n## LSMS / LRN REST Endpoints\n\nThe LRN API serves live NPAC porting data from an in-memory Judy Array store (500M+ records, sub-millisecond) backed by a PostgreSQL LSMS database.\n\n### LRN Lookup (`lrn_lookup` tool)\n\n`GET /v1/telique/lrn/{phone_number}?format=json`\n\nReturns the current LRN and carrier for a phone number. This is the fastest lookup \u2014 served from in-memory store, not PostgreSQL.\n\n**JSON response shape:**\n```json\n{\n  \"phone_number\": \"3036298301\",\n  \"lrn\": \"7207081999\",\n  \"status\": \"success\",\n  \"timestamp\": \"2025-08-07T02:30:00Z\",\n  \"metadata\": {\n    \"spid\": \"567G\",\n    \"lnp_type\": \"lspp\",\n    \"activation_timestamp\": \"2024-01-15T10:30:00Z\",\n    \"last_updated\": \"2025-08-07T01:30:00Z\"\n  }\n}\n```\n\nDefault format is plain text (`LRN;SPID`, e.g., `7207081999;567G`). Use `?format=json` for structured response.\n\n### LSMS Relationship Queries (`lrn_relationship_query` tool)\n\nQuery relationships between phone numbers, LRNs, and SPIDs from the LSMS PostgreSQL database. These hit the database directly and have higher latency than the in-memory LRN lookup.\n\n**6 query types and their endpoints:**\n\n| query_type | Endpoint | Description |\n|------------|----------|-------------|\n| `phones_by_lrn` | `GET /v1/telique/lsms/list/phone_number?lrn={value}` | All phone numbers for a given LRN |\n| `phones_by_spid` | `GET /v1/telique/lsms/list/phone_number?spid={value}` | All phone numbers for a given SPID |\n| `spid_by_lrn` | `GET /v1/telique/lsms/list/spid?lrn={value}` | All SPIDs associated with a given LRN |\n| `spid_by_phone` | `GET /v1/telique/lsms/list/spid?phone_number={value}` | All SPIDs for a given phone number |\n| `lrn_by_spid` | `GET /v1/telique/lsms/list/lrn?spid={value}` | All LRNs for a given SPID |\n| `lrn_by_phone` | `GET /v1/telique/lsms/list/lrn?phone_number={value}` | All LRNs for a given phone number |\n\n**Constraints:**\n- Exactly ONE query parameter per request (multiple parameters return a validation error)\n- Results are filtered to active records only\n- Phone numbers and LRNs are returned as strings\n\n**Example response (phones_by_lrn):**\n```json\n{\n  \"phone_numbers\": [\"3036298301\", \"3039982743\", \"3033334444\"],\n  \"count\": 3,\n  \"query\": { \"lrn\": \"7207081999\", \"spid\": null, \"phone_number\": null }\n}\n```\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- Phone numbers are auto-normalized: E.164 (+12003456789), domestic (12003456789), and international (0012003456789) formats all accepted\n\n---\n\n## RouteLink \u2014 Toll-Free Number Routing\n\n**What is a toll-free number?** A phone number with an 8XX NPA (area code) that is free for the caller \u2014 the called party pays. Toll-free NPAs: **800, 888, 877, 866, 855, 844, 833, 822**. Any 10-digit number starting with one of these NPAs is a toll-free number (also called TFN or CRN in RouteLink context).\n\nToll-free numbers are managed by the **Somos TFN Registry**, not NPAC/LSMS. They have their own routing system (CPR decision trees) and their own management hierarchy (RespOrgs, not SPIDs). Use the RouteLink tools for toll-free lookups \u2014 do NOT use `lrn_lookup` for toll-free numbers (they don't have LRNs).\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\"`)\n\n**CRITICAL naming rules:**\n- **Query names** are camelCase: `lerg1`, `lerg6`, `lerg7Sha`, `lerg7ShaIns`, `lerg12`, etc.\n- **Object-type names use a `Gql` prefix.** `__type(name: \"Lerg6\")` returns null \u2014 the actual type is `GqlLerg6`. Rule: snake_case table ID \u2192 PascalCase + `Gql` prefix (`lerg_6` \u2192 `GqlLerg6`, `lerg_7_sha` \u2192 `GqlLerg7Sha`, `lerg_8_loc` \u2192 `GqlLerg8Loc`). Use this when introspecting types directly.\n- **Return fields** MUST be camelCase: `ocnName`, `locState`, `locName`, `shaIndicator`, `hTrmDTdm`\n- **REST fields are snake_case; GraphQL fields are camelCase \u2014 1:1 convertible.** `coc_type` \u2194 `cocType`, `loc_name` \u2194 `locName`, `ocn_num` \u2194 `ocnNum`, `sha_indicator` \u2194 `shaIndicator`. GraphQL `FilterInput` `field:` accepts both forms; REST query paths and GraphQL selection sets do not.\n- **Filter field names** accept BOTH camelCase (`ocnName`) and snake_case (`ocn_name`)\n- **All values are strings** \u2014 even numeric fields. Always quote: `value: \"720\"` not `value: 720`\n- **GraphQL LIKE is case-sensitive (SQL)** \u2014 LERG data is stored UPPERCASE, so patterns must be uppercase: `%VERIZON%` not `%verizon%`. (The REST `like` operator is case-insensitive \u2014 this only applies to GraphQL.)\n\n**FilterInput:**\n```graphql\n{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }   # partial match (UPPERCASE!)\n{ field: \"npa\", op: EQ, value: \"720\" }                # exact match\n{ field: \"npa\", op: IN, values: [\"212\", \"646\", \"917\"] } # IN uses 'values' (plural), not 'value'\n```\n\nOperators: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, IS_NULL, IS_NOT_NULL\n\n**Predefined relationships** (avoid N+1 \u2014 use these instead of separate queries):\n- `lerg6` \u2192 `carrier` (joins to lerg1 via OCN), `switchInfo` (\u2192 lerg7), `homingArrangements` (\u2192 lerg7Sha)\n- `lerg7` \u2192 `carrier` (\u2192 lerg1)\n- `lerg7Sha` \u2192 `tandemSwitch` (\u2192 lerg7)\n\n**Example \u2014 find all Verizon OCNs:**\n```graphql\n{\n  lerg1(\n    filters: [{ field: \"ocnName\", op: LIKE, value: \"%VERIZON%\" }]\n    pagination: { limit: 10 }\n  ) {\n    ocnNum\n    ocnName\n    ocnState\n    category\n  }\n}\n```\n\n**Example \u2014 NPA-NXX with carrier and switch in one query:**\n```graphql\n{\n  lerg6(\n    filters: [{ field: \"npa\", op: EQ, value: \"303\" }, { field: \"nxx\", op: EQ, value: \"629\" }]\n    pagination: { limit: 1 }\n  ) {\n    npa nxx ocn locName switch\n    carrier { ocnNum ocnName ocnState }\n    switchInfo { switch eqpType swCity swState }\n    homingArrangements {\n      shaIndicator hTrmDTdm\n      tandemSwitch { switch swCity swState }\n    }\n  }\n}\n```\n\n**dynamicJoin** \u2014 for arbitrary cross-table SQL joins (returns raw JSON):\n```graphql\n{\n  dynamicJoin(input: {\n    table: \"lerg_6\"\n    fields: [\"npa\", \"nxx\", \"ocn\", \"locName\"]\n    filters: [{ field: \"locName\", op: LIKE, value: \"%DENVER%\" }]\n    join: {\n      table: \"lerg_1\"\n      fields: [\"ocnName\", \"category\"]\n      on: [{ leftField: \"ocn\", rightField: \"ocnNum\" }]\n      joinType: \"INNER\"\n    }\n    pagination: { limit: 10 }\n  })\n}\n```\nNote: dynamicJoin uses snake_case table IDs (lerg_6, lerg_1, lerg_7_sha) and returns raw PostgreSQL column names (UPPERCASE with spaces, e.g., `\"OCN_NAME\"`, `\"LOC NAME\"`, `\"EFF DATE\"`), NOT GraphQL camelCase.\n\n### LSMS GraphQL (`service=\"lsms\"`)\n\nThe LSMS GraphQL API is a **completely separate implementation** from LERG GraphQL. It has different query patterns, different field naming, and different schema design. Do NOT use LERG-style FilterInput syntax with LSMS.\n\n**5 tables:**\n\n| Table | ~Rows | Requires Filter? |\n|-------|-------|------------------|\n| subscriptionVersions | 514M | Yes (phoneNumber, lrn, or spid) |\n| numberBlocks | 751K | Yes (npanxxx, spid, or lrn) |\n| serviceProviders | 5.2K | No |\n| locationRoutingNumbers | 56K | No |\n| npanxx | 192K | No |\n\n**Query patterns (NOT FilterInput \u2014 uses typed named parameters):**\n```graphql\n# Single phone number lookup\n{ subscriptionVersion(phoneNumber: \"3036298301\") { phoneNumber lrn spid serviceProvider { name } } }\n\n# Paginated list by LRN (returns totalCount, hasMore)\n{ subscriptionVersionsByLrn(lrn: \"7207081999\", limit: 10) { totalCount hasMore items { phoneNumber spid } } }\n\n# Paginated list by SPID\n{ subscriptionVersionsBySpid(spid: \"567G\", limit: 10) { totalCount hasMore items { phoneNumber lrn } } }\n\n# Number block lookup (single)\n{ numberBlock(npanxxx: \"3035551\") { npanxxx lrn spid serviceProvider { name } } }\n\n# Number blocks by SPID or LRN (paginated \u2014 at least one filter required)\n{ numberBlocks(spid: \"567G\", limit: 10) { totalCount hasMore items { npanxxx lrn spid } } }\n\n# Single carrier lookup (note: composite PK \u2014 same SPID may exist in multiple regions)\n{ serviceProvider(spid: \"567G\") { spid name npacRegion status contactInfo } }\n\n# List carriers (paginated)\n{ serviceProviders(limit: 20) { spid name npacRegion } }\n\n# LRN metadata\n{ locationRoutingNumber(lrn: \"7207081999\") { lrn ocn regionId status switchInfo } }\n\n# NPA-NXX single lookup\n{ npanxx(npa: \"303\", nxx: \"629\") { npa nxx spid effectiveTimestamp serviceProvider { name } } }\n\n# NPA-NXX codes for a carrier (paginated)\n{ npanxxBySpid(spid: \"567G\", limit: 50) { npa nxx effectiveTimestamp } }\n\n# Database statistics\n{ lsmsStats { activeSubscriptionVersions activeNumberBlocks totalServiceProviders totalLocationRoutingNumbers activeNpanxx } }\n```\n\n**Relationships** (use DataLoader batching \u2014 no N+1):\n- subscriptionVersion \u2192 `serviceProvider`, `lrnMetadata`\n- numberBlock \u2192 `serviceProvider`, `lrnMetadata`\n- npanxx \u2192 `serviceProvider`\n\n**Safety limits:** max 1000 results, depth 5, complexity 200, 10-second statement timeout\n**Auto-filters:** Soft-deletable records filter to is_active = true automatically\n**Note:** Phone numbers/LRNs are strings (stored as BIGINT but GraphQL Int is 32-bit). SPIDs are auto-trimmed (stored as CHAR(4) with trailing spaces).\n**Note:** Service providers have a composite PK of (spid, npac_region) \u2014 the same SPID may appear in multiple NPAC regions.\n\n---\n\n## REST Paths for Direct API Access\n\nThe MCP tools wrap these HTTP endpoints. Use this table when calling the Telique API directly with `curl` or another HTTP client. Base URL: `https://api-dev.ringer.tel`. Authentication: `-H \"x-api-token: tlq_\u2026\"` (per-request header, never in query string).\n\n| Tool | Method | Path | Notes |\n|------|--------|------|-------|\n| `lrn_lookup` | GET | `/v1/telique/lrn/{phone_number}` | Add `?format=json` for structured response; default is `LRN;SPID` plain text |\n| `cnam_lookup` | GET | `/v1/telique/cnam/{phone_number}` | Returns calling_name, presentation_indicator |\n| `dno_check` | GET | `/v1/telique/dno/{phone_number}` | Add `?format=json` for details; default is `true`/`false` text |\n| `lrn_relationship_query` | GET | `/v1/telique/lsms/list/{resource}?{filter}={value}` | `resource` \u2208 {phone_number, spid, lrn}; filter \u2208 {lrn, spid, phone_number}; exactly one filter |\n| `lerg_table_info` | GET | `/v1/telique/lerg/tables` or `/v1/telique/lerg/tables/{table_name}` | No args = list all tables |\n| `lerg_query` | GET | `/v1/telique/lerg/{table_name}/{fields}/{query}` | Example: `/lerg/lerg_6/npa,nxx,ocn/npa=303&nxx=629` |\n| `lerg_complex_query` | POST | `/v1/telique/lerg/query` | JSON body with table, fields, filters, join, limit, offset |\n| `lerg_tandem` | GET | `/v1/telique/lerg/tandem?npa={npa}&nxx={nxx}` | Pre-joined tandem lookup |\n| `routelink_lookup` (ror) | GET | `/v1/telique/ror/{crn}` | Responsible Organization for a toll-free number |\n| `routelink_lookup` (cic/cicror) | GET | `/v1/telique/{cic\\|cicror}/{crn}/{ani}/{lata}` | CIC or CIC+ROR for a toll-free call |\n| `routelink_ror_query` | GET | `/v1/telique/ror/{ror}/{tfns\\|cprs}` | List TFNs or CPRs for a ROR; paginated `?limit=&offset=` |\n| `routelink_cpr` | GET | `/v1/telique/cpr/{crn}` | Call Processing Record; add `?expand=true` to inline templates |\n| `graphql_query` (lerg) | POST | `/v1/telique/lerg/gql` | JSON body `{\"query\":\"...\"}`; GET returns GraphiQL playground HTML |\n| `graphql_query` (lsms) | POST | `/v1/telique/lsms/gql` | JSON body `{\"query\":\"...\"}`; GET returns GraphiQL playground HTML |\n| `lookup_tn` | \u2014 | (composite) | Not a single endpoint \u2014 fans out to `/lrn/`, `/cnam/`, `/dno/`, `/lerg/\u2026` in parallel |\n\n**Note on RouteLink paths**: there is NO `/routelink/` segment. The public OpenAPI spec at `https://telique.ringer.tel/docs/api-reference` historically listed `/v1/telique/routelink/cpr/{crn}` etc. \u2014 those paths return 404. The real paths are bare (`/v1/telique/cpr/{crn}`) as shown above.\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\n7. **GraphQL return fields must be camelCase** \u2014 `ocnName` not `ocn_name`, `locState` not `loc_state`\n8. **GraphQL LIKE patterns must be UPPERCASE** \u2014 LERG data is uppercase in PostgreSQL, so `%VERIZON%` works but `%verizon%` returns nothing. (REST `like` is case-insensitive \u2014 this only applies to GraphQL.)\n9. **IN operator uses `values` (plural)** \u2014 `{ field: \"npa\", op: IN, values: [\"212\", \"646\"] }` not `value`\n";

package/dist/knowledge.js

@@ -301,7 +301,9 @@ Use \`graphql_query\` for complex queries not possible with REST:
 
 **CRITICAL naming rules:**
 - **Query names** are camelCase: \`lerg1\`, \`lerg6\`, \`lerg7Sha\`, \`lerg7ShaIns\`, \`lerg12\`, etc.
+- **Object-type names use a \`Gql\` prefix.** \`__type(name: "Lerg6")\` returns null — the actual type is \`GqlLerg6\`. Rule: snake_case table ID → PascalCase + \`Gql\` prefix (\`lerg_6\` → \`GqlLerg6\`, \`lerg_7_sha\` → \`GqlLerg7Sha\`, \`lerg_8_loc\` → \`GqlLerg8Loc\`). Use this when introspecting types directly.
 - **Return fields** MUST be camelCase: \`ocnName\`, \`locState\`, \`locName\`, \`shaIndicator\`, \`hTrmDTdm\`
+- **REST fields are snake_case; GraphQL fields are camelCase — 1:1 convertible.** \`coc_type\` ↔ \`cocType\`, \`loc_name\` ↔ \`locName\`, \`ocn_num\` ↔ \`ocnNum\`, \`sha_indicator\` ↔ \`shaIndicator\`. GraphQL \`FilterInput\` \`field:\` accepts both forms; REST query paths and GraphQL selection sets do not.
 - **Filter field names** accept BOTH camelCase (\`ocnName\`) and snake_case (\`ocn_name\`)
 - **All values are strings** — even numeric fields. Always quote: \`value: "720"\` not \`value: 720\`
 - **GraphQL LIKE is case-sensitive (SQL)** — LERG data is stored UPPERCASE, so patterns must be uppercase: \`%VERIZON%\` not \`%verizon%\`. (The REST \`like\` operator is case-insensitive — this only applies to GraphQL.)

package/dist/setup.js

@@ -3,6 +3,7 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { execSync, execFileSync } from "node:child_process";
 import { stdin, stdout } from "node:process";
 import { CONFIG_DIR, CONFIG_FILE } from "./config.js";
+import { TeliqueClient } from "./client.js";
 import { ICON_DARK_DATA_URI } from "./icons.js";
 const REGISTER_URL = "https://telique.ringer.tel/register";
 const API_BASE_URL = "https://api-dev.ringer.tel";
@@ -127,11 +128,13 @@ function detectMcpClients() {
             register: (token) => registerJsonConfig(cursorConfig, token),
         });
     }
-    // Codex CLI
-    if (commandExists("codex")) {
+    // Codex (CLI and/or Desktop — both share ~/.codex/config.toml,
+    // so one `codex mcp add` configures whichever surfaces are installed)
+    const codex = findCodexBinary();
+    if (codex) {
         clients.push({
-            name: "Codex CLI",
-            register: (token) => registerCodex(token),
+            name: codex.label,
+            register: (token) => registerCodex(token, codex.bin),
         });
     }
     // GitHub Copilot (VS Code)
@@ -184,11 +187,11 @@ function registerClaudeCode(token) {
         return false;
     }
 }
-function registerCodex(token) {
+function registerCodex(token, bin = "codex") {
     try {
         // Remove existing entry first
         try {
-            execFileSync("codex", ["mcp", "remove", "telique"], { stdio: "ignore" });
+            execFileSync(bin, ["mcp", "remove", "telique"], { stdio: "ignore" });
         }
         catch {
             // ignore
@@ -198,7 +201,7 @@ function registerCodex(token) {
             args.push("--env", `TELIQUE_API_TOKEN=${token}`);
         }
         args.push("--", "npx", "-y", "telique-mcp");
-        execFileSync("codex", args, { stdio: "ignore" });
+        execFileSync(bin, args, { stdio: "ignore" });
         return true;
     }
     catch {
@@ -315,6 +318,25 @@ function commandExists(cmd) {
         return false;
     }
 }
+function findCodexBinary() {
+    // Codex Desktop ships its own codex binary inside the .app bundle, and both
+    // it and the standalone CLI read/write the same ~/.codex/config.toml — so
+    // either binary is sufficient to register an MCP server for both surfaces.
+    const desktopBin = process.platform === "darwin"
+        ? "/Applications/Codex.app/Contents/Resources/codex"
+        : null;
+    const desktopAvailable = desktopBin !== null && existsSync(desktopBin);
+    if (commandExists("codex")) {
+        return {
+            bin: "codex",
+            label: desktopAvailable ? "Codex (CLI + Desktop)" : "Codex CLI",
+        };
+    }
+    if (desktopAvailable && desktopBin) {
+        return { bin: desktopBin, label: "Codex Desktop" };
+    }
+    return null;
+}
 function loadExistingToken() {
     try {
         const raw = readFileSync(CONFIG_FILE, "utf-8");
@@ -334,12 +356,17 @@ function saveToken(token) {
     writeFileSync(CONFIG_FILE, JSON.stringify(existing, null, 2) + "\n");
 }
 async function validateToken(token) {
+    // Dip a documented, token-required endpoint. /health is an internal probe
+    // not in openapi.yaml and returns 403 from non-allowlisted IPs, which
+    // would falsely reject valid tokens during setup.
     try {
-        const response = await fetch(`${API_BASE_URL}/health`, {
-            headers: { "x-api-token": token },
-            signal: AbortSignal.timeout(10000),
+        const client = new TeliqueClient({
+            baseUrl: API_BASE_URL,
+            apiToken: token,
+            requestTimeoutMs: 10000,
         });
-        return response.ok;
+        const result = await client.get("/v1/telique/lerg/tables");
+        return (typeof result === "object" && result !== null && !("_error" in result));
     }
     catch {
         return false;

package/dist/tools/status.js

@@ -5,6 +5,8 @@ export function registerStatusTools(server, client) {
     server.tool("telique_status", "Returns the Telique MCP server version, authentication mode, and API connectivity status. Use this when asked about the server version or connection status.", {}, READ_ONLY_ANNOTATIONS, async () => {
         let apiReachable = false;
         try {
+            // Internal probe: /health is not in openapi.yaml and returns 403 from
+            // non-allowlisted IPs. Best-effort connectivity indicator only.
             const result = await client.get("/health");
             apiReachable =
                 typeof result === "object" &&

package/openapi.yaml

@@ -0,0 +1,882 @@
+openapi: 3.1.0
+info:
+  title: Telique Telecom API
+  version: 1.0.0
+  description: |
+    Unified telecom data API providing access to LRN (Local Routing Number) lookups,
+    CNAM (Caller Name) identification, LERG (Local Exchange Routing Guide) infrastructure data,
+    toll-free number routing via RouteLink, and GraphQL interfaces for advanced queries.
+
+    ## Authentication
+
+    All endpoints require an API token passed via the `x-api-token` header.
+    Anonymous access is available with a rate limit of 10 requests per minute.
+    Authenticated access provides higher rate limits based on your subscription.
+
+    Get your API token at [telique.ringer.tel](https://telique.ringer.tel).
+
+    ## MCP Server
+
+    For AI-assisted development, install the Telique MCP server:
+    ```
+    npm install -g telique-mcp
+    ```
+
+    ## Key Concepts
+
+    - **LERG** — Static telecom infrastructure reference (27 tables, updated monthly from iconectiv BIRRDS). Contains NPA-NXX assignments, switches, tandems, rate centers, carrier names.
+    - **LSMS** — Live NPAC porting data (refreshed within minutes). Contains phone number ownership (SPID), LRN assignments, porting state.
+    - **LRN** — Local Routing Number. Identifies the switch serving a ported phone number. Always dip the LRN before doing LERG lookups on a specific phone number.
+    - **RouteLink** — Toll-free number routing. CPR (Call Processing Records) are decision trees that determine how toll-free calls are routed.
+  contact:
+    name: Ringer Support
+    email: support@ringer.com
+    url: https://telique.ringer.tel
+  license:
+    name: Proprietary
+
+servers:
+  - url: https://api.telique.ringer.tel
+    description: Production
+
+security:
+  - apiToken: []
+
+tags:
+  - name: LRN
+    description: Local Routing Number lookups and LSMS relationship queries (live NPAC porting data)
+  - name: CNAM
+    description: Caller Name identification via TransUnion LIDB
+  - name: LERG
+    description: Local Exchange Routing Guide — static telecom infrastructure reference (27 tables)
+  - name: RouteLink
+    description: Toll-free number routing — CIC, ROR, and CPR lookups
+  - name: GraphQL
+    description: GraphQL interfaces for LSMS and LERG with advanced filtering and joins
+
+paths:
+  # ── LRN ──────────────────────────────────────────────────────────
+  /v1/telique/lrn/{phone_number}:
+    get:
+      operationId: lrnLookup
+      tags: [LRN]
+      summary: Look up LRN for a phone number
+      description: |
+        Returns the Local Routing Number (LRN), SPID (Service Provider ID), LNP type,
+        and activation timestamp. LRN identifies the switch that serves a ported phone number.
+        Queries live LSMS/NPAC porting data.
+      parameters:
+        - name: phone_number
+          in: path
+          required: true
+          description: 10-digit US phone number
+          schema:
+            type: string
+            pattern: '^\d{10}$'
+            example: '3036298301'
+      responses:
+        '200':
+          description: LRN lookup result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LrnLookupResponse'
+              example:
+                lrn: '7207081999'
+                spid: '6214'
+                lnp_type: '1'
+                activation_timestamp: '2019-03-15T00:00:00Z'
+        '404':
+          description: Phone number not found in LSMS
+        '429':
+          description: Rate limit exceeded
+
+  /v1/telique/lsms/list/{resource}:
+    get:
+      operationId: lrnRelationshipQuery
+      tags: [LRN]
+      summary: Query LSMS relationships
+      description: |
+        Find phone numbers by LRN or SPID, SPIDs by LRN or phone number, or LRNs by SPID
+        or phone number. Queries live NPAC porting data.
+      parameters:
+        - name: resource
+          in: path
+          required: true
+          description: The resource type to list
+          schema:
+            type: string
+            enum: [phone_number, spid, lrn]
+        - name: lrn
+          in: query
+          description: Filter by LRN (10-digit)
+          schema:
+            type: string
+        - name: spid
+          in: query
+          description: Filter by SPID (4-character)
+          schema:
+            type: string
+        - name: phone_number
+          in: query
+          description: Filter by phone number (10-digit)
+          schema:
+            type: string
+      responses:
+        '200':
+          description: List of matching resources
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                  count:
+                    type: integer
+
+  /v1/telique/dno/{phone_number}:
+    get:
+      operationId: dnoCheck
+      tags: [LRN]
+      summary: Check Do Not Originate (DNO) list
+      description: |
+        Check if a phone number is on the Do Not Originate list. DNO numbers should never
+        appear as a caller ID because they belong to entities that only receive calls
+        (e.g., IRS, major banks). A match indicates potential caller ID spoofing.
+        Supports prefix matching (3, 6, 7, or 10 digit patterns).
+      parameters:
+        - name: phone_number
+          in: path
+          required: true
+          description: 10-digit US phone number to check
+          schema:
+            type: string
+            pattern: '^\d{10}$'
+            example: '8002829500'
+      responses:
+        '200':
+          description: DNO check result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DnoCheckResponse'
+              example:
+                is_dno: true
+                matched_pattern: '8002829500'
+                source: 'FTC'
+
+  # ── CNAM ─────────────────────────────────────────────────────────
+  /v1/telique/cnam/{phone_number}:
+    get:
+      operationId: cnamLookup
+      tags: [CNAM]
+      summary: Look up Caller Name (CNAM)
+      description: |
+        Look up the Caller Name (CNAM) for a phone number via TransUnion LIDB.
+        Returns the calling name (up to 15 characters), status, and presentation indicator.
+        Results are cached server-side for 24 hours.
+      parameters:
+        - name: phone_number
+          in: path
+          required: true
+          description: 10-15 digit phone number
+          schema:
+            type: string
+            pattern: '^\d{10,15}$'
+            example: '3036298301'
+      responses:
+        '200':
+          description: CNAM lookup result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CnamLookupResponse'
+              example:
+                calling_name: 'SMITH JOHN'
+                calling_name_status: 'available'
+                presentation_indicator: 'allowed'
+
+  # ── LERG ─────────────────────────────────────────────────────────
+  /v1/telique/lerg/tables:
+    get:
+      operationId: lergListTables
+      tags: [LERG]
+      summary: List all LERG tables
+      description: |
+        Returns metadata for all 27 LERG tables. Key tables: lerg_1 (OCN/carrier directory),
+        lerg_6 (NPA-NXX block assignments), lerg_7 (switch details),
+        lerg_7_sha (switch homing arrangements/tandems), lerg_12 (LRN registry).
+      responses:
+        '200':
+          description: List of LERG tables with metadata
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/LergTableInfo'
+
+  /v1/telique/lerg/tables/{table_name}:
+    get:
+      operationId: lergTableInfo
+      tags: [LERG]
+      summary: Get LERG table schema
+      description: Returns detailed metadata and field schema for a specific LERG table.
+      parameters:
+        - name: table_name
+          in: path
+          required: true
+          description: "Table name (e.g. lerg_1, lerg_6, lerg_7_sha)"
+          schema:
+            type: string
+            example: lerg_6
+      responses:
+        '200':
+          description: Table schema and metadata
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LergTableInfo'
+        '404':
+          description: Table not found
+
+  /v1/telique/lerg/{table_name}/{fields}/{query}:
+    get:
+      operationId: lergQuery
+      tags: [LERG]
+      summary: Query a LERG table
+      description: |
+        Query any LERG table by field values. Common queries:
+        - Carrier by OCN: `lerg_1/ocn_num,ocn_name,ocn_state/ocn_num=9545`
+        - NPA-NXX info: `lerg_6/npa,nxx,loc_name,ocn,switch,lata/npa=303&nxx=629`
+        - Switch details: `lerg_7/switch,ocn,aocn/switch=DNVRCOMADS0`
+        - LRN registry: `lerg_12/lrn,lata,switch,ocn/lrn=7207081999`
+
+        Multiple filters are joined with `&` in the query path segment.
+      parameters:
+        - name: table_name
+          in: path
+          required: true
+          description: Table to query (e.g. lerg_1, lerg_6, lerg_7)
+          schema:
+            type: string
+        - name: fields
+          in: path
+          required: true
+          description: Comma-separated field names to return
+          schema:
+            type: string
+            example: 'npa,nxx,loc_name,ocn,switch,lata'
+        - name: query
+          in: path
+          required: true
+          description: "Filter in field=value format, multiple filters joined with & (URL-encoded as %26)"
+          schema:
+            type: string
+            example: 'npa=303%26nxx=629'
+        - name: limit
+          in: query
+          description: Max results (default 100, max 10000)
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 10000
+            default: 100
+        - name: offset
+          in: query
+          description: Pagination offset
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        '200':
+          description: Query results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LergQueryResponse'
+
+  /v1/telique/lerg/query:
+    post:
+      operationId: lergComplexQuery
+      tags: [LERG]
+      summary: Complex LERG query with JOINs
+      description: |
+        Execute a complex LERG query with JOINs across multiple tables. Supports filter
+        operators: eq, ne, gt, gte, lt, lte, like, in, isnull, isnotnull.
+
+        Use this when you need to combine data from different LERG tables, such as joining
+        NPA-NXX data (lerg_6) with carrier info (lerg_1) via OCN.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LergComplexQueryRequest'
+            example:
+              table: lerg_6
+              fields: ['npa', 'nxx', 'ocn', 'loc_name']
+              filters:
+                - field: npa
+                  operator: eq
+                  value: '303'
+                - field: nxx
+                  operator: eq
+                  value: '629'
+              join:
+                table: lerg_1
+                on:
+                  - left_field: ocn
+                    right_field: ocn_num
+                fields: ['ocn_name', 'ocn_state']
+                join_type: inner
+              limit: 100
+              offset: 0
+      responses:
+        '200':
+          description: Query results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LergQueryResponse'
+
+  /v1/telique/lerg/tandem:
+    get:
+      operationId: lergTandem
+      tags: [LERG]
+      summary: Look up tandem routing
+      description: |
+        Look up tandem routing information via SQL JOINs across lerg_6, lerg_7_sha, and lerg_1.
+        Query by NPA+NXX, switch CLLI, tandem CLLI, or carrier name pattern.
+        Returns tandem switch, OCN, LATA, and routing path.
+      parameters:
+        - name: npa
+          in: query
+          description: 3-digit area code (use with nxx)
+          schema:
+            type: string
+            pattern: '^\d{3}$'
+        - name: nxx
+          in: query
+          description: 3-digit exchange code (use with npa)
+          schema:
+            type: string
+            pattern: '^\d{3}$'
+        - name: switch
+          in: query
+          description: Switch CLLI code (e.g. DNVRCOMADS0)
+          schema:
+            type: string
+        - name: tandem
+          in: query
+          description: Tandem CLLI code — reverse lookup to find what subtends it
+          schema:
+            type: string
+        - name: name
+          in: query
+          description: "Carrier name pattern with % wildcard (e.g. %VERIZON%). Case-insensitive."
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: Max results (default 100, max 10000)
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 10000
+            default: 100
+        - name: offset
+          in: query
+          description: Pagination offset
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        '200':
+          description: Tandem routing results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LergQueryResponse'
+
+  # ── RouteLink ────────────────────────────────────────────────────
+  /v1/telique/ror/{crn}:
+    get:
+      operationId: routelinkRorLookup
+      tags: [RouteLink]
+      summary: Look up Responsible Organization for a toll-free number
+      description: |
+        Resolves a toll-free number (CRN) to its Responsible Organization (ROR).
+        The ROR is the entity responsible for managing the toll-free number's routing.
+      parameters:
+        - name: crn
+          in: path
+          required: true
+          description: 10-digit toll-free number (CRN)
+          schema:
+            type: string
+            pattern: '^\d{10}$'
+            example: '8005551234'
+      responses:
+        '200':
+          description: ROR lookup result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RorLookupResponse'
+              example:
+                crn: '8005551234'
+                ror: 'ATX01'
+
+  /v1/telique/{lookup_type}/{crn}/{ani}/{lata}:
+    get:
+      operationId: routelinkCicLookup
+      tags: [RouteLink]
+      summary: Look up toll-free carrier routing
+      description: |
+        Resolves a toll-free number (CRN) to its carrier (CIC) by interpreting the CPR
+        decision tree using the caller's ANI and LATA. Use `cicror` to get both CIC and ROR
+        in a single request.
+      parameters:
+        - name: lookup_type
+          in: path
+          required: true
+          description: "Type of lookup: cic (carrier only) or cicror (carrier + responsible org)"
+          schema:
+            type: string
+            enum: [cic, cicror]
+        - name: crn
+          in: path
+          required: true
+          description: 10-digit toll-free number (CRN)
+          schema:
+            type: string
+            pattern: '^\d{10}$'
+            example: '8005551234'
+        - name: ani
+          in: path
+          required: true
+          description: 10-digit calling party number
+          schema:
+            type: string
+            pattern: '^\d{10}$'
+            example: '3035551234'
+        - name: lata
+          in: path
+          required: true
+          description: 3-digit LATA code
+          schema:
+            type: string
+            pattern: '^\d{3}$'
+            example: '656'
+      responses:
+        '200':
+          description: Carrier routing result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CicLookupResponse'
+              example:
+                crn: '8005551234'
+                cic: '0288'
+                ror: 'ATX01'
+
+  /v1/telique/ror/{ror}/{resource_type}:
+    get:
+      operationId: routelinkRorQuery
+      tags: [RouteLink]
+      summary: List toll-free numbers or CPRs by ROR
+      description: |
+        List toll-free numbers (TFNs) or Call Processing Records (CPRs) associated with
+        a Responsible Organization. Use this to explore which toll-free numbers a specific
+        organization manages.
+      parameters:
+        - name: ror
+          in: path
+          required: true
+          description: 1-5 character alphanumeric ROR code
+          schema:
+            type: string
+            pattern: '^[A-Za-z0-9]{1,5}$'
+            example: 'ATX01'
+        - name: resource_type
+          in: path
+          required: true
+          description: Whether to list TFNs or CPRs
+          schema:
+            type: string
+            enum: [tfns, cprs]
+        - name: limit
+          in: query
+          description: Max results (default 100, max 10000)
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 10000
+            default: 100
+        - name: offset
+          in: query
+          description: Pagination offset
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        '200':
+          description: List of TFNs or CPRs
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                  count:
+                    type: integer
+
+  /v1/telique/cpr/{crn}:
+    get:
+      operationId: routelinkCpr
+      tags: [RouteLink]
+      summary: Retrieve Call Processing Record (CPR)
+      description: |
+        Retrieve the full Call Processing Record for a toll-free number. A CPR is a routing
+        decision tree that determines how calls are routed based on criteria like LATA, NPA,
+        NXX, ANI, DAY_OF_WEEK, TIME_OF_DAY, PERCENT, STATE, etc.
+
+        Returns the CPR structure, SHA1 hash, ROR, and optionally expanded template references.
+      parameters:
+        - name: crn
+          in: path
+          required: true
+          description: 1-10 digit CRN (toll-free number or template CRN). Shorter values are zero-padded to 10 digits.
+          schema:
+            type: string
+            pattern: '^\d{1,10}$'
+            example: '8005551234'
+        - name: expand
+          in: query
+          description: Recursively resolve and inline template decision trees (default true)
+          schema:
+            type: boolean
+            default: true
+      responses:
+        '200':
+          description: CPR decision tree
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CprResponse'
+
+  # ── GraphQL ──────────────────────────────────────────────────────
+  /v1/telique/lsms/gql:
+    post:
+      operationId: graphqlLsms
+      tags: [GraphQL]
+      summary: LSMS GraphQL endpoint
+      description: |
+        Execute GraphQL queries against the LSMS (live NPAC porting data).
+
+        Key queries: `subscriptionVersion(phoneNumber)`, `subscriptionVersionsByLrn(lrn, limit)`,
+        `subscriptionVersionsBySpid(spid, limit)`, `numberBlock(npanxxx)`, `serviceProviders(limit)`,
+        `locationRoutingNumber(lrn)`, `npanxxBySpid(spid, limit)`, `lsmsStats`.
+
+        Relationships: `subscriptionVersion` → `serviceProvider`, → `lrnMetadata`.
+        Safety limits: max 1000 results, 10s timeout. Large tables (subscriptionVersions 514M rows) MUST be filtered.
+
+        **Important:** LSMS uses named query parameters, NOT FilterInput syntax.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GraphQLRequest'
+            example:
+              query: '{ subscriptionVersion(phoneNumber: "3036298301") { phoneNumber lrn spid lnpType activationTimestamp } }'
+      responses:
+        '200':
+          description: GraphQL response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GraphQLResponse'
+
+  /v1/telique/lerg/gql:
+    post:
+      operationId: graphqlLerg
+      tags: [GraphQL]
+      summary: LERG GraphQL endpoint
+      description: |
+        Execute GraphQL queries against the LERG (static telecom reference data).
+
+        27 tables with camelCase names (lerg1, lerg6, lerg7Sha). Return fields MUST be camelCase
+        (ocnName not ocn_name). Uses FilterInput with operators: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, ISNULL, ISNOTNULL.
+
+        LIKE patterns MUST be UPPERCASE. Filter syntax: `{ field: "ocnName", op: LIKE, value: "%VERIZON%" }`.
+        IN uses `values` (plural). Relationships: `lerg6` → `carrier`, → `switchInfo`, → `homingArrangements`.
+        Also supports `dynamicJoin` for arbitrary cross-table SQL joins.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GraphQLRequest'
+            example:
+              query: '{ lerg6(filters: [{ field: "npa", op: EQ, value: "303" }, { field: "nxx", op: EQ, value: "629" }], limit: 5) { npa nxx locName ocn switchClli lata carrier { ocnName } } }'
+      responses:
+        '200':
+          description: GraphQL response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GraphQLResponse'
+
+components:
+  securitySchemes:
+    apiToken:
+      type: apiKey
+      in: header
+      name: x-api-token
+      description: |
+        API token for authentication. Get yours at [telique.ringer.tel](https://telique.ringer.tel).
+        Anonymous access (no token) is rate-limited to 10 requests per minute.
+
+  schemas:
+    LrnLookupResponse:
+      type: object
+      properties:
+        lrn:
+          type: string
+          description: 10-digit Local Routing Number
+          example: '7207081999'
+        spid:
+          type: string
+          description: 4-character Service Provider ID
+          example: '6214'
+        lnp_type:
+          type: string
+          description: Local Number Portability type
+          example: '1'
+        activation_timestamp:
+          type: string
+          format: date-time
+          description: When the port was activated
+
+    DnoCheckResponse:
+      type: object
+      properties:
+        is_dno:
+          type: boolean
+          description: Whether the number is on the DNO list
+        matched_pattern:
+          type: string
+          description: The DNO pattern that matched (3, 6, 7, or 10 digits)
+        source:
+          type: string
+          description: Source of the DNO listing
+
+    CnamLookupResponse:
+      type: object
+      properties:
+        calling_name:
+          type: string
+          description: Caller name (up to 15 characters)
+          example: 'SMITH JOHN'
+        calling_name_status:
+          type: string
+          enum: [available, unavailable]
+          description: Whether a name was found
+        presentation_indicator:
+          type: string
+          enum: [allowed, restricted]
+          description: Whether the name may be displayed
+
+    LergTableInfo:
+      type: object
+      properties:
+        table_name:
+          type: string
+          example: lerg_6
+        description:
+          type: string
+        row_count:
+          type: integer
+        fields:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+              type:
+                type: string
+              description:
+                type: string
+
+    LergQueryResponse:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            type: object
+          description: Array of result rows
+        count:
+          type: integer
+          description: Total matching rows (may exceed returned rows)
+        limit:
+          type: integer
+        offset:
+          type: integer
+
+    LergComplexQueryRequest:
+      type: object
+      required: [table, filters]
+      properties:
+        table:
+          type: string
+          description: Primary table name (e.g. lerg_6)
+        fields:
+          type: array
+          items:
+            type: string
+          description: Fields to return from primary table
+        filters:
+          type: array
+          items:
+            $ref: '#/components/schemas/LergFilter'
+          description: Filter conditions
+        join:
+          $ref: '#/components/schemas/LergJoin'
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 10000
+          default: 100
+        offset:
+          type: integer
+          minimum: 0
+          default: 0
+
+    LergFilter:
+      type: object
+      required: [field, operator, value]
+      properties:
+        field:
+          type: string
+        operator:
+          type: string
+          enum: [eq, ne, gt, gte, lt, lte, like, in, isnull, isnotnull]
+        value:
+          oneOf:
+            - type: string
+            - type: number
+
+    LergJoin:
+      type: object
+      required: [table, on]
+      properties:
+        table:
+          type: string
+          description: Table to join (e.g. lerg_1)
+        on:
+          type: array
+          items:
+            type: object
+            required: [left_field, right_field]
+            properties:
+              left_field:
+                type: string
+              right_field:
+                type: string
+          description: Join conditions
+        fields:
+          type: array
+          items:
+            type: string
+          description: Fields to return from joined table
+        join_type:
+          type: string
+          enum: [inner, left]
+          default: inner
+
+    RorLookupResponse:
+      type: object
+      properties:
+        crn:
+          type: string
+          description: The toll-free number queried
+        ror:
+          type: string
+          description: 1-5 character Responsible Organization code
+
+    CicLookupResponse:
+      type: object
+      properties:
+        crn:
+          type: string
+          description: The toll-free number queried
+        cic:
+          type: string
+          description: 4-digit Carrier Identification Code
+        ror:
+          type: string
+          description: Responsible Organization code (only for cicror lookups)
+
+    CprResponse:
+      type: object
+      properties:
+        crn:
+          type: string
+        ror:
+          type: string
+        sha1:
+          type: string
+          description: SHA1 hash of the CPR
+        cpr:
+          type: object
+          description: |
+            CPR decision tree structure. Nodes contain a `type` (LATA, NPA, NXX, ANI,
+            DAY_OF_WEEK, TIME_OF_DAY, PERCENT, STATE, etc.) and either `branches`
+            (for decision nodes) or a `cic` (for terminal/carrier nodes).
+          properties:
+            type:
+              type: string
+            branches:
+              type: array
+              items:
+                type: object
+
+    GraphQLRequest:
+      type: object
+      required: [query]
+      properties:
+        query:
+          type: string
+          description: GraphQL query string
+        variables:
+          type: object
+          additionalProperties: true
+          description: Optional GraphQL variables
+
+    GraphQLResponse:
+      type: object
+      properties:
+        data:
+          type: object
+          description: Query result data
+        errors:
+          type: array
+          items:
+            type: object
+            properties:
+              message:
+                type: string
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telique-mcp",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "description": "MCP server for Telique telecom APIs (RouteLink, LRN, CNAM, LERG)",
   "type": "module",
   "main": "dist/index.js",
@@ -19,13 +19,15 @@
   },
   "files": [
     "dist",
-    "postinstall.js"
+    "postinstall.js",
+    "openapi.yaml"
   ],
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "postinstall": "node postinstall.js",
+    "validate:openapi": "tsx scripts/validate-openapi.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -42,7 +44,7 @@
     "type": "git",
     "url": "git+https://github.com/Ringer/telique-mcp.git"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0"