# aartiq/servicenow-mcp architecture

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

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

## Overview

NowAIKit connects AI clients to ServiceNow through an MCP server, with REST and agent-to-agent access as additional entry points. The principal flow is a client request routed to a domain tool, which uses the ServiceNow client to perform work against an instance and returns a result. The README also highlights prompts, reports, resources, setup, multi-instance support, and a desktop dashboard. The graph uses documented or excerpted relationships; unsampled feature modules are represented at supported paths without inferred call chains.

Main entry points: [`src/server.ts`](https://github.com/aartiq/servicenow-mcp/blob/main/src/server.ts) (MCP server), [`src/tools/index.ts`](https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/index.ts) (Tool router), [`src/servicenow/client.ts`](https://github.com/aartiq/servicenow-mcp/blob/main/src/servicenow/client.ts) (ServiceNow client), [`src/api/index.ts`](https://github.com/aartiq/servicenow-mcp/blob/main/src/api/index.ts) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client access"]
  node_transports["MCP transports<br/>[index.ts]"]
  node_http["HTTP server<br/>[http-server.ts]"]
  node_rest["REST API<br/>[index.ts]"]
  node_a2a["A2A tasks<br/>[task-manager.ts]"]
  node_cli["CLI<br/>[index.ts]"]
  node_dashboard["Web dashboard<br/>[index.ts]"]
end

subgraph group_runtime["Server runtime"]
  node_server["MCP server<br/>[server.ts]"]
  node_snclient["ServiceNow client<br/>[client.ts]"]
end

subgraph group_domain["ServiceNow capabilities"]
  node_tools["Tool router<br/>[index.ts]"]
  node_coretools["Core tools<br/>[core.ts]"]
  node_itops["ITSM and ITOM tools<br/>[incident.ts]"]
  node_automation["Automation tools<br/>[flow.ts]"]
  node_scripting["Scripting tools<br/>[script.ts]"]
  node_reporttools["Reporting tools<br/>[reporting.ts]"]
end

subgraph group_support["Configuration and outputs"]
  node_instances["Instance manager<br/>[instances.ts]"]
  node_prompts["Prompt catalog<br/>[index.ts]"]
  node_resources["MCP resources<br/>[index.ts]"]
  node_reports["Report generation<br/>[index.ts]"]
  node_config[("CLI configuration<br/>[config-store.ts]")]
  node_setup["Setup wizard<br/>[setup.ts]"]
end

subgraph group_desktop["Desktop dashboard"]
  node_desktopmain["Desktop main<br/>[index.ts]"]
  node_desktopmanager["Server manager<br/>[server-manager.ts]"]
  node_desktopui["Desktop UI<br/>[App.tsx]"]
end

node_ai(("AI client"))
node_servicenow[("ServiceNow instance")]
node_llm(("LLM provider"))

node_ai -->|"sends MCP requests"| node_server
node_server -->|"connects transport"| node_transports
node_transports -->|"starts HTTP"| node_http
node_server -->|"lists and executes"| node_tools
node_server -->|"resolves prompts"| node_prompts
node_server -->|"reads resources"| node_resources
node_server -->|"mounts routes"| node_rest
node_server -->|"mounts A2A"| node_a2a
node_rest -->|"executes tools"| node_tools
node_rest -->|"reads resources"| node_resources
node_a2a -->|"executes tool"| node_tools
node_tools -->|"dispatches calls"| node_coretools
node_tools -->|"dispatches calls"| node_itops
node_tools -->|"dispatches calls"| node_automation
node_tools -->|"dispatches calls"| node_scripting
node_tools -->|"dispatches calls"| node_reporttools
node_server -->|"gets client"| node_instances
node_rest -->|"gets client"| node_instances
node_a2a -->|"gets client"| node_instances
node_instances -->|"creates clients"| node_snclient
node_coretools -.->|"uses client"| node_snclient
node_itops -.->|"uses client"| node_snclient
node_automation -.->|"uses client"| node_snclient
node_scripting -.->|"uses client"| node_snclient
node_reporttools -.->|"uses client"| node_snclient
node_snclient -->|"queries and updates"| node_servicenow
node_cli -->|"runs setup"| node_setup
node_setup -.->|"writes settings"| node_config
node_prompts -->|"loads settings"| node_config
node_reporttools -.->|"generates reports"| node_reports
node_cli -->|"uses report tools"| node_reports
node_dashboard -->|"uses HTTP server"| node_http
node_desktopui -->|"uses desktop API"| node_desktopmain
node_desktopmain -->|"delegates server control"| node_desktopmanager
node_desktopmanager -->|"manages server process"| node_server
node_llm -.->|"answers direct-mode requests"| node_cli

click node_server "https://github.com/aartiq/servicenow-mcp/blob/main/src/server.ts"
click node_transports "https://github.com/aartiq/servicenow-mcp/blob/main/src/transport/index.ts"
click node_http "https://github.com/aartiq/servicenow-mcp/blob/main/src/transport/http-server.ts"
click node_rest "https://github.com/aartiq/servicenow-mcp/blob/main/src/api/index.ts"
click node_a2a "https://github.com/aartiq/servicenow-mcp/blob/main/src/a2a/task-manager.ts"
click node_tools "https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/index.ts"
click node_coretools "https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/core.ts"
click node_itops "https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/incident.ts"
click node_automation "https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/flow.ts"
click node_scripting "https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/script.ts"
click node_reporttools "https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/reporting.ts"
click node_snclient "https://github.com/aartiq/servicenow-mcp/blob/main/src/servicenow/client.ts"
click node_instances "https://github.com/aartiq/servicenow-mcp/blob/main/src/servicenow/instances.ts"
click node_prompts "https://github.com/aartiq/servicenow-mcp/blob/main/src/prompts/index.ts"
click node_resources "https://github.com/aartiq/servicenow-mcp/blob/main/src/resources/index.ts"
click node_reports "https://github.com/aartiq/servicenow-mcp/blob/main/src/reports/index.ts"
click node_config "https://github.com/aartiq/servicenow-mcp/blob/main/src/cli/config-store.ts"
click node_setup "https://github.com/aartiq/servicenow-mcp/blob/main/src/cli/setup.ts"
click node_cli "https://github.com/aartiq/servicenow-mcp/blob/main/src/cli/index.ts"
click node_dashboard "https://github.com/aartiq/servicenow-mcp/blob/main/src/dashboard/index.ts"
click node_desktopmain "https://github.com/aartiq/servicenow-mcp/blob/main/desktop/main/index.ts"
click node_desktopmanager "https://github.com/aartiq/servicenow-mcp/blob/main/desktop/main/server-manager.ts"
click node_desktopui "https://github.com/aartiq/servicenow-mcp/blob/main/desktop/renderer/src/App.tsx"

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_transports,node_http,node_rest,node_a2a,node_cli,node_dashboard,node_ai toneBlue
class node_server,node_snclient,node_servicenow toneAmber
class node_tools,node_coretools,node_itops,node_automation,node_scripting,node_reporttools toneMint
class node_instances,node_prompts,node_resources,node_reports,node_config,node_setup toneRose
class node_desktopmain,node_desktopmanager,node_desktopui,node_llm toneIndigo
```

## Components

### Client access

- [MCP transports](https://github.com/aartiq/servicenow-mcp/blob/main/src/transport/index.ts): `src/transport/index.ts`
- [HTTP server](https://github.com/aartiq/servicenow-mcp/blob/main/src/transport/http-server.ts): `src/transport/http-server.ts`
- [REST API](https://github.com/aartiq/servicenow-mcp/blob/main/src/api/index.ts): `src/api/index.ts`
- [A2A tasks](https://github.com/aartiq/servicenow-mcp/blob/main/src/a2a/task-manager.ts): `src/a2a/task-manager.ts`
- [CLI](https://github.com/aartiq/servicenow-mcp/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [Web dashboard](https://github.com/aartiq/servicenow-mcp/blob/main/src/dashboard/index.ts): `src/dashboard/index.ts`

### Server runtime

- [MCP server](https://github.com/aartiq/servicenow-mcp/blob/main/src/server.ts): `src/server.ts`
- [ServiceNow client](https://github.com/aartiq/servicenow-mcp/blob/main/src/servicenow/client.ts): `src/servicenow/client.ts`

### ServiceNow capabilities

- [Tool router](https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/index.ts): `src/tools/index.ts`
- [Core tools](https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/core.ts): `src/tools/core.ts`
- [ITSM and ITOM tools](https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/incident.ts): `src/tools/incident.ts`
- [Automation tools](https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/flow.ts): `src/tools/flow.ts`
- [Scripting tools](https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/script.ts): `src/tools/script.ts`
- [Reporting tools](https://github.com/aartiq/servicenow-mcp/blob/main/src/tools/reporting.ts): `src/tools/reporting.ts`

### Configuration and outputs

- [Instance manager](https://github.com/aartiq/servicenow-mcp/blob/main/src/servicenow/instances.ts): `src/servicenow/instances.ts`
- [Prompt catalog](https://github.com/aartiq/servicenow-mcp/blob/main/src/prompts/index.ts): `src/prompts/index.ts`
- [MCP resources](https://github.com/aartiq/servicenow-mcp/blob/main/src/resources/index.ts): `src/resources/index.ts`
- [Report generation](https://github.com/aartiq/servicenow-mcp/blob/main/src/reports/index.ts): `src/reports/index.ts`
- [CLI configuration](https://github.com/aartiq/servicenow-mcp/blob/main/src/cli/config-store.ts): `src/cli/config-store.ts`
- [Setup wizard](https://github.com/aartiq/servicenow-mcp/blob/main/src/cli/setup.ts): `src/cli/setup.ts`

### Desktop dashboard

- [Desktop main](https://github.com/aartiq/servicenow-mcp/blob/main/desktop/main/index.ts): `desktop/main/index.ts`
- [Server manager](https://github.com/aartiq/servicenow-mcp/blob/main/desktop/main/server-manager.ts): `desktop/main/server-manager.ts`
- [Desktop UI](https://github.com/aartiq/servicenow-mcp/blob/main/desktop/renderer/src/App.tsx): `desktop/renderer/src/App.tsx`

### Other components

- **AI client**
- **ServiceNow instance**
- **LLM provider**

## Connections

- AI client → MCP server: sends MCP requests (evidence: `README.md`)
- MCP server → MCP transports: connects transport (evidence: `src/server.ts`)
- MCP transports → HTTP server: starts HTTP (evidence: `src/transport/index.ts`)
- MCP server → Tool router: lists and executes (evidence: `src/server.ts`)
- MCP server → Prompt catalog: resolves prompts (evidence: `src/server.ts`)
- MCP server → MCP resources: reads resources (evidence: `src/server.ts`)
- MCP server → REST API: mounts routes (evidence: `src/server.ts`)
- MCP server → A2A tasks: mounts A2A (evidence: `src/server.ts`)
- REST API → Tool router: executes tools (evidence: `src/api/index.ts`)
- REST API → MCP resources: reads resources (evidence: `src/api/index.ts`)
- A2A tasks → Tool router: executes tool (evidence: `src/a2a/task-manager.ts`)
- Tool router → Core tools: dispatches calls (evidence: `src/tools/index.ts`)
- Tool router → ITSM and ITOM tools: dispatches calls (evidence: `src/tools/index.ts`)
- Tool router → Automation tools: dispatches calls (evidence: `src/tools/index.ts`)
- Tool router → Scripting tools: dispatches calls (evidence: `src/tools/index.ts`)
- Tool router → Reporting tools: dispatches calls (evidence: `src/tools/index.ts`)
- MCP server → Instance manager: gets client (evidence: `src/server.ts`)
- REST API → Instance manager: gets client (evidence: `src/api/index.ts`)
- A2A tasks → Instance manager: gets client (evidence: `src/a2a/task-manager.ts`)
- Instance manager → ServiceNow client: creates clients (evidence: `src/servicenow/instances.ts`)
- Core tools → ServiceNow client: uses client
- ITSM and ITOM tools → ServiceNow client: uses client
- Automation tools → ServiceNow client: uses client
- Scripting tools → ServiceNow client: uses client
- Reporting tools → ServiceNow client: uses client
- ServiceNow client → ServiceNow instance: queries and updates (evidence: `README.md`)
- CLI → Setup wizard: runs setup (evidence: `src/cli/index.ts`)
- Setup wizard → CLI configuration: writes settings
- Prompt catalog → CLI configuration: loads settings (evidence: `src/prompts/index.ts`)
- Reporting tools → Report generation: generates reports
- CLI → Report generation: uses report tools (evidence: `src/cli/index.ts`)
- Web dashboard → HTTP server: uses HTTP server (evidence: `src/dashboard/index.ts`)
- Desktop UI → Desktop main: uses desktop API (evidence: `desktop/renderer/src/App.tsx`)
- Desktop main → Server manager: delegates server control (evidence: `desktop/main/index.ts`)
- Server manager → MCP server: manages server process (evidence: `desktop/main/server-manager.ts`)
- LLM provider → CLI: answers direct-mode requests
