@sthan/mcp-server 0.1.2 → 0.1.4

package/README.md

@@ -1,96 +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
+# @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.js

@@ -17,15 +17,32 @@ function getClient() {
         baseUrl: process.env.STHAN_API_URL,
     });
 }
+// Every tool is a read-only lookup against the sthan.io API: no state is
+// changed, repeating a call with the same input returns the same result, and
+// it reaches an external service (the open world of US addresses).
+const READ_ONLY_HINTS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
 const server = new mcp_js_1.McpServer({
     name: "sthan",
-    version: "0.1.2",
+    version: "0.1.4",
 });
 // --- 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'"),
+server.registerTool("sthan_verify_address", {
+    title: "Verify US Address",
+    description: "Verify whether a US street address is real and deliverable. Returns the standardized address, ZIP+4, county, a deliverability status, and the dpvConfirmation code (Y = deliverable; N = not found or undeliverable; S = address found but the apartment/unit is missing or unconfirmed; blank = unknown). " +
+        "Use to confirm a US mailing address, clean address data, or check an address before shipping. " +
+        "Do not use for non-US addresses, to get map coordinates (use sthan_geocode), or to only split an address into fields without checking it (use sthan_parse_address). " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message, for example an invalid API key, an exceeded rate limit, or an address that could not be found.",
+    inputSchema: {
+        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'"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ address }) => {
     try {
         const response = await getClient().verifyAddress(address);
@@ -38,10 +55,18 @@ server.tool("sthan_verify_address", "Verify if a US address is real and delivera
     }
 });
 // --- 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'"),
+server.registerTool("sthan_parse_address", {
+    title: "Parse US Address",
+    description: "Break a freeform US address string into structured components: address number, street name, pre/post directionals, street type, unit type and number, city, state, ZIP, and ZIP+4. " +
+        "Use when you have messy or unstructured US address text and need the individual fields. " +
+        "This parses and standardizes only; it does not confirm the address is deliverable (use sthan_verify_address) and does not return coordinates (use sthan_geocode). " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message, for example an invalid API key or an exceeded rate limit.",
+    inputSchema: {
+        address: zod_1.z
+            .string()
+            .describe("Raw address text to parse. Freeform input, abbreviations OK. Example: 'apt 2b 500 broadway new york ny'"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ address }) => {
     try {
         const response = await getClient().parseAddress(address);
@@ -54,10 +79,18 @@ server.tool("sthan_parse_address", "Parse a freeform US address string into stru
     }
 });
 // --- 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'"),
+server.registerTool("sthan_autocomplete_address", {
+    title: "Autocomplete US Address",
+    description: "Return a list of complete US street-address suggestions for partial input, intended for type-ahead / autocomplete fields. " +
+        "Use while a user is typing an address and you want to offer full matches. " +
+        "For city-only suggestions use sthan_autocomplete_city; for ZIP-only suggestions use sthan_autocomplete_zipcode; to validate a finished address use sthan_verify_address. " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message.",
+    inputSchema: {
+        text: zod_1.z
+            .string()
+            .describe("Partial address text (3+ characters recommended). Example: '123 Main'"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ text }) => {
     try {
         const response = await getClient().autocompleteAddress(text);
@@ -70,15 +103,23 @@ server.tool("sthan_autocomplete_address", "Get address suggestions from partial
     }
 });
 // --- 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')"),
+server.registerTool("sthan_autocomplete_city", {
+    title: "Autocomplete US City",
+    description: "Return a list of US city suggestions (with state) for partial input. " +
+        "Use for city-field type-ahead, or to resolve a partial city name to its full name and state. " +
+        "For full street-address suggestions use sthan_autocomplete_address; for ZIP codes use sthan_autocomplete_zipcode. " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message.",
+    inputSchema: {
+        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')"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ text, display_type }) => {
     try {
         const response = await getClient().autocompleteCity(text, display_type);
@@ -91,15 +132,23 @@ server.tool("sthan_autocomplete_city", "Get US city name suggestions from partia
     }
 });
 // --- 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"),
+server.registerTool("sthan_autocomplete_zipcode", {
+    title: "Autocomplete US ZIP Code",
+    description: "Return a list of US ZIP code suggestions for partial input, each with state (and optionally ZIP+4). " +
+        "Use for ZIP-field type-ahead or to expand a partial ZIP. " +
+        "For city suggestions use sthan_autocomplete_city; for full addresses use sthan_autocomplete_address. " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message.",
+    inputSchema: {
+        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"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ text, display_type }) => {
     try {
         const response = await getClient().autocompleteZipCode(text, display_type);
@@ -112,10 +161,18 @@ server.tool("sthan_autocomplete_zipcode", "Get US ZIP code suggestions from part
     }
 });
 // --- 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'"),
+server.registerTool("sthan_geocode", {
+    title: "Geocode US Address",
+    description: "Convert a US address to latitude/longitude coordinates. Returns the coordinates, a formatted address, an accuracy type (rooftop, interpolated, centroid, or approximate), and a confidence score. " +
+        "Use when you need map coordinates for an address. " +
+        "To go the other way (coordinates to address) use sthan_reverse_geocode; to check deliverability rather than location use sthan_verify_address. " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message, for example an address that could not be located.",
+    inputSchema: {
+        address: zod_1.z
+            .string()
+            .describe("US address to geocode (freeform text). Example: '1600 Pennsylvania Ave, Washington DC'"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ address }) => {
     try {
         const response = await getClient().geocodeAddress(address);
@@ -128,9 +185,17 @@ server.tool("sthan_geocode", "Convert a US address to latitude/longitude coordin
     }
 });
 // --- 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"),
+server.registerTool("sthan_reverse_geocode", {
+    title: "Reverse Geocode Coordinates",
+    description: "Convert latitude/longitude coordinates to the nearest US street address. Returns the address, the distance in meters from the input point, an accuracy type, and a confidence score. " +
+        "Use when you have coordinates and need the closest address. US coverage only. " +
+        "To go the other way (address to coordinates) use sthan_geocode. " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message.",
+    inputSchema: {
+        latitude: zod_1.z.number().min(-90).max(90).describe("Latitude coordinate"),
+        longitude: zod_1.z.number().min(-180).max(180).describe("Longitude coordinate"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ latitude, longitude }) => {
     try {
         const response = await getClient().reverseGeocode(latitude, longitude);
@@ -143,10 +208,18 @@ server.tool("sthan_reverse_geocode", "Convert latitude/longitude coordinates to
     }
 });
 // --- 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"),
+server.registerTool("sthan_ip_geolocation", {
+    title: "IP Geolocation",
+    description: "Look up the approximate geographic location of an IPv4 or IPv6 address. Returns country, region, city, coordinates, timezone, and postal code (some fields may be null when unknown). " +
+        "Use to estimate where an IP is located, for example for analytics or choosing a default region. " +
+        "This locates IP addresses, not postal addresses; to work with a street address use sthan_verify_address, sthan_parse_address, or sthan_geocode. " +
+        "Read-only with no side effects. Requires a sthan.io API key in STHAN_API_KEY; each call counts toward your plan's rate limit (a free tier is available). On failure it returns an error message.",
+    inputSchema: {
+        ip: zod_1.z
+            .string()
+            .describe("IPv4 (e.g. '8.8.8.8') or IPv6 (e.g. '2001:4860:4860::8888') address"),
+    },
+    annotations: READ_ONLY_HINTS,
 }, async ({ ip }) => {
     try {
         const response = await getClient().ipGeolocation(ip);

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@sthan/mcp-server",
-  "version": "0.1.2",
-  "mcpName": "io.github.sthan-io/mcp-server",
-  "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/sthan-io/mcp-server"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "@sthan/core": "0.1.2"
-  },
-  "devDependencies": {
-    "@types/node": "^25.5.0",
-    "typescript": "^6.0.2"
-  }
-}
+{
+  "name": "@sthan/mcp-server",
+  "version": "0.1.4",
+  "mcpName": "io.github.sthan-io/mcp-server",
+  "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/sthan-io/mcp-server"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@sthan/core": "0.1.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2"
+  }
+}