igrid-sce-mcp-tool v4 — Чтение / Запись / Администрирование

Уровень интеграции MCP на Node.js/JavaScript для существующих REST API iGrid-Prometheus. Серверная часть iGrid и разделение на восемь инструментов остаются без изменений; эта версия добавляет авторизацию на основе ролей XSUAA SAP BTP на уровне инструментов MCP.

Модель авторизации

Теперь проект определяет три области XSUAA, три шаблона ролей и три предопределённые коллекции ролей:

Проверка авторизации выполняется внутри общего MCP toolHandler перед любым downstream-запросом к API iGrid. Пользователь без необходимой области получает ошибку инструмента MCP Forbidden:.

Related MCP server: agent-sudo-mcp

Ровно 8 инструментов MCP

Группа Bearer — src/tools/bearer-tools.js

1. igrid_list_domains → GET /api/hub/datasets → Чтение/Админ

2. igrid_get_template → GET /api/hub/template/:domain → Чтение/Админ

3. igrid_run_agent → POST /api/ai/run → Запись/Админ

4. igrid_propose_action → POST /api/ai/action/propose → Запись/Админ

5. igrid_decide_action → POST /api/ai/action/decide → Запись/Админ

6. igrid_metrics → GET /api/ai/metrics → Чтение/Админ

Группа x-api-key — src/tools/api-key-tools.js

7. igrid_ingest_csv → POST /api/ingest/:domain → Запись/Админ

8. igrid_export_csv → GET /api/export/:domain → Чтение/Админ

igrid_propose_action намеренно отнесён к Записи, поскольку требуемое правило авторизации основано на фактической HTTP-операции, а этот инструмент использует POST.

Инструмент MCP igrid_health не предоставляется. /healthz остаётся только конечной точкой работоспособности приложения.

Существующее downstream-поведение iGrid не изменено

• Шесть инструментов продолжают использовать сессию Bearer/сервиса iGrid.

• igrid_ingest_csv и igrid_export_csv продолжают использовать канал x-api-key iGrid.

• Не внедряется ни служба Destination, ни служба Connectivity.

• Никакие учётные данные или секреты не зашиты в коде.

Важные файлы

xs-security.json                 XSUAA scopes, role templates, role collections
src/auth/xsuaa.js               XSUAA authentication + OAuth metadata
src/auth/authorization.js       Read/Write/Admin authorization checks
src/context/auth-context.js     Per-request auth context propagation
src/tools/response.js           Common MCP tool-level enforcement
src/tools/bearer-tools.js       6 Bearer tools and permission mapping
src/tools/api-key-tools.js      2 x-api-key tools and permission mapping

Окружение

IGRID_BASE_URL=https://igrid-prometheus.azurewebsites.net
IGRID_API_KEY=<IGRID_API_KEY>
IGRID_BEARER_TOKEN=<optional pre-issued iGrid Bearer>
IGRID_SERVICE_EMAIL=<optional approved iGrid service email>
IGRID_SERVICE_PASSWORD=<optional approved iGrid service password>
IGRID_MFA_CODE=<optional MFA code>
IGRID_MFA_BODY_JSON=<approved MFA JSON body using {{code}}>
IGRID_REQUEST_TIMEOUT_MS=30000

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_PATH=/mcp

# Local stdio / local HTTP test authorization only.
# Ignored for a hosted request authenticated through XSUAA.
MCP_LOCAL_ROLE=Admin
MCP_HTTP_AUTH_TOKEN=

Для инструментов Bearer предпочтительно использование предварительно выпущенного IGRID_BEARER_TOKEN. При его отсутствии существующий менеджер токенов может использовать утверждённый контракт входа/MFA iGrid при наличии необходимой конфигурации MFA.

Сборка

npm install
npm run check
npm run security:check
npm test
npx mbt build -t mta_archives

Развёртывание в BTP

cf login
cf target -o <ORG> -s <SPACE>
cf deploy mta_archives/igrid-sce-mcp-tool_4.0.0.mtar -f

Установите секреты iGrid после развёртывания:

cf set-env igrid-sce-mcp-tool IGRID_API_KEY '<IGRID_API_KEY>'
cf set-env igrid-sce-mcp-tool IGRID_BEARER_TOKEN '<IGRID_BEARER_TOKEN>'
cf restart igrid-sce-mcp-tool

Или при использовании утверждённого процесса входа/MFA сервиса:

cf set-env igrid-sce-mcp-tool IGRID_SERVICE_EMAIL '<SERVICE_EMAIL>'
cf set-env igrid-sce-mcp-tool IGRID_SERVICE_PASSWORD '<SERVICE_PASSWORD>'
cf set-env igrid-sce-mcp-tool IGRID_MFA_BODY_JSON '<APPROVED_JSON_WITH_{{code}}>'
cf restart igrid-sce-mcp-tool

Назначение ролей XSUAA

Развёртывание создаёт/обновляет экземпляр службы XSUAA igrid-sce-mcp-tool-xsuaa из файла xs-security.json.

После развёртывания в подаккаунте SAP BTP:

1. Откройте Безопасность → Коллекции ролей.

2. Убедитесь, что предопределённые коллекции iGrid-MCP-Read, iGrid-MCP-Write и iGrid-MCP-Admin существуют.

3. Назначьте iGrid-MCP-Read пользователям только для чтения.

4. Назначьте iGrid-MCP-Write пользователям только для записи.

5. Назначьте iGrid-MCP-Admin только пользователям, которым нужны как GET, так и POST инструменты MCP.

6. Повторно аутентифицируйте клиент MCP, чтобы его новый токен содержал назначенные области.

Если у пользователя есть только Read, инструменты POST завершаются ошибкой на уровне MCP. Если у пользователя есть только Write, инструменты GET завершаются ошибкой. Admin может вызывать все восемь инструментов.

OAuth / удалённый MCP Claude

Используйте развёрнутую конечную точку:

https://<BTP_ROUTE>/mcp

Метаданные обнаружения OAuth теперь содержат области XSUAA read, write и admin. Для применения ролей, специфичных для пользователя, используйте поток OAuth, который генерирует токен пользователя (обычно код авторизации), чтобы коллекции ролей пользователя BTP были представлены в токене.

Ключ службы по-прежнему может предоставлять учётные данные клиента OAuth XSUAA, но токен client_credentials — это идентификация технического клиента, и его не следует рассматривать как наследующий коллекцию ролей пользователя-человека.

Локальный stdio

Локальный stdio не имеет JWT пользователя BTP, поэтому поведение ролей имитируется с помощью MCP_LOCAL_ROLE. По умолчанию — Admin, чтобы сохранить предыдущее локальное поведение.

Локальный тест только для чтения:

MCP_LOCAL_ROLE=Read npm run start:stdio

Локальный тест только для записи:

MCP_LOCAL_ROLE=Write npm run start:stdio

Полный локальный тест:

MCP_LOCAL_ROLE=Admin npm run start:stdio

Пример для Claude Desktop/Code:

{
  "mcpServers": {
    "igrid-sce-mcp-tool": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/igrid-sce-mcp-tool/src/server.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MCP_LOCAL_ROLE": "Read",
        "IGRID_BASE_URL": "https://igrid-prometheus.azurewebsites.net",
        "IGRID_API_KEY": "<IGRID_API_KEY>",
        "IGRID_BEARER_TOKEN": "<IGRID_BEARER_TOKEN>"
      }
    }
  }
}

Приёмочный тест ролей

Используйте трёх пользователей (или три назначения ролей) и получите новый токен после каждого назначения.

Пользователь только для чтения

Ожидаемый успех:

igrid_list_domains
igrid_get_template
igrid_metrics
igrid_export_csv

Ожидаемый Forbidden::

igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv

Пользователь только для записи

Ожидаемый успех:

igrid_run_agent
igrid_propose_action
igrid_decide_action
igrid_ingest_csv

Ожидаемый Forbidden::

igrid_list_domains
igrid_get_template
igrid_metrics
igrid_export_csv

Пользователь-администратор

Все восемь инструментов должны пройти проверку роли MCP. Downstream-аутентификация/авторизация и проверка запросов iGrid по-прежнему применяются.

Замечания по безопасности

• Проверка разрешений выполняется до вызова API iGrid.

• XSUAA управляет входящими разрешениями MCP; iGrid остаётся авторитетным в отношении downstream-учётных данных и бизнес-авторизации.

• Никогда не помещайте ключ API iGrid, пароль iGrid, Bearer-токен, секрет клиента XSUAA или ключ службы в систему контроля версий.

• См. README-SECURITY.md для кратких указаний по безопасности.