@cyanheads/geonames-mcp-server 0.1.3 → 0.2.1

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 (56) hide show
  1. package/AGENTS.md +23 -9
  2. package/CLAUDE.md +23 -9
  3. package/Dockerfile +9 -3
  4. package/README.md +49 -110
  5. package/changelog/0.1.x/0.1.3.md +1 -0
  6. package/changelog/0.2.x/0.2.0.md +37 -0
  7. package/changelog/0.2.x/0.2.1.md +30 -0
  8. package/changelog/template.md +10 -3
  9. package/dist/index.js +2 -1
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.d.ts.map +1 -1
  12. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js +9 -4
  13. package/dist/mcp-server/tools/definitions/find-postal-codes.tool.js.map +1 -1
  14. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts +6 -0
  15. package/dist/mcp-server/tools/definitions/get-children.tool.d.ts.map +1 -1
  16. package/dist/mcp-server/tools/definitions/get-children.tool.js +18 -7
  17. package/dist/mcp-server/tools/definitions/get-children.tool.js.map +1 -1
  18. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts +6 -0
  19. package/dist/mcp-server/tools/definitions/get-countries.tool.d.ts.map +1 -1
  20. package/dist/mcp-server/tools/definitions/get-countries.tool.js +15 -5
  21. package/dist/mcp-server/tools/definitions/get-countries.tool.js.map +1 -1
  22. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts +3 -1
  23. package/dist/mcp-server/tools/definitions/get-place.tool.d.ts.map +1 -1
  24. package/dist/mcp-server/tools/definitions/get-place.tool.js +23 -8
  25. package/dist/mcp-server/tools/definitions/get-place.tool.js.map +1 -1
  26. package/dist/mcp-server/tools/definitions/index.d.ts +23 -3
  27. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  28. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts +6 -0
  29. package/dist/mcp-server/tools/definitions/list-reference.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/list-reference.tool.js +13 -3
  31. package/dist/mcp-server/tools/definitions/list-reference.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.d.ts.map +1 -1
  33. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js +53 -5
  34. package/dist/mcp-server/tools/definitions/reverse-geocode.tool.js.map +1 -1
  35. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts +2 -2
  36. package/dist/mcp-server/tools/definitions/search-places.tool.d.ts.map +1 -1
  37. package/dist/mcp-server/tools/definitions/search-places.tool.js +19 -8
  38. package/dist/mcp-server/tools/definitions/search-places.tool.js.map +1 -1
  39. package/dist/mcp-server/tools/shared-inputs.d.ts +6 -2
  40. package/dist/mcp-server/tools/shared-inputs.d.ts.map +1 -1
  41. package/dist/mcp-server/tools/shared-inputs.js +9 -3
  42. package/dist/mcp-server/tools/shared-inputs.js.map +1 -1
  43. package/dist/services/geonames/response-parsers.d.ts +1 -0
  44. package/dist/services/geonames/response-parsers.d.ts.map +1 -1
  45. package/dist/services/geonames/response-parsers.js +8 -1
  46. package/dist/services/geonames/response-parsers.js.map +1 -1
  47. package/dist/services/geonames/upstream-errors.d.ts.map +1 -1
  48. package/dist/services/geonames/upstream-errors.js +7 -7
  49. package/dist/services/geonames/upstream-errors.js.map +1 -1
  50. package/dist/utils/inline-text.d.ts +23 -18
  51. package/dist/utils/inline-text.d.ts.map +1 -1
  52. package/dist/utils/inline-text.js +26 -24
  53. package/dist/utils/inline-text.js.map +1 -1
  54. package/package.json +14 -12
  55. package/server.json +3 -3
  56. package/skills/geonames-guide/SKILL.md +64 -0
package/server.json CHANGED
@@ -7,7 +7,7 @@
7
7
  "url": "https://github.com/cyanheads/geonames-mcp-server",
8
8
  "source": "github"
9
9
  },
10
- "version": "0.1.3",
10
+ "version": "0.2.1",
11
11
  "remotes": [
12
12
  {
13
13
  "type": "streamable-http",
@@ -20,7 +20,7 @@
20
20
  "registryBaseUrl": "https://registry.npmjs.org",
21
21
  "identifier": "@cyanheads/geonames-mcp-server",
22
22
  "runtimeHint": "npx",
23
- "version": "0.1.3",
23
+ "version": "0.2.1",
24
24
  "environmentVariables": [
25
25
  {
26
26
  "name": "GEONAMES_USERNAME",
@@ -46,7 +46,7 @@
46
46
  "registryBaseUrl": "https://registry.npmjs.org",
47
47
  "identifier": "@cyanheads/geonames-mcp-server",
48
48
  "runtimeHint": "npx",
49
- "version": "0.1.3",
49
+ "version": "0.2.1",
50
50
  "environmentVariables": [
51
51
  {
52
52
  "name": "MCP_TRANSPORT_TYPE",
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: geonames-guide
3
+ description: Gates and identifier crossings for the geonames_* gazetteer tools. Covers moving from a postal code to gazetteer admin codes and geonameIds, a town's complete postal-code list, a city that exists as two features with two populations, ranking or summing places by population, searching inside a state or county, microstates, nearest-place lists that stop at a cap, and the timezone at a coordinate. Use before counting, ranking, or chaining geonames_* results.
4
+ license: Apache-2.0
5
+ metadata:
6
+ author: cyanheads
7
+ version: "1.1"
8
+ ---
9
+
10
+ ## Scope
11
+
12
+ GeoNames holds named features as points, with a bounding box where one is recorded, plus their admin tree, a postal database, and country facts. It does not cover:
13
+
14
+ - **Street addresses.** No tool takes an address or a house number. Geocode the address elsewhere, such as an OpenStreetMap server, and bring the coordinate to `geonames_reverse_geocode`.
15
+ - **Boundaries.** A bounding box is not the outline (Gate 5). Only `geonames_reverse_geocode` says which divisions contain a point.
16
+ - **Distances between two places.** `distanceInKm` is measured only from a query point: on nearby rows, and on a country `geonames_reverse_geocode` matched within `coastalBufferKm`. For any other pair, compute the distance from the two `lat`/`lng` values.
17
+ - **Official statistics.** `population` is GeoNames' community-edited figure, and one city can carry two figures (Gate 2). Cite it as GeoNames, not as a census.
18
+
19
+ Where `geonames_get_place` lists a `wkdt` identifier, it is the Wikidata QID for a Wikidata server. Not every record has one: Seattle (5809844) lists only `iata` and `unlc`.
20
+
21
+ ## Identifiers
22
+
23
+ - **Postal rows carry no geonameId, and their admin codes can differ from search admin codes.** They come from the postal dataset. In one probe, Munich's 80331 had `adminCode1` BY, while the gazetteer codes Bavaria `02`; its `adminCode2` 091 and `adminCode3` 09162 happened to match. `geonames_search_places` with `countries` DE and `adminCode1` BY matched nothing. The postal BY equals the gazetteer's level-1 `isoCode`, not its `code`.
24
+ - **To cross from a postal row into the gazetteer, reverse-geocode its centroid.** Call `geonames_reverse_geocode` at the row's `lat`/`lng` with `nearbyLimit` 0. 80331's centroid returned 02 Bavaria, 091 Upper Bavaria, and 09162 Munich Urban District down to level 5, each with a geonameId and a code that search accepts. Never pass a postal row's admin code to search.
25
+
26
+ ## Gates
27
+
28
+ 1. **Get a town's postal codes from the postal database, with the admin name in the query.** Mode `place_name` matches its text against place, admin, and country names, and it has no admin filter.
29
+ - `Springfield` in US filled a 100-row page with rows from dozens of states, including East Springfield, West Springfield, and places with other names, and more pages remained.
30
+ - `Springfield Illinois` returned only rows for Springfield, IL.
31
+
32
+ Read to the last page (no `nextOffset`) before calling a list complete. A place record's `postalCodes` is a separate list that GeoNames links to the feature, and it can be shorter. In one probe, Springfield, IL (4250542) linked every code the postal database returned except 62711 and 62712. Never report that list as the complete set.
33
+
34
+ 2. **Say which feature's population you report.** Many cities are two features, each with its own geonameId and population. Seattle is the populated place 5809844 (PPLA2) and the admin division "City of Seattle" 7174408 (ADM3), and in one probe they carried 780,995 and 608,660. Nearest-place rows and a class P search return the populated place. Containment (`adminLevels`) returns the division, and Seattle's populated-place record lists that division at level 3. Name the geonameId and feature code beside any population you report.
35
+
36
+ 3. **Filter feature codes before you rank, sum, or count settlements.** Class P mixes a city with features whose populations overlap it, and with places that no longer exist:
37
+ - **Sections.** `Paris` in FR, class P, returned Paris (PPLC) beside its arrondissements, which were filed as PPL with their own populations, and beside PPLX sections.
38
+ - **Groups.** In Washington, ranked by population, Tri-Cities (PPLS) came second. It is a group of three cities that each appear as their own rows.
39
+ - **Former places.** PPLH (historical), PPLQ (abandoned), and PPLW (destroyed) are class P too.
40
+
41
+ Drop PPLX, PPLS, PPLH, PPLQ, and PPLW rows, and look for a city's subdivisions filed as PPL, before you add or rank populations. Without a class filter, other classes rank too. `Springfield, IL` returned the Springfield, IL Metro Area (RGNE), with a larger population than the city (PPLA), beside the airport, the township (ADM3), and a park. Set `featureClasses` P (or exact `featureCodes`) before `orderBy` population.
42
+
43
+ 4. **No population threshold exists above 15,000.** The `cities` tiers stop at 15,000. For "places over 100,000", sort with `orderBy` population and stop paging at the first row below the threshold.
44
+
45
+ 5. **Search inside a division with admin codes, not its box.** A bounding box is the rectangle around a division, so it takes in the neighbours. In one probe, the box from Texas's own record (4736286) matched about a third more airports than `countries` US with `adminCode1` TX. Its first page held airports in New Mexico, Arkansas, Oklahoma, Louisiana, and Mexico. For a country, use `countries`: the `geonames_get_countries` box is a rectangle too, and for Fiji, Kiribati, and Russia it crosses the 180° meridian (`west` above `east`), which search takes as it stands. Use a box only where no admin code fits, such as around a point, or where the admin-code search returns only the division itself: City of Algona, WA (ADM3 `7172907`) matched just itself by `adminCode3`, while its box held the town (PPL), a school, and a church.
46
+
47
+ 6. **Check for a microstate or enclave before naming the country.** Containment polygons do not always carve them out. A point inside Vatican City returned Italy, Lazio, and Rome, down to Trionfale. Its nearest populated place, 0.09 km away, was Vatican City (PPLC, `countryCode` VA). When the nearest place a few hundred metres away carries another `countryCode`, report both rather than the containing country alone.
48
+
49
+ 7. **Take the timezone at a coordinate from `geonames_reverse_geocode`.** Set `includeTimezone`, with `nearbyLimit` 0 if you need nothing else. The timezone on a `geonames_get_place` record is the zone GeoNames associates with that feature, not one verified at its coordinates. On a feature with no country it can be far off. South Pacific Ocean (4030483, at −45, −130) carries Pacific/Tongatapu (+13), but `geonames_reverse_geocode` at those same coordinates finds no IANA zone and offsets of −9.
50
+
51
+ 8. **Nearest-place lists cannot be continued in distance order.** `geonames_reverse_geocode` lists at most the nearest 50 and does not page. Mode `nearby` of `geonames_find_postal_codes` lists at most 100 and takes no `offset`. Search orders only by relevance or population. In a dense city the cap covers little ground: in one probe, the nearest 8 places to downtown Seattle all lay within 1.2 km. To list every place or feature within a radius:
52
+ 1. Run the `geonames_search_places` call that the full-page notice of `geonames_reverse_geocode` prints; its box encloses the circle.
53
+ 2. Page to the end. The search reaches its first 5,100 rows, so split the box when `totalCount` runs past that.
54
+ 3. Compute each row's distance from its `lat`/`lng`, and keep the rows inside the radius. GeoNames' own distances run up to about 0.5% shorter than a haversine on a 6,371 km sphere, so allow that much slack at the edge. Drop sections by `featureCode` only before you rank or sum populations (Gate 3).
55
+
56
+ Postal codes have no such route: `geonames_find_postal_codes` takes no box, and a call from another point returns that point's nearest 100.
57
+
58
+ ## Workflows
59
+
60
+ **Every county or province of a state, with population.** Get the state's geonameId with `geonames_search_places`, using `featureCodes` ADM1 and `countries`. Then call `geonames_get_children` with `limit` 500. In one probe, one call returned all 254 Texas counties (ADM2), each with a population.
61
+
62
+ **What a point is in, and its local time.** Call `geonames_reverse_geocode` with `nearbyLimit` 0 and `includeTimezone`. That returns the country, the divisions, and the IANA zone with local time, without the nearby lookup's 3 or 4 credits. Add the nearby lookup only when you need a settlement name, and apply Gate 6 before naming the country.
63
+
64
+ **One place from an ambiguous name.** Put the admin name or code in the query text (`Springfield, IL` ranked Springfield, IL first), or pass `countries` with `adminCode1`. Add `featureClasses` P for a settlement or A for a division (Gate 3). Confirm the pick from `adminName1`, `featureCode`, and `population` before you chain its geonameId.