# michaelbuckner/servicenow-mcp architecture

> Architecture diagram of the GitHub repository michaelbuckner/servicenow-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michaelbuckner/servicenow-mcp
- Repository: https://github.com/michaelbuckner/servicenow-mcp

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client Layer
    A["AI Agent / MCP-aware Client"]:::external
    A --> B["CLI Wrapper\n(mcp_server_servicenow/cli.py)"]:::internal

    click B "https://github.com/michaelbuckner/servicenow-mcp/blob/master/mcp_server_servicenow/cli.py"

    %% Configuration & Auth
    C["Config & Auth\n(.env.example,\nenv vars)"]:::crosscut
    click C "https://github.com/michaelbuckner/servicenow-mcp/blob/master/.env.example"
    B --> C
    C --> D["Package Metadata\n(mcp_server_servicenow/__init__.py)"]:::internal
    click D "https://github.com/michaelbuckner/servicenow-mcp/blob/master/mcp_server_servicenow/__init__.py"

    %% Server Core
    subgraph "MCP Server Core" 
        direction TB
        E["Dispatcher\n(mcp_server_servicenow/server.py)"]:::internal
        click E "https://github.com/michaelbuckner/servicenow-mcp/blob/master/mcp_server_servicenow/server.py"
        E --> F["URI-based Handlers\n(search_records, get_record, etc.)"]:::internal
        E --> G["NLP-based Handlers"]:::internal
    end

    D --> E
    C --> E

    %% NLP Processor
    G --> H["NLP Processor\n(nlp.py)"]:::internal
    click H "https://github.com/michaelbuckner/servicenow-mcp/blob/master/mcp_server_servicenow/nlp.py"
    H --> F

    %% Infrastructure Layer
    F --> I["ServiceNow API Client\n(requests / pysnow)"]:::infra
    C --> I
    I --> J["External ServiceNow Instance"]:::external

    %% Responses back through layers
    J --> I
    I --> F
    F --> E
    E --> B
    B --> A

    %% Development Pipeline
    subgraph "CI/CD & Tests"
        direction TB
        K["Unit Tests\n(tests/test_nlp.py)"]:::test
        click K "https://github.com/michaelbuckner/servicenow-mcp/blob/master/tests/test_nlp.py"
        L["GitHub Actions\n(python-package.yml)"]:::test
        click L "https://github.com/michaelbuckner/servicenow-mcp/blob/master/.github/workflows/python-package.yml"
        M["Build Config\n(pyproject.toml,\nrequirements.txt)"]:::test
        click M "https://github.com/michaelbuckner/servicenow-mcp/blob/master/pyproject.toml"
        click M "https://github.com/michaelbuckner/servicenow-mcp/blob/master/requirements.txt"
        N["Docs\n(README.md,\nCONTRIBUTING.md)"]:::test
        click N "https://github.com/michaelbuckner/servicenow-mcp/blob/master/README.md"
        click N "https://github.com/michaelbuckner/servicenow-mcp/blob/master/CONTRIBUTING.md"
    end

    M --> K
    L --> K

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#02457A,stroke-width:1px;
    classDef external fill:#D6F5D6,stroke:#1A7F1A,stroke-width:1px;
    classDef crosscut fill:#FFE8CC,stroke:#CC8400,stroke-width:1px;
    classDef infra fill:#F0F0F0,stroke:#666666,stroke-width:1px;
    classDef test fill:#F5D0FF,stroke:#8A0272,stroke-width:1px;
```
