@sthan/mcp-server 0.1.3 → 0.1.5
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.
- package/dist/index.js +115 -42
- package/package.json +2 -2
package/dist/index.js
CHANGED
|
@@ -17,15 +17,32 @@ function getClient() {
|
|
|
17
17
|
baseUrl: process.env.STHAN_API_URL,
|
|
18
18
|
});
|
|
19
19
|
}
|
|
20
|
+
// Every tool is a read-only lookup against the sthan.io API: no state is
|
|
21
|
+
// changed, repeating a call with the same input returns the same result, and
|
|
22
|
+
// it reaches an external service (the open world of US addresses).
|
|
23
|
+
const READ_ONLY_HINTS = {
|
|
24
|
+
readOnlyHint: true,
|
|
25
|
+
destructiveHint: false,
|
|
26
|
+
idempotentHint: true,
|
|
27
|
+
openWorldHint: true,
|
|
28
|
+
};
|
|
20
29
|
const server = new mcp_js_1.McpServer({
|
|
21
30
|
name: "sthan",
|
|
22
|
-
version: "0.1.
|
|
31
|
+
version: "0.1.5",
|
|
23
32
|
});
|
|
24
33
|
// --- Tool 1: Verify US Address ---
|
|
25
|
-
server.
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
34
|
+
server.registerTool("sthan_verify_address", {
|
|
35
|
+
title: "Verify US Address",
|
|
36
|
+
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). " +
|
|
37
|
+
"Use to confirm a US mailing address, clean address data, or check an address before shipping. " +
|
|
38
|
+
"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). " +
|
|
39
|
+
"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.",
|
|
40
|
+
inputSchema: {
|
|
41
|
+
address: zod_1.z
|
|
42
|
+
.string()
|
|
43
|
+
.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'"),
|
|
44
|
+
},
|
|
45
|
+
annotations: READ_ONLY_HINTS,
|
|
29
46
|
}, async ({ address }) => {
|
|
30
47
|
try {
|
|
31
48
|
const response = await getClient().verifyAddress(address);
|
|
@@ -38,10 +55,18 @@ server.tool("sthan_verify_address", "Verify if a US address is real and delivera
|
|
|
38
55
|
}
|
|
39
56
|
});
|
|
40
57
|
// --- Tool 2: Parse US Address ---
|
|
41
|
-
server.
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
58
|
+
server.registerTool("sthan_parse_address", {
|
|
59
|
+
title: "Parse US Address",
|
|
60
|
+
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. " +
|
|
61
|
+
"Use when you have messy or unstructured US address text and need the individual fields. " +
|
|
62
|
+
"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). " +
|
|
63
|
+
"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.",
|
|
64
|
+
inputSchema: {
|
|
65
|
+
address: zod_1.z
|
|
66
|
+
.string()
|
|
67
|
+
.describe("Raw address text to parse. Freeform input, abbreviations OK. Example: 'apt 2b 500 broadway new york ny'"),
|
|
68
|
+
},
|
|
69
|
+
annotations: READ_ONLY_HINTS,
|
|
45
70
|
}, async ({ address }) => {
|
|
46
71
|
try {
|
|
47
72
|
const response = await getClient().parseAddress(address);
|
|
@@ -54,10 +79,18 @@ server.tool("sthan_parse_address", "Parse a freeform US address string into stru
|
|
|
54
79
|
}
|
|
55
80
|
});
|
|
56
81
|
// --- Tool 3: Autocomplete US Address ---
|
|
57
|
-
server.
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
82
|
+
server.registerTool("sthan_autocomplete_address", {
|
|
83
|
+
title: "Autocomplete US Address",
|
|
84
|
+
description: "Return a list of complete US street-address suggestions for partial input, intended for type-ahead / autocomplete fields. " +
|
|
85
|
+
"Use while a user is typing an address and you want to offer full matches. " +
|
|
86
|
+
"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. " +
|
|
87
|
+
"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.",
|
|
88
|
+
inputSchema: {
|
|
89
|
+
text: zod_1.z
|
|
90
|
+
.string()
|
|
91
|
+
.describe("Partial address text (3+ characters recommended). Example: '123 Main'"),
|
|
92
|
+
},
|
|
93
|
+
annotations: READ_ONLY_HINTS,
|
|
61
94
|
}, async ({ text }) => {
|
|
62
95
|
try {
|
|
63
96
|
const response = await getClient().autocompleteAddress(text);
|
|
@@ -70,15 +103,23 @@ server.tool("sthan_autocomplete_address", "Get address suggestions from partial
|
|
|
70
103
|
}
|
|
71
104
|
});
|
|
72
105
|
// --- Tool 4: Autocomplete US City ---
|
|
73
|
-
server.
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
.
|
|
77
|
-
.
|
|
78
|
-
.
|
|
79
|
-
|
|
80
|
-
.
|
|
81
|
-
|
|
106
|
+
server.registerTool("sthan_autocomplete_city", {
|
|
107
|
+
title: "Autocomplete US City",
|
|
108
|
+
description: "Return a list of US city suggestions (with state) for partial input. " +
|
|
109
|
+
"Use for city-field type-ahead, or to resolve a partial city name to its full name and state. " +
|
|
110
|
+
"For full street-address suggestions use sthan_autocomplete_address; for ZIP codes use sthan_autocomplete_zipcode. " +
|
|
111
|
+
"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.",
|
|
112
|
+
inputSchema: {
|
|
113
|
+
text: zod_1.z.string().describe("Partial city name. Example: 'San Fr'"),
|
|
114
|
+
display_type: zod_1.z
|
|
115
|
+
.number()
|
|
116
|
+
.int()
|
|
117
|
+
.min(0)
|
|
118
|
+
.max(1)
|
|
119
|
+
.default(0)
|
|
120
|
+
.describe("0 = City, StateCode (e.g. 'San Francisco, CA'). 1 = City, State (e.g. 'San Francisco, California')"),
|
|
121
|
+
},
|
|
122
|
+
annotations: READ_ONLY_HINTS,
|
|
82
123
|
}, async ({ text, display_type }) => {
|
|
83
124
|
try {
|
|
84
125
|
const response = await getClient().autocompleteCity(text, display_type);
|
|
@@ -91,15 +132,23 @@ server.tool("sthan_autocomplete_city", "Get US city name suggestions from partia
|
|
|
91
132
|
}
|
|
92
133
|
});
|
|
93
134
|
// --- Tool 5: Autocomplete US ZIP Code ---
|
|
94
|
-
server.
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
.
|
|
98
|
-
.
|
|
99
|
-
.
|
|
100
|
-
|
|
101
|
-
.
|
|
102
|
-
|
|
135
|
+
server.registerTool("sthan_autocomplete_zipcode", {
|
|
136
|
+
title: "Autocomplete US ZIP Code",
|
|
137
|
+
description: "Return a list of US ZIP code suggestions for partial input, each with state (and optionally ZIP+4). " +
|
|
138
|
+
"Use for ZIP-field type-ahead or to expand a partial ZIP. " +
|
|
139
|
+
"For city suggestions use sthan_autocomplete_city; for full addresses use sthan_autocomplete_address. " +
|
|
140
|
+
"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.",
|
|
141
|
+
inputSchema: {
|
|
142
|
+
text: zod_1.z.string().describe("Partial ZIP code. Example: '9021'"),
|
|
143
|
+
display_type: zod_1.z
|
|
144
|
+
.number()
|
|
145
|
+
.int()
|
|
146
|
+
.min(0)
|
|
147
|
+
.max(3)
|
|
148
|
+
.default(0)
|
|
149
|
+
.describe("0 = Zip,StateCode. 1 = Zip,State. 2 = Zip-Zip4,StateCode. 3 = Zip-Zip4,State"),
|
|
150
|
+
},
|
|
151
|
+
annotations: READ_ONLY_HINTS,
|
|
103
152
|
}, async ({ text, display_type }) => {
|
|
104
153
|
try {
|
|
105
154
|
const response = await getClient().autocompleteZipCode(text, display_type);
|
|
@@ -112,10 +161,18 @@ server.tool("sthan_autocomplete_zipcode", "Get US ZIP code suggestions from part
|
|
|
112
161
|
}
|
|
113
162
|
});
|
|
114
163
|
// --- Tool 6: Forward Geocode US Address ---
|
|
115
|
-
server.
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
164
|
+
server.registerTool("sthan_geocode", {
|
|
165
|
+
title: "Geocode US Address",
|
|
166
|
+
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. " +
|
|
167
|
+
"Use when you need map coordinates for an address. " +
|
|
168
|
+
"To go the other way (coordinates to address) use sthan_reverse_geocode; to check deliverability rather than location use sthan_verify_address. " +
|
|
169
|
+
"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.",
|
|
170
|
+
inputSchema: {
|
|
171
|
+
address: zod_1.z
|
|
172
|
+
.string()
|
|
173
|
+
.describe("US address to geocode (freeform text). Example: '1600 Pennsylvania Ave, Washington DC'"),
|
|
174
|
+
},
|
|
175
|
+
annotations: READ_ONLY_HINTS,
|
|
119
176
|
}, async ({ address }) => {
|
|
120
177
|
try {
|
|
121
178
|
const response = await getClient().geocodeAddress(address);
|
|
@@ -128,9 +185,17 @@ server.tool("sthan_geocode", "Convert a US address to latitude/longitude coordin
|
|
|
128
185
|
}
|
|
129
186
|
});
|
|
130
187
|
// --- Tool 7: Reverse Geocode ---
|
|
131
|
-
server.
|
|
132
|
-
|
|
133
|
-
|
|
188
|
+
server.registerTool("sthan_reverse_geocode", {
|
|
189
|
+
title: "Reverse Geocode Coordinates",
|
|
190
|
+
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. " +
|
|
191
|
+
"Use when you have coordinates and need the closest address. US coverage only. " +
|
|
192
|
+
"To go the other way (address to coordinates) use sthan_geocode. " +
|
|
193
|
+
"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.",
|
|
194
|
+
inputSchema: {
|
|
195
|
+
latitude: zod_1.z.number().min(-90).max(90).describe("Latitude coordinate"),
|
|
196
|
+
longitude: zod_1.z.number().min(-180).max(180).describe("Longitude coordinate"),
|
|
197
|
+
},
|
|
198
|
+
annotations: READ_ONLY_HINTS,
|
|
134
199
|
}, async ({ latitude, longitude }) => {
|
|
135
200
|
try {
|
|
136
201
|
const response = await getClient().reverseGeocode(latitude, longitude);
|
|
@@ -143,10 +208,18 @@ server.tool("sthan_reverse_geocode", "Convert latitude/longitude coordinates to
|
|
|
143
208
|
}
|
|
144
209
|
});
|
|
145
210
|
// --- Tool 8: IP Geolocation ---
|
|
146
|
-
server.
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
211
|
+
server.registerTool("sthan_ip_geolocation", {
|
|
212
|
+
title: "IP Geolocation",
|
|
213
|
+
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). " +
|
|
214
|
+
"Use to estimate where an IP is located, for example for analytics or choosing a default region. " +
|
|
215
|
+
"This locates IP addresses, not postal addresses; to work with a street address use sthan_verify_address, sthan_parse_address, or sthan_geocode. " +
|
|
216
|
+
"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.",
|
|
217
|
+
inputSchema: {
|
|
218
|
+
ip: zod_1.z
|
|
219
|
+
.string()
|
|
220
|
+
.describe("IPv4 (e.g. '8.8.8.8') or IPv6 (e.g. '2001:4860:4860::8888') address"),
|
|
221
|
+
},
|
|
222
|
+
annotations: READ_ONLY_HINTS,
|
|
150
223
|
}, async ({ ip }) => {
|
|
151
224
|
try {
|
|
152
225
|
const response = await getClient().ipGeolocation(ip);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sthan/mcp-server",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
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.
|
|
49
|
+
"@sthan/core": "0.1.5"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
52
|
"@types/node": "^25.5.0",
|