catastro-gps-mcp 1.2.2 → 1.3.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.
- package/CHANGELOG.md +20 -0
- package/README.md +55 -51
- package/build/client/catastrogps-api.d.ts +21 -11
- package/build/client/catastrogps-api.js +85 -19
- package/build/server.js +6 -0
- package/build/tools/compare-parcels.js +3 -3
- package/build/tools/get-agriculture.js +2 -2
- package/build/tools/get-boundaries.js +2 -2
- package/build/tools/get-ground-motion.d.ts +4 -0
- package/build/tools/get-ground-motion.js +48 -0
- package/build/tools/get-market.js +2 -2
- package/build/tools/get-parcel.js +6 -6
- package/build/tools/get-score.js +2 -2
- package/build/tools/get-solar.js +2 -2
- package/build/tools/get-terrain.js +24 -13
- package/build/tools/get-units.d.ts +4 -0
- package/build/tools/get-units.js +73 -0
- package/build/tools/get-value-history.js +2 -2
- package/build/tools/resolve-reference.d.ts +4 -0
- package/build/tools/resolve-reference.js +33 -0
- package/build/tools/search-address.js +50 -24
- package/build/tools/shared.d.ts +13 -1
- package/build/tools/shared.js +56 -4
- package/build/types/index.d.ts +169 -7
- package/build/types/index.js +11 -0
- package/build/version.d.ts +2 -2
- package/build/version.js +1 -1
- package/package.json +11 -4
- package/server.json +9 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.3.1 (2026-10-05)
|
|
4
|
+
|
|
5
|
+
- Coverage stated with the real numbers in README, package.json, manifest.json, server.json and the `get_parcel` description: 29 European countries, 31 official cadastres including the Basque Country and Navarre.
|
|
6
|
+
|
|
7
|
+
## 1.3.0 (2026-10-05)
|
|
8
|
+
|
|
9
|
+
- `search_address` now uses `GET /api/search/address/candidates`: ranked candidates with confidence in Spain and 26 more countries (`country`, `limit`), instead of the live Spanish street index only. Sweden and Croatia answer `CNV_COVERAGE`.
|
|
10
|
+
- New `get_units`: every unit of a Spanish building (ES, PV, NA) with stair, floor, door, use, area, participation and year, page by page with `cursor`. Costs one quota unit per unit served.
|
|
11
|
+
- New `resolve_reference`: free classification of a text as reference, coordinates or place name per country (`GET /api/resolve`).
|
|
12
|
+
- `get_terrain` returns the ERA5-Land `climate` block. `get_terrain` and `get_ground_motion` accept every reference country except Croatia, with `latitude`/`longitude` outside ES, PV, NA, PT, FR, IT and DE.
|
|
13
|
+
- Every result carries a `quota` object from its own response: monthly quota, prepaid overage balance, units the balance still covers, per-minute headroom and the per-finca cap on `get_units`.
|
|
14
|
+
- `KEY_AUTH_004` says whether to top up the prepaid balance or upgrade; `KEY_RATE_002` says how many seconds to wait.
|
|
15
|
+
- Fixed: the per-minute limiter was read as the monthly quota when `X-Quota-Limit` was missing; `compare_parcels` description now says it costs one unit per parcel found.
|
|
16
|
+
- Directory metadata (server.json, manifest.json, smithery.yaml) at 1.3.0 with the 13 tools.
|
|
17
|
+
|
|
18
|
+
## 1.2.2
|
|
19
|
+
|
|
20
|
+
- `get_ground_motion` (Copernicus EGMS) and `get_terrain` (Copernicus DEM, Natura 2000).
|
package/README.md
CHANGED
|
@@ -2,14 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
<!-- mcp-name: com.parcelgps/catastro-gps -->
|
|
4
4
|
|
|
5
|
-
Official cadastral parcels for AI agents
|
|
5
|
+
Official cadastral parcels for AI agents from **29 European countries (31 official cadastres, including the Basque Country and Navarre)**, with one API key. In Croatia (ARKOD agricultural parcels), Sweden (agricultural blocks) and Scotland (by coordinates) the source is not a full cadastre.
|
|
6
6
|
|
|
7
|
-
Ask your agent for a parcel by its cadastral reference, by a point on the map or
|
|
7
|
+
Ask your agent for a parcel by its cadastral reference, by a point on the map or by a postal address. It gets back the reference, location, area, land use and the parcel outline; it can list every dwelling of a Spanish building, read relief, protected areas, climate normals and satellite ground motion, estimate solar and agricultural potential, read aggregated market prices, and score and compare parcels.
|
|
8
8
|
|
|
9
|
-
- **31
|
|
10
|
-
- **The country is optional.** It is detected from the reference format or from the point.
|
|
11
|
-
- **
|
|
12
|
-
- **
|
|
9
|
+
- **31 cadastres, 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. When bare digits fit several countries the API says so (`CNV_AMBIGUOUS`) and `resolve_reference` tells you which ones, for free.
|
|
11
|
+
- **Address search in 27 countries.** `"Calle Gran Via 31, Madrid"`, `"8 boulevard du Port, Amiens"` or `"Damrak 1, 1012 LG Amsterdam"` become ranked parcels.
|
|
12
|
+
- **Buildings, not only plots.** `get_units` lists every dwelling, shop and garage of a Spanish building with floor, door, area and participation coefficient.
|
|
13
|
+
- **Your quota in every answer.** Each result carries the monthly quota left, the prepaid balance and the per-minute headroom.
|
|
13
14
|
- **Free tier for good.** 250 calls a month at no cost, no card. Failed lookups are not charged.
|
|
14
15
|
|
|
15
16
|
Get a key at **[parcelgps.com/developers](https://www.parcelgps.com/developers)**.
|
|
@@ -44,20 +45,27 @@ Use the same `npx -y catastro-gps-mcp` command with `CATASTROGPS_API_KEY` in the
|
|
|
44
45
|
|
|
45
46
|
| Tool | What it does | Countries |
|
|
46
47
|
|------|--------------|-----------|
|
|
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` |
|
|
48
|
+
| `get_parcel` | Parcel by cadastral reference **or** WGS84 coordinates: reference, location, address, municipality, area, land use, outline | All 31 codes (UK and HR: coordinates only) |
|
|
49
|
+
| `search_address` | Postal address in free text to ranked parcels, with confidence and whether the number and municipality match | ES (with PV and NA entrances) and FR, IT, DE, AT, NL, BE, PL, CH, CZ, DK, NO, FI, EE, LV, LT, SI, SK, BG, GR, CY, LU, LI, IS, IE, UK, PT |
|
|
50
|
+
| `get_units` | Every unit (dwelling, shop, garage, storage) of a Spanish building: stair, floor, door, use, area, participation, year. Paginated, 200 per page | ES, PV, NA |
|
|
51
|
+
| `resolve_reference` | Free, no quota: is this text a reference, coordinates or a place name, and of which country | All |
|
|
49
52
|
| `get_boundaries` | Parcel outline as GeoJSON / `[lat, lng]` ring, centroid and area | 30 codes (all but UK) |
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
53
|
+
| `get_terrain` | Relief over the parcel outline (Copernicus DEM GLO-30), Natura 2000 / protected areas (EEA) and ERA5-Land climate normals with the recent change | Every reference country but HR; outside ES, PV, NA, PT, FR, IT, DE pass `latitude`/`longitude` |
|
|
54
|
+
| `get_ground_motion` | Ground motion measured by satellite (Copernicus EGMS, 2020-2024): subsidence or uplift in mm/year, fastest-sinking cell, east-west motion, yearly displacement; says so when there are no radar reflectors | Same as `get_terrain` |
|
|
55
|
+
| `get_solar_potential` | PVGIS photovoltaic estimate: kWp, kWh/year, savings, payback, CO2, tilt | ES, PV, NA, PT, FR, IT, DE |
|
|
52
56
|
| `get_agriculture` | Land use, main crop, NDVI and a reference crop price (SIGPAC detail in Spain) | ES, PV, NA, PT, FR, IT, DE |
|
|
53
57
|
| `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 |
|
|
54
|
-
| `get_investment_score` | Score 0
|
|
58
|
+
| `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 |
|
|
55
59
|
| `get_value_history` | Area and land-use snapshots of the parcel over time | ES, PV, NA, PT, FR, IT, DE, AT |
|
|
56
60
|
| `compare_parcels` | Two or three parcels side by side: location, solar, agriculture, score | ES, PT, FR, IT, DE (not PV or NA) |
|
|
57
61
|
|
|
58
|
-
|
|
62
|
+
## Quota, prepaid balance and limits
|
|
59
63
|
|
|
60
|
-
|
|
64
|
+
- Only successful answers with data spend quota: a not found, a validation error, `CNV_COVERAGE`, `CNV_AMBIGUOUS`, a 5xx and an answer without data (`available: false`) are free. `resolve_reference` never spends.
|
|
65
|
+
- Each successful call costs 1 unit, except `get_units` (one unit per unit served in the page, minimum 1) and `compare_parcels` (one per parcel found).
|
|
66
|
+
- Every result carries a `quota` object read from that same response: `remaining`, `limit`, `resets_at`, `plan`, and when they apply `prepaid_overage`, `prepaid_balance_eur`, `overage_units_left`, `per_minute_remaining`, and on `get_units` with a contract per-finca cap `finca_cap` / `finca_cap_used`.
|
|
67
|
+
- When the monthly quota runs out the API does not cut you off if you have prepaid balance: each extra unit is paid from it (top up at [parcelgps.com/app/developer](https://parcelgps.com/app/developer)). With the quota used up and no balance the call fails with `KEY_AUTH_004` (HTTP 429, never 402) and the error says whether to top up or upgrade, and when the quota resets.
|
|
68
|
+
- A separate per-minute limit depends on the plan (Free 10, Developer 60, Startup 120, Growth 300 calls per minute; a global per-IP guard also applies). Going over it answers `KEY_RATE_002` with the seconds to wait.
|
|
61
69
|
|
|
62
70
|
### What the market, score and history tools can and cannot tell
|
|
63
71
|
|
|
@@ -68,43 +76,34 @@ The API reports the monthly quota of your plan in the `X-Quota-Limit`, `X-Quota-
|
|
|
68
76
|
|
|
69
77
|
## Coverage
|
|
70
78
|
|
|
71
|
-
What each code answers today. "Partial" means the official source does not cover the whole territory.
|
|
72
|
-
|
|
73
|
-
| Code | Country / region | By reference | By coordinates |
|
|
74
|
-
|
|
75
|
-
| `ES` | Spain (central Catastro) |
|
|
76
|
-
| `PV` | Basque Country (
|
|
77
|
-
| `NA` | Navarre |
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
| `FI` | Finland | ✅ | ✅ | ✅ | |
|
|
100
|
-
| `IS` | Iceland | ✅ | ✅ | ✅ | |
|
|
101
|
-
| `EE` | Estonia | ✅ | ✅ | ✅ | |
|
|
102
|
-
| `LV` | Latvia | ✅ | ✅ | ✅ | |
|
|
103
|
-
| `LT` | Lithuania | ✅ | ✅ | ✅ | |
|
|
104
|
-
| `IE` | Ireland | ✅ | ✅ | ✅ | |
|
|
105
|
-
| `UK` | United Kingdom | — | Scotland | Scotland | Registers of Scotland; England, Wales and Northern Ireland not yet |
|
|
106
|
-
|
|
107
|
-
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`.
|
|
79
|
+
What each code answers today (measured against production on 1 October 2026). "Partial" means the official source does not cover the whole territory.
|
|
80
|
+
|
|
81
|
+
| Code | Country / region | By reference | By coordinates | Address search | Notes |
|
|
82
|
+
|------|------------------|---|---|---|-------|
|
|
83
|
+
| `ES` | Spain (central Catastro) | yes | yes | yes | Buildings and dwellings with `get_units` |
|
|
84
|
+
| `PV` | Basque Country (Araba, Bizkaia, Gipuzkoa) | yes | yes | with `country: ES` | Foral cadastres; `get_units` without participation coefficient |
|
|
85
|
+
| `NA` | Navarre | yes | yes | with `country: ES` | Foral cadastre; `get_units` |
|
|
86
|
+
| `FR` | France | yes | yes | yes | |
|
|
87
|
+
| `IT` | Italy | yes | yes | yes | |
|
|
88
|
+
| `DE` | Germany | partial | partial | partial | 15 of 16 Lander: **not Bavaria** |
|
|
89
|
+
| `AT` | Austria | yes | yes | yes | |
|
|
90
|
+
| `NL` | Netherlands | yes | yes | yes | |
|
|
91
|
+
| `BE` | Belgium | yes | yes (slow source) | yes | |
|
|
92
|
+
| `PL` | Poland | yes | yes | yes | TERYT parcel IDs |
|
|
93
|
+
| `CH` | Switzerland | yes | partial | yes | Not in cantons that publish no parcels (e.g. Vaud) |
|
|
94
|
+
| `CZ` `DK` `NO` `FI` `EE` | Czechia, Denmark, Norway, Finland, Estonia | yes | yes | yes | |
|
|
95
|
+
| `LT` `SI` `SK` `BG` | Lithuania, Slovenia, Slovakia, Bulgaria | yes | yes | yes | |
|
|
96
|
+
| `LU` `LI` `IS` | Luxembourg, Liechtenstein, Iceland | yes | yes | yes | |
|
|
97
|
+
| `CY` | Cyprus | yes | yes | yes, low confidence | Few house numbers mapped |
|
|
98
|
+
| `LV` | Latvia | with `country: LV` | yes | yes | |
|
|
99
|
+
| `GR` | Greece | with `country: GR` | yes | yes | |
|
|
100
|
+
| `PT` | Portugal | yes | partial | partial | The cadastre does not cover Lisbon, Porto or Coimbra; the DGT source is often down |
|
|
101
|
+
| `IE` | Ireland | with `country: IE` (SP_ID) | partial | partial | |
|
|
102
|
+
| `UK` | United Kingdom | no | Scotland only | Scotland only | England, Wales and Northern Ireland not yet |
|
|
103
|
+
| `HR` | Croatia | no | ARKOD agricultural parcels only | no | No open cadastre; not Zagreb or Rijeka |
|
|
104
|
+
| `SE` | Sweden | agricultural blocks | agricultural blocks | no | Not property units |
|
|
105
|
+
|
|
106
|
+
Hungary, Romania and the rest of Europe are not covered: a reference or point there answers `CNV_COVERAGE`. Data comes from each country's official cadastre or INSPIRE service (Spain from our copy of the Catastro), so availability follows theirs; when one is down the server answers `SERVICE_UNAVAILABLE`, which is free.
|
|
108
107
|
|
|
109
108
|
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.
|
|
110
109
|
|
|
@@ -114,6 +113,10 @@ Ask your agent:
|
|
|
114
113
|
|
|
115
114
|
> Find the cadastral parcel at Calle Mallorca 213, Barcelona, and give me its area and outline.
|
|
116
115
|
|
|
116
|
+
> List every flat of the building at Avenida Jose Rodriguez de la Borbolla 10, Dos Hermanas, with floor, door and area.
|
|
117
|
+
|
|
118
|
+
> Is the ground sinking under parcel 30024A16000286? Is it inside a Natura 2000 site?
|
|
119
|
+
|
|
117
120
|
> What is the parcel at 52.2297, 21.0122? What's its area?
|
|
118
121
|
|
|
119
122
|
> Look up the Polish parcel 146510_8.0502.1/3 and tell me its area.
|
|
@@ -147,7 +150,7 @@ Errors come back as a code plus a sentence the agent can act on, for example:
|
|
|
147
150
|
```text
|
|
148
151
|
CNV_COVERAGE: That reference or point is in a country that is not covered yet.
|
|
149
152
|
SERVICE_UNAVAILABLE: The official cadastre for this country is not responding. Try again in a few minutes.
|
|
150
|
-
KEY_AUTH_004: Monthly quota
|
|
153
|
+
KEY_AUTH_004: Monthly quota used up and prepaid balance empty: top up at https://parcelgps.com/app/developer (or upgrade at https://www.parcelgps.com/developers).
|
|
151
154
|
```
|
|
152
155
|
|
|
153
156
|
## Pricing
|
|
@@ -178,6 +181,7 @@ Details and sign-up: [parcelgps.com/developers](https://www.parcelgps.com/develo
|
|
|
178
181
|
npm install
|
|
179
182
|
npm run lint
|
|
180
183
|
npm test
|
|
184
|
+
npm run test:coverage
|
|
181
185
|
npm run build
|
|
182
186
|
CATASTROGPS_API_KEY=pk_live_xxx node build/index.js
|
|
183
187
|
```
|
|
@@ -1,17 +1,18 @@
|
|
|
1
|
-
import type { ServerConfig, ApiResponse, ParcelData, PolygonData, SolarData, TerrainData, AgroData, MarketData, ScoreData, ValueHistoryData, CompareData, CoordinatesSearchData,
|
|
1
|
+
import type { Quota, ServerConfig, ApiResponse, ParcelData, PolygonData, SolarData, TerrainData, GroundMotionData, AgroData, MarketData, ScoreData, ValueHistoryData, CompareData, CoordinatesSearchData, AddressCandidatesData, UnitsPageData, ResolveData } from "../types/index.js";
|
|
2
|
+
export interface ApiErrorExtras {
|
|
3
|
+
quota?: Quota;
|
|
4
|
+
retryAfterSeconds?: number;
|
|
5
|
+
}
|
|
2
6
|
export declare class CatastroGPSApiError extends Error {
|
|
3
7
|
readonly code: string;
|
|
4
8
|
readonly status: number;
|
|
5
9
|
readonly details?: unknown | undefined;
|
|
6
|
-
readonly
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
plan?: string;
|
|
11
|
-
limit?: number;
|
|
12
|
-
remaining?: number;
|
|
13
|
-
resetsAt?: string;
|
|
10
|
+
readonly quota?: Quota;
|
|
11
|
+
readonly retryAfterSeconds?: number;
|
|
12
|
+
constructor(code: string, message: string, status: number, details?: unknown | undefined, extras?: ApiErrorExtras);
|
|
13
|
+
get resetsAt(): string | undefined;
|
|
14
14
|
}
|
|
15
|
+
export type { Quota };
|
|
15
16
|
export declare function readQuota(headers: Headers): Quota | undefined;
|
|
16
17
|
export declare class CatastroGPSClient {
|
|
17
18
|
private readonly apiKey;
|
|
@@ -24,10 +25,19 @@ export declare class CatastroGPSClient {
|
|
|
24
25
|
private parcelPath;
|
|
25
26
|
getParcelByReference(reference: string, country?: string): Promise<ApiResponse<ParcelData>>;
|
|
26
27
|
getParcelByCoordinates(lat: number, lng: number, country?: string): Promise<ApiResponse<CoordinatesSearchData>>;
|
|
27
|
-
|
|
28
|
+
searchAddressCandidates(address: string, country?: string, limit?: number): Promise<ApiResponse<AddressCandidatesData>>;
|
|
29
|
+
getUnits(reference: string, country?: string, cursor?: string): Promise<ApiResponse<UnitsPageData>>;
|
|
30
|
+
resolve(text: string, hint?: string): Promise<ApiResponse<ResolveData>>;
|
|
28
31
|
getPolygon(reference: string, country?: string): Promise<ApiResponse<PolygonData>>;
|
|
29
32
|
getSolarPotential(reference: string, country?: string): Promise<ApiResponse<SolarData>>;
|
|
30
|
-
getTerrain(reference: string, country?: string
|
|
33
|
+
getTerrain(reference: string, country?: string, point?: {
|
|
34
|
+
lat: number;
|
|
35
|
+
lng: number;
|
|
36
|
+
}): Promise<ApiResponse<TerrainData>>;
|
|
37
|
+
getGroundMotion(reference: string, country?: string, point?: {
|
|
38
|
+
lat: number;
|
|
39
|
+
lng: number;
|
|
40
|
+
}): Promise<ApiResponse<GroundMotionData>>;
|
|
31
41
|
getAgriculture(reference: string, country?: string): Promise<ApiResponse<AgroData>>;
|
|
32
42
|
getMarketData(reference: string, country?: string): Promise<ApiResponse<MarketData>>;
|
|
33
43
|
getInvestmentScore(reference: string, country?: string): Promise<ApiResponse<ScoreData>>;
|
|
@@ -3,30 +3,83 @@ export class CatastroGPSApiError extends Error {
|
|
|
3
3
|
code;
|
|
4
4
|
status;
|
|
5
5
|
details;
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
quota;
|
|
7
|
+
retryAfterSeconds;
|
|
8
|
+
constructor(code, message, status, details, extras = {}) {
|
|
8
9
|
super(message);
|
|
9
10
|
this.code = code;
|
|
10
11
|
this.status = status;
|
|
11
12
|
this.details = details;
|
|
12
|
-
this.resetsAt = resetsAt;
|
|
13
13
|
this.name = "CatastroGPSApiError";
|
|
14
|
+
this.quota = extras.quota;
|
|
15
|
+
this.retryAfterSeconds = extras.retryAfterSeconds;
|
|
16
|
+
}
|
|
17
|
+
get resetsAt() {
|
|
18
|
+
return this.quota?.resetsAt;
|
|
14
19
|
}
|
|
15
20
|
}
|
|
16
|
-
|
|
17
|
-
const
|
|
18
|
-
|
|
19
|
-
|
|
21
|
+
function numberHeader(headers, name) {
|
|
22
|
+
const raw = headers.get(name);
|
|
23
|
+
if (raw === null || raw.trim() === "")
|
|
24
|
+
return undefined;
|
|
25
|
+
const value = Number(raw);
|
|
26
|
+
return Number.isFinite(value) ? value : undefined;
|
|
27
|
+
}
|
|
28
|
+
function readOverage(headers) {
|
|
29
|
+
const flag = headers.get("X-Quota-Overage");
|
|
30
|
+
if (flag === null)
|
|
20
31
|
return undefined;
|
|
21
|
-
const limit = headers.get(`${family}-Limit`);
|
|
22
|
-
const remaining = headers.get(`${family}-Remaining`);
|
|
23
32
|
return {
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
33
|
+
enabled: flag.trim().toLowerCase() === "on",
|
|
34
|
+
balanceEur: numberHeader(headers, "X-Quota-Balance"),
|
|
35
|
+
unitPriceEur: numberHeader(headers, "X-Quota-Overage-Unit-Price"),
|
|
36
|
+
unitsLeft: numberHeader(headers, "X-Quota-Overage-Remaining"),
|
|
28
37
|
};
|
|
29
38
|
}
|
|
39
|
+
function readPerMinute(headers) {
|
|
40
|
+
if (!headers.has("X-RateLimit-Limit") && !headers.has("X-RateLimit-Remaining"))
|
|
41
|
+
return undefined;
|
|
42
|
+
return {
|
|
43
|
+
limit: numberHeader(headers, "X-RateLimit-Limit"),
|
|
44
|
+
remaining: numberHeader(headers, "X-RateLimit-Remaining"),
|
|
45
|
+
resetSeconds: numberHeader(headers, "X-RateLimit-Reset"),
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
function readFincaCap(headers) {
|
|
49
|
+
const cap = numberHeader(headers, "X-Quota-Finca-Cap");
|
|
50
|
+
if (cap === undefined)
|
|
51
|
+
return undefined;
|
|
52
|
+
return { cap, used: numberHeader(headers, "X-Quota-Finca-Cap-Used") };
|
|
53
|
+
}
|
|
54
|
+
export function readQuota(headers) {
|
|
55
|
+
const quota = {};
|
|
56
|
+
const plan = headers.get("X-Quota-Tier");
|
|
57
|
+
if (plan !== null)
|
|
58
|
+
quota.plan = plan;
|
|
59
|
+
const limit = numberHeader(headers, "X-Quota-Limit");
|
|
60
|
+
if (limit !== undefined)
|
|
61
|
+
quota.limit = limit;
|
|
62
|
+
const remaining = numberHeader(headers, "X-Quota-Remaining");
|
|
63
|
+
if (remaining !== undefined)
|
|
64
|
+
quota.remaining = remaining;
|
|
65
|
+
const resetsAt = headers.get("X-Quota-Reset");
|
|
66
|
+
if (resetsAt !== null)
|
|
67
|
+
quota.resetsAt = resetsAt;
|
|
68
|
+
const overage = readOverage(headers);
|
|
69
|
+
if (overage)
|
|
70
|
+
quota.overage = overage;
|
|
71
|
+
const perMinute = readPerMinute(headers);
|
|
72
|
+
if (perMinute)
|
|
73
|
+
quota.perMinute = perMinute;
|
|
74
|
+
const fincaCap = readFincaCap(headers);
|
|
75
|
+
if (fincaCap)
|
|
76
|
+
quota.fincaCap = fincaCap;
|
|
77
|
+
return Object.keys(quota).length > 0 ? quota : undefined;
|
|
78
|
+
}
|
|
79
|
+
function retryAfterSeconds(headers) {
|
|
80
|
+
const value = numberHeader(headers, "Retry-After");
|
|
81
|
+
return value !== undefined && value > 0 ? value : undefined;
|
|
82
|
+
}
|
|
30
83
|
export class CatastroGPSClient {
|
|
31
84
|
apiKey;
|
|
32
85
|
baseUrl;
|
|
@@ -69,9 +122,13 @@ export class CatastroGPSClient {
|
|
|
69
122
|
this.lastQuota = quota;
|
|
70
123
|
if (!response.ok) {
|
|
71
124
|
const errorBody = (await response.json().catch(() => ({})));
|
|
72
|
-
throw new CatastroGPSApiError(errorBody.code || `HTTP_${response.status}`, errorBody.error || errorBody.message || `API returned ${response.status}`, response.status, errorBody.data ?? errorBody.parsed, quota
|
|
125
|
+
throw new CatastroGPSApiError(errorBody.code || `HTTP_${response.status}`, errorBody.error || errorBody.message || `API returned ${response.status}`, response.status, errorBody.data ?? errorBody.parsed, { quota, retryAfterSeconds: retryAfterSeconds(response.headers) });
|
|
73
126
|
}
|
|
74
|
-
|
|
127
|
+
const payload = (await response.json());
|
|
128
|
+
if (quota && payload && typeof payload === "object") {
|
|
129
|
+
return { ...payload, quota };
|
|
130
|
+
}
|
|
131
|
+
return payload;
|
|
75
132
|
}
|
|
76
133
|
catch (error) {
|
|
77
134
|
if (error instanceof CatastroGPSApiError)
|
|
@@ -94,8 +151,14 @@ export class CatastroGPSClient {
|
|
|
94
151
|
async getParcelByCoordinates(lat, lng, country) {
|
|
95
152
|
return this.send("GET", "/api/search/coordinates", { lat, lng, country });
|
|
96
153
|
}
|
|
97
|
-
async
|
|
98
|
-
return this.send("
|
|
154
|
+
async searchAddressCandidates(address, country, limit) {
|
|
155
|
+
return this.send("GET", "/api/search/address/candidates", { q: address, country, limit });
|
|
156
|
+
}
|
|
157
|
+
async getUnits(reference, country, cursor) {
|
|
158
|
+
return this.send("GET", this.parcelPath(reference, "/units"), { country, cursor });
|
|
159
|
+
}
|
|
160
|
+
async resolve(text, hint) {
|
|
161
|
+
return this.send("GET", "/api/resolve", { q: text, hint });
|
|
99
162
|
}
|
|
100
163
|
async getPolygon(reference, country) {
|
|
101
164
|
return this.send("GET", this.parcelPath(reference, "/polygon"), { country });
|
|
@@ -103,8 +166,11 @@ export class CatastroGPSClient {
|
|
|
103
166
|
async getSolarPotential(reference, country) {
|
|
104
167
|
return this.send("GET", this.parcelPath(reference, "/solar"), { country });
|
|
105
168
|
}
|
|
106
|
-
async getTerrain(reference, country) {
|
|
107
|
-
return this.send("GET", this.parcelPath(reference, "/terrain"), { country });
|
|
169
|
+
async getTerrain(reference, country, point) {
|
|
170
|
+
return this.send("GET", this.parcelPath(reference, "/terrain"), { country, lat: point?.lat, lng: point?.lng });
|
|
171
|
+
}
|
|
172
|
+
async getGroundMotion(reference, country, point) {
|
|
173
|
+
return this.send("GET", this.parcelPath(reference, "/ground-motion"), { country, lat: point?.lat, lng: point?.lng });
|
|
108
174
|
}
|
|
109
175
|
async getAgriculture(reference, country) {
|
|
110
176
|
return this.send("GET", this.parcelPath(reference, "/agro"), { country });
|
package/build/server.js
CHANGED
|
@@ -5,11 +5,14 @@ import { registerSearchAddress } from "./tools/search-address.js";
|
|
|
5
5
|
import { registerGetBoundaries } from "./tools/get-boundaries.js";
|
|
6
6
|
import { registerGetSolar } from "./tools/get-solar.js";
|
|
7
7
|
import { registerGetTerrain } from "./tools/get-terrain.js";
|
|
8
|
+
import { registerGetGroundMotion } from "./tools/get-ground-motion.js";
|
|
8
9
|
import { registerGetAgriculture } from "./tools/get-agriculture.js";
|
|
9
10
|
import { registerGetMarket } from "./tools/get-market.js";
|
|
10
11
|
import { registerGetScore } from "./tools/get-score.js";
|
|
11
12
|
import { registerGetValueHistory } from "./tools/get-value-history.js";
|
|
12
13
|
import { registerCompareParcels } from "./tools/compare-parcels.js";
|
|
14
|
+
import { registerGetUnits } from "./tools/get-units.js";
|
|
15
|
+
import { registerResolveReference } from "./tools/resolve-reference.js";
|
|
13
16
|
import { SERVER_VERSION } from "./version.js";
|
|
14
17
|
export const DEFAULT_API_URL = "https://api.parcelgps.com";
|
|
15
18
|
export const DEFAULT_TIMEOUT_MS = 20000;
|
|
@@ -24,11 +27,14 @@ export function createServer(config) {
|
|
|
24
27
|
registerGetBoundaries(server, client);
|
|
25
28
|
registerGetSolar(server, client);
|
|
26
29
|
registerGetTerrain(server, client);
|
|
30
|
+
registerGetGroundMotion(server, client);
|
|
27
31
|
registerGetAgriculture(server, client);
|
|
28
32
|
registerGetMarket(server, client);
|
|
29
33
|
registerGetScore(server, client);
|
|
30
34
|
registerGetValueHistory(server, client);
|
|
31
35
|
registerCompareParcels(server, client);
|
|
36
|
+
registerGetUnits(server, client);
|
|
37
|
+
registerResolveReference(server, client);
|
|
32
38
|
return server;
|
|
33
39
|
}
|
|
34
40
|
export function loadEndpointConfig() {
|
|
@@ -33,7 +33,7 @@ export function registerCompareParcels(server, client) {
|
|
|
33
33
|
"common regime), PT, FR, IT and DE. The Basque Country and Navarre are not supported here " +
|
|
34
34
|
"(use the single-parcel tools). Area, land use and municipality are only filled for Spain. " +
|
|
35
35
|
"No market prices. A parcel that is not found comes back with an error and the others are " +
|
|
36
|
-
"still compared.
|
|
36
|
+
"still compared. Costs one quota unit per parcel found (0 to 3).",
|
|
37
37
|
inputSchema: {
|
|
38
38
|
parcels: z
|
|
39
39
|
.array(z.object({
|
|
@@ -46,9 +46,9 @@ export function registerCompareParcels(server, client) {
|
|
|
46
46
|
},
|
|
47
47
|
}, async ({ parcels }) => {
|
|
48
48
|
try {
|
|
49
|
-
const { data } = await client.compareParcels(parcels);
|
|
49
|
+
const { data, quota } = await client.compareParcels(parcels);
|
|
50
50
|
const items = data.comparacion ?? [];
|
|
51
|
-
return jsonResult({ total: data.total ?? items.length, parcels: items.map(summarize) });
|
|
51
|
+
return jsonResult({ total: data.total ?? items.length, parcels: items.map(summarize) }, quota);
|
|
52
52
|
}
|
|
53
53
|
catch (error) {
|
|
54
54
|
return handleToolError(error);
|
|
@@ -17,8 +17,8 @@ export function registerGetAgriculture(server, client) {
|
|
|
17
17
|
},
|
|
18
18
|
}, async ({ reference, country }) => {
|
|
19
19
|
try {
|
|
20
|
-
const { data } = await client.getAgriculture(reference, country);
|
|
21
|
-
return jsonResult({ reference, country: country ?? null, agriculture: data.agro ?? data });
|
|
20
|
+
const { data, quota } = await client.getAgriculture(reference, country);
|
|
21
|
+
return jsonResult({ reference, country: country ?? null, agriculture: data.agro ?? data }, quota);
|
|
22
22
|
}
|
|
23
23
|
catch (error) {
|
|
24
24
|
return handleToolError(error);
|
|
@@ -16,7 +16,7 @@ export function registerGetBoundaries(server, client) {
|
|
|
16
16
|
},
|
|
17
17
|
}, async ({ reference, country }) => {
|
|
18
18
|
try {
|
|
19
|
-
const { data: d } = await client.getPolygon(reference, country);
|
|
19
|
+
const { data: d, quota } = await client.getPolygon(reference, country);
|
|
20
20
|
return jsonResult(compact({
|
|
21
21
|
reference: d.refCatastral || d.refcat || reference,
|
|
22
22
|
country: d.pais || country,
|
|
@@ -25,7 +25,7 @@ export function registerGetBoundaries(server, client) {
|
|
|
25
25
|
area_m2: d.area || d.superficieParcela,
|
|
26
26
|
outline_lat_lng: d.poligono,
|
|
27
27
|
geojson: d.geojson,
|
|
28
|
-
}));
|
|
28
|
+
}), quota);
|
|
29
29
|
}
|
|
30
30
|
catch (error) {
|
|
31
31
|
return handleToolError(error);
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import type { CatastroGPSClient } from "../client/catastrogps-api.js";
|
|
3
|
+
export declare function registerGetGroundMotion(server: McpServer, client: CatastroGPSClient): void;
|
|
4
|
+
//# sourceMappingURL=get-ground-motion.d.ts.map
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { SITE_ANALYSIS_COUNTRIES } from "../types/index.js";
|
|
3
|
+
import { handleToolError, jsonResult, sitePoint } from "./shared.js";
|
|
4
|
+
export function registerGetGroundMotion(server, client) {
|
|
5
|
+
server.registerTool("get_ground_motion", {
|
|
6
|
+
title: "Get Ground Motion (Subsidence)",
|
|
7
|
+
description: "Whether the ground under the parcel sinks or rises and how fast, measured by satellite radar " +
|
|
8
|
+
"(Copernicus European Ground Motion Service, EGMS L3 Ortho, Sentinel-1 InSAR, 100 m grid, 2020-2024): " +
|
|
9
|
+
"mean vertical velocity in mm/year over the parcel outline (negative = sinking), fastest-sinking cell, " +
|
|
10
|
+
"east-west velocity, class from stable to severe_subsidence, cells with data and the mean displacement " +
|
|
11
|
+
"of each year. status no_data with reason no_reflectors means the satellite found nothing stable to " +
|
|
12
|
+
"measure (fields, forest, water): there is no figure, not a zero. Carries the source, licence and the " +
|
|
13
|
+
"attribution to show. Every covered country inside EGMS coverage: in ES, PV, NA, PT, FR, IT and DE the " +
|
|
14
|
+
"reference is enough; elsewhere also pass latitude and longitude (from get_parcel). Costs 1 quota unit.",
|
|
15
|
+
inputSchema: {
|
|
16
|
+
reference: z.string().min(1).describe("Official cadastral reference"),
|
|
17
|
+
country: z
|
|
18
|
+
.enum(SITE_ANALYSIS_COUNTRIES)
|
|
19
|
+
.optional()
|
|
20
|
+
.describe("Optional country code. Omit to auto-detect from the reference."),
|
|
21
|
+
latitude: z.number().min(-90).max(90).optional()
|
|
22
|
+
.describe("Latitude of the parcel point (WGS84). Required outside ES, PV, NA, PT, FR, IT and DE"),
|
|
23
|
+
longitude: z.number().min(-180).max(180).optional()
|
|
24
|
+
.describe("Longitude of the parcel point (WGS84). Required outside ES, PV, NA, PT, FR, IT and DE"),
|
|
25
|
+
},
|
|
26
|
+
}, async ({ reference, country, latitude, longitude }) => {
|
|
27
|
+
const { point, error } = sitePoint(country, latitude, longitude);
|
|
28
|
+
if (error)
|
|
29
|
+
return error;
|
|
30
|
+
try {
|
|
31
|
+
const { data, quota } = await client.getGroundMotion(reference, country, point);
|
|
32
|
+
return jsonResult({
|
|
33
|
+
reference: data.refcat,
|
|
34
|
+
country: data.country,
|
|
35
|
+
status: data.status,
|
|
36
|
+
reason: data.reason,
|
|
37
|
+
period: data.period?.label,
|
|
38
|
+
ground_motion: data.ground_motion,
|
|
39
|
+
source: data.source,
|
|
40
|
+
calculated_at: data.calculated_at,
|
|
41
|
+
}, quota);
|
|
42
|
+
}
|
|
43
|
+
catch (caught) {
|
|
44
|
+
return handleToolError(caught);
|
|
45
|
+
}
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
//# sourceMappingURL=get-ground-motion.js.map
|
|
@@ -20,7 +20,7 @@ export function registerGetMarket(server, client) {
|
|
|
20
20
|
},
|
|
21
21
|
}, async ({ reference, country }) => {
|
|
22
22
|
try {
|
|
23
|
-
const { data: d } = await client.getMarketData(reference, country);
|
|
23
|
+
const { data: d, quota } = await client.getMarketData(reference, country);
|
|
24
24
|
const hasFigures = (d.precio_m2_eur ?? 0) > 0 || (d.precio_estimado_eur ?? 0) > 0;
|
|
25
25
|
return jsonResult({
|
|
26
26
|
reference,
|
|
@@ -36,7 +36,7 @@ export function registerGetMarket(server, client) {
|
|
|
36
36
|
updated: d.fecha_actualizacion || null,
|
|
37
37
|
source: d.fuente ?? null,
|
|
38
38
|
note: d.mensaje_usuario ?? null,
|
|
39
|
-
});
|
|
39
|
+
}, quota);
|
|
40
40
|
}
|
|
41
41
|
catch (error) {
|
|
42
42
|
return handleToolError(error);
|
|
@@ -4,8 +4,8 @@ import { compact, errorResult, handleToolError, jsonResult } from "./shared.js";
|
|
|
4
4
|
export function registerGetParcel(server, client) {
|
|
5
5
|
server.registerTool("get_parcel", {
|
|
6
6
|
title: "Get Parcel",
|
|
7
|
-
description: "Look up a cadastral parcel in 29 European countries
|
|
8
|
-
"
|
|
7
|
+
description: "Look up a cadastral parcel in 29 European countries (31 official cadastres, including the " +
|
|
8
|
+
"Basque Country and Navarre) by its official cadastral reference or by WGS84 coordinates. Returns the " +
|
|
9
9
|
"reference, location, address, municipality, area, land use and the parcel outline when " +
|
|
10
10
|
"the official source provides them. The country is detected from the reference format or " +
|
|
11
11
|
"the point when omitted. United Kingdom: coordinates only. Codes: " + COUNTRY_CODES_TEXT + ".",
|
|
@@ -28,7 +28,7 @@ export function registerGetParcel(server, client) {
|
|
|
28
28
|
if (country === "UK") {
|
|
29
29
|
return errorResult("MCP_002", "United Kingdom parcels can only be looked up by coordinates.");
|
|
30
30
|
}
|
|
31
|
-
const { data: d } = await client.getParcelByReference(reference, country);
|
|
31
|
+
const { data: d, quota } = await client.getParcelByReference(reference, country);
|
|
32
32
|
return jsonResult(compact({
|
|
33
33
|
reference: d.refCatastral,
|
|
34
34
|
country: d.pais || country,
|
|
@@ -46,12 +46,12 @@ export function registerGetParcel(server, client) {
|
|
|
46
46
|
source: d.fuenteDatos,
|
|
47
47
|
outline_lat_lng: d.poligono,
|
|
48
48
|
google_maps_url: d.googleMapsUrl,
|
|
49
|
-
}));
|
|
49
|
+
}), quota);
|
|
50
50
|
}
|
|
51
51
|
if (latitude === undefined || longitude === undefined) {
|
|
52
52
|
return errorResult("MCP_001", "Provide either 'reference' or both 'latitude' and 'longitude'.");
|
|
53
53
|
}
|
|
54
|
-
const { data: d } = await client.getParcelByCoordinates(latitude, longitude, country);
|
|
54
|
+
const { data: d, quota } = await client.getParcelByCoordinates(latitude, longitude, country);
|
|
55
55
|
return jsonResult(compact({
|
|
56
56
|
reference: d.referenciaCatastral || d.refCatastral,
|
|
57
57
|
country: d.pais || country,
|
|
@@ -64,7 +64,7 @@ export function registerGetParcel(server, client) {
|
|
|
64
64
|
area_m2: d.superficieParcela,
|
|
65
65
|
property_type: d.tipoInmueble,
|
|
66
66
|
google_maps_url: d.googleMapsUrl,
|
|
67
|
-
}));
|
|
67
|
+
}), quota);
|
|
68
68
|
}
|
|
69
69
|
catch (error) {
|
|
70
70
|
return handleToolError(error);
|
package/build/tools/get-score.js
CHANGED
|
@@ -45,7 +45,7 @@ export function registerGetScore(server, client) {
|
|
|
45
45
|
},
|
|
46
46
|
}, async ({ reference, country }) => {
|
|
47
47
|
try {
|
|
48
|
-
const { data } = await client.getInvestmentScore(reference, country);
|
|
48
|
+
const { data, quota } = await client.getInvestmentScore(reference, country);
|
|
49
49
|
const s = data.score_inversion;
|
|
50
50
|
return jsonResult({
|
|
51
51
|
reference,
|
|
@@ -57,7 +57,7 @@ export function registerGetScore(server, client) {
|
|
|
57
57
|
risk_factors: s.factores_riesgo ?? [],
|
|
58
58
|
opportunity_factors: s.factores_oportunidad ?? [],
|
|
59
59
|
note: "Score based on the data available for this parcel. Factor levels are qualitative.",
|
|
60
|
-
});
|
|
60
|
+
}, quota);
|
|
61
61
|
}
|
|
62
62
|
catch (error) {
|
|
63
63
|
return handleToolError(error);
|
package/build/tools/get-solar.js
CHANGED
|
@@ -16,7 +16,7 @@ export function registerGetSolar(server, client) {
|
|
|
16
16
|
},
|
|
17
17
|
}, async ({ reference, country }) => {
|
|
18
18
|
try {
|
|
19
|
-
const { data: d } = await client.getSolarPotential(reference, country);
|
|
19
|
+
const { data: d, quota } = await client.getSolarPotential(reference, country);
|
|
20
20
|
return jsonResult({
|
|
21
21
|
available: d.disponible,
|
|
22
22
|
status: d.estado,
|
|
@@ -31,7 +31,7 @@ export function registerGetSolar(server, client) {
|
|
|
31
31
|
optimal_orientation: d.orientacion_optima ?? null,
|
|
32
32
|
optimal_tilt_deg: d.angulo_inclinacion ?? null,
|
|
33
33
|
source: d.fuente ?? "PVGIS",
|
|
34
|
-
});
|
|
34
|
+
}, quota);
|
|
35
35
|
}
|
|
36
36
|
catch (error) {
|
|
37
37
|
return handleToolError(error);
|