convez.ai
MCP Server
mdasiff

servicenow-mcp

mdasiff/servicenow-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

servicenow incident mcp server ai agent | node.js typescript

Instalação

$npx convez-ai mdasiff/servicenow-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

ServiceNow Incident MCP Server

A production-ready Model Context Protocol (MCP) server that turns any MCP-compatible AI assistant (Claude, Cursor, etc.) into an AI-powered ServiceNow Incident Management Assistant. It exposes ServiceNow incidents, users, CMDB records, and knowledge articles through clean, validated MCP tools.

AI Assistant  ──►  MCP Server (Node.js + TypeScript)  ──►  ServiceNow REST API  ──►  ServiceNow Instance

Features

  • 12 MCP tools across three phases (read, actions, AI-powered helpers).
  • Reusable ServiceNow REST client (Axios) with Basic auth, request timeout, and exponential-backoff retry on transient failures.
  • Zod-validated inputs for every tool.
  • Structured logging to stderr with automatic secret redaction — passwords and auth headers are never logged.
  • Self-contained, deterministic AI tools — no external LLM or API key required.
  • Modular, enterprise-grade architecture with a full unit-test suite (Vitest).

Project Structure

src/
├── clients/
│   └── servicenowClient.ts   # Axios wrapper: GET/POST/PATCH, auth, retry, timeout, Table API helpers
├── config/
│   └── env.ts                # Zod-validated environment configuration
├── schemas/
│   └── index.ts              # Zod input schemas for every tool
├── services/
│   ├── incidentService.ts    # incident reads/writes + journal (comments/work notes)
│   ├── userService.ts        # sys_user lookups
│   ├── cmdbService.ts        # cmdb_ci search
│   ├── knowledgeService.ts   # kb_knowledge search
│   ├── aiService.ts          # rule-based classification, routing, summaries
│   └── index.ts              # service container
├── tools/
│   ├── phase1.read.ts        # get_incident, search_incidents, get_user, search_cmdb, get_knowledge_article
│   ├── phase2.actions.ts     # create_incident, update_incident, assign_incident, close_incident
│   ├── phase3.ai.ts          # classify_incident, incident_summary, suggest_assignment_group
│   ├── helpers.ts            # response builders + central error handling
│   └── index.ts              # registers all tools
├── types/
│   └── servicenow.ts         # shared TypeScript interfaces
├── utils/
│   ├── logger.ts             # structured logger + redaction
│   ├── errors.ts             # ServiceNowError + safe message mapping
│   └── format.ts             # raw ServiceNow record → clean object mappers
├── server.ts                 # builds the MCP server (config → client → services → tools)
└── index.ts                  # entrypoint (stdio transport)
tests/                        # Vitest unit tests

Setup

Prerequisites

  • Node.js 18+
  • A ServiceNow instance and an account with Table API access.

Install & build

npm install
cp .env.example .env      # then edit .env with your instance + credentials
npm run build

Configure environment

VariableRequiredDefaultDescription
SNOW_INSTANCEyes—Instance base URL, e.g. https://dev123.service-now.com
SNOW_USERNAMEyes—Basic auth username
SNOW_PASSWORDyes—Basic auth password
SNOW_TIMEOUT_MSno30000Per-request timeout (ms)
SNOW_MAX_RETRIESno3Retry attempts on network/429/5xx errors
SNOW_DEFAULT_LIMITno10Default result count for search tools
LOG_LEVELnoinfodebug | info | warn | error

Run

npm start          # run the built server (dist/index.js)
npm run dev        # run from TypeScript with hot reload

The server speaks MCP over stdio.

Tool Reference

Phase 1 — Read

ToolInputReturns
get_incident{ incidentNumber }Number, state, priority, assignment group, assignee, descriptions, timestamps
search_incidents{ assignedTo?, caller?, priority?, state?, limit? }Matching incidents (newest first)
get_user{ userName }User name, email, phone, title, department
search_cmdb{ name, limit? }Matching CMDB CIs
get_knowledge_article{ keyword, limit? }Matching published KB articles

Phase 2 — Actions

ToolInputEffect
create_incident{ shortDescription, description?, callerId?, assignmentGroup?, impact?, urgency? }Creates an incident → { incidentNumber, sysId }
update_incident{ incidentNumber, workNote?, comment? }Appends work note / comment
assign_incident{ incidentNumber, assignmentGroup?, assignedTo? }Updates assignment
close_incident{ incidentNumber, closeNotes, closeCode? }Resolves & closes the incident

Phase 3 — AI-powered (deterministic, rule-based)

ToolInputReturns
classify_incident{ issue }{ impact, urgency, priority, reason }
incident_summary{ incidentNumber }Executive summary built from the incident + journal
suggest_assignment_group{ issue }{ assignmentGroup, reason }

Classification Logic

classify_incident mirrors ServiceNow's Impact × Urgency → Priority matrix. It infers impact from the scope of the issue and urgency from time-critical language, both via documented keyword rules (case-insensitive, first match wins).

Scope detected in the issue textImpactUrgencyPriority
Entire office / company / site / everyone11P1
Entire team / department / group / floor22P2
Single employee / one user / "my…"32P3
Minor / cosmetic / typo / question / slow33P4
Unrecognized (default)33P3

Time-critical words (urgent, critical, outage, down, blocked, cannot work, production, emergency, …) escalate urgency → 1, and priority is recomputed from the matrix:

 Impact \ Urgency   1    2    3
        1          P1   P2   P3
        2          P2   P3   P4
        3          P3   P4   P4

suggest_assignment_group uses a keyword→group routing table (VPN/network → Network Operations, email/Outlook → Messaging & Collaboration, password/login → Identity & Access Management, database/SQL → Database Team, laptop/printer → Desktop Support, phone/call forwarding → Telephony, application/crash → Application Support), defaulting to Service Desk.

These rules live in src/services/aiService.ts and are easy to tune for your org's groups.

Sample MCP Client Configuration

Add the server to your MCP client config. Use absolute paths and supply credentials via env.

Claude Desktop (claude_desktop_config.json) / Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp/dist/index.js"],
      "env": {
        "SNOW_INSTANCE": "https://dev12345.service-now.com",
        "SNOW_USERNAME": "admin",
        "SNOW_PASSWORD": "your-password",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Run npm run build first so dist/index.js exists.

Testing & Quality

npm test            # run the unit test suite (Vitest)
npm run test:coverage
npm run typecheck   # tsc --noEmit
npm run lint        # eslint

Tests are fully offline — the ServiceNow client is mocked, and the AI tools are deterministic.

Manual smoke test with MCP Inspector

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Then list tools and try classify_incident / suggest_assignment_group (work offline) or a read tool against your instance.

Security

  • Credentials are read only from environment variables; .env is git-ignored.
  • The logger redacts any password / authorization / token / secret field, and logs go to stderr only (keeping the MCP stdout channel clean).
  • All HTTP requests use a configurable timeout and retry transient failures with exponential backoff; 4xx errors (other than 429) fail fast with safe messages.

License

MIT

Ver o original no GitHub

Bom para

Relacionados