MCP ITSM集成服务器

MCP ITSM

统一的IT服务管理 模型上下文协议 --从任何兼容MCP的LLM客户端跨ServiceNow、Jira、Zendesk、Ivanti Neurons和Cherwell创建、跟踪和解析票证。

______________________________________________________________________

目录

• 概述
• 建筑
• 快速开始
• 项目结构
• MCP工具
• MCP资源
• MCP提示
• 配置
• 监控仪表板
• API 参考
• Smithery部署
• 发展
• 贡献
• 许可证

______________________________________________________________________

概述

MCP ITSM公开了一组标准化的 MCP工具、资源和提示 以便任何LLM客户端（Claude、Cursor、定制代理）都可以在不知道底层ITSM系统的API的情况下管理IT票证。

它是什么：

为什么重要：\ LLM没有为ServiceNow、Jira、Zendesk、Ivanti和Cherwell编写单独的集成，而是调用 create_ticket 一旦正确的系统接收到它。每个工具都携带 安全注释 (readOnlyHint, destructiveHint)因此，模型知道它可以在没有风险的情况下调用什么。

______________________________________________________________________

建筑

graph TB
    subgraph "MCP Clients"
        Claude["Claude / Cursor / Agent"]
        Inspector["MCP Inspector"]
        UI["React Frontend :3000"]
    end

    subgraph "Transport"
        Stdio["StdioServerTransport\n(Smithery / Inspector)"]
        Bridge["Express API :5000\nSDK Client + StdioClientTransport"]
    end

    subgraph "MCP Server  —  index.js  v3.0.0"
        McpSrv["McpServer\nspec 2025-11-25"]
        Tools["7 Tools\nZod · annotated"]
        Resources["4 Resources\nKB articles · Tickets"]
        Prompts["3 Prompts\nIncident · Status · KB-assist"]
        Store["In-Memory Store\nTickets & KB articles"]
    end

    subgraph "Backend Services"
        Auth["JWT Auth"]
        Metrics["Metrics Store"]
        Mongo[("MongoDB")]
    end

    Claude -->|stdio| Stdio
    Inspector -->|stdio| Stdio
    UI -->|HTTP + JWT| Bridge

    Stdio --> McpSrv
    Bridge -->|"MCP SDK Client\n(proper handshake)"| McpSrv

    McpSrv --> Tools
    McpSrv --> Resources
    McpSrv --> Prompts
    Tools  Store
    Resources --> Store

    Bridge --> Auth
    Bridge --> Metrics
    Auth --> Mongo

请求流——浏览器工具调用：

sequenceDiagram
    participant U as User
    participant UI as React UI :3000
    participant API as Express API :5000
    participant C as MCP SDK Client
    participant MCP as McpServer index.js

    U->>UI: Submit form
    UI->>API: POST /api/mcp/tools/call (JWT)
    API->>C: client.callTool(name, args)
    Note over C: StdioClientTransport
    C->>MCP: tools/call (MCP protocol)
    Note over MCP: Zod validates input
    MCP->>MCP: tool handler + in-memory store
    MCP-->>C: CallToolResult
    C-->>API: result
    API->>API: recordCall() → metrics
    API-->>UI: { success, data, _meta }
    UI->>U: Show result

______________________________________________________________________

快速开始

先决条件

• Node.js≥18
• MongoDB （本地或Atlas——后端需要）
• 可选： Smithery CLI 用于云部署

1--安装依赖项

# Root (MCP server)
npm install

# Backend API
cd backend && npm install && cd ..

# Frontend
cd frontend && npm install && cd ..

2--配置环境

cp .env.example .env          # root — API key for Smithery / MCP auth
cp backend/.env.example backend/.env   # backend — Mongo URI, JWT secret, ITSM creds

本地开发所需的最低要求（编辑 backend/.env):

MONGODB_URI=mongodb://localhost:27017/mcp-itsm
JWT_SECRET=change-me-in-production

3--启动所有服务

打开三个终端：

# Terminal 1 — MCP server (stdio)
npm start

# Terminal 2 — Backend API
cd backend && npm start        # http://localhost:5000

# Terminal 3 — Frontend
cd frontend && npm start       # http://localhost:3000

flowchart LR
    T1["Terminal 1\nnpm start\nMCP server on stdio"]
    T2["Terminal 2\ncd backend\nnpm start  :5000"]
    T3["Terminal 3\ncd frontend\nnpm start  :3000"]
    UI["localhost:3000\nTicket Manager\nMonitor Dashboard"]

    T1 -->|"SDK Client\nStdioClientTransport"| T2
    T2 -->|"HTTP + JWT"| T3
    T3 --> UI

接入点

______________________________________________________________________

项目结构

mcp-itsm/
├── index.js                  # MCP server (McpServer, Zod, stdio)
├── tools.json                # Static tool catalogue for Smithery browser
├── smithery.yaml             # Smithery deployment config
├── package.json              # Root deps: @modelcontextprotocol/sdk, zod
├── .env.example              # Root env template
│
├── backend/
│   ├── package.json          # Express, Mongoose, JWT, MCP SDK Client
│   ├── .env.example          # Backend env template
│   └── src/
│       ├── index.js          # Express app bootstrap
│       ├── config/config.js  # Env-driven configuration
│       ├── routes/
│       │   ├── mcp.routes.js      # MCP bridge + metrics endpoints
│       │   ├── auth.routes.js
│       │   ├── context.routes.js
│       │   ├── integration.routes.js
│       │   └── user.routes.js
│       ├── middleware/
│       │   ├── auth.middleware.js
│       │   └── validation.middleware.js
│       ├── models/
│       ├── validators/
│       └── utils/logger.js
│
├── frontend/
│   ├── package.json          # React 18, Bootstrap, react-router-dom
│   └── src/
│       ├── App.js
│       ├── pages/
│       │   ├── MCPTicketManager.js     # Ticket CRUD UI
│       │   ├── MCPMonitorDashboard.js  # Live monitoring (polls every 10s)
│       │   ├── Dashboard.js
│       │   ├── LLMChatClient.js
│       │   └── ...
│       ├── services/
│       │   ├── mcpService.js   # HTTP client for MCP tool calls
│       │   └── api.js          # Axios instance with JWT interceptor
│       └── components/
│           ├── Header.js
│           └── ...
│
└── docs/
    ├── api-documentation.md
    ├── mcp_relationship.md
    └── llm_enabled_tickets.md

______________________________________________________________________

MCP工具

所有7个工具都是通过注册的 McpServer.tool() 随着 Zod输入模式 和 安全注释.LLM客户端使用注释来决定是否在没有用户确认的情况下调用工具。

支持的系统 （通过可选 system 参数）： servicenow · jira · zendesk · ivanti_neurons · cherwell （默认值： jira)

graph LR
    subgraph RO["Read-only  —  safe to call freely"]
        GT["get_ticket\nreadOnly · idempotent"]
        LT["list_tickets\nreadOnly · idempotent"]
        SK["search_knowledge_base\nreadOnly · idempotent"]
    end
    subgraph WR["Write  —  require user intent"]
        CT["create_ticket\nwrite"]
        UT["update_ticket\nwrite"]
        AT["assign_ticket\nwrite · idempotent"]
        AC["add_comment\nwrite"]
    end
    style RO fill:#f0fdf4,stroke:#86efac
    style WR fill:#fff1f2,stroke:#fecdd3

示例——创建工单

// Tool call
{
  "name": "create_ticket",
  "arguments": {
    "title": "VPN not connecting after Windows update",
    "description": "Since the KB5034441 update, VPN client fails to authenticate on first attempt.",
    "priority": "high",
    "system": "jira"
  }
}

// Response
{
  "success": true,
  "ticket": {
    "id": "JIRA-1000",
    "title": "VPN not connecting after Windows update",
    "system": "jira",
    "status": "open",
    "priority": "high",
    "url": "https://example.com/jira/tickets/JIRA-1000"
  }
}

______________________________________________________________________

MCP资源

资源公开了LLM客户端可以在不调用工具的情况下读取的实时数据。

graph LR
    McpSrv["McpServer"]
    McpSrv -->|"static\nkb://articles"| KBAll["kb-articles\nAll KB articles as JSON"]
    McpSrv -->|"template\nkb://articles/{id}"| KBOne["kb-article\nSingle article by ID"]
    McpSrv -->|"static\nitsm://tickets/open"| TOpen["open-tickets\nLive filtered view"]
    McpSrv -->|"template\nitsm://tickets/{id}"| TOne["ticket\nSingle ticket by ID"]
    style McpSrv fill:#f0fdf4,stroke:#86efac

______________________________________________________________________

MCP提示

提示是客户端在工具调用序列之前向用户呈现的引导消息模板。

sequenceDiagram
    participant U as User
    participant C as MCP Client
    participant MCP as McpServer

    U->>C: "My printer won't install"
    C->>MCP: prompts/get  kb-search-assist
    MCP-->>C: message template
    C->>MCP: tools/call  search_knowledge_base
    MCP-->>C: KB-005 Printer setup guide
    C->>U: Show article — no ticket needed
    Note over C,U: Only escalates to create_ticket if no article resolves it

______________________________________________________________________

配置

根 .env （MCP服务器+Smithery）

# API key used when running via Smithery (injected as API_KEY env var)
API_KEY=your-smithery-api-key

后端 backend/.env

# Server
PORT=5000
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/mcp-itsm

# Auth
JWT_SECRET=change-me-to-a-long-random-string
JWT_EXPIRES_IN=1d

# ITSM integrations (all optional — only needed for live system calls)
SERVICENOW_BASE_URL=https://your-instance.service-now.com
SERVICENOW_USERNAME=admin
SERVICENOW_PASSWORD=

JIRA_BASE_URL=https://your-org.atlassian.net
JIRA_EMAIL=you@example.com
JIRA_API_TOKEN=

ZENDESK_BASE_URL=https://your-org.zendesk.com
ZENDESK_USERNAME=you@example.com
ZENDESK_TOKEN=

IVANTI_BASE_URL=https://your-instance.ivanti.com
IVANTI_CLIENT_ID=
IVANTI_CLIENT_SECRET=

CHERWELL_BASE_URL=https://your-instance.cherwell.com
CHERWELL_CLIENT_ID=
CHERWELL_USERNAME=
CHERWELL_PASSWORD=

# Logging
LOG_LEVEL=info

______________________________________________________________________

监控仪表板

前端包括一个实时监控仪表板，位于 /mcp-monitor 每一次都会对后端进行轮询 10秒.

它显示了什么：

• 服务器连接/断开状态及正常运行时间
• 总呼叫数、成功率、失败呼叫数
• 具有平均延迟标记的每个工具调用统计数据
• 带有注释标签的可用工具（只读、写入、幂等）
• 已注册的资源和提示
• 最近20次工具调用的实时活动日志

数据来源于存储在中的内存度量 backend/src/routes/mcp.routes.js 并在后端重新启动时重置。

flowchart TD
    DB["React Dashboard\n/mcp-monitor\npoll every 10 s"]
    DB -->|"GET /api/mcp/health"| H["connected · uptimeSeconds"]
    DB -->|"GET /api/mcp/metrics"| M["totalCalls · successRate\ntoolStats · recentCalls"]
    DB -->|"GET /api/mcp/tools/list"| T["tool names + annotations"]
    DB -->|"GET /api/mcp/resources/list"| R["resource URIs"]
    DB -->|"GET /api/mcp/prompts/list"| P["prompt names"]

______________________________________________________________________

API 参考

全部 /api/mcp/* 终结点中需要有效的JWT Authorization: Bearer 头球

工具调用示例（curl）

# Authenticate first
TOKEN=$(curl -s -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}' | jq -r '.token')

# Call a tool
curl -X POST http://localhost:5000/api/mcp/tools/call \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_knowledge_base",
    "arguments": { "query": "vpn", "limit": 3 }
  }'

______________________________________________________________________

Smithery部署

服务器发布在 @马多什/mcp 在Smithery。

flowchart LR
    Dev["Developer\nnpm publish via\nsmithery publish"]
    Smithery["Smithery Cloud\nDocker container\nenv API_KEY injected"]
    MCPSrv["McpServer v3.0.0\nnpm start → stdio"]
    Client["Claude / Cursor\nany MCP client"]

    Dev -->|"smithery.yaml\ntools.json"| Smithery
    Smithery -->|"spawn"| MCPSrv
    Client -->|"MCP protocol\nstdio"| Smithery
    Smithery |"proxy"| MCPSrv

通过Smithery CLI安装

npx -y @smithery/cli install @madosh/mcp-itsm --client claude

手动Smithery部署

npm install -g @smithery/cli
smithery login
smithery publish

这 smithery.yaml 配置：

startCommand:
  type: stdio
  configSchema:
    type: object
    required: [apiKey]
    properties:
      apiKey:
        type: string
  commandFunction: |-
    (config) => ({ command: 'npm', args: ['start'], env: { API_KEY: config.apiKey } })
tools:
  path: ./tools.json

与Claude Desktop一起使用

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-itsm": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-itsm/index.js"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

使用MCP检查器进行调试

npm run debug-mcp
# Opens MCP Inspector at http://localhost:5173

______________________________________________________________________

发展

可用脚本

# Root
npm start              # Start MCP server on stdio
npm run debug-mcp      # Start with MCP Inspector attached

# Backend
cd backend
npm start              # Production
npm run dev            # Development (nodemon hot-reload)
npm test               # Jest test suite

# Frontend
cd frontend
npm start              # Dev server on :3000
npm run build          # Production build

技术栈

使用Docker运行

docker build -t mcp-itsm .
docker run -e API_KEY=your-key mcp-itsm

______________________________________________________________________

贡献

欢迎捐款。拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feat/my-feature)
3. 提交您的更改(git commit -m 'feat: add my feature')
4. 推到分支(git push origin feat/my-feature)
5. 打开拉取请求

路线图

• \[\]外部客户端的OAuth 2.1/OIDC授权
• \[\]诱导——服务器发起的通话中用户提示
• \[\]实验任务——持久异步票证工作流
• \[\]实时ITSM系统适配器（ServiceNow、Jira、Zendesk）
• \[ \] outputSchema / structuredContent 在所有工具上

graph LR
    subgraph Done["Shipped in v3.0.0"]
        D1["SDK 1.28.0 + Zod"]
        D2["McpServer API"]
        D3["Tool annotations"]
        D4["Resources + Prompts"]
        D5["SDK Client transport"]
        D6["Metrics + Dashboard"]
    end
    subgraph Next["Next"]
        N1["OAuth 2.1 / OIDC"]
        N2["Elicitation"]
        N3["Tasks API"]
        N4["Live ITSM adapters"]
    end
    style Done fill:#f0fdf4,stroke:#86efac
    style Next fill:#eff6ff,stroke:#bfdbfe

______________________________________________________________________

许可证

麻省理工学院——见 许可证 了解详情。

______________________________________________________________________

资源

• 模型上下文协议
• MCP规范2025-11-25
• Smithery文件
• MCP TypeScript SDK