@sthan/mcp-server 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +133 -96
  2. package/dist/index.js +1 -1
  3. package/package.json +55 -55
package/README.md CHANGED
@@ -1,96 +1,133 @@
1
- # @sthan/mcp-server
2
-
3
- MCP server for [sthan.io](https://sthan.io) — US address verification, parsing, autocomplete, geocoding, and IP geolocation.
4
-
5
- Works with Claude Code, Cursor, VS Code, Windsurf, and any MCP-compatible client.
6
-
7
- ## Setup
8
-
9
- ### 1. Get an API key
10
-
11
- 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).
12
-
13
- ### 2. Configure your client
14
-
15
- **Claude Code** (`~/.claude/mcp.json` or project `.claude/mcp.json`):
16
-
17
- ```json
18
- {
19
- "mcpServers": {
20
- "sthan": {
21
- "command": "npx",
22
- "args": ["@sthan/mcp-server"],
23
- "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
24
- }
25
- }
26
- }
27
- ```
28
-
29
- **Cursor** (`.cursor/mcp.json`):
30
-
31
- ```json
32
- {
33
- "mcpServers": {
34
- "sthan": {
35
- "command": "npx",
36
- "args": ["@sthan/mcp-server"],
37
- "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
38
- }
39
- }
40
- }
41
- ```
42
-
43
- **VS Code** (`settings.json`):
44
-
45
- ```json
46
- {
47
- "mcp.servers": {
48
- "sthan": {
49
- "command": "npx",
50
- "args": ["@sthan/mcp-server"],
51
- "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
52
- }
53
- }
54
- }
55
- ```
56
-
57
- ## Tools
58
-
59
- | Tool | Description |
60
- |------|-------------|
61
- | `sthan_verify_address` | Verify a US address for deliverability. Returns DPV confirmation, ZIP+4, carrier route. |
62
- | `sthan_parse_address` | Parse freeform address text into structured components (street, city, state, zip, unit). |
63
- | `sthan_autocomplete_address` | Get address suggestions from partial input. Sub-100ms response time. |
64
- | `sthan_autocomplete_city` | Get US city suggestions from partial input. |
65
- | `sthan_autocomplete_zipcode` | Get US ZIP code suggestions from partial input. |
66
- | `sthan_geocode` | Convert a US address to latitude/longitude coordinates. |
67
- | `sthan_reverse_geocode` | Convert coordinates to the nearest US street address. |
68
- | `sthan_ip_geolocation` | Look up geographic location of an IPv4 or IPv6 address. |
69
-
70
- ## Environment variables
71
-
72
- | Variable | Required | Description |
73
- |----------|----------|-------------|
74
- | `STHAN_API_KEY` | Yes | Your sthan.io API key (`sthan_test_*` or `sthan_live_*`) |
75
- | `STHAN_API_URL` | No | Override base URL (default: `https://api.sthan.io`) |
76
-
77
- ## Examples
78
-
79
- Once configured, just ask your AI assistant naturally:
80
-
81
- - "Is 123 Main St, New York, NY 10001 a real address?"
82
- - "Parse this address: apt 2b 500 broadway new york ny"
83
- - "What are the coordinates for the White House?"
84
- - "What address is at 40.7128, -74.0060?"
85
- - "Where is IP 8.8.8.8 located?"
86
-
87
- ## Links
88
-
89
- - [API docs](https://sthan.io/docs)
90
- - [Pricing](https://sthan.io/pricing/united-states)
91
- - [OpenAPI spec](https://api.sthan.io/openapi.json)
92
- - [AI reference](https://api.sthan.io/llms-full.txt)
93
-
94
- ## License
95
-
96
- MIT
1
+ # @sthan/mcp-server
2
+
3
+ MCP server for [sthan.io](https://sthan.io) — US address verification, parsing, autocomplete, geocoding, and IP geolocation.
4
+
5
+ Works with Claude Code, Cursor, VS Code, Windsurf, and any MCP-compatible client.
6
+
7
+ ## Setup
8
+
9
+ ### 1. Get an API key
10
+
11
+ 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).
12
+
13
+ ### 2. One-click install
14
+
15
+ [![Add to Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Download_extension-D97757?style=for-the-badge)](https://github.com/sthan-io/mcp-server/releases/latest/download/sthan.mcpb)
16
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=sthan&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22sthan_api_key%22%2C%22description%22%3A%22sthan.io%20API%20key%20%28free%20at%20https%3A//sthan.io%29%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40sthan/mcp-server%22%5D%2C%22env%22%3A%7B%22STHAN_API_KEY%22%3A%22%24%7Binput%3Asthan_api_key%7D%22%7D%7D)
17
+ [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=sthan&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22sthan_api_key%22%2C%22description%22%3A%22sthan.io%20API%20key%20%28free%20at%20https%3A//sthan.io%29%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40sthan/mcp-server%22%5D%2C%22env%22%3A%7B%22STHAN_API_KEY%22%3A%22%24%7Binput%3Asthan_api_key%7D%22%7D%7D&quality=insiders)
18
+ [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_to_Cursor-000000?style=for-the-badge)](https://cursor.com/install-mcp?name=sthan&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzdGhhbi9tY3Atc2VydmVyIl0sImVudiI6eyJTVEhBTl9BUElfS0VZIjoieW91cl9rZXlfaGVyZSJ9fQ%3D%3D)
19
+
20
+ - **Claude Desktop**: download `sthan.mcpb` and double-click it. Claude asks for your API key and keeps it in your system keychain. Nothing else to install.
21
+ - **VS Code**: click the button. VS Code asks for your API key and stores it securely.
22
+ - **Cursor**: click the button, then replace `your_key_here` with your key in Cursor Settings > MCP.
23
+ - **Claude Code**: `claude mcp add sthan -e STHAN_API_KEY=your_key_here -- npx -y @sthan/mcp-server` (details below).
24
+
25
+ ### 3. Or set it up manually
26
+
27
+ Replace `your_key_here` with your key. Every setup below downloads the latest `@sthan/mcp-server` from npm and calls the live API at `https://api.sthan.io`.
28
+
29
+ **Claude Code** (terminal):
30
+
31
+ ```bash
32
+ claude mcp add sthan -e STHAN_API_KEY=your_key_here -- npx -y @sthan/mcp-server
33
+ ```
34
+
35
+ On native Windows, wrap `npx` with `cmd /c`:
36
+
37
+ ```powershell
38
+ claude mcp add sthan -e STHAN_API_KEY=your_key_here -- cmd /c npx -y @sthan/mcp-server
39
+ ```
40
+
41
+ Add `--scope user` to use it in every project. Start `claude` and type `/mcp` to confirm `sthan` is connected.
42
+
43
+ **Claude Desktop**: edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), then restart Claude Desktop:
44
+
45
+ ```json
46
+ {
47
+ "mcpServers": {
48
+ "sthan": {
49
+ "command": "npx",
50
+ "args": ["-y", "@sthan/mcp-server"],
51
+ "env": { "STHAN_API_KEY": "your_key_here" }
52
+ }
53
+ }
54
+ }
55
+ ```
56
+
57
+ **Cursor**: the same JSON in `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project).
58
+
59
+ **Windsurf**: the same JSON in `~/.codeium/windsurf/mcp_config.json`.
60
+
61
+ **VS Code**: create `.vscode/mcp.json`. VS Code asks for the key once and stores it securely:
62
+
63
+ ```json
64
+ {
65
+ "inputs": [
66
+ { "type": "promptString", "id": "sthan-api-key", "description": "sthan.io API key", "password": true }
67
+ ],
68
+ "servers": {
69
+ "sthan": {
70
+ "type": "stdio",
71
+ "command": "npx",
72
+ "args": ["-y", "@sthan/mcp-server"],
73
+ "env": { "STHAN_API_KEY": "${input:sthan-api-key}" }
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ **Try it without an AI client** (opens the official MCP Inspector in your browser):
80
+
81
+ ```bash
82
+ npx @modelcontextprotocol/inspector -e STHAN_API_KEY=your_key_here npx -y @sthan/mcp-server
83
+ ```
84
+
85
+ Click **Connect**, then **Tools** > **List Tools**, pick a tool, and run it.
86
+
87
+ **Troubleshooting**
88
+
89
+ - Keep the `-y` in `npx -y`. Without it, `npx` waits for an "OK to install?" answer that an AI client cannot give, and the server never starts.
90
+ - On Windows, run the `claude mcp add ... cmd /c ...` command from PowerShell or Command Prompt. Git Bash rewrites `/c` to `C:/`, which saves a broken command that times out (fix: prefix it with `MSYS_NO_PATHCONV=1`).
91
+ - On Windows, if a client reports `spawn npx ENOENT`, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@sthan/mcp-server"]`.
92
+ - Address verification and parsing can take up to about 2 minutes when a live postal lookup is needed. If your client gives up sooner, raise its tool timeout (Claude Code: set `MCP_TOOL_TIMEOUT=150000` before starting `claude`; MCP Inspector: raise **Request Timeout** in its Configuration panel).
93
+
94
+ ## Tools
95
+
96
+ | Tool | Description |
97
+ |------|-------------|
98
+ | `sthan_verify_address` | Verify a US address for deliverability. Returns DPV confirmation, ZIP+4, carrier route. |
99
+ | `sthan_parse_address` | Parse freeform address text into structured components (street, city, state, zip, unit). |
100
+ | `sthan_autocomplete_address` | Get address suggestions from partial input. Sub-100ms response time. |
101
+ | `sthan_autocomplete_city` | Get US city suggestions from partial input. |
102
+ | `sthan_autocomplete_zipcode` | Get US ZIP code suggestions from partial input. |
103
+ | `sthan_geocode` | Convert a US address to latitude/longitude coordinates. |
104
+ | `sthan_reverse_geocode` | Convert coordinates to the nearest US street address. |
105
+ | `sthan_ip_geolocation` | Look up geographic location of an IPv4 or IPv6 address. |
106
+
107
+ ## Environment variables
108
+
109
+ | Variable | Required | Description |
110
+ |----------|----------|-------------|
111
+ | `STHAN_API_KEY` | Yes | Your sthan.io API key (`sthan_test_*` or `sthan_live_*`) |
112
+ | `STHAN_API_URL` | No | Override base URL (default: `https://api.sthan.io`) |
113
+
114
+ ## Examples
115
+
116
+ Once configured, just ask your AI assistant naturally:
117
+
118
+ - "Is 123 Main St, New York, NY 10001 a real address?"
119
+ - "Parse this address: apt 2b 500 broadway new york ny"
120
+ - "What are the coordinates for the White House?"
121
+ - "What address is at 40.7128, -74.0060?"
122
+ - "Where is IP 8.8.8.8 located?"
123
+
124
+ ## Links
125
+
126
+ - [API docs](https://sthan.io/docs)
127
+ - [Pricing](https://sthan.io/pricing/united-states)
128
+ - [OpenAPI spec](https://api.sthan.io/openapi.json)
129
+ - [AI reference](https://api.sthan.io/llms-full.txt)
130
+
131
+ ## License
132
+
133
+ MIT
package/dist/index.js CHANGED
@@ -28,7 +28,7 @@ const READ_ONLY_HINTS = {
28
28
  };
29
29
  const server = new mcp_js_1.McpServer({
30
30
  name: "sthan",
31
- version: "0.1.5",
31
+ version: "0.1.7",
32
32
  });
33
33
  // --- Tool 1: Verify US Address ---
34
34
  server.registerTool("sthan_verify_address", {
package/package.json CHANGED
@@ -1,55 +1,55 @@
1
- {
2
- "name": "@sthan/mcp-server",
3
- "version": "0.1.5",
4
- "mcpName": "io.github.sthan-io/mcp-server",
5
- "description": "MCP server for sthan.io — US address verification, parsing, autocomplete, geocoding, and IP geolocation",
6
- "main": "dist/index.js",
7
- "types": "dist/index.d.ts",
8
- "bin": {
9
- "sthan-mcp-server": "dist/index.js"
10
- },
11
- "files": [
12
- "dist",
13
- "README.md"
14
- ],
15
- "scripts": {
16
- "build": "tsc",
17
- "dev": "tsc --watch",
18
- "start": "node dist/index.js"
19
- },
20
- "keywords": [
21
- "mcp",
22
- "mcp-server",
23
- "model-context-protocol",
24
- "address-verification",
25
- "address-parser",
26
- "address-autocomplete",
27
- "geocoding",
28
- "reverse-geocoding",
29
- "ip-geolocation",
30
- "sthan",
31
- "claude",
32
- "cursor",
33
- "vscode",
34
- "ai",
35
- "ai-tools"
36
- ],
37
- "author": "sthan.io",
38
- "license": "MIT",
39
- "homepage": "https://sthan.io",
40
- "repository": {
41
- "type": "git",
42
- "url": "https://github.com/sthan-io/mcp-server"
43
- },
44
- "engines": {
45
- "node": ">=20"
46
- },
47
- "dependencies": {
48
- "@modelcontextprotocol/sdk": "^1.12.1",
49
- "@sthan/core": "0.1.5"
50
- },
51
- "devDependencies": {
52
- "@types/node": "^25.5.0",
53
- "typescript": "^6.0.2"
54
- }
55
- }
1
+ {
2
+ "name": "@sthan/mcp-server",
3
+ "version": "0.1.7",
4
+ "mcpName": "io.github.sthan-io/mcp-server",
5
+ "description": "MCP server for sthan.io — US address verification, parsing, autocomplete, geocoding, and IP geolocation",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "bin": {
9
+ "sthan-mcp-server": "dist/index.js"
10
+ },
11
+ "files": [
12
+ "dist",
13
+ "README.md"
14
+ ],
15
+ "scripts": {
16
+ "build": "tsc",
17
+ "dev": "tsc --watch",
18
+ "start": "node dist/index.js"
19
+ },
20
+ "keywords": [
21
+ "mcp",
22
+ "mcp-server",
23
+ "model-context-protocol",
24
+ "address-verification",
25
+ "address-parser",
26
+ "address-autocomplete",
27
+ "geocoding",
28
+ "reverse-geocoding",
29
+ "ip-geolocation",
30
+ "sthan",
31
+ "claude",
32
+ "cursor",
33
+ "vscode",
34
+ "ai",
35
+ "ai-tools"
36
+ ],
37
+ "author": "sthan.io",
38
+ "license": "MIT",
39
+ "homepage": "https://sthan.io",
40
+ "repository": {
41
+ "type": "git",
42
+ "url": "https://github.com/sthan-io/mcp-server"
43
+ },
44
+ "engines": {
45
+ "node": ">=20"
46
+ },
47
+ "dependencies": {
48
+ "@modelcontextprotocol/sdk": "^1.12.1",
49
+ "@sthan/core": "0.1.7"
50
+ },
51
+ "devDependencies": {
52
+ "@types/node": "^25.5.0",
53
+ "typescript": "^6.0.2"
54
+ }
55
+ }