# mapicgc-mcp

Servidor **MCP (Model Context Protocol)** que ensenya assistents d'IA (opencode,
Claude, Cursor, GitHub Copilot...) a utilitzar correctament la llibreria
[**mapicgc-gl-js**](https://github.com/OpenICGC/mapicgc-gl-js) de l'ICGC
(documentació: https://openicgc.github.io/mapicgc-doc/).

> Aquest MCP **no executa ni empaqueta** mapicgc-gl-js: només serveix text i
> dades (documentació, exemples de codi i la configuració d'estils/capes de
> l'ICGC) perquè un model d'IA sàpiga quina API fer servir i com.

English version below ⬇️ / [Versió en anglès més avall](#mapicgc-mcp-english)

---

## Què és?

mapicgc-gl-js és un embolcall de MapLibre GL JS amb funcions específiques per
treballar amb les dades i serveis de l'ICGC (estils, capes vectorials i
ràster, terrenys 3D, geocodificador, cerca territorial...). Aquest MCP
exposa aquesta informació com a eines, recursos i prompts de l'estàndard
Model Context Protocol, perquè qualsevol client MCP pugui consultar-la en
temps real sense que calgui enganxar documentació manualment al context.

## Instal·lació

No cal instal·lar-lo manualment: qualsevol client MCP el pot executar amb
`npx`:

```bash
npx -y mapicgc-mcp
```

Si vols treballar-hi en local (clonant aquest repositori):

```bash
npm install
npm run sync    # descarrega la documentació real de mapicgc-gl-js a content/
npm run build   # compila TypeScript a dist/
npm start        # mode stdio
# o
npm run start:http   # mode Streamable HTTP (PORT configurable, per defecte 3000)
```

## Configuració per client MCP

### opencode

Afegeix al teu `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mapicgc": {
      "type": "local",
      "command": ["npx", "-y", "mapicgc-mcp"],
      "enabled": true
    }
  }
}
```

Per a una versió desplegada per URL (Streamable HTTP):

```json
{
  "mcp": {
    "mapicgc": {
      "type": "remote",
      "url": "https://el-teu-domini.exemple/mcp"
    }
  }
}
```

### Claude Desktop

A `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mapicgc": {
      "command": "npx",
      "args": ["-y", "mapicgc-mcp"]
    }
  }
}
```

### VS Code (GitHub Copilot)

A `.vscode/mcp.json` del teu projecte (o a la configuració d'usuari de VS Code):

```json
{
  "servers": {
    "mapicgc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mapicgc-mcp"]
    }
  }
}
```

## Eines (tools)

| Eina | Descripció |
| --- | --- |
| `get_started` | Instal·lació (NPM i CDN) i exemple mínim de mapa. |
| `search_docs(query, limit?)` | Cerca per paraules clau a tota la documentació empaquetada. |
| `get_api(name)` | Documentació d'un mètode o classe concret (p. ex. `Map.addMarker`). |
| `get_example(topic)` | Exemple de codi complet per a un tema (terreny 3D, marcadors, geocodificador...). |
| `list_styles` | Estils, terrenys i grups de capes disponibles (en viu, amb còpia local de seguretat). |
| `get_changelog(version?)` | Historial de canvis complet, o d'una versió concreta. |

També registra els **recursos** `mapicgc://readme` i `mapicgc://changelog`, i el
**prompt** `crear_mapa(estil, ubicacio)`.

> **Nota honesta**: el README de mapicgc-gl-js esmenta "mapes estàtics" i un
> "motor de cerca de CRS" com a capacitats de la llibreria, però aquests
> mètodes no existeixen al codi font actual. Les capacitats reals i
> documentades aquí són: geocodificació (`addGeocoderICGC`), geolocalització
> (`addGeolocateControl`), exportació de la vista a imatge/PDF
> (`addExportControl`) i cerca territorial per clic
> (`addApiTerritorialICGC` / `searchApiTerritorialICGC`).

## Actualitzar el contingut

La documentació de `content/` (README, referència de l'API i el CHANGELOG de
mapicgc-gl-js, més la còpia de seguretat de la configuració de l'ICGC) es
descarrega amb:

```bash
npm run sync
```

Els exemples de `content/examples/` estan escrits a mà (basats en exemples
reals del repositori de mapicgc-gl-js) i no es regeneren amb `sync`.

## Publicar

```bash
npm run sync && npm run build
npm pack --dry-run   # revisa què s'empaquetaria
npm publish
```

---

<a id="mapicgc-mcp-english"></a>

## mapicgc-mcp (English)

An **MCP (Model Context Protocol)** server that teaches AI assistants
(opencode, Claude, Cursor, GitHub Copilot...) how to correctly use the
[**mapicgc-gl-js**](https://github.com/OpenICGC/mapicgc-gl-js) library from
ICGC (docs: https://openicgc.github.io/mapicgc-doc/).

> This MCP does **not** run or bundle mapicgc-gl-js: it only serves text and
> data (documentation, code examples, and the ICGC style/layer
> configuration) so an AI model knows which API to use and how.

### Installation

No manual install needed — any MCP client can run it with `npx`:

```bash
npx -y mapicgc-mcp
```

For local development (cloning this repo):

```bash
npm install
npm run sync    # downloads the real mapicgc-gl-js docs into content/
npm run build   # compiles TypeScript to dist/
npm start        # stdio mode
# or
npm run start:http   # Streamable HTTP mode (PORT env var, default 3000)
```

### Client configuration

See the Catalan section above for ready-to-use JSON snippets for **opencode**,
**Claude Desktop** and **VS Code** — the configuration is identical
regardless of language.

### Tools

| Tool | Description |
| --- | --- |
| `get_started` | Installation (NPM and CDN) and a minimal working map example. |
| `search_docs(query, limit?)` | Keyword search across all bundled documentation. |
| `get_api(name)` | Detailed docs for a specific method/class (e.g. `Map.addMarker`). |
| `get_example(topic)` | A complete code example for a topic (3D terrain, markers, geocoder...). |
| `list_styles` | Available styles, terrains and layer groups (live, with a local fallback). |
| `get_changelog(version?)` | Full changelog, or just one version's entries. |

It also registers the `mapicgc://readme` and `mapicgc://changelog` **resources**,
and the `crear_mapa(estil, ubicacio)` **prompt**.

> **Honesty note**: the mapicgc-gl-js README mentions "static maps" and a
> "CRS search engine" as library capabilities, but no such methods exist in
> the current source code. The real, documented capabilities covered here
> are: geocoding (`addGeocoderICGC`), geolocation (`addGeolocateControl`),
> exporting the current view to an image/PDF (`addExportControl`), and
> click-based territorial lookup (`addApiTerritorialICGC` /
> `searchApiTerritorialICGC`).

### Updating content

Everything under `content/` that comes straight from mapicgc-gl-js (README,
API reference, CHANGELOG, and the ICGC config fallback snapshot) is
downloaded with:

```bash
npm run sync
```

Files under `content/examples/` are hand-written (based on real examples
from the mapicgc-gl-js repository) and are **not** regenerated by `sync`.

### Publishing

```bash
npm run sync && npm run build
npm pack --dry-run   # review what would be published
npm publish
```

## License

BSD-3-Clause, same as mapicgc-gl-js. See [LICENSE](./LICENSE).