ServiceNow Knowledge MCP

Детерминированная, доступная только для чтения интеграция FastMCP для поиска по базе знаний ServiceNow. Она не выполняет генерацию ответов, суммаризацию, семантическое переранжирование, векторный поиск или разбор документов.

Архитектура

AI platform / MCP client
        ↓
FastMCP server
        ↓
KnowledgeService
        ↓
ServiceNowKnowledgeClient
        ↓
ServiceNow Knowledge Management REST API

Клиент централизует заголовки аутентификации, построение конечных точек, выбор полей, ограниченные повторные попытки при временных сбоях, сопоставление таймаутов и ошибок, нормализацию JSON и ограничения на размер бинарных вложений. Учётные данные, заголовки авторизации, содержимое статей и тела вложений не логируются.

Related MCP server: ServiceNow MCP Server

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

search_knowledge
    → GET /knowledge/articles

get_knowledge_article
    → GET /knowledge/articles/{id}

get_knowledge_attachment
    → GET /knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

search_knowledge сохраняет порядок результатов ServiceNow и возвращает компактные кандидаты. Он не заявляет о семантическом, векторном, ИИ- или полнотекстовом поведении. get_knowledge_article возвращает выбранную каноническую статью и полезные метаданные о действительности. get_knowledge_attachment возвращает ограниченные бинарные данные в формате base64, поскольку структурированный вывод MCP совместим с JSON; вызывающий код должен их декодировать, при этом никакой разбор или OCR не выполняется.

Разработка

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
pytest
ruff format --check src tests
ruff check src tests
mypy src
servicenow-knowledge-mcp

Сетевой транспорт по умолчанию — stateless Streamable HTTP на http://localhost:8080/mcp. Установите TRANSPORT=stdio для локально запускаемого MCP-клиента.

Сборка контейнера:

docker build -t servicenow-knowledge-mcp .
docker run --env-file .env -p 8080:8080 servicenow-knowledge-mcp

Конфигурация

Все настройки показаны в .env.example. SERVICENOW_BASE_URL обязателен во время выполнения. SERVICENOW_ACCESS_TOKEN предоставляет токен идентификации интеграции. Выбор полей для поиска и статей централизован в SERVICENOW_SEARCH_FIELDS и SERVICENOW_ARTICLE_FIELDS, чтобы проверенные стандартные или пользовательские поля можно было применять без изменения клиента.

Путь API по умолчанию и имена параметров запроса являются предположениями реализации, которые необходимо проверить на соответствие выбранной версии API управления знаниями ServiceNow. Поиск можно ограничить с помощью настроенных или передаваемых в инструмент значений базы знаний и языка. Запрашиваемый лимит результатов, длина содержимого статьи, объём вложений в байтах, таймаут и количество повторных попыток ограничены.

Границы авторизации

Идентичность интеграции сама по себе не доказывает, что разрешения конечного пользователя на доступ к знаниям соблюдаются. Аутентификатор принимает внутренний контекст авторизации, чтобы подтверждённый делегированный механизм можно было добавить без перепроектирования клиента, но инструменты MCP сегодня не изобретают и не принимают делегированные учётные данные.

Открытый вопрос безопасности: когда MCP обращается к ServiceNow с использованием идентичности интеграции, оцениваются ли ACL базы знаний, критерии пользователей, роли, членство в группах и ограничения на уровне статей только относительно идентичности интеграции, или можно ли распространять и применять контекст авторизации конечного пользователя?

Использование в производстве не должно начинаться, пока не будет подтверждён и протестирован применимый контракт на права доступа.

Допущения и открытые вопросы

Отслеживаемые Epic, Stories, Tasks, допущения и нерешённые вопросы интеграции ведутся в docs/implementation-plan.md. Важные нерешённые пункты включают:

1. Какая возможность поиска/индексации/ранжирования поддерживает параметр query, и соответствует ли она интерфейсу Knowledge UI?

2. Какие базы знаний, языки и состояния публикации входят в область действия?

3. Как будет обеспечиваться авторизация конечного пользователя при использовании идентичности интеграции?

4. Какое стандартное или пользовательское поле содержит каноническое содержимое статьи?

5. Какие поля требуются для аудитории, действительности, публикации, цитирования и актуальности?

6. Какие механизм аутентификации, версия API, лимиты скорости и пропускная способность применяются?

7. Какие непроизводственная среда и репрезентативные фикстуры для оценки качества поиска доступны?