@sthan/mcp-server 0.1.6 → 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 +56 -19
  2. package/dist/index.js +1 -1
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -10,50 +10,87 @@ Works with Claude Code, Cursor, VS Code, Windsurf, and any MCP-compatible client
10
10
 
11
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
12
 
13
- ### 2. Configure your client
13
+ ### 2. One-click install
14
14
 
15
- **Claude Code** (`~/.claude/mcp.json` or project `.claude/mcp.json`):
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)
16
19
 
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
- }
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
27
33
  ```
28
34
 
29
- **Cursor** (`.cursor/mcp.json`):
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:
30
44
 
31
45
  ```json
32
46
  {
33
47
  "mcpServers": {
34
48
  "sthan": {
35
49
  "command": "npx",
36
- "args": ["@sthan/mcp-server"],
37
- "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
50
+ "args": ["-y", "@sthan/mcp-server"],
51
+ "env": { "STHAN_API_KEY": "your_key_here" }
38
52
  }
39
53
  }
40
54
  }
41
55
  ```
42
56
 
43
- **VS Code** (`settings.json`):
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:
44
62
 
45
63
  ```json
46
64
  {
47
- "mcp.servers": {
65
+ "inputs": [
66
+ { "type": "promptString", "id": "sthan-api-key", "description": "sthan.io API key", "password": true }
67
+ ],
68
+ "servers": {
48
69
  "sthan": {
70
+ "type": "stdio",
49
71
  "command": "npx",
50
- "args": ["@sthan/mcp-server"],
51
- "env": { "STHAN_API_KEY": "sthan_test_your_api_key_here" }
72
+ "args": ["-y", "@sthan/mcp-server"],
73
+ "env": { "STHAN_API_KEY": "${input:sthan-api-key}" }
52
74
  }
53
75
  }
54
76
  }
55
77
  ```
56
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
+
57
94
  ## Tools
58
95
 
59
96
  | Tool | Description |
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.6",
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,6 +1,6 @@
1
1
  {
2
2
  "name": "@sthan/mcp-server",
3
- "version": "0.1.6",
3
+ "version": "0.1.7",
4
4
  "mcpName": "io.github.sthan-io/mcp-server",
5
5
  "description": "MCP server for sthan.io — US address verification, parsing, autocomplete, geocoding, and IP geolocation",
6
6
  "main": "dist/index.js",
@@ -46,7 +46,7 @@
46
46
  },
47
47
  "dependencies": {
48
48
  "@modelcontextprotocol/sdk": "^1.12.1",
49
- "@sthan/core": "0.1.6"
49
+ "@sthan/core": "0.1.7"
50
50
  },
51
51
  "devDependencies": {
52
52
  "@types/node": "^25.5.0",