Головна / Статті / Під'єднуємо ШІ-агентів до GeoServer 2.28 через розширення MCP

Під'єднуємо ШІ-агентів до 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.

Встановлення

Відкрийте GeoServer і зазирніть в About & Status, потім About GeoServer. Версія має починатися з 2.28.
Зупиніть GeoServer.
Скопіюйте 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 підхоплює плагін сам.

Перевіряємо, що плагін завантажився

Відкрийте http://127.0.0.1:8080/geoserver/web/ і увійдіть.
Перейдіть в About & Status, потім Modules.
Знайдіть там 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.

Відкрийте Settings, потім Developer, потім Edit Config — відкриється claude_desktop_config.json. У Windows він лежить у %APPDATA%\Claude\claude_desktop_config.json, у macOS — у ~/Library/Application Support/Claude/claude_desktop_config.json.
Додайте сервер нижче, зберігши інші записи 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.

Повністю закрийте Claude Desktop і відкрийте знову.
Перевірте запитом на кшталт «Які робочі області є на цьому 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.

Усі статті Надіслати бриф