# ivanbbaev/servicenow-mcp-ai architecture

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

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

## Overview

servicenow-mcp-ai is an MCP server through which clients inspect and operate on ServiceNow instances. The principal workflow is a client tool request, package registration and dispatch, domain API work, then REST access to the selected instance; writes default to previews unless explicitly applied. Separate capabilities cover script and artifact intelligence, automation tracing, drift and update-set comparison, operations, and local documentation. Bootstrap and task wiring are evidenced in sampled source; domain coverage is based mainly on the README and file tree, so uncertain internal call links are omitted.

Main entry points: [`src/tools`](https://github.com/ivanbbaev/servicenow-mcp-ai/tree/main/src/tools) (Domain tools), [`src/core/http.ts`](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/http.ts) (HTTP transport), [`src/server.ts`](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/server.ts) (MCP server), [`src/mcp/registry.ts`](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/mcp/registry.ts) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["MCP interface"]
  node_server["MCP server<br/>[server.ts]"]
  node_registry["Tool registry<br/>[registry.ts]"]
  node_tools["Domain tools"]
  node_resources["Resources and prompts<br/>[resources.ts]"]
end

subgraph group_domain["ServiceNow operations"]
  node_table["Table and metadata<br/>[table.ts]"]
  node_process["Catalog and change<br/>[catalog.ts]"]
  node_cmdb["CMDB and imports<br/>[cmdb.ts]"]
  node_attachments["Attachments and batch<br/>[attachment.ts]"]
  node_ops["Operations and history<br/>[ops.ts]"]
end

subgraph group_intelligence["Instance intelligence"]
  node_scripts["Script intelligence<br/>[scripts.ts]"]
  node_flows["Flow tracing<br/>[flows.ts]"]
  node_artifacts["Artifact reads<br/>[artifacts.ts]"]
  node_whereused["Usage and references<br/>[whereused.ts]"]
  node_codecheck["Code checking<br/>[codecheck.ts]"]
  node_compare["Drift and snapshots<br/>[compare.ts]"]
  node_updatesets["Update sets<br/>[updatesets.ts]"]
  node_documentation["Knowledge and diagrams<br/>[document.ts]"]
end

subgraph group_runtime["Runtime services"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_config["Profiles and config<br/>[config.ts]"]
  node_http["HTTP transport<br/>[http.ts]"]
  node_policy["Write policy<br/>[policy.ts]"]
  node_journal["Write journal<br/>[write-journal.ts]"]
end

node_client(("MCP client"))
node_instance{{"ServiceNow instance"}}

node_client -->|"sends requests"| node_server
node_server -->|"registers tools"| node_registry
node_server -->|"registers"| node_resources
node_registry -->|"dispatches calls"| node_tools
node_tools -->|"invokes operations"| node_table
node_tools -->|"invokes operations"| node_process
node_tools -->|"invokes operations"| node_cmdb
node_tools -->|"invokes operations"| node_attachments
node_tools -->|"invokes intelligence"| node_scripts
node_tools -->|"invokes tracing"| node_flows
node_tools -->|"invokes reads"| node_artifacts
node_tools -->|"invokes search"| node_whereused
node_tools -->|"invokes checks"| node_codecheck
node_tools -->|"invokes comparison"| node_compare
node_tools -->|"invokes operations"| node_updatesets
node_tools -->|"invokes generation"| node_documentation
node_tools -->|"invokes diagnostics"| node_ops
node_table -->|"requests data"| node_http
node_process -->|"requests data"| node_http
node_cmdb -->|"requests data"| node_http
node_attachments -->|"transfers files"| node_http
node_scripts -->|"reads records"| node_http
node_flows -->|"reads records"| node_http
node_ops -->|"reads records"| node_http
node_http -->|"obtains credentials"| node_auth
node_auth -->|"resolves profile"| node_config
node_http -->|"REST requests"| node_instance
node_tools -->|"checks write mode"| node_policy
node_tools -->|"records writes"| node_journal

click node_server "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/server.ts"
click node_registry "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/mcp/registry.ts"
click node_tools "https://github.com/ivanbbaev/servicenow-mcp-ai/tree/main/src/tools"
click node_resources "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/mcp/resources.ts"
click node_table "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/table.ts"
click node_process "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/catalog.ts"
click node_cmdb "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/cmdb.ts"
click node_attachments "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/attachment.ts"
click node_scripts "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/scripts.ts"
click node_flows "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/flows.ts"
click node_artifacts "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/artifacts.ts"
click node_whereused "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/whereused.ts"
click node_codecheck "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/codecheck.ts"
click node_compare "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/compare.ts"
click node_updatesets "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/updatesets.ts"
click node_documentation "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/document.ts"
click node_ops "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/ops.ts"
click node_auth "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/auth.ts"
click node_config "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/config.ts"
click node_http "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/http.ts"
click node_policy "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/policy.ts"
click node_journal "https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/write-journal.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_registry,node_tools,node_resources,node_client toneBlue
class node_table,node_process,node_cmdb,node_attachments,node_ops toneAmber
class node_scripts,node_flows,node_artifacts,node_whereused,node_codecheck,node_compare,node_updatesets,node_documentation toneMint
class node_auth,node_config,node_http,node_policy,node_journal toneRose
class node_instance toneIndigo
```

## Components

### MCP interface

- [MCP server](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/server.ts): `src/server.ts`
- [Tool registry](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/mcp/registry.ts): `src/mcp/registry.ts`
- [Domain tools](https://github.com/ivanbbaev/servicenow-mcp-ai/tree/main/src/tools): `src/tools`
- [Resources and prompts](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/mcp/resources.ts): `src/mcp/resources.ts`

### ServiceNow operations

- [Table and metadata](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/table.ts): `src/api/table.ts`
- [Catalog and change](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/catalog.ts): `src/api/catalog.ts`
- [CMDB and imports](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/cmdb.ts): `src/api/cmdb.ts`
- [Attachments and batch](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/attachment.ts): `src/api/attachment.ts`
- [Operations and history](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/ops.ts): `src/api/ops.ts`

### Instance intelligence

- [Script intelligence](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/scripts.ts): `src/api/scripts.ts`
- [Flow tracing](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/flows.ts): `src/api/flows.ts`
- [Artifact reads](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/artifacts.ts): `src/api/artifacts.ts`
- [Usage and references](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/whereused.ts): `src/api/whereused.ts`
- [Code checking](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/codecheck.ts): `src/api/codecheck.ts`
- [Drift and snapshots](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/compare.ts): `src/api/compare.ts`
- [Update sets](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/updatesets.ts): `src/api/updatesets.ts`
- [Knowledge and diagrams](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/api/document.ts): `src/api/document.ts`

### Runtime services

- [Authentication](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/auth.ts): `src/core/auth.ts`
- [Profiles and config](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/config.ts): `src/core/config.ts`
- [HTTP transport](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/http.ts): `src/core/http.ts`
- [Write policy](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/policy.ts): `src/core/policy.ts`
- [Write journal](https://github.com/ivanbbaev/servicenow-mcp-ai/blob/main/src/core/write-journal.ts): `src/core/write-journal.ts`

### Other components

- **MCP client**
- **ServiceNow instance**

## Connections

- MCP client → MCP server: sends requests
- MCP server → Tool registry: registers tools
- MCP server → Resources and prompts: registers
- Tool registry → Domain tools: dispatches calls
- Domain tools → Table and metadata: invokes operations
- Domain tools → Catalog and change: invokes operations
- Domain tools → CMDB and imports: invokes operations
- Domain tools → Attachments and batch: invokes operations
- Domain tools → Script intelligence: invokes intelligence
- Domain tools → Flow tracing: invokes tracing
- Domain tools → Artifact reads: invokes reads
- Domain tools → Usage and references: invokes search
- Domain tools → Code checking: invokes checks
- Domain tools → Drift and snapshots: invokes comparison
- Domain tools → Update sets: invokes operations
- Domain tools → Knowledge and diagrams: invokes generation
- Domain tools → Operations and history: invokes diagnostics
- Table and metadata → HTTP transport: requests data
- Catalog and change → HTTP transport: requests data
- CMDB and imports → HTTP transport: requests data
- Attachments and batch → HTTP transport: transfers files
- Script intelligence → HTTP transport: reads records
- Flow tracing → HTTP transport: reads records
- Operations and history → HTTP transport: reads records
- HTTP transport → Authentication: obtains credentials
- Authentication → Profiles and config: resolves profile
- HTTP transport → ServiceNow instance: REST requests
- Domain tools → Write policy: checks write mode
- Domain tools → Write journal: records writes