catastro-gps-mcp 1.0.1 → 1.2.0

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 (57) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +137 -85
  3. package/build/client/catastrogps-api.d.ts +16 -12
  4. package/build/client/catastrogps-api.js +44 -72
  5. package/build/index.d.ts +0 -9
  6. package/build/index.js +0 -9
  7. package/build/server.d.ts +2 -0
  8. package/build/server.js +11 -6
  9. package/build/sse.d.ts +0 -9
  10. package/build/sse.js +2 -16
  11. package/build/tools/compare-parcels.js +38 -15
  12. package/build/tools/get-agriculture.js +13 -20
  13. package/build/tools/get-boundaries.js +18 -20
  14. package/build/tools/get-market.js +30 -13
  15. package/build/tools/get-parcel.js +47 -62
  16. package/build/tools/get-score.d.ts +4 -0
  17. package/build/tools/get-score.js +51 -20
  18. package/build/tools/get-solar.js +25 -23
  19. package/build/tools/get-value-history.js +28 -14
  20. package/build/tools/search-address.d.ts +4 -0
  21. package/build/tools/search-address.js +41 -0
  22. package/build/tools/shared.d.ts +11 -1
  23. package/build/tools/shared.js +51 -27
  24. package/build/types/index.d.ts +118 -60
  25. package/build/types/index.js +20 -2
  26. package/build/version.d.ts +4 -0
  27. package/build/version.js +4 -0
  28. package/package.json +33 -13
  29. package/server.json +58 -0
  30. package/build/client/catastrogps-api.d.ts.map +0 -1
  31. package/build/client/catastrogps-api.js.map +0 -1
  32. package/build/index.d.ts.map +0 -1
  33. package/build/index.js.map +0 -1
  34. package/build/server.d.ts.map +0 -1
  35. package/build/server.js.map +0 -1
  36. package/build/sse.d.ts.map +0 -1
  37. package/build/sse.js.map +0 -1
  38. package/build/tools/compare-parcels.d.ts.map +0 -1
  39. package/build/tools/compare-parcels.js.map +0 -1
  40. package/build/tools/get-agriculture.d.ts.map +0 -1
  41. package/build/tools/get-agriculture.js.map +0 -1
  42. package/build/tools/get-boundaries.d.ts.map +0 -1
  43. package/build/tools/get-boundaries.js.map +0 -1
  44. package/build/tools/get-market.d.ts.map +0 -1
  45. package/build/tools/get-market.js.map +0 -1
  46. package/build/tools/get-parcel.d.ts.map +0 -1
  47. package/build/tools/get-parcel.js.map +0 -1
  48. package/build/tools/get-score.d.ts.map +0 -1
  49. package/build/tools/get-score.js.map +0 -1
  50. package/build/tools/get-solar.d.ts.map +0 -1
  51. package/build/tools/get-solar.js.map +0 -1
  52. package/build/tools/get-value-history.d.ts.map +0 -1
  53. package/build/tools/get-value-history.js.map +0 -1
  54. package/build/tools/shared.d.ts.map +0 -1
  55. package/build/tools/shared.js.map +0 -1
  56. package/build/types/index.d.ts.map +0 -1
  57. package/build/types/index.js.map +0 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 The Hidden Panda
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,24 +1,30 @@
1
- # catastro-gps-mcp
1
+ # Catastro GPS MCP server
2
2
 
3
- MCP server for European cadastral and territorial data. Access parcel information, solar potential, agricultural data, market prices, and investment scores across Spain, Portugal, France, Italy, and Germany.
3
+ <!-- mcp-name: com.parcelgps/catastro-gps -->
4
4
 
5
- **The first MCP server for European cadastral data.**
5
+ Official cadastral parcels for AI agents, across **29 European countries plus the Basque Country and Navarre** (31 country and region codes), with one API key.
6
6
 
7
- ## Quick Start
7
+ Ask your agent for a parcel by its cadastral reference, by a point on the map or, in Spain, by a postal address typed as free text. It gets back the reference, location, area, land use and the parcel outline, and it can estimate solar and agricultural potential, read aggregated market prices, score and compare parcels in Spain, Portugal, France, Italy and Germany.
8
8
 
9
- ### Claude Desktop
9
+ - **31 codes, one call shape.** `ES`, `PT`, `FR`, `IT`, `DE`, `PL`, `NL`, `CH`… and the two Spanish foral cadastres (`PV`, `NA`) that the central Catastro does not serve.
10
+ - **The country is optional.** It is detected from the reference format or from the point. A few references are valid in more than one country (some German and Portuguese numbers look alike): pass `country` to be explicit.
11
+ - **Free-text Spanish addresses.** `"Calle Mallorca 213, Barcelona"` becomes a cadastral reference.
12
+ - **Geometry included.** Parcel outlines as GeoJSON or `[lat, lng]` rings, with centroid and area.
13
+ - **Free tier for good.** 250 calls a month at no cost, no card. Failed lookups are not charged.
14
+
15
+ Get a key at **[catastrogps.es/developers](https://www.catastrogps.es/developers)**.
10
16
 
11
- Add to your `claude_desktop_config.json`:
17
+ ## Install
18
+
19
+ ### Claude Desktop
12
20
 
13
21
  ```json
14
22
  {
15
23
  "mcpServers": {
16
- "catastrogps": {
24
+ "catastro-gps": {
17
25
  "command": "npx",
18
- "args": ["-y", "catastrogps-mcp"],
19
- "env": {
20
- "CATASTROGPS_API_KEY": "pk_live_YOUR_KEY_HERE"
21
- }
26
+ "args": ["-y", "catastro-gps-mcp"],
27
+ "env": { "CATASTROGPS_API_KEY": "pk_live_your_key_here" }
22
28
  }
23
29
  }
24
30
  }
@@ -27,104 +33,150 @@ Add to your `claude_desktop_config.json`:
27
33
  ### Claude Code
28
34
 
29
35
  ```bash
30
- claude mcp add catastrogps -- npx -y catastrogps-mcp
36
+ claude mcp add catastro-gps --env CATASTROGPS_API_KEY=pk_live_your_key_here -- npx -y catastro-gps-mcp
31
37
  ```
32
38
 
33
- Then set the environment variable `CATASTROGPS_API_KEY=pk_live_YOUR_KEY_HERE`.
39
+ ### Cursor, Windsurf, VS Code and other MCP clients
40
+
41
+ Use the same `npx -y catastro-gps-mcp` command with `CATASTROGPS_API_KEY` in the environment.
42
+
43
+ ## Tools
34
44
 
35
- ### SSE (Remote / Web Agents)
45
+ | Tool | What it does | Countries |
46
+ |------|--------------|-----------|
47
+ | `get_parcel` | Parcel by cadastral reference **or** WGS84 coordinates: reference, location, address, municipality, area, land use, outline | All 31 codes (UK: coordinates only) |
48
+ | `search_address` | Spanish postal address in free text → cadastral reference | Spain, central Catastro |
49
+ | `get_boundaries` | Parcel outline as GeoJSON / `[lat, lng]` ring, centroid and area | 30 codes (all but UK) |
50
+ | `get_solar_potential` | PVGIS photovoltaic estimate: kWp, kWh/year, savings, payback, CO₂, tilt | ES, PV, NA, PT, FR, IT, DE |
51
+ | `get_agriculture` | Land use, main crop, NDVI and a reference crop price (SIGPAC detail in Spain) | ES, PV, NA, PT, FR, IT, DE |
52
+ | `get_market_data` | Aggregated price reference for the parcel's area. Never individual sales | Figures: FR, IT, DE (NRW only). ES, PV, NA, PT: note without figures |
53
+ | `get_investment_score` | Score 0–100 with a rating and qualitative factor levels (high / medium / low / not available) | ES, PV, NA, PT, FR, IT, DE |
54
+ | `get_value_history` | Area and land-use snapshots of the parcel over time | ES, PV, NA, PT, FR, IT, DE, AT |
55
+ | `compare_parcels` | Two or three parcels side by side: location, solar, agriculture, score | ES, PT, FR, IT, DE (not PV or NA) |
56
+
57
+ Every tool call is one API call against your monthly quota, including calls that end in "not found". `compare_parcels` is one call for the whole comparison.
58
+
59
+ ### What the market, score and history tools can and cannot tell
60
+
61
+ - **`get_market_data`** has numbers only where an official source gives them: France (DVF recorded sales: average €/m², number of sales, last sale date, estimated value), Italy (OMI zone values from the Agenzia delle Entrate) and Germany (official *Bodenrichtwert* land value per m², North Rhine-Westphalia only; elsewhere in Germany it answers `available: false`). In Spain and Portugal it answers with a note and no figures: there is no per-parcel price source yet.
62
+ - **`get_investment_score`** combines what the API can gather for the parcel: solar potential and agricultural use everywhere it answers, market prices only in France, Italy and Germany (NRW). Accessibility and risk are not computed yet and come back as `not_available`, so the score is relative to the factors that were available. You get the score, the rating and qualitative factor levels, never the weights.
63
+ - **`get_value_history`** starts the first time anyone looks the parcel up through Catastro GPS (at most one snapshot every 30 days). A parcel nobody has queried returns an empty list. It records area and land use; the official cadastral value is not recorded yet, so `cadastral_value_eur` is always `null` and `change_pct` is the change in area.
64
+ - **`compare_parcels`** fills area, land use and municipality only for Spanish parcels; for Portugal, France, Italy and Germany it returns the location, solar, agriculture and score. It does not include market prices. A parcel that is not found comes back with an error and the others are still compared.
65
+
66
+ ## Coverage
67
+
68
+ What each code answers today. "Partial" means the official source does not cover the whole territory.
69
+
70
+ | Code | Country / region | By reference | By coordinates | Geometry | Notes |
71
+ |------|------------------|:---:|:---:|:---:|-------|
72
+ | `ES` | Spain (central Catastro) | ✅ | ✅ | ✅ | Free-text address search too |
73
+ | `PV` | Basque Country (Álava, Bizkaia, Gipuzkoa) | ✅ | ✅ | ✅ | Foral cadastres, separate from the central Catastro |
74
+ | `NA` | Navarre | ✅ | ✅ | ✅ | Foral cadastre |
75
+ | `PT` | Portugal | Partial | ✅ | Partial | Digital cadastre does not cover the whole country |
76
+ | `FR` | France | ✅ | ✅ | ✅ | |
77
+ | `IT` | Italy | ✅ | ✅ | ✅ | |
78
+ | `DE` | Germany | Partial | Partial | Partial | Every Land except Bavaria |
79
+ | `AT` | Austria | ✅ | ✅ | ✅ | |
80
+ | `CH` | Switzerland | ✅ | ✅ | ✅ | E-GRID references |
81
+ | `LI` | Liechtenstein | ✅ | ✅ | ✅ | |
82
+ | `BE` | Belgium | ✅ | ✅ | ✅ | |
83
+ | `NL` | Netherlands | ✅ | ✅ | ✅ | |
84
+ | `LU` | Luxembourg | ✅ | ✅ | ✅ | |
85
+ | `PL` | Poland | ✅ | ✅ | ✅ | TERYT parcel IDs |
86
+ | `CZ` | Czechia | ✅ | ✅ | ✅ | |
87
+ | `SK` | Slovakia | ✅ | ✅ | ✅ | |
88
+ | `SI` | Slovenia | ✅ | ✅ | ✅ | |
89
+ | `HR` | Croatia | ✅ | ✅ | ✅ | |
90
+ | `BG` | Bulgaria | ✅ | ✅ | ✅ | |
91
+ | `GR` | Greece | ✅ | ✅ | ✅ | |
92
+ | `CY` | Cyprus | ✅ | ✅ | ✅ | |
93
+ | `DK` | Denmark | ✅ | ✅ | ✅ | |
94
+ | `SE` | Sweden | ✅ | ✅ | ✅ | Agricultural blocks (Jordbruksverket), not property units |
95
+ | `NO` | Norway | ✅ | ✅ | ✅ | |
96
+ | `FI` | Finland | ✅ | ✅ | ✅ | |
97
+ | `IS` | Iceland | ✅ | ✅ | ✅ | |
98
+ | `EE` | Estonia | ✅ | ✅ | ✅ | |
99
+ | `LV` | Latvia | ✅ | ✅ | ✅ | |
100
+ | `LT` | Lithuania | ✅ | ✅ | ✅ | |
101
+ | `IE` | Ireland | ✅ | ✅ | ✅ | |
102
+ | `UK` | United Kingdom | — | Scotland | Scotland | Registers of Scotland; England, Wales and Northern Ireland not yet |
103
+
104
+ Data comes live from each country's official cadastre or INSPIRE service, so availability follows theirs: some national services are slow, and the server raises a clear `SERVICE_UNAVAILABLE` when one is down. Outside the table, a point or reference answers `CNV_COVERAGE`.
105
+
106
+ Official registry documents (Spanish *nota simple*, Italian *visura*, Portuguese *certidão permanente* and others) can be ordered at [catastrogps.es](https://www.catastrogps.es). They are not exposed through the API or this server yet.
107
+
108
+ ## Examples
109
+
110
+ Ask your agent:
111
+
112
+ > Find the cadastral parcel at Calle Mallorca 213, Barcelona, and give me its area and outline.
113
+
114
+ > What is the parcel at 52.2297, 21.0122? What's its area?
115
+
116
+ > Look up the Polish parcel 146510_8.0502.1/3 and tell me its area.
117
+
118
+ > Compare the solar potential of these two rural parcels in Navarre and Portugal.
119
+
120
+ > Compare these three parcels in Spain, France and Italy and tell me which has the best investment score.
121
+
122
+ > What do land prices look like around the French parcel 75056000AB0001?
123
+
124
+ What a `get_parcel` call returns (shortened; values are illustrative):
36
125
 
37
126
  ```json
38
127
  {
39
- "mcpServers": {
40
- "catastrogps": {
41
- "url": "https://mcp.catastrogps.es/sse",
42
- "headers": {
43
- "X-API-Key": "pk_live_YOUR_KEY_HERE"
44
- }
45
- }
46
- }
128
+ "reference": "9872023VH5797S0001WX",
129
+ "country": "ES",
130
+ "latitude": 40.4165,
131
+ "longitude": -3.7038,
132
+ "address": "CL MAYOR 1",
133
+ "municipality": "MADRID",
134
+ "province": "MADRID",
135
+ "area_m2": 512,
136
+ "land_use": "Residencial",
137
+ "outline_lat_lng": [[40.41662, -3.70391], [40.41671, -3.70362], "..."],
138
+ "google_maps_url": "https://maps.google.com/?q=40.4165,-3.7038"
47
139
  }
48
140
  ```
49
141
 
50
- ## Get an API Key
51
-
52
- 1. Sign up at [catastrogps.es](https://catastrogps.es)
53
- 2. Go to **Settings > API Keys**
54
- 3. Create a new key
55
- 4. Copy the `pk_live_xxx` key (shown only once)
56
-
57
- ## Tools
58
-
59
- | Tool | Description | Cost |
60
- |------|-------------|------|
61
- | `get_parcel` | Get cadastral data by reference or GPS coordinates | 1 call |
62
- | `get_solar_potential` | Solar energy potential (PVGIS) | 1 call |
63
- | `get_agriculture` | Land use, NDVI, crop prices | 1 call |
64
- | `get_market_data` | Real estate transactions and prices | 1 call |
65
- | `get_investment_score` | Investment score 1-10 | 1 call |
66
- | `get_value_history` | Historical cadastral value | 1 call |
67
- | `compare_parcels` | Compare 2-3 parcels side by side | 2 calls |
142
+ Errors come back as a code plus a sentence the agent can act on, for example:
68
143
 
69
- ## Supported Countries
70
-
71
- | Code | Country | Source |
72
- |------|---------|--------|
73
- | `ES` | Spain | Catastro Nacional (SOAP) |
74
- | `PV` | Basque Country | WFS INSPIRE (3 provinces) |
75
- | `NA` | Navarra | WFS IDENA |
76
- | `PT` | Portugal | OGC API DGT |
77
- | `FR` | France | Geoplateforme IGN + DVF |
78
- | `IT` | Italy | WFS Agenzia Entrate |
79
- | `DE` | Germany (NRW) | WFS NRW ALKIS |
80
-
81
- ## Example Usage
82
-
83
- Ask Claude:
84
-
85
- > "What's the solar potential of parcel 9872323VK2897S0001WX in Spain?"
144
+ ```text
145
+ CNV_COVERAGE: That reference or point is in a country that is not covered yet.
146
+ SERVICE_UNAVAILABLE: The official cadastre for this country is not responding. Try again in a few minutes.
147
+ KEY_AUTH_004: Monthly quota exhausted. Upgrade at https://catastrogps.es/developers
148
+ ```
86
149
 
87
- > "Compare these two parcels: 9872323VK2897S0001WX in Spain and 750560000AB0001 in France"
150
+ ## Pricing
88
151
 
89
- > "Find the parcel at coordinates 40.4165, -3.7038 in Spain and give me its investment score"
152
+ The same key works for this server, the REST API and the SDKs ([`catastrogps`](https://www.npmjs.com/package/catastrogps) on npm and PyPI).
90
153
 
91
- ## Pricing
154
+ | Plan | Price | Calls / month |
155
+ |------|-------|---------------|
156
+ | Free | €0, forever | 100 |
157
+ | Developer | €19 / month | 5,000 |
158
+ | Startup | €49 / month | 15,000 |
159
+ | Growth | €99 / month | 50,000 |
160
+ | Enterprise | Contact us | Custom |
92
161
 
93
- | Tier | Price | Calls/month |
94
- |------|-------|-------------|
95
- | Free | 0€ | 100 |
96
- | Developer | 19€/mo | 5,000 |
97
- | Startup | 49€/mo | 15,000 |
98
- | Growth | 99€/mo | 50,000 |
99
- | Enterprise | Contact | Unlimited + SLA |
100
- | Overage | 0.01€/call | Beyond tier limit |
162
+ Details and sign-up: [catastrogps.es/developers](https://www.catastrogps.es/developers).
101
163
 
102
- ## Environment Variables
164
+ ## Configuration
103
165
 
104
166
  | Variable | Required | Default | Description |
105
167
  |----------|----------|---------|-------------|
106
- | `CATASTROGPS_API_KEY` | Yes | — | Your API key (`pk_live_xxx`) |
107
- | `CATASTROGPS_API_URL` | No | `https://api.catastrogps.es` | Backend API URL |
108
- | `CATASTROGPS_TIMEOUT` | No | `10000` | Request timeout (ms) |
109
- | `MCP_PORT` | No | `3001` | SSE server port |
168
+ | `CATASTROGPS_API_KEY` | Yes | | Your API key |
169
+ | `CATASTROGPS_TIMEOUT` | No | `20000` | Request timeout in ms. Official cadastres can be slow |
170
+ | `CATASTROGPS_API_URL` | No | `https://api.parcelgps.com` | API base URL |
110
171
 
111
172
  ## Development
112
173
 
113
174
  ```bash
114
- # Install dependencies
115
175
  npm install
116
-
117
- # Build
118
- npm run build
119
-
120
- # Run locally (stdio)
121
- CATASTROGPS_API_KEY=pk_test_xxx node build/index.js
122
-
123
- # Run SSE server
124
- CATASTROGPS_API_KEY=pk_test_xxx node build/sse.js
125
-
126
- # Run tests
176
+ npm run lint
127
177
  npm test
178
+ npm run build
179
+ CATASTROGPS_API_KEY=pk_live_xxx node build/index.js
128
180
  ```
129
181
 
130
182
  ## License
@@ -1,24 +1,28 @@
1
- import type { ServerConfig, ApiResponse, ParcelData, PolygonData, SolarData, AgroData, MarketData, ScoreData, ValueHistoryData, CompareData, CoordinatesSearchData } from "../types/index.js";
1
+ import type { ServerConfig, ApiResponse, ParcelData, PolygonData, SolarData, AgroData, MarketData, ScoreData, ValueHistoryData, CompareData, CoordinatesSearchData, AddressSearchData } from "../types/index.js";
2
2
  export declare class CatastroGPSApiError extends Error {
3
3
  readonly code: string;
4
4
  readonly status: number;
5
- constructor(code: string, message: string, status: number);
5
+ readonly details?: unknown | undefined;
6
+ readonly resetsAt?: string | undefined;
7
+ constructor(code: string, message: string, status: number, details?: unknown | undefined, resetsAt?: string | undefined);
6
8
  }
7
9
  export declare class CatastroGPSClient {
8
10
  private readonly apiKey;
9
11
  private readonly baseUrl;
10
12
  private readonly timeout;
11
13
  constructor(config: ServerConfig);
12
- private request;
13
- private post;
14
- getParcelByReference(reference: string, country: string): Promise<ApiResponse<ParcelData>>;
15
- getParcelByCoordinates(lat: number, lng: number, country: string): Promise<ApiResponse<CoordinatesSearchData>>;
16
- getPolygon(reference: string, country: string): Promise<ApiResponse<PolygonData>>;
17
- getSolarPotential(reference: string, country: string): Promise<ApiResponse<SolarData>>;
18
- getAgriculture(reference: string, country: string): Promise<ApiResponse<AgroData>>;
19
- getMarketData(reference: string, country: string): Promise<ApiResponse<MarketData>>;
20
- getInvestmentScore(reference: string, country: string): Promise<ApiResponse<ScoreData>>;
21
- getValueHistory(reference: string, country: string): Promise<ApiResponse<ValueHistoryData>>;
14
+ private buildUrl;
15
+ private send;
16
+ private parcelPath;
17
+ getParcelByReference(reference: string, country?: string): Promise<ApiResponse<ParcelData>>;
18
+ getParcelByCoordinates(lat: number, lng: number, country?: string): Promise<ApiResponse<CoordinatesSearchData>>;
19
+ searchAddress(address: string): Promise<ApiResponse<AddressSearchData>>;
20
+ getPolygon(reference: string, country?: string): Promise<ApiResponse<PolygonData>>;
21
+ getSolarPotential(reference: string, country?: string): Promise<ApiResponse<SolarData>>;
22
+ getAgriculture(reference: string, country?: string): Promise<ApiResponse<AgroData>>;
23
+ getMarketData(reference: string, country?: string): Promise<ApiResponse<MarketData>>;
24
+ getInvestmentScore(reference: string, country?: string): Promise<ApiResponse<ScoreData>>;
25
+ getValueHistory(reference: string, country?: string): Promise<ApiResponse<ValueHistoryData>>;
22
26
  compareParcels(parcels: Array<{
23
27
  reference: string;
24
28
  country: string;
@@ -1,10 +1,15 @@
1
+ import { USER_AGENT } from "../version.js";
1
2
  export class CatastroGPSApiError extends Error {
2
3
  code;
3
4
  status;
4
- constructor(code, message, status) {
5
+ details;
6
+ resetsAt;
7
+ constructor(code, message, status, details, resetsAt) {
5
8
  super(message);
6
9
  this.code = code;
7
10
  this.status = status;
11
+ this.details = details;
12
+ this.resetsAt = resetsAt;
8
13
  this.name = "CatastroGPSApiError";
9
14
  }
10
15
  }
@@ -17,64 +22,36 @@ export class CatastroGPSClient {
17
22
  this.baseUrl = config.apiUrl.replace(/\/$/, "");
18
23
  this.timeout = config.timeout;
19
24
  }
20
- async request(path, params) {
21
- const url = new URL(path, this.baseUrl);
22
- if (params) {
23
- for (const [key, value] of Object.entries(params)) {
24
- if (value !== undefined && value !== "") {
25
- url.searchParams.set(key, value);
26
- }
25
+ buildUrl(path, params) {
26
+ const url = new URL(`${this.baseUrl}${path}`);
27
+ for (const [key, value] of Object.entries(params ?? {})) {
28
+ if (value !== undefined && value !== "") {
29
+ url.searchParams.set(key, String(value));
27
30
  }
28
31
  }
29
- const controller = new AbortController();
30
- const timeoutId = setTimeout(() => controller.abort(), this.timeout);
31
- try {
32
- const response = await fetch(url.toString(), {
33
- method: "GET",
34
- headers: {
35
- "X-API-Key": this.apiKey,
36
- "Accept": "application/json",
37
- "User-Agent": "catastro-gps-mcp/1.0.1",
38
- },
39
- signal: controller.signal,
40
- });
41
- if (!response.ok) {
42
- const body = await response.json().catch(() => ({}));
43
- throw new CatastroGPSApiError(body.code || `HTTP_${response.status}`, body.error || `API returned ${response.status}`, response.status);
44
- }
45
- return (await response.json());
46
- }
47
- catch (error) {
48
- if (error instanceof CatastroGPSApiError)
49
- throw error;
50
- if (error instanceof Error && error.name === "AbortError") {
51
- throw new CatastroGPSApiError("MCP_TIMEOUT", "Request timed out", 408);
52
- }
53
- throw new CatastroGPSApiError("MCP_NETWORK", `Network error: ${error instanceof Error ? error.message : "unknown"}`, 0);
54
- }
55
- finally {
56
- clearTimeout(timeoutId);
57
- }
32
+ return url.toString();
58
33
  }
59
- async post(path, body) {
60
- const url = new URL(path, this.baseUrl);
34
+ async send(method, path, params, body) {
61
35
  const controller = new AbortController();
62
36
  const timeoutId = setTimeout(() => controller.abort(), this.timeout);
37
+ const headers = {
38
+ "X-API-Key": this.apiKey,
39
+ Accept: "application/json",
40
+ "User-Agent": USER_AGENT,
41
+ };
42
+ if (body !== undefined) {
43
+ headers["Content-Type"] = "application/json";
44
+ }
63
45
  try {
64
- const response = await fetch(url.toString(), {
65
- method: "POST",
66
- headers: {
67
- "X-API-Key": this.apiKey,
68
- "Content-Type": "application/json",
69
- "Accept": "application/json",
70
- "User-Agent": "catastro-gps-mcp/1.0.1",
71
- },
72
- body: JSON.stringify(body),
46
+ const response = await fetch(this.buildUrl(path, params), {
47
+ method,
48
+ headers,
49
+ body: body === undefined ? undefined : JSON.stringify(body),
73
50
  signal: controller.signal,
74
51
  });
75
52
  if (!response.ok) {
76
- const resBody = await response.json().catch(() => ({}));
77
- throw new CatastroGPSApiError(resBody.code || `HTTP_${response.status}`, resBody.error || `API returned ${response.status}`, response.status);
53
+ const errorBody = (await response.json().catch(() => ({})));
54
+ throw new CatastroGPSApiError(errorBody.code || `HTTP_${response.status}`, errorBody.error || errorBody.message || `API returned ${response.status}`, response.status, errorBody.data ?? errorBody.parsed, response.headers.get("X-RateLimit-Reset") ?? undefined);
78
55
  }
79
56
  return (await response.json());
80
57
  }
@@ -90,45 +67,40 @@ export class CatastroGPSClient {
90
67
  clearTimeout(timeoutId);
91
68
  }
92
69
  }
93
- // GET /api/catastro/:refcat?country=XX
70
+ parcelPath(reference, suffix = "") {
71
+ return `/api/catastro/${encodeURIComponent(reference)}${suffix}`;
72
+ }
94
73
  async getParcelByReference(reference, country) {
95
- return this.request(`/api/catastro/${encodeURIComponent(reference)}`, { country });
74
+ return this.send("GET", this.parcelPath(reference), { country });
96
75
  }
97
- // POST /api/search/coordinates
98
76
  async getParcelByCoordinates(lat, lng, country) {
99
- return this.post("/api/search/coordinates", {
100
- latitude: lat,
101
- longitude: lng,
102
- country,
103
- });
77
+ return this.send("GET", "/api/search/coordinates", { lat, lng, country });
78
+ }
79
+ async searchAddress(address) {
80
+ return this.send("POST", "/api/search/address/parse", undefined, { direccion: address });
104
81
  }
105
- // GET /api/catastro/:refcat/polygon?country=XX
106
82
  async getPolygon(reference, country) {
107
- return this.request(`/api/catastro/${encodeURIComponent(reference)}/polygon`, { country });
83
+ return this.send("GET", this.parcelPath(reference, "/polygon"), { country });
108
84
  }
109
- // GET /api/catastro/:refcat/solar?country=XX
110
85
  async getSolarPotential(reference, country) {
111
- return this.request(`/api/catastro/${encodeURIComponent(reference)}/solar`, { country });
86
+ return this.send("GET", this.parcelPath(reference, "/solar"), { country });
112
87
  }
113
- // GET /api/catastro/:refcat/agro?country=XX
114
88
  async getAgriculture(reference, country) {
115
- return this.request(`/api/catastro/${encodeURIComponent(reference)}/agro`, { country });
89
+ return this.send("GET", this.parcelPath(reference, "/agro"), { country });
116
90
  }
117
- // GET /api/catastro/:refcat/mercado?country=XX
118
91
  async getMarketData(reference, country) {
119
- return this.request(`/api/catastro/${encodeURIComponent(reference)}/mercado`, { country });
92
+ return this.send("GET", this.parcelPath(reference, "/market"), { country });
120
93
  }
121
- // GET /api/catastro/:refcat/score?country=XX
122
94
  async getInvestmentScore(reference, country) {
123
- return this.request(`/api/catastro/${encodeURIComponent(reference)}/score`, { country });
95
+ return this.send("GET", this.parcelPath(reference, "/score"), { country });
124
96
  }
125
- // GET /api/catastro/:refcat/historico-valor?country=XX
126
97
  async getValueHistory(reference, country) {
127
- return this.request(`/api/catastro/${encodeURIComponent(reference)}/historico-valor`, { country });
98
+ return this.send("GET", this.parcelPath(reference, "/value-history"), { country });
128
99
  }
129
- // POST /api/catastro/comparar
130
100
  async compareParcels(parcels) {
131
- return this.post("/api/catastro/comparar", { parcels });
101
+ return this.send("POST", "/api/catastro/compare", undefined, {
102
+ parcelas: parcels.map((parcel) => ({ ref_catastral: parcel.reference, country: parcel.country })),
103
+ });
132
104
  }
133
105
  }
134
106
  //# sourceMappingURL=catastrogps-api.js.map
package/build/index.d.ts CHANGED
@@ -1,12 +1,3 @@
1
1
  #!/usr/bin/env node
2
- /**
3
- * Catastro GPS MCP Server — stdio transport
4
- *
5
- * Entry point for Claude Desktop, Claude Code, and other MCP clients
6
- * that use the stdio transport (JSON-RPC over stdin/stdout).
7
- *
8
- * Usage:
9
- * CATASTROGPS_API_KEY=pk_live_xxx npx catastro-gps-mcp
10
- */
11
2
  export {};
12
3
  //# sourceMappingURL=index.d.ts.map
package/build/index.js CHANGED
@@ -1,13 +1,4 @@
1
1
  #!/usr/bin/env node
2
- /**
3
- * Catastro GPS MCP Server — stdio transport
4
- *
5
- * Entry point for Claude Desktop, Claude Code, and other MCP clients
6
- * that use the stdio transport (JSON-RPC over stdin/stdout).
7
- *
8
- * Usage:
9
- * CATASTROGPS_API_KEY=pk_live_xxx npx catastro-gps-mcp
10
- */
11
2
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
12
3
  import { createServer, loadConfig } from "./server.js";
13
4
  const log = (msg) => console.error(`[catastro-gps-mcp] ${msg}`);
package/build/server.d.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import type { ServerConfig } from "./types/index.js";
3
+ export declare const DEFAULT_API_URL = "https://api.parcelgps.com";
4
+ export declare const DEFAULT_TIMEOUT_MS = 20000;
3
5
  export declare function createServer(config: ServerConfig): McpServer;
4
6
  export declare function loadConfig(): ServerConfig;
5
7
  //# sourceMappingURL=server.d.ts.map
package/build/server.js CHANGED
@@ -1,21 +1,25 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { CatastroGPSClient } from "./client/catastrogps-api.js";
3
3
  import { registerGetParcel } from "./tools/get-parcel.js";
4
+ import { registerSearchAddress } from "./tools/search-address.js";
5
+ import { registerGetBoundaries } from "./tools/get-boundaries.js";
4
6
  import { registerGetSolar } from "./tools/get-solar.js";
5
7
  import { registerGetAgriculture } from "./tools/get-agriculture.js";
6
8
  import { registerGetMarket } from "./tools/get-market.js";
7
9
  import { registerGetScore } from "./tools/get-score.js";
8
10
  import { registerGetValueHistory } from "./tools/get-value-history.js";
9
11
  import { registerCompareParcels } from "./tools/compare-parcels.js";
10
- import { registerGetBoundaries } from "./tools/get-boundaries.js";
12
+ import { SERVER_VERSION } from "./version.js";
13
+ export const DEFAULT_API_URL = "https://api.parcelgps.com";
14
+ export const DEFAULT_TIMEOUT_MS = 20000;
11
15
  export function createServer(config) {
12
16
  const server = new McpServer({
13
17
  name: "catastrogps",
14
- version: "1.0.0",
18
+ version: SERVER_VERSION,
15
19
  });
16
20
  const client = new CatastroGPSClient(config);
17
- // Register all 8 tools
18
21
  registerGetParcel(server, client);
22
+ registerSearchAddress(server, client);
19
23
  registerGetBoundaries(server, client);
20
24
  registerGetSolar(server, client);
21
25
  registerGetAgriculture(server, client);
@@ -29,13 +33,14 @@ export function loadConfig() {
29
33
  const apiKey = process.env.CATASTROGPS_API_KEY;
30
34
  if (!apiKey) {
31
35
  console.error("[catastro-gps-mcp] ERROR: CATASTROGPS_API_KEY environment variable is required.\n" +
32
- "Get your API key at https://catastrogps.es/api");
36
+ "Get a free key (250 calls/month, failed lookups are free) at https://catastrogps.es/developers");
33
37
  process.exit(1);
34
38
  }
39
+ const timeout = parseInt(process.env.CATASTROGPS_TIMEOUT || "", 10);
35
40
  return {
36
41
  apiKey,
37
- apiUrl: process.env.CATASTROGPS_API_URL || "https://api.catastrogps.es",
38
- timeout: parseInt(process.env.CATASTROGPS_TIMEOUT || "10000", 10),
42
+ apiUrl: process.env.CATASTROGPS_API_URL || DEFAULT_API_URL,
43
+ timeout: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_TIMEOUT_MS,
39
44
  };
40
45
  }
41
46
  //# sourceMappingURL=server.js.map
package/build/sse.d.ts CHANGED
@@ -1,12 +1,3 @@
1
1
  #!/usr/bin/env node
2
- /**
3
- * Catastro GPS MCP Server — SSE transport
4
- *
5
- * HTTP server for web-based MCP clients and remote agents.
6
- * Exposes SSE endpoint at /sse and message endpoint at /message.
7
- *
8
- * Usage:
9
- * CATASTROGPS_API_KEY=pk_live_xxx MCP_PORT=3001 node build/sse.js
10
- */
11
2
  export {};
12
3
  //# sourceMappingURL=sse.d.ts.map