ServiceNow Knowledge MCP

ServiceNow Knowledge 검색을 위한 결정적(deterministic) 읽기 전용 FastMCP 통합입니다. 답변 생성, 요약, 의미론적 재순위화, 벡터 검색 또는 문서 파싱을 수행하지 않습니다.

아키텍처

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 결과 순서를 유지하고 간결한 후보를 반환합니다. 의미론적, 벡터, AI 또는 전체 텍스트 동작을 주장하지 않습니다. get_knowledge_article은 선택된 표준 문서와 유용한 유효성 메타데이터를 반환합니다. get_knowledge_attachment는 구조화된 MCP 출력이 JSON 호환 가능하므로 제한된 바이너리 데이터를 base64로 반환합니다. 호출자는 이를 디코딩해야 하며, 파싱이나 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

기본 네트워크 전송은 http://localhost:8080/mcp의 상태 비저장 Streamable HTTP입니다. 로컬에서 생성된 MCP 클라이언트의 경우 TRANSPORT=stdio를 설정하세요.

컨테이너 빌드:

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은 통합 ID 토큰을 제공합니다. 검색 및 문서 필드 선택은 SERVICENOW_SEARCH_FIELDS와 SERVICENOW_ARTICLE_FIELDS에 중앙 집중화되어 있어, 검증된 표준 또는 사용자 정의 필드를 클라이언트를 수정하지 않고 채택할 수 있습니다.

기본 API 경로와 쿼리 매개변수 이름은 선택한 ServiceNow Knowledge Management API 버전과 대조하여 확인해야 하는 구현 가정입니다. 검색은 구성된 또는 도구별 Knowledge Base 및 언어 값으로 범위를 지정할 수 있습니다. 요청된 결과 제한, 문서 콘텐츠 길이, 첨부 파일 바이트, 타임아웃 및 일시적 재시도는 제한됩니다.

권한 부여 경계

통합 ID 자체만으로는 최종 사용자의 Knowledge 권한이 적용된다는 것을 증명하지 않습니다. 인증자는 내부 권한 부여 컨텍스트를 수용하므로, 확인된 위임 메커니즘을 클라이언트를 재설계하지 않고 추가할 수 있습니다. 그러나 MCP 도구는 현재 위임된 자격 증명을 생성하거나 수용하지 않습니다.

공개 보안 질문: MCP가 통합 ID를 사용하여 ServiceNow를 호출할 때, Knowledge Base ACL, 사용자 기준(User Criteria), 역할, 그룹 구성원 및 문서 수준 제한이 통합 ID에 대해서만 평가됩니까, 아니면 최종 사용자 권한 부여 컨텍스트가 전파되어 적용될 수 있습니까?

적용 가능한 자격(entitlement) 계약이 확인되고 테스트될 때까지 프로덕션 사용을 진행해서는 안 됩니다.

가정 및 미해결 질문

추적 가능한 Epic, Stories, Tasks, 가정 및 미해결 통합 질문은 docs/implementation-plan.md에 유지 관리됩니다. 중요한 미해결 항목은 다음과 같습니다:

1. query 매개변수를 지원하는 검색/인덱싱/순위 기능은 무엇이며, Knowledge UI와 일치합니까?

2. 어떤 Knowledge Base, 언어 및 게시 상태가 범위에 포함됩니까?

3. 통합 ID가 사용될 때 최종 사용자 권한 부여는 어떻게 적용됩니까?

4. 어떤 표준 또는 사용자 정의 필드에 표준 문서 콘텐츠가 포함됩니까?

5. 대상, 유효성, 게시, 인용 및 최신성에 필요한 필드는 무엇입니까?

6. 어떤 인증 메커니즘, API 버전, 속도 제한 및 처리량이 적용됩니까?

7. 어떤 비프로덕션 환경과 대표적인 검색 품질 픽스처를 사용할 수 있습니까?