@sthan/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @sthan/mcp-server
+
+MCP server for [sthan.io](https://sthan.io) — US address verification, parsing, autocomplete, geocoding, and IP geolocation.
+
+Works with Claude Code, Cursor, VS Code, Windsurf, and any MCP-compatible client.
+
+## Setup
+
+### 1. Get an API key
+
+Sign up at [sthan.io](https://sthan.io) (free tier, no credit card required). Create an API key from your [dashboard](https://sthan.io/dashboard).
+
+### 2. Configure your client
+
+**Claude Code** (`~/.claude/mcp.json` or project `.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "sthan": {
+      "command": "npx",
+      "args": ["@sthan/mcp-server"],
+      "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "sthan": {
+      "command": "npx",
+      "args": ["@sthan/mcp-server"],
+      "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
+    }
+  }
+}
+```
+
+**VS Code** (`settings.json`):
+
+```json
+{
+  "mcp.servers": {
+    "sthan": {
+      "command": "npx",
+      "args": ["@sthan/mcp-server"],
+      "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `sthan_verify_address` | Verify a US address for deliverability. Returns DPV confirmation, ZIP+4, carrier route. |
+| `sthan_parse_address` | Parse freeform address text into structured components (street, city, state, zip, unit). |
+| `sthan_autocomplete_address` | Get address suggestions from partial input. Sub-100ms response time. |
+| `sthan_autocomplete_city` | Get US city suggestions from partial input. |
+| `sthan_autocomplete_zipcode` | Get US ZIP code suggestions from partial input. |
+| `sthan_geocode` | Convert a US address to latitude/longitude coordinates. |
+| `sthan_reverse_geocode` | Convert coordinates to the nearest US street address. |
+| `sthan_ip_geolocation` | Look up geographic location of an IPv4 or IPv6 address. |
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `STHAN_API_KEY` | Yes | Your sthan.io API key (`sthan_test_*` or `sthan_live_*`) |
+| `STHAN_API_URL` | No | Override base URL (default: `https://api.sthan.io`) |
+
+## Examples
+
+Once configured, just ask your AI assistant naturally:
+
+- "Is 123 Main St, New York, NY 10001 a real address?"
+- "Parse this address: apt 2b 500 broadway new york ny"
+- "What are the coordinates for the White House?"
+- "What address is at 40.7128, -74.0060?"
+- "Where is IP 8.8.8.8 located?"
+
+## Links
+
+- [API docs](https://sthan.io/docs)
+- [Pricing](https://sthan.io/pricing/united-states)
+- [OpenAPI spec](https://api.sthan.io/openapi.json)
+- [AI reference](https://api.sthan.io/llms-full.txt)
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const core_1 = require("@sthan/core");
+const zod_1 = require("zod");
+const apiKey = process.env.STHAN_API_KEY;
+if (!apiKey) {
+    console.error("Error: STHAN_API_KEY environment variable is required.\n" +
+        "Get your API key at https://sthan.io/dashboard\n" +
+        "Set it: export STHAN_API_KEY=sthan_test_your_key_here");
+    process.exit(1);
+}
+const client = new core_1.SthanClient({
+    apiKey,
+    baseUrl: process.env.STHAN_API_URL,
+});
+const server = new mcp_js_1.McpServer({
+    name: "sthan",
+    version: "0.1.0",
+});
+// --- Tool 1: Verify US Address ---
+server.tool("sthan_verify_address", "Verify if a US address is real and deliverable. Returns standardized format, ZIP+4, delivery point validation (DPV), and whether it's residential or commercial. Use when someone asks 'is this address real?', 'can mail be delivered here?', or 'verify this address'.", {
+    address: zod_1.z
+        .string()
+        .describe("Full or partial US address in any format. Examples: '123 Main St, New York, NY 10001', '123 main st nyc', '1600 Pennsylvania Ave Washington DC'"),
+}, async ({ address }) => {
+    try {
+        const response = await client.verifyAddress(address);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Tool 2: Parse US Address ---
+server.tool("sthan_parse_address", "Parse a freeform US address string into structured components (street number, name, type, direction, unit, city, state, zip). Use when someone has messy or unstructured address text and needs it broken into parts.", {
+    address: zod_1.z
+        .string()
+        .describe("Raw address text to parse. Freeform input, abbreviations OK. Example: 'apt 2b 500 broadway new york ny'"),
+}, async ({ address }) => {
+    try {
+        const response = await client.parseAddress(address);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Tool 3: Autocomplete US Address ---
+server.tool("sthan_autocomplete_address", "Get address suggestions from partial input. Sub-100ms response time. Returns array of complete US address strings. Use for type-ahead address completion.", {
+    text: zod_1.z
+        .string()
+        .describe("Partial address text (3+ characters recommended). Example: '123 Main'"),
+}, async ({ text }) => {
+    try {
+        const response = await client.autocompleteAddress(text);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Tool 4: Autocomplete US City ---
+server.tool("sthan_autocomplete_city", "Get US city name suggestions from partial input. Returns matching cities with state.", {
+    text: zod_1.z.string().describe("Partial city name. Example: 'San Fr'"),
+    display_type: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe("0 = City, StateCode (e.g. 'San Francisco, CA'). 1 = City, State (e.g. 'San Francisco, California')"),
+}, async ({ text, display_type }) => {
+    try {
+        const response = await client.autocompleteCity(text, display_type);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Tool 5: Autocomplete US ZIP Code ---
+server.tool("sthan_autocomplete_zipcode", "Get US ZIP code suggestions from partial input.", {
+    text: zod_1.z.string().describe("Partial ZIP code. Example: '9021'"),
+    display_type: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .max(3)
+        .default(0)
+        .describe("0 = Zip,StateCode. 1 = Zip,State. 2 = Zip-Zip4,StateCode. 3 = Zip-Zip4,State"),
+}, async ({ text, display_type }) => {
+    try {
+        const response = await client.autocompleteZipCode(text, display_type);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Tool 6: Forward Geocode US Address ---
+server.tool("sthan_geocode", "Convert a US address to latitude/longitude coordinates. Returns accuracy type (rooftop, interpolated, centroid, approximate) and confidence score. Use when someone needs coordinates for an address.", {
+    address: zod_1.z
+        .string()
+        .describe("US address to geocode (freeform text). Example: '1600 Pennsylvania Ave, Washington DC'"),
+}, async ({ address }) => {
+    try {
+        const response = await client.geocodeAddress(address);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Tool 7: Reverse Geocode ---
+server.tool("sthan_reverse_geocode", "Convert latitude/longitude coordinates to the nearest US street address. Returns the address with distance in meters from input coordinates. Use when someone has coordinates and wants the address.", {
+    latitude: zod_1.z.number().min(-90).max(90).describe("Latitude coordinate"),
+    longitude: zod_1.z.number().min(-180).max(180).describe("Longitude coordinate"),
+}, async ({ latitude, longitude }) => {
+    try {
+        const response = await client.reverseGeocode(latitude, longitude);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Tool 8: IP Geolocation ---
+server.tool("sthan_ip_geolocation", "Look up the geographic location of an IPv4 or IPv6 address. Returns country, region, city, coordinates, timezone, and postal code. Use when someone wants to know where an IP address is located.", {
+    ip: zod_1.z
+        .string()
+        .describe("IPv4 (e.g. '8.8.8.8') or IPv6 (e.g. '2001:4860:4860::8888') address"),
+}, async ({ ip }) => {
+    try {
+        const response = await client.ipGeolocation(ip);
+        return {
+            content: [{ type: "text", text: JSON.stringify(response.Result, null, 2) }],
+        };
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// --- Error helper ---
+function errorResult(e) {
+    if (e instanceof core_1.SthanApiError) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error (${e.statusCode}): ${e.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+        content: [{ type: "text", text: `Error: ${msg}` }],
+        isError: true,
+    };
+}
+// --- Start server ---
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error("Fatal:", e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@sthan/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for sthan.io — US address verification, parsing, autocomplete, geocoding, and IP geolocation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "sthan-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "address-verification",
+    "address-parser",
+    "address-autocomplete",
+    "geocoding",
+    "reverse-geocoding",
+    "ip-geolocation",
+    "sthan",
+    "claude",
+    "cursor",
+    "vscode",
+    "ai",
+    "ai-tools"
+  ],
+  "author": "sthan.io",
+  "license": "MIT",
+  "homepage": "https://sthan.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nishka-llc/sthan"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@sthan/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}