@aartiq/servicenow-mcp 1.0.0

package/README.md

@@ -0,0 +1,910 @@
+<div align="center">
+
+[![AI-Powered](https://img.shields.io/badge/AI--Powered-Claude%20%7C%20ChatGPT%20%7C%20Gemini%20%7C%20Groq%20%7C%20OpenRouter-00D4AA?style=flat-square)](https://github.com/aartiq/servicenow-mcp)
+[![Tools](https://img.shields.io/badge/400%2B%20Tools-All%20Modules-0F4C81?style=flat-square)](docs/TOOLS.md)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square)](LICENSE)
+[![ServiceNow](https://img.shields.io/badge/ServiceNow-Latest%20Release-00D4AA?style=flat-square)](https://developer.servicenow.com)
+[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-0F4C81?style=flat-square)](https://modelcontextprotocol.io)
+[![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
+
+<br/>
+
+# servicenow-mcp
+
+## The Most Comprehensive ServiceNow MCP Server
+
+> **400+ tools · 31+ ServiceNow modules · 5-minute setup · MIT licensed · Works with any AI**
+
+**servicenow-mcp** is the most comprehensive, production-ready MCP server for ServiceNow — and the only one that truly does it all.
+
+Connect **Claude**, **ChatGPT**, **Gemini**, **Cursor**, **GitHub Copilot**, or any MCP-compatible AI in under 5 minutes. Then let your AI read, build, deploy, and automate across every ServiceNow module — incidents, changes, scripts, flows, portals, integrations, HRSD, CSM, and more.
+
+Ask in plain English. Deploy business rules from chat. Run ATF suites on demand. Query dev, staging, and prod simultaneously. Automate across multiple customer tenants without switching tabs. **Your AI, your instance, your rules.**
+
+**Any AI. Any instance. Any scale. 100% open-source.**
+
+> **Keywords:** ServiceNow MCP server · Model Context Protocol · ServiceNow AI · ITSM automation · ServiceNow Claude · ServiceNow ChatGPT · ServiceNow Cursor · ServiceNow Copilot · ServiceNow LLM · ServiceNow agent · MCP tools · ServiceNow API · agentic AI · ServiceNow developer tools
+
+<br/>
+
+| | |
+|---|---|
+| **Beginners** | Zero ServiceNow API knowledge needed. Connect in 5 minutes. Ask in plain English. Free PDI at developer.servicenow.com. |
+| **Developers** | Write, deploy, test, and manage scripts, flows, widgets, and integrations at AI speed — 10x faster. |
+| **Architects & MSPs** | Orchestrate multi-step autonomous workflows. Compare environments. Manage multiple customer tenants in one session. |
+
+<br/>
+
+</div>
+
+---
+
+## Who Is This For?
+
+<table>
+<tr>
+<td width="33%" valign="top">
+
+### Beginners
+**Zero ServiceNow API knowledge required.**
+
+Connect Claude Desktop or Cursor to your free PDI in 5 minutes. Ask questions in plain English, browse incidents, search KB articles, place catalog orders, monitor SLAs — all from your AI chat window. No code. No Postman. No documentation diving. Just ask.
+
+*Start here → [5-Minute Quickstart](#getting-started)*
+
+</td>
+<td width="33%" valign="top">
+
+### Developers
+**10x faster with AI as your development partner.**
+
+Write business rules, deploy client scripts, manage UI Policies and ACLs, create Service Portal widgets, configure REST Messages, manage Transform Maps, and update changesets — all in plain English. Full TypeScript types, ATF integration, and role-based packages built in.
+
+*Explore → [Platform Developer Package](#role-based-tool-packages)*
+
+</td>
+<td width="33%" valign="top">
+
+### Architects, Admins & MSPs
+**Autonomous workflows. Multi-instance. Multi-customer.**
+
+Trigger Agentic Playbooks, orchestrate multi-step ITSM/HRSD/CSM processes, compare environments side by side, manage dozens of customer tenants in one session, and run full data quality audits — at AI speed, across your entire ServiceNow estate.
+
+*Deep dive → [Now Assist & Agentic Guide](docs/NOW_ASSIST.md)*
+
+</td>
+</tr>
+</table>
+
+---
+
+## Why servicenow-mcp
+
+<table>
+<tr>
+<td width="33%" valign="top">
+
+### Fully Autonomous AI Operations
+
+Your AI doesn't just answer questions — it *acts*. Create incidents, write and deploy scripts, trigger flows, fire events, upload attachments, manage changesets, and run full ATF suites — end-to-end, without manual steps. Native Now Assist Agentic Playbook support for next-generation ServiceNow AI automation.
+
+</td>
+<td width="33%" valign="top">
+
+### Works With Every AI, Out of the Box
+
+**Claude, ChatGPT, Gemini, Grok, Cursor, Windsurf, GitHub Copilot, Amazon Q, JetBrains, Continue.dev, Cline, Zed, Google AI Studio, Ollama** — all supported out of the box. Any MCP-compatible client. Any custom Python or TypeScript agent. One server, every AI platform, zero lock-in.
+
+</td>
+<td width="33%" valign="top">
+
+### Unmatched Platform Coverage
+
+**400+ production-ready tools** across every ServiceNow domain — ITSM, ITOM, HRSD, CSM, SecOps, GRC, Agile, ATF, Flow Designer, Scripting, Now Assist, Service Portal, Integration Hub, Performance Analytics, System Properties, Update Sets, Virtual Agent, ITAM, DevOps, Machine Learning, Workspace/UIB, Mobile, and Deployment. Nothing else comes close.
+
+</td>
+</tr>
+<tr>
+<td width="33%" valign="top">
+
+### Role-Based Tool Intelligence
+
+Fourteen pre-built persona packages — service desk, platform developer, portal developer, integration engineer, ITOM engineer, AI developer, ITAM analyst, DevOps engineer, and more. Each exposes exactly the right tools for that role. Reduce noise, enforce least-privilege, and configure once per team.
+
+</td>
+<td width="33%" valign="top">
+
+### Safe by Default, Powerful When Needed
+
+A five-tier permission model keeps your instance protected. **Read is always on.** Write, CMDB, Scripting, Now Assist, and ATF capabilities each require an explicit opt-in flag. No AI can accidentally modify your production data. Scale permissions as your confidence grows — without touching code.
+
+</td>
+<td width="33%" valign="top">
+
+### True Multi-Instance & Multi-Customer
+
+Connect to **unlimited ServiceNow instances** from one session — dev, staging, prod, *and* multiple customer tenants simultaneously. Pass `instance: "acme_prod"` on any tool call, or `switch_instance` globally. MSPs, consultants, and enterprise teams can compare, query, and automate across every environment at once. No other ServiceNow MCP server does this.
+
+</td>
+</tr>
+</table>
+
+---
+
+## Quick Links
+
+| Resource | Link |
+|----------|------|
+| All Tools Reference | [docs/TOOLS.md](docs/TOOLS.md) |
+| Client Setup (All AI tools, beginner + advanced) | [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md) |
+| Role-Based Tool Packages | [docs/TOOL_PACKAGES.md](docs/TOOL_PACKAGES.md) |
+| Now Assist & AI Integration | [docs/NOW_ASSIST.md](docs/NOW_ASSIST.md) |
+| ATF Testing Guide | [docs/ATF.md](docs/ATF.md) |
+| Scripting Management | [docs/SCRIPTING.md](docs/SCRIPTING.md) |
+| Reporting & Analytics | [docs/REPORTING.md](docs/REPORTING.md) |
+| Multi-Instance Setup | [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) |
+| 120+ Real-World Examples | [EXAMPLES.md](EXAMPLES.md) |
+| Changelog | [CHANGELOG.md](CHANGELOG.md) |
+
+---
+
+## Module Coverage
+
+Domain modules covering the full ServiceNow platform:
+
+| Module | Key Capabilities |
+|--------|-----------------|
+| Core & CMDB | Record query, schema discovery, CMDB CIs, ITOM Discovery, MID Servers, multi-instance management |
+| Incident Management | Create, update, resolve, close, work notes, comments |
+| Problem Management | Problem records, root cause analysis, known errors |
+| Change Management | Create, get, update, submit for approval, close change requests |
+| Task Management | Generic tasks, my-task lists, completions |
+| Knowledge Base | Search, create, update, publish KB articles |
+| Service Catalog & Approvals | Catalog browsing, create/update items, order items, SLA tracking, approval workflows, approval rules |
+| User & Group Management | Users, groups, membership, role assignments |
+| Reporting & Analytics | Aggregate queries, trend analysis, create/update reports, scheduled job CRUD, run history |
+| ATF Testing | Test suites, test execution, ATF Failure Insight |
+| Now Assist / AI | NLQ, AI Search, summaries, resolution suggestions, Agentic Playbooks |
+| Scripting | Business rules, script includes, client script CRUD, UI Policies, UI Actions, ACL management, changesets |
+| Agile / Scrum | Stories, epics, sprints, scrum tasks |
+| HR Service Delivery (HRSD) | HR cases, HR services, employee profiles, onboarding/offboarding |
+| Customer Service Management (CSM) | Customer cases, accounts, contacts, products, SLAs |
+| Security Operations & GRC | SecOps incidents, vulnerabilities, GRC risks, controls, threat intel |
+| Flow Designer & Process Automation | Flows, subflows, triggers, executions, Process Automation playbooks |
+| Service Portal & UI Builder | Create/list portals & pages, widgets (create/update/deploy), Next Experience apps/pages, themes |
+| Integration Hub | REST Messages, Transform Maps, Import Sets, Event Registry, OAuth apps, credential aliases |
+| Notifications & Attachments | Email notifications, email logs, file attachments (upload/list/delete), templates, subscriptions |
+| Performance Analytics | PA indicators/scorecards, time-series, create/update dashboards, PA jobs, data quality checks |
+| System Properties | Get, set, bulk operations, validate, export/import, audit history |
+| Update Set Management | Create, switch, preview, complete, export, auto-ensure active set |
+| Virtual Agent (VA) | Topic authoring, conversation history, categories, topic listing |
+| IT Asset Management (ITAM) | Assets, software licenses, contracts, compliance reporting |
+| DevOps & Pipeline Tracking | Pipelines, deployments, change governance, DORA metrics |
+| Scoped Applications (App Studio) | List, get, create, and update scoped application records |
+
+---
+
+## Authentication
+
+Two authentication methods are supported:
+
+| Method | Best For |
+|--------|----------|
+| **Basic Auth** | Development, personal instances, quick setup |
+| **OAuth 2.0** (client credentials / password grant) | Production deployments, service accounts |
+
+For OAuth setup in ServiceNow, see [docs/SERVICENOW_OAUTH_SETUP.md](docs/SERVICENOW_OAUTH_SETUP.md).
+
+---
+
+## Permission System
+
+A five-tier permission model keeps your instance safe by default:
+
+| Tier | Environment Variable | Covers |
+|------|---------------------|--------|
+| 0 — Read | *(always on)* | All query and read operations |
+| 1 — Write | `WRITE_ENABLED=true` | Create/update across ITSM, HRSD, CSM, Agile |
+| 2 — CMDB Write | `CMDB_WRITE_ENABLED=true` | CI create/update in the CMDB |
+| 3 — Scripting | `SCRIPTING_ENABLED=true` | Business rules, script includes, changesets |
+| 4 — Now Assist | `NOW_ASSIST_ENABLED=true` | AI Agentic Playbooks, NLQ, AI Search |
+
+---
+
+## Role-Based Tool Packages
+
+Set `MCP_TOOL_PACKAGE` to expose only the tools relevant to each persona:
+
+| Package | Persona | Tools Included |
+|---------|---------|---------------|
+| `full` | Administrators | All tools (400+) |
+| `service_desk` | L1/L2 Agents | Incidents, tasks, approvals, KB, SLA |
+| `change_coordinator` | Change Managers | Changes (create/approve/close), CAB, CMDB, approvals |
+| `knowledge_author` | KB Authors | Knowledge base create/publish |
+| `catalog_builder` | Catalog Admins | Catalog, users, groups |
+| `system_administrator` | Sys Admins | Users, groups, reports, logs, notifications, attachments, ACLs, PA |
+| `platform_developer` | Developers | Scripts, UI Policies, UI Actions, ACLs, client scripts, ATF, changesets |
+| `portal_developer` | Portal/UX Devs | Portals, pages, widgets (create/update), UI Policies, UI Actions, client scripts |
+| `integration_engineer` | Integration Devs | REST Messages, Transform Maps, Import Sets, Events, OAuth, credentials |
+| `itom_engineer` | ITOM Engineers | CMDB, Discovery, MID servers, events |
+| `agile_manager` | Scrum Masters | Stories, epics, sprints |
+| `ai_developer` | AI Builders | Now Assist, NLQ, Agentic Playbooks |
+
+---
+
+## Getting Started
+
+### Option A — Interactive Setup Wizard (Recommended)
+
+```bash
+# Install globally (Node.js 20+ required)
+npm install -g servicenow-mcp
+
+# Run the wizard — detects your AI clients and writes config automatically
+npx servicenow-mcp setup
+```
+
+The wizard will:
+1. Ask for your ServiceNow instance URL + credentials
+2. Test the connection
+3. Let you pick a tool package and permission level
+4. Detect Claude Desktop, Cursor, VS Code, Windsurf, Continue.dev, Claude Code on your machine
+5. Write the config directly — no copy-paste, no manual JSON editing
+
+```
+# Add a second instance later
+servicenow-mcp setup --add
+
+# Manage instances
+servicenow-mcp instances list
+```
+
+### Option B — Manual Setup
+
+```bash
+git clone https://github.com/aartiq/servicenow-mcp.git && cd servicenow-mcp
+npm install && npm run build
+cp .env.example .env   # fill in your ServiceNow credentials
+```
+
+Then point your AI client at `dist/server.js` — see [Supported AI Clients](#supported-ai-clients) below.
+
+> **No ServiceNow instance?** Get a free Personal Developer Instance at [developer.servicenow.com](https://developer.servicenow.com) — ready in minutes.
+
+**Full installation guide → [docs/INSTALLATION.md](docs/INSTALLATION.md)**
+
+---
+
+## Client Setup Guides
+
+Step-by-step setup for every major AI client — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, GitHub Copilot, Continue.dev, Cline, JetBrains, Amazon Q, Google AI Studio, ChatGPT, Grok, Ollama, and more.
+
+**Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)**
+
+For quick setup snippets, see the [Supported AI Clients](#supported-ai-clients) section below.
+---
+
+## Example Interactions
+
+Once connected, ask your AI assistant in plain language:
+
+**ITSM & Change Management:**
+```
+Show me all open P1 incidents assigned to the Network Operations group.
+```
+```
+Create a normal change request for deploying the new API gateway — implementation planned for Saturday midnight.
+```
+```
+What CMDB CIs does the ERP application depend on?
+```
+
+**Scripting & Development:**
+```
+List all client scripts on the incident table and show me the ones that fire on form load.
+```
+```
+Create a UI action button "Escalate to L3" on the incident form that assigns the ticket to the L3-Support group.
+```
+```
+Show me all ACL rules for the change_request table that restrict the "delete" operation.
+```
+
+**Service Portal & UI Builder:**
+```
+List all widgets in the Service Portal that contain "catalog" in their name.
+```
+```
+Get the full source code of the "Stock Ticker" widget so I can update its server script.
+```
+```
+Create a new portal widget called "My Approvals Widget" with a simple Angular template that lists pending approvals.
+```
+
+**Integrations & Events:**
+```
+List all REST Message definitions that connect to external APIs.
+```
+```
+Show me all transform maps that target the incident table.
+```
+```
+Fire the custom event "myapp.ticket.escalated" on incident INC0012345.
+```
+
+For 120+ real-world examples with inputs, outputs, and advanced workflows, see [EXAMPLES.md](EXAMPLES.md).
+
+---
+
+## Slash Commands & @ Mentions
+
+Once connected, type `/` in Claude Desktop or Cursor to see built-in ServiceNow shortcuts:
+
+| Command | What it does |
+|---------|-------------|
+| `/morning-standup` | P1/P2 open incidents, changes due today, SLA breaches |
+| `/my-tickets` | All open tasks/incidents assigned to you |
+| `/p1-alerts` | Active P1 incidents with time-open and assignee |
+| `/my-changes` | Your pending change requests and approval status |
+| `/create-incident` | Guided incident creation |
+| `/sla-breaches` | Records currently breaching SLA |
+| `/ci-health` | CMDB CI health check |
+| `/run-atf` | Trigger ATF test suite |
+| `/switch-instance` | Interactive instance picker |
+| `/knowledge-search` | Search KB articles |
+| `/deploy-updateset` | Guided update set commit |
+
+Type `@` to pull live ServiceNow data into your AI context:
+
+| Mention | Returns |
+|---------|---------|
+| `@my-incidents` | Your open incidents |
+| `@open-changes` | Pending change requests |
+| `@sla-breaches` | Records breaching SLA now |
+| `@instance:info` | Current instance metadata |
+| `@ci:<name>` | CMDB CI by name |
+| `@kb:<title>` | Knowledge article by title |
+
+Add your own commands in `servicenow-mcp.commands.json`:
+
+```json
+[
+  {
+    "name": "my-p1-runbook",
+    "description": "P1 runbook for my team",
+    "template": "List all P1 incidents in the Network category. For each: number, description, assignee, time open. Flag SLA breaches."
+  }
+]
+```
+
+## Advanced Configuration
+
+| Topic | Guide |
+|-------|-------|
+| OAuth 2.0 setup (ServiceNow OAuth app creation) | [docs/SERVICENOW_OAUTH_SETUP.md](docs/SERVICENOW_OAUTH_SETUP.md) |
+| Multi-instance / multi-customer (dev, staging, prod, tenants) | [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) |
+| Role-based tool packages | [docs/TOOL_PACKAGES.md](docs/TOOL_PACKAGES.md) |
+| All environment variables reference | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
+
+---
+
+## Supported AI Clients
+
+**Any MCP-compatible AI works.** servicenow-mcp has been tested with every major AI assistant, editor, and agent framework. Pick yours and follow the 3-step setup below.
+
+### AI Assistants & Chat
+
+<details>
+<summary><b>Claude Desktop</b> — Anthropic (Mac / Windows / Linux)</summary>
+
+1. Install Claude Desktop from [claude.ai/download](https://claude.ai/download)
+2. Edit config:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+3. Add this block — **single instance** (replace path and credentials):
+
+```json
+{
+  "mcpServers": {
+    "servicenow-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+        "SERVICENOW_AUTH_METHOD": "basic",
+        "SERVICENOW_BASIC_USERNAME": "admin",
+        "SERVICENOW_BASIC_PASSWORD": "your_password",
+        "WRITE_ENABLED": "false"
+      }
+    }
+  }
+}
+```
+
+Or use **multi-instance** (dev + staging + prod, or multiple customer tenants):
+
+```json
+{
+  "mcpServers": {
+    "servicenow-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
+      "env": {
+        "SN_INSTANCES_CONFIG": "/absolute/path/to/instances.json"
+      }
+    }
+  }
+}
+```
+
+Copy `instances.example.json` → `instances.json`, fill in your instances, then ask:
+> *"List instances"* → *"Switch to prod"* → *"Show me all P1 incidents"*
+> *"Get open changes from customer_acme"* (uses `instance` parameter per-call)
+
+4. Restart Claude Desktop. The hammer icon confirms connection.
+
+Full guide → [clients/claude-desktop/SETUP.md](clients/claude-desktop/SETUP.md) | [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md)
+</details>
+
+<details>
+<summary><b>ChatGPT / OpenAI</b> (API)</summary>
+
+OpenAI supports MCP via the **Responses API** (`mcp` tool type) in the latest SDK (v1.50+):
+
+```python
+from openai import OpenAI
+import os, subprocess
+
+# Start servicenow-mcp as a subprocess MCP server
+proc = subprocess.Popen(
+    ["node", "/path/to/servicenow-mcp/dist/server.js"],
+    stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+    env={**os.environ,
+         "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+         "SERVICENOW_AUTH_METHOD": "basic",
+         "SERVICENOW_BASIC_USERNAME": "admin",
+         "SERVICENOW_BASIC_PASSWORD": "your_password"}
+)
+
+client = OpenAI()
+response = client.responses.create(
+    model="gpt-4o",
+    tools=[{"type": "mcp", "server_label": "servicenow-mcp"}],
+    input="Show me all open P1 incidents"
+)
+```
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+<details>
+<summary><b>Google Gemini / Vertex AI</b> (API)</summary>
+
+1. Install servicenow-mcp: `npm install -g servicenow-mcp`
+2. Use the Python client in `clients/gemini/`:
+
+```bash
+pip install google-generativeai
+python clients/gemini/servicenow_gemini_client.py
+```
+
+Full guide → [clients/gemini/SETUP.md](clients/gemini/SETUP.md)
+</details>
+
+---
+
+### AI Code Editors
+
+<details>
+<summary><b>Cursor</b> — AI-first code editor</summary>
+
+1. Open Cursor → Settings → MCP
+2. Add server config:
+
+```json
+{
+  "mcpServers": {
+    "servicenow-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+        "SERVICENOW_AUTH_METHOD": "basic",
+        "SERVICENOW_BASIC_USERNAME": "admin",
+        "SERVICENOW_BASIC_PASSWORD": "your_password",
+        "WRITE_ENABLED": "true",
+        "SCRIPTING_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+3. Restart Cursor. Ask in Chat: *"List all open P1 incidents"*
+
+**Multi-instance:** Replace the env block with `"SN_INSTANCES_CONFIG": "/path/to/instances.json"` to connect to multiple tenants.
+
+Full guide → [clients/cursor/SETUP.md](clients/cursor/SETUP.md)
+</details>
+
+<details>
+<summary><b>Windsurf (Codeium)</b> — AI-native editor</summary>
+
+1. Open Windsurf → Cascade → Configure MCP
+2. Add the same JSON block as Cursor above
+3. Reload Windsurf window
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+<details>
+<summary><b>Zed Editor</b> — collaborative AI editor</summary>
+
+1. Open Zed → `~/.config/zed/settings.json`
+2. Add under `"context_servers"`:
+
+```json
+{
+  "context_servers": {
+    "servicenow-mcp": {
+      "command": { "path": "node", "args": ["/path/to/servicenow-mcp/dist/server.js"] },
+      "settings": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+        "SERVICENOW_AUTH_METHOD": "basic",
+        "SERVICENOW_BASIC_USERNAME": "admin",
+        "SERVICENOW_BASIC_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+---
+
+### IDE Extensions
+
+<details>
+<summary><b>VS Code</b> — Native MCP (v1.99+, no subscription required)</summary>
+
+VS Code 1.99 and later includes built-in MCP support — no extension or subscription required.
+
+1. Install [VS Code 1.99+](https://code.visualstudio.com/download)
+2. Create `.vscode/mcp.json` in your workspace (or edit User settings):
+
+```json
+{
+  "servers": {
+    "servicenow-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/absolute/path/to/servicenow-mcp/dist/server.js"],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+        "SERVICENOW_AUTH_METHOD": "basic",
+        "SERVICENOW_BASIC_USERNAME": "admin",
+        "SERVICENOW_BASIC_PASSWORD": "your_password",
+        "WRITE_ENABLED": "true",
+        "SCRIPTING_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
+3. Open the Command Palette (`Cmd/Ctrl+Shift+P`) → **MCP: List Servers** to verify the connection
+4. Open Copilot Chat (or any AI assistant in VS Code) and use `@servicenow-mcp` or just ask naturally
+
+> **Tip:** Add `.vscode/mcp.json` to `.gitignore` if it contains credentials, or use environment variables from a `.env` file.
+
+Full guide → [clients/vscode/SETUP.md](clients/vscode/SETUP.md)
+</details>
+
+<details>
+<summary><b>VS Code — GitHub Copilot</b> (agent mode)</summary>
+
+1. Install VS Code + GitHub Copilot extension
+2. Create `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "servicenow-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/../../servicenow-mcp/dist/server.js"],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+        "SERVICENOW_AUTH_METHOD": "basic",
+        "SERVICENOW_BASIC_USERNAME": "admin",
+        "SERVICENOW_BASIC_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+3. Open Copilot Chat → Agent mode → `@servicenow-mcp`
+
+Full guide → [clients/vscode/SETUP.md](clients/vscode/SETUP.md)
+</details>
+
+<details>
+<summary><b>VS Code — Continue.dev</b> (open-source Copilot alternative)</summary>
+
+1. Install [Continue](https://marketplace.visualstudio.com/items?itemName=Continue.continue) from VS Code Marketplace
+2. Edit `~/.continue/config.json`:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "servicenow-mcp",
+      "command": "node",
+      "args": ["/path/to/servicenow-mcp/dist/server.js"],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+        "SERVICENOW_AUTH_METHOD": "basic",
+        "SERVICENOW_BASIC_USERNAME": "admin",
+        "SERVICENOW_BASIC_PASSWORD": "your_password"
+      }
+    }
+  ]
+}
+```
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+<details>
+<summary><b>VS Code — Cline</b> (autonomous AI agent)</summary>
+
+1. Install [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) from VS Code Marketplace
+2. Open Cline → MCP Servers → Add Server
+3. Enter the path to `servicenow-mcp/dist/server.js` and your environment variables
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+<details>
+<summary><b>JetBrains AI Assistant</b> (IntelliJ IDEA, PyCharm, WebStorm, etc.)</summary>
+
+1. Install JetBrains AI Assistant plugin
+2. Go to Settings → Tools → AI Assistant → MCP Servers
+3. Add a new server with the path to `servicenow-mcp/dist/server.js`
+4. Set environment variables in the server configuration dialog
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+<details>
+<summary><b>Amazon Q Developer</b> (AWS CLI + IDE)</summary>
+
+1. Install Amazon Q Developer extension for VS Code or IntelliJ
+2. Configure MCP via `~/.aws/amazonq/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "servicenow-mcp": {
+      "command": "node",
+      "args": ["/path/to/servicenow-mcp/dist/server.js"],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com",
+        "SERVICENOW_AUTH_METHOD": "basic",
+        "SERVICENOW_BASIC_USERNAME": "admin",
+        "SERVICENOW_BASIC_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+---
+
+### CLI & Terminal Agents
+
+<details>
+<summary><b>Claude Code / Claude CLI</b> — Anthropic's official CLI</summary>
+
+```bash
+# Install Claude Code
+npm install -g @anthropic-ai/claude-code
+
+# Register servicenow-mcp as an MCP server
+claude mcp add servicenow-mcp node /absolute/path/to/servicenow-mcp/dist/server.js \
+  --env SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com \
+  --env SERVICENOW_AUTH_METHOD=basic \
+  --env SERVICENOW_BASIC_USERNAME=admin \
+  --env SERVICENOW_BASIC_PASSWORD=your_password
+
+# Verify
+claude mcp list
+
+# Use it
+claude "Show me all unresolved P1 incidents"
+```
+
+Full guide → [clients/claude-code/SETUP.md](clients/claude-code/SETUP.md)
+</details>
+
+<details>
+<summary><b>Ollama</b> — run AI locally (Llama, Mistral, Phi, etc.)</summary>
+
+1. Install [Ollama](https://ollama.ai) and pull a model: `ollama pull llama3`
+2. Use an MCP-compatible client (e.g. Cline or Continue) configured to use Ollama as the model
+3. Point the MCP server at `servicenow-mcp/dist/server.js`
+
+Full guide → [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)
+</details>
+
+---
+
+### Quick Reference
+
+| Client | Type | Auth | Guide |
+|--------|------|------|-------|
+| Claude Desktop | Desktop app | Basic, OAuth | [Setup](clients/claude-desktop/SETUP.md) |
+| Claude Code CLI | Terminal | Basic, OAuth | [Setup](clients/claude-code/SETUP.md) |
+| Cursor | AI editor | Basic, OAuth | [Setup](clients/cursor/SETUP.md) |
+| Windsurf | AI editor | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| Zed | AI editor | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| **VS Code** (Native MCP 1.99+) | IDE | Basic, OAuth | [Setup](clients/vscode/SETUP.md) |
+| VS Code + GitHub Copilot | IDE | Basic, OAuth | [Setup](clients/vscode/SETUP.md) |
+| VS Code + Continue.dev | IDE | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| VS Code + Cline | IDE | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| JetBrains AI | IDE | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| Amazon Q Developer | IDE / CLI | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| ChatGPT / OpenAI | API | Basic, OAuth | [Setup](clients/codex/SETUP.md) |
+| **Google AI Studio** | API / Agent | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| Google Gemini API | API | Basic, OAuth | [Setup](clients/gemini/SETUP.md) |
+| Grok (xAI) | API | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+| Ollama (local) | Local | Basic | [Setup](docs/CLIENT_SETUP.md) |
+| Anthropic Agent SDK | Python | Basic, OAuth | [Setup](docs/CLIENT_SETUP.md) |
+
+---
+
+## What's New in v1.0
+
+Initial public release of **servicenow-mcp** — 400+ ServiceNow MCP tools, full CLI, multi-instance support, and 14 role-based tool packages. See [CHANGELOG.md](CHANGELOG.md) for details.
+
+---
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [docs/TOOLS.md](docs/TOOLS.md) | Complete reference for all tools with parameters, return types, and permission requirements |
+| [docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md) | Step-by-step beginner + advanced setup for all AI clients |
+| [docs/TOOL_PACKAGES.md](docs/TOOL_PACKAGES.md) | Role-based package reference — which tools each of the 14 persona packages includes |
+| [docs/NOW_ASSIST.md](docs/NOW_ASSIST.md) | Now Assist and AI integration guide — NLQ, AI Search, Agentic Playbooks |
+| [docs/ATF.md](docs/ATF.md) | ATF testing guide — suites, test runs, ATF Failure Insight |
+| [docs/SCRIPTING.md](docs/SCRIPTING.md) | Scripting management — business rules, script includes, UI Policies, UI Actions, ACLs, changesets |
+| [docs/REPORTING.md](docs/REPORTING.md) | Reporting and analytics — aggregate queries, Performance Analytics, scheduled jobs |
+| [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md) | Multi-instance configuration via `instances.json` or environment variables |
+| [docs/SERVICENOW_OAUTH_SETUP.md](docs/SERVICENOW_OAUTH_SETUP.md) | Creating an OAuth application in ServiceNow for secure API access |
+| [docs/INSTALLATION.md](docs/INSTALLATION.md) | Full installation guide including environment variables reference |
+| [EXAMPLES.md](EXAMPLES.md) | 120+ real-world examples with inputs, outputs, and advanced workflows |
+
+---
+
+## Development
+
+```bash
+npm install          # install dependencies
+npm run build        # compile TypeScript → dist/
+npm test             # run unit tests
+npm run dev          # watch mode (hot reload)
+npm run type-check   # TypeScript type check only
+npm run lint         # lint
+```
+
+### Project Structure
+
+```
+src/
+  server.ts              — MCP server entry point (stdio)
+  servicenow/
+    client.ts            — ServiceNow REST API client (Basic / OAuth / per-user)
+    instances.ts         — Multi-instance manager
+    types.ts             — TypeScript type definitions + AuthMode
+  tools/
+    index.ts             — Tool router & role-based package system
+    core.ts, incident.ts, change.ts, problem.ts, task.ts
+    knowledge.ts, catalog.ts, user.ts, reporting.ts, atf.ts
+    now-assist.ts, script.ts, agile.ts, hrsd.ts, csm.ts
+    security.ts, flow.ts, portal.ts, integration.ts, notification.ts
+    performance.ts, sys-properties.ts, updateset.ts, va.ts, itam.ts, devops.ts
+  prompts/
+    index.ts             — MCP prompts registry (/ slash commands)
+    itsm.ts              — 11 built-in slash commands
+    user-prompts.ts      — Custom commands from servicenow-mcp.commands.json
+  resources/
+    index.ts             — MCP resources (@ mentions)
+  cli/
+    index.ts             — CLI entry point (commander.js)
+    setup.ts             — Interactive setup wizard
+    detect-clients.ts    — Auto-detect installed AI clients
+    config-store.ts      — ~/.config/servicenow-mcp/instances.json
+    auth.ts              — servicenow-mcp auth login/logout/whoami
+    writers/index.ts     — Write configs to AI client config files
+  utils/
+    permissions.ts       — Five-tier permission gate functions
+    errors.ts            — Typed error classes
+    logging.ts           — Structured logger
+tests/
+  tools/                 — Unit tests
+docs/                    — Reference documentation
+clients/
+  claude-desktop/        — Claude Desktop setup guide
+  cursor/                — Cursor setup guide
+  vscode/                — VS Code setup guide
+  claude-code/           — Claude Code setup guide
+  codex/                 — OpenAI Codex Python client
+  gemini/                — Google Gemini Python client
+smithery.yaml            — Smithery registry config
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+
+- Bug reports and feature requests: [open an issue](../../issues)
+- New tool domains, additional tests, or documentation improvements are especially appreciated
+- All PRs require `npm test` to pass
+
+---
+
+## Security
+
+If you discover a security vulnerability, please follow the responsible disclosure process in [SECURITY.md](SECURITY.md). Do not open a public issue.
+
+---
+
+## Frequently Asked Questions
+
+**Do I need to know the ServiceNow API to use this?**
+No. For beginners, you just connect your AI and ask questions in plain English. The server handles all API calls automatically.
+
+**Which ServiceNow versions are supported?**
+All actively supported ServiceNow releases. The server targets the latest available APIs and has been tested on the three most recent releases.
+
+**Can I use this on a free Personal Developer Instance (PDI)?**
+Yes. Get a free PDI at [developer.servicenow.com](https://developer.servicenow.com) and connect in 5 minutes.
+
+**Is it safe to use on production?**
+Yes. The permission system is read-only by default. Write, scripting, and Now Assist capabilities must each be explicitly enabled with environment variables. Use role packages to limit the tool surface.
+
+**Does it support multi-instance / multiple customers?**
+Yes. Configure any number of instances (prod, staging, dev, or multiple customer tenants) via `instances.json` or environment variables. Use `list_instances`, `switch_instance`, and `get_current_instance` tools to manage them, or pass `instance: "name"` to any individual tool call. See [docs/MULTI_INSTANCE.md](docs/MULTI_INSTANCE.md).
+
+**Is it free?**
+Completely free and open-source under the MIT license.
+
+---
+
+## License
+
+[MIT](LICENSE) — free for personal and commercial use.
+
+---
+
+<div align="center">
+
+### The only ServiceNow MCP server you'll ever need.
+
+400+ tools. 31+ modules. Every AI platform. True multi-instance. Open-source forever.
+
+**servicenow-mcp** &bull; ServiceNow MCP Server &bull; ServiceNow AI Agent &bull; ServiceNow Claude Integration &bull; ServiceNow ChatGPT &bull; ServiceNow Cursor &bull; ServiceNow Gemini &bull; ServiceNow Automation &bull; ServiceNow Developer Tools &bull; ServiceNow Multi-Instance &bull; ServiceNow MSP
+
+If servicenow-mcp saves you time, please ⭐ star the repository — it helps others find the project.
+
+[![GitHub Stars](https://img.shields.io/github/stars/aartiq/servicenow-mcp?style=social)](../../stargazers)
+
+</div>