Главная / Статьи / Подключаем ИИ-агентов к GeoServer 2.28 через расширение MCP

geoservermcpai-agentsgislangchain

Подключаем ИИ-агентов к GeoServer 2.28 через расширение MCP

Устанавливаем JAR расширения GeoServer MCP, проверяем, что он загрузился, вызываем эндпоинт через curl, подключаем Claude Desktop или LangChain и закрываем доступ и инструменты записи.

1377 слов

Дайте ИИ-агентам живой доступ к GeoServer

Чтобы агент начал опрашивать ваш каталог по MCP, хватит одного расширения и одного перезапуска. Никакого сайдкара на Python и лишнего Docker-контейнера. Заметки относятся к версии 0.1.0 расширения GeoServer MCP Extension и GeoServer 2.28.x. Расширение распространяется как JAR в пре-релизе на GitHub и не заменяет пакет geoserver-mcp на PyPI.

Что делает расширение

Это обычный плагин GeoServer. Как только JAR оказался в GeoServer и сервер перезапущен, сам GeoServer начинает говорить на MCP по такому адресу:

http://127.0.0.1:8080/geoserver/mcp

Агенты отправляют JSON-RPC поверх HTTP (Streamable HTTP), а GeoServer отвечает из собственного каталога. Результаты по-прежнему фильтруются правилами безопасности GeoServer.

Названия инструментов для работы с каталогом (list, get, query, create, delete, publish) те же, что и у MCP-сервера на Python. А вот административные дополнения Python-пакета (управление пользователями, reload, загрузка файлов) сюда не переехали, об этом ещё будет ниже, в разделе про типичные ошибки.

Инструменты записи включены по умолчанию. Если нужен эндпоинт только для чтения, пропишите mcp.allowWrites=false в конфигурации каталога данных.

В Windows пишите 127.0.0.1 вместо localhost. Некоторые MCP-клиенты на Python превращают localhost в IPv6-адрес ::1 и получают HTTP 503, даже когда маршрут по IPv4 работает.

Что понадобится

  • GeoServer 2.28.x на Java 17 или 21
  • Пользователь GeoServer (свежая установка идёт с admin / geoserver)
  • JAR расширения, о нём дальше

Не кладите этот JAR в GeoServer 2.20.x и 3.x. Версия 2.20 работает на Java 11 и просто не запустится, отдавая HTTP 503. GeoServer 3 перешёл на Jakarta Servlet, и эта сборка там не загрузится. Если старый GeoServer ещё нужен для других задач, не трогайте его и поставьте под плагин отдельный экземпляр 2.28.

Где взять JAR

Вам нужен файл gs-mcp-0.1.0.jar, он опубликован как релиз на GitHub, ссылка для скачивания: https://download.gis-mcp.com/geoserver-mcp-extension, сохраните его куда-нибудь под рукой, например в «Загрузки». Его также можно собрать самому или взять из репозитория https://github.com/mahdin75/geoserver-mcp.

Установка

  1. Откройте GeoServer и загляните в About & Status, затем About GeoServer. Версия должна начинаться с 2.28.
  2. Остановите GeoServer.
  3. Скопируйте gs-mcp-0.1.0.jar в папку WEB-INF/lib веб-приложения. Для бинарной сборки с Jetty это <GEOSERVER_ROOT>/webapps/geoserver/WEB-INF/lib, а для Tomcat — <CATALINA_BASE>/webapps/geoserver/WEB-INF/lib.

В Windows итоговый путь обычно выглядит так:

D:\geoserver-2.28.5\webapps\geoserver\WEB-INF\lib\gs-mcp-0.1.0.jar

Затем снова запустите сервер:

Start GeoServer.

Править web.xml не нужно: GeoServer подхватывает плагин сам.

Проверяем, что плагин загрузился

  1. Откройте http://127.0.0.1:8080/geoserver/web/ и войдите.
  2. Перейдите в About & Status, затем Modules.
  3. Найдите там GeoServer MCP Extension (gs-mcp).

Если после копирования сам веб-интерфейс отдаёт 503, значит, JAR попал не в тот GeoServer. Удалите его, перезапустите сервер и ставьте в экземпляр 2.28.x.

Вызываем эндпоинт

Плагин живёт по пути /mcp внутри веб-приложения GeoServer, поэтому для GeoServer, смонтированного в /geoserver, публичный адрес будет /geoserver/mcp. Из коробки нужен логин: HTTP Basic с настоящим пользователем GeoServer. В Windows PowerShell вызывайте curl.exe, потому что просто curl там совсем другая команда.

Initialize

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"}}}" \
  http://127.0.0.1:8080/geoserver/mcp

Список инструментов

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}" \
  http://127.0.0.1:8080/geoserver/mcp

В ответе должно быть около 30 инструментов каталога, например list_workspaces, list_layers, create_workspace и query_features.

Список слоёв

curl.exe -s -u admin:geoserver \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-03-26" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"list_layers\",\"arguments\":{}}}" \
  http://127.0.0.1:8080/geoserver/mcp

Три быстрые проверки:

  • POST с -u admin:geoserver возвращает JSON с результатом.
  • POST без пользователя возвращает HTTP 401.
  • GET на /geoserver/mcp возвращает HTTP 405.

Подключаем ИИ-клиента

Клиенту достаточно уметь отправлять JSON методом POST на URL. Claude Desktop и LangChain в плагин не встроены, так что всё, что нужно, — направить клиента на GeoServer.

Claude Desktop

Локальные MCP-серверы общаются с Claude Desktop через stdio, а этот плагин — HTTP-сервис. Их связывает небольшой мост mcp-remote, и для него нужен Node.js, чтобы был доступен npx.

  1. Откройте Settings, затем Developer, затем Edit Config — откроется claude_desktop_config.json. В Windows он лежит в %APPDATA%\Claude\claude_desktop_config.json, в macOS — в ~/Library/Application Support/Claude/claude_desktop_config.json.
  2. Добавьте сервер ниже, сохранив остальные записи mcpServers, если они уже есть:
{
  "mcpServers": {
    "geoserver": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8080/geoserver/mcp",
        "--allow-http",
        "--header",
        "Authorization:Basic YWRtaW46Z2Vvc2VydmVy"
      ]
    }
  }
}

YWRtaW46Z2Vvc2VydmVy — это admin:geoserver в Base64, так что замените его, если пароль у вас не стандартный. Флаг --allow-http нужен потому, что локальный GeoServer работает по обычному HTTP, а не по HTTPS.

  1. Полностью закройте Claude Desktop и откройте заново.
  2. Проверьте запросом вроде «Какие рабочие области есть на этом GeoServer?» или «Создай рабочую область demo_mcp, а потом покажи слои внутри topp».

Если инструменты не появились, сначала убедитесь, что сервер запущен и что POST через curl из примера выше проходит с -u admin:geoserver.

LangChain

Начните с импорта:

from langchain_mcp_adapters.client import MultiServerMCPClient

Затем создайте клиента:

client = MultiServerMCPClient(
    {
        "geoserver": {
            "transport": "streamable_http",
            "url": "http://127.0.0.1:8080/geoserver/mcp",
            "headers": {"Authorization": "Basic YWRtaW46Z2Vvc2VydmVy"},
        }
    }
)
tools = await client.get_tools()

Если streamable_http не принимается, попробуйте вместо него "transport": "http". URL и заголовок Basic остаются прежними.

В проекте есть смоук-тест extension/examples/langchain_mcp_test.py:

pip install -r extension/examples/requirements-langchain.txt
python extension/examples/langchain_mcp_test.py --url http://127.0.0.1:8080/geoserver/mcp

У скрипта есть необязательный ключ --agent, который дополнительно запускает агента LangChain через OpenRouter, и для него должна быть задана OPENROUTER_API_KEY. Нужен Python 3.10.11 или новее (3.11+ тоже подходит). Ранние сборки 3.10.0 часто валятся на TLS при подключении к OpenRouter.

Закрываем доступ анонимам

Аутентификация включена по умолчанию. Её можно настроить через необязательный файл mcp.properties в каталоге данных GeoServer:

mcp.enabled=true
mcp.path=/mcp
mcp.requireAuthentication=true
mcp.allowWrites=true
mcp.maxFeatures=100

При mcp.requireAuthentication=true запрос без логина получает HTTP 401, а запрос с пользователем GeoServer выполняет инструменты. Этот пользователь всё равно видит и меняет только то, что разрешает безопасность данных GeoServer.

Оставляйте true, если только анонимные клиенты действительно не должны видеть публичные объекты каталога. Настройка mcp.allowWrites=false скрывает инструменты записи из tools/list и отклоняет их в tools/call. После любого изменения mcp.properties перезапускайте GeoServer.

Ошибки, на которых спотыкаются

  • Не та серия GeoServer. JAR работает только на 2.28.x, а на 2.20.x веб-приложение не стартует.
  • Не та Java. GeoServer 2.28 нужна Java 17 или 21, на Java 11 плагин не загрузится.
  • Нет перезапуска после копирования JAR.
  • Нет заголовка Authorization. В конфигурации по умолчанию ответ будет 401.
  • localhost в Windows. MCP-клиенты на Python могут пойти через IPv6 и получить 503, поэтому используйте http://127.0.0.1:8080/geoserver/mcp.
  • Рабочая область с именем mcp. Выберите другое имя, иначе оно может конфликтовать с путём /mcp.
  • Ожидание административных инструментов. Загрузки шейпфайлов, SQL-представлений, reload и управления пользователями в этом плагине нет.
  • Ошибки TLS с --agent. На Python 3.10.0 часть смоук-теста с GeoServer может пройти, а вызов OpenRouter упадёт, поэтому переходите на 3.10.11 или 3.11+.

Где лежит код

Исходники размещены на https://github.com/mahdin75/geoserver-mcp (смотрите папку extension). У сборки 0.1.0 есть своя страница релиза, https://github.com/mahdin75/geoserver-mcp/releases/tag/extension-v0.1.0, а issues и pull request'ы принимаются в том же репозитории.

Весь цикл коротко: скачать JAR, положить его в WEB-INF/lib установки 2.28, перезапустить и слать POST на /geoserver/mcp с действующими учётными данными GeoServer.

Все статьиПрислать бриф