@riv-lc/areacode-mcp 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,77 @@
+# areacode-mcp
+
+**North American (NANP) area-code & phone-number intelligence for AI agents.**
+
+An [MCP](https://modelcontextprotocol.io) server that gives Claude, Cursor, and
+other agents a small, trusted reference for US & Canada phone numbering — area
+codes, NANP validation, local time, city/state coverage, overlays, and
+scam/spoofing context. Backed by [**areacode.fyi**](https://areacode.fyi), which
+publishes directly from the official NANPA numbering database. Every result
+includes a canonical `areacode.fyi` URL and the source date.
+
+> **Scope.** This is area-code-level **reference and education** — not a
+> carrier/identity API. It does **not** return a caller's identity, exact
+> location, or live/ported carrier, and caller ID can be spoofed, so a number's
+> area code never proves who is calling. For caller identity you need a
+> carrier-grade (LRN/HLR) provider.
+
+## Install
+
+Run it with `npx` (no install needed) — add it to your client's MCP config.
+
+**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "areacode": {
+      "command": "npx",
+      "args": ["-y", "@riv-lc/areacode-mcp"]
+    }
+  }
+}
+```
+
+That's it — restart your client and the tools below are available.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `lookup_area_code` | Country, state/province, cities, time zone, current local time, overlays, nearby codes |
+| `lookup_phone_number` | Parse/validate a NANP number → area code, region, local time, E.164 |
+| `area_codes_for_city` | Area codes serving a city (optionally disambiguated by state) |
+| `area_codes_for_state` | Every area code in a US state or Canadian province |
+| `is_scam_area_code` | Whether an area code is associated with scams + spoofing context |
+| `check_number_reputation` | Unverified, crowd-sourced community signal (low / mid / high) for a number |
+| `explain_area_code_topic` | Source-backed explainers: neighbor spoofing, overlays vs splits, toll-free, area-code-vs-country-code, temporary numbers |
+
+## Example prompts
+
+- *"A lead entered phone number +1 702-555-0199. Where are they likely located and what time is it there?"*
+- *"I got a call from 469 — is that area code suspicious?"*
+- *"Which area codes cover Las Vegas?"*
+- *"Normalize this list of US/Canada numbers and flag any that are invalid or toll-free."*
+- *"Explain neighbor spoofing for a help-center article."*
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `AREACODE_API_BASE` | `https://areacode.fyi` | Point at a different host (e.g. a self-hosted or staging API) |
+
+## Data & sourcing
+
+Tools call the public `https://areacode.fyi/api/v1` JSON API, which reads the
+same dataset the site renders — sourced from the official **North American
+Numbering Plan Administrator (NANPA)** database and refreshed monthly. Each
+response carries `source`, `canonical_url`, and `data_date` so answers can cite
+where the data came from.
+
+The `check_number_reputation` signal is **unverified and crowd-sourced**
+(`low` = people looked the number up; `mid`/`high` = it has user reports). It is
+never proof that a specific number is fraudulent.
+
+## License
+
+MIT © Reindex Ventures. Built for [areacode.fyi](https://areacode.fyi).

package/dist/index.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * areacode-mcp — North American (NANP) area-code & phone-number intelligence
+ * for AI agents. A thin MCP server over the areacode.fyi public API
+ * (https://areacode.fyi/api/v1). Every result carries a canonical areacode.fyi
+ * URL + the NANPA source date.
+ *
+ * Scope: area-code-level reference + education. It does NOT return a caller's
+ * identity, exact location, or live/ported carrier — and caller ID can be
+ * spoofed, so a number's area code never proves who is calling.
+ *
+ * Config: set AREACODE_API_BASE to point at a different host (default
+ * https://areacode.fyi).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_BASE = (process.env.AREACODE_API_BASE || "https://areacode.fyi").replace(/\/+$/, "") + "/api/v1";
+const enc = encodeURIComponent;
+/** Fetch an API path and return it as an MCP tool result (raw JSON text). */
+async function api(path) {
+    try {
+        const res = await fetch(API_BASE + path, {
+            headers: { accept: "application/json", "user-agent": "areacode-mcp" },
+        });
+        const text = await res.text();
+        return { content: [{ type: "text", text }], isError: !res.ok };
+    }
+    catch (e) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: `Request to ${API_BASE} failed: ${e.message}` }),
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+const server = new McpServer({ name: "areacode-mcp", version: "0.1.0" });
+server.registerTool("lookup_area_code", {
+    title: "Look up an area code",
+    description: "Look up a North American (NANP) area code: country, state/province, principal city and served cities, time zone, current local time, 10-digit-dialing flag, overlay codes, and nearby codes. Returns a canonical areacode.fyi URL and the NANPA source date.",
+    inputSchema: { code: z.string().describe('A 3-digit area code, e.g. "702".') },
+}, ({ code }) => api(`/area-code/${enc(code)}`));
+server.registerTool("lookup_phone_number", {
+    title: "Look up a phone number",
+    description: "Parse and validate a US/Canada (NANP) phone number. Returns whether the format is valid, the E.164 form, the area code, the likely region and time zone, and the current local time there. Area-code level only — NOT the caller's identity, exact location, or live carrier; caller ID can be spoofed.",
+    inputSchema: { number: z.string().describe('A phone number in any format, e.g. "+1 702-555-0199".') },
+}, ({ number }) => api(`/phone/${enc(number)}`));
+server.registerTool("area_codes_for_city", {
+    title: "Area codes for a city",
+    description: "List the area codes that serve a US or Canadian city. Optionally pass a state/province to disambiguate cities that share a name.",
+    inputSchema: {
+        city: z.string().describe('City name, e.g. "Las Vegas".'),
+        state: z
+            .string()
+            .optional()
+            .describe('Optional state/province name or 2-letter code to disambiguate, e.g. "NV".'),
+    },
+}, ({ city, state }) => api(`/area-codes?city=${enc(city)}${state ? `&state=${enc(state)}` : ""}`));
+server.registerTool("area_codes_for_state", {
+    title: "Area codes for a state/province",
+    description: "List every area code in a US state or Canadian province.",
+    inputSchema: {
+        state: z.string().describe('State/province name or 2-letter code, e.g. "Nevada" or "ON".'),
+    },
+}, ({ state }) => api(`/area-codes?state=${enc(state)}`));
+server.registerTool("is_scam_area_code", {
+    title: "Is an area code a scam?",
+    description: "Explain whether an area code is associated with scams. An area code is never a scam by itself; this returns that context plus spoofing notes — caller ID can be faked, so judge calls by what they ask for, not the area code.",
+    inputSchema: { code: z.string().describe('A 3-digit area code, e.g. "702".') },
+}, ({ code }) => api(`/scam/${enc(code)}`));
+server.registerTool("check_number_reputation", {
+    title: "Check a number's community reputation",
+    description: "Return the UNVERIFIED, crowd-sourced community signal for a US/Canada number from areacode.fyi: 'low' (people have looked it up), 'mid'/'high' (it has user reports). Caller ID can be spoofed — this is never proof a specific number is fraudulent.",
+    inputSchema: { number: z.string().describe('A US/Canada phone number, e.g. "702-555-0199".') },
+}, ({ number }) => api(`/reputation/${enc(number)}`));
+server.registerTool("explain_area_code_topic", {
+    title: "Explain a phone / area-code topic",
+    description: "Source-backed explanation of a phone-numbering topic, suitable for answering end users.",
+    inputSchema: {
+        topic: z
+            .enum([
+            "neighbor_spoofing",
+            "overlays",
+            "toll_free",
+            "country_code_vs_area_code",
+            "temporary_phone_numbers",
+        ])
+            .describe("The topic to explain."),
+    },
+}, ({ topic }) => api(`/explain/${enc(topic)}`));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@riv-lc/areacode-mcp",
+  "version": "0.1.0",
+  "description": "North American (NANP) area-code & phone-number intelligence for AI agents — an MCP server backed by areacode.fyi.",
+  "type": "module",
+  "bin": {
+    "areacode-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "area-code",
+    "nanp",
+    "phone-number",
+    "telephony",
+    "claude",
+    "ai-agents",
+    "areacode.fyi"
+  ],
+  "license": "MIT",
+  "author": "Reindex Ventures",
+  "homepage": "https://areacode.fyi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/riv-lc/areacode-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/riv-lc/areacode-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3"
+  }
+}