How michaelbuckner/servicenow-mcp works
Project type and purpose
• This is a standalone Python MCP (Model Context Protocol) server. Its purpose is to expose ServiceNow resources and operations through a secure, natural-language-friendly API, so that AI agents (or other clients) can list, query, update, and manage ServiceNow data via MCP URIs and tools.
File structure
• Top‐level files:
• servicenow-mcp.py (legacy entrypoint)
• pyproject.toml / requirements.txt (build & deps)
• .env.example (env-based config)
• mcp_server_servicenow package:
• cli.py (CLI entrypoint)
• server.py (MCP server implementation: routes resources → handlers)
• nlp.py (natural-language parsing & mapping to API calls)
• __init__.py (package metadata)
• tests/: unit tests for the NLP module (test_nlp.py)
• .github/workflows: CI pipeline for linting, building, testing
README for additional insights
• ServiceNow resources and tools (incidents, tables, scripts).
• Authentication modes (basic, token, OAuth).
• Usage: CLI flags or environment variables launch the server.
• Dependency on Python 3.8+, pytest, and typical HTTP API client libraries.
Main components of the system
a. Client Layer
– AI agent or MCP-aware client (e.g., Cline) that issues MCP requests (servicenow:// URIs or JSON‐RPC).
– CLI wrapper (mcp_server_servicenow.cli) that reads args/env and starts the server process on STDIN/STDOUT or a socket.
b. MCP Server Core (mcp_server_servicenow.server)
– Request dispatcher: parses MCP URIs, maps to handlers.
– Handlers implement the low-level API calls (search_records, get_record, etc.).
c. Natural-Language Processor (mcp_server_servicenow.nlp)
– Translates free-text commands into structured queries or updates.
– Implements “natural_language_search”, “natural_language_update”, etc.
d. ServiceNow API Client
– Underlying HTTP client (requests or pysnow) that handles authentication and issues REST calls to the external ServiceNow instance.
e. External ServiceNow Instance
– The actual tenant instance with tables, records, and script includes.
f. Configuration & Auth
– Environment variables or CLI args for URL, credentials, tokens.
– .env file loader or os.environ.
g. CI/CD & Tests
– pytest tests exercise NLP and server logic.
– GitHub Actions pipeline for automated testing, linting, packaging.
Relationships and interactions
• The AI agent → invokes CLI module → spawns MCP server.
• Server receives MCP request → dispatcher routes to either:
• Direct API handler (calls ServiceNow API client)
• NLP handler (nlp module produces structured query → passes to API handler)
• ServiceNow API client → makes HTTPS requests → returns JSON → server formats MCP response → client.
• Configuration component injects auth tokens/credentials into the client.
• Tests operate on the NLP and server modules in isolation (mocking the HTTP layer).
Architectural patterns and design principles
• Layered architecture: Presentation (CLI/MCP protocol) → Application (dispatcher & NLP) → Infrastructure (HTTP client).
• Adapter pattern: nlp module adapts free-text into standard API calls.
• Dependency injection for config and authentication.
• Single responsibility: Each module has a clear role (cli, server, nlp, client).
• Testable components: decoupled NLP and HTTP client for mocking.