Now SDK Ext MCP

现在sdk-ext mcp

MCP（模型上下文协议）服务器，使AI助手能够直接与ServiceNow实例交互——执行后台脚本、查询数据、运行ATF测试、跟踪日志等。

快速开始

先决条件

• Node.js >= 22
• ServiceNow CLI凭据 通过配置 now-sdk auth --add

安装和构建

git clone 
cd now-sdk-ext-mcp
npm install
npm run build

配置凭据

此服务器使用与ServiceNow CLI相同的凭据存储。如果您还没有，请配置您的实例凭据：

now-sdk auth --add 

这将在本地存储凭据，以便MCP服务器可以在不提示的情况下进行身份验证。

v2.0.0中的重大变化（ServiceNow SDK 4.3.0） v2.0.0将底层ServiceNow SDK从4.2.x升级到4.3.0 更改了凭据别名的存储方式 （替换之前的 keytar-基于新实现的凭证存储）。 如果您从v1.x升级： - 使用ServiceNow SDK 4.2.x创建的凭据别名 无法读取 通过SDK 4.3.x - 你 必须重新创建所有实例别名 升级后 ``bash # 1. Update the global CLI npm install -g @servicenow/sdk@4.3.0 # 2. Re-add each instance alias now-sdk auth --add # 3. Verify your aliases work now-sdk auth --list ``

运行服务器

node dist/index.js

服务器通过以下方式进行通信 标准 （标准输入/输出）使用MCP JSON-RPC协议。它并非旨在以交互方式运行，而是设计为由MCP客户端（Claude Desktop、VS Code、Cursor等）启动。

连接到MCP客户端

克劳德桌面版

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/now-sdk-ext-mcp/dist/index.js"]
    }
  }
}

要设置默认实例（这样您就不必每次都指定它）：

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/now-sdk-ext-mcp/dist/index.js"],
      "env": {
        "SN_AUTH_ALIAS": "myinstance"
      }
    }
  }
}

VS代码/光标

添加到您的 .vscode/mcp.json 或光标MCP设置：

{
  "servers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/now-sdk-ext-mcp/dist/index.js"],
      "env": {
        "SN_AUTH_ALIAS": "myinstance"
      }
    }
  }
}

克劳德代码

添加到您的 .claude/settings.json 或项目级别 .mcp.json:

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/now-sdk-ext-mcp/dist/index.js"],
      "env": {
        "SN_AUTH_ALIAS": "myinstance"
      }
    }
  }
}

开源代码

添加到您的 .config/opencode/opencode.json 或项目级别 opencode.jsonc

{
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": ["node", "/absolute/path/to/now-sdk-ext-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "SN_AUTH_ALIAS": "myinstance"
      }
    }
  }
}

运作原理

连接后，您可以自然地与您的AI助手交谈：

“查找myinstance实例上计算机类中的所有CMDB CI记录”

“在myinstance上运行一个脚本，按优先级统计所有活动事件”

“查询sys_user表中prod上具有管理员角色的用户”

AI将：

1. 编写适当的ServiceNow服务器端JavaScript
2. 打电话给 execute_script 带有实例别名和脚本的工具
3. 以可读格式返回结果

这个 instance 参数可以按请求显式传递，也可以通过默认方式传递 SN_AUTH_ALIAS 环境变量，所以如果你只处理一个实例，你可以设置并忘记。

可用工具

看 TOOLS.md 查看带有参数和示例的可用工具的完整列表。

环境变量

发展

项目结构

src/
├── index.ts                 # Server entry point — registers tools, starts stdio transport
├── tools/                   # MCP tool implementations (one file per tool)
│   └── execute-script.ts    # execute_script tool
└── common/
    └── connection.ts        # ServiceNow connection manager (credential resolution + caching)

test/
├── __mocks__/               # Manual mocks for external dependencies
├── helpers/                 # Shared test utilities and factories
├── unit/                    # Unit tests (mocked external deps)
│   ├── common/
│   └── tools/
└── integration/             # Integration tests (full MCP protocol, no real SN calls)

脚本

添加新工具

1. 在中创建新文件 src/tools/ （例如。， src/tools/query-table.ts).

1. 导出注册功能：

   import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
   import { z } from "zod";
   import { getServiceNowInstance } from "../common/connection.js";

   export function registerQueryTableTool(server: McpServer): void {
     server.registerTool(
       "query_table",
       {
         title: "Query Table",
         description: "Query records from a ServiceNow table.",
         inputSchema: {
           instance: z.string().optional().describe("ServiceNow instance auth alias"),
           table: z.string().describe("Table name to query"),
           // ... more params
         },
       },
       async ({ instance, table }) => {
         const snInstance = await getServiceNowInstance(instance);
         // ... use core library to query
         return {
           content: [{ type: "text" as const, text: "results here" }],
         };
       }
     );
   }

1. 在中注册 src/index.ts:

   import { registerQueryTableTool } from "./tools/query-table.js";

   registerQueryTableTool(server);

1. 在中添加测试 test/unit/tools/ 遵循现有模式。

1. 将工具记录在 TOOLS.md.

测试方法

测试使用MCP SDK InMemoryTransport 完全在进程内创建链接的客户端+服务器对。这意味着测试会通过完整的MCP协议栈（JSON-RPC序列化、模式验证、处理程序调度），而不会产生进程或接触网络。

• 单元测试 (test/unit/)：模拟外部依赖关系(@sonisoft/now-sdk-ext-core, @servicenow/sdk-cli)使用 jest.unstable_mockModule() ESM兼容性。通过MCP客户端测试工具行为。
• 集成测试 (test/integration/)：在不模拟的情况下验证MCP协议生命周期（握手、工具列表、顺序调用）。

兄弟姐妹项目

此MCP服务器封装了CLI使用的相同核心库：

• 核心库: @sonisoft/now-sdk-ext-core --所有ServiceNow通信（身份验证、HTTP、WebSocket、脚本执行、ATF、syslog）
• 命令行界面: @sonisoft/now-sdk-ext-cli --the nex 用oclif封装核心库的CLI

添加新的MCP工具时，请参考中的相应CLI命令 now-sdk-ext-cli/src/commands/ 对于预期的行为和数据流。

贡献

测试

该项目有三层测试：

1.自动化测试（Jest）

使用MCP SDK的单元和集成测试完全在进程中运行 InMemoryTransport --没有服务器进程，没有网络，不需要凭据。

npm test                 # Unit tests (default, fast)
npm run test:unit        # Unit tests with coverage + junit
npm run test:integration # MCP protocol integration tests
npm run test:all         # Everything

单元测试模拟所有外部依赖关系(@sonisoft/now-sdk-ext-core, @servicenow/sdk-cli)所以它们是快速和确定的。集成测试验证MCP协议生命周期（握手、工具列表、工具调用、错误响应），而不会影响真实的ServiceNow实例。

永远奔跑 npm test 在承诺之前。

2.MCP检查员（交互式测试）

官方的 MCP检查员 是一个充当MCP客户端的web UI，允许您交互式浏览工具，使用自定义输入调用它们，并查看结果，而无需连接到Claude或任何AI客户端。

# Build first
npm run build

# Launch the inspector (opens a browser UI at http://localhost:6274)
npx @modelcontextprotocol/inspector node dist/index.js

# Pass env vars to the server (e.g., default instance alias)
npx @modelcontextprotocol/inspector -e SN_AUTH_ALIAS=myinstance node dist/index.js

在检查器UI中，您可以：

• 在中浏览已注册的工具及其输入模式 工具 标签
• 填写参数并调用工具
• 查看JSON-RPC请求/响应和工具输出
• 在中查看服务器stderr日志 通知 窗格

检查器还具有用于脚本编写的无头CLI模式：

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# Call a specific tool
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name execute_script \
  --tool-arg instance=myinstance \
  --tool-arg script='gs.print("hello")' \
  --tool-arg scope=global

3.使用Claude代码进行测试

要使用Claude Code作为MCP客户端对服务器进行端到端测试：

添加服务器：

# From the now-sdk-ext-mcp project root (after building):
claude mcp add --transport stdio --env SN_AUTH_ALIAS=myinstance servicenow \
  -- node /absolute/path/to/now-sdk-ext-mcp/dist/index.js

或者创建一个 .mcp.json 在项目根目录下（可以通过版本控制共享）：

{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/now-sdk-ext-mcp/dist/index.js"],
      "env": {
        "SN_AUTH_ALIAS": "myinstance"
      }
    }
  }
}

验证连接：

在Claude Code会话中，运行 /mcp 查看所有连接的服务器及其状态。这个 servicenow 服务器应显示为已连接。

测试一下：

问克劳德这样的问题：

“在myinstance上运行一个脚本，使用gs.print（gs.getUserName（））打印当前用户名”

克劳德应该打电话给 execute_script 工具并返回结果。

管理服务器：

claude mcp list              # List all configured servers
claude mcp get servicenow    # Show details for the servicenow server
claude mcp remove servicenow # Remove it

手动stdin测试

由于服务器通过stdio上的JSON-RPC进行通信，您可以直接通过管道发送消息进行快速烟雾测试：

# List tools (single-message shortcut — works for basic inspection)
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  | node dist/index.js 2>/dev/null \
  | jq '.result.tools[].name'

对于完整的协议交换（初始化握手+工具调用）：

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":0}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  | node dist/index.js 2>/dev/null \
  | jq

调试

由于stdout是为JSON-RPC保留的， 绝不使用 console.log() 在服务器代码中 --它破坏了协议流。请改用以下方法：

• console.error() --写入stderr，这在MCP检查器的“通知”窗格和Claude Desktop的日志文件中是安全且可见的(~/Library/Logs/Claude/mcp*.log).
• MCP检查员 --在检查器下运行服务器，实时查看所有JSON-RPC消息和stderr输出。
• 文件日志记录 --对于持久调试日志，核心库的 Logger 类写入 logs/ 温斯顿。根据需要通过工具的逻辑设置日志级别。

代码约定

• ES模块("type": "module" 在package.json中）
• TypeScript严格模式
• 目标ES2022，模块Node16
• 匹配兄弟姐妹的图案和风格 now-sdk-ext-core 和 now-sdk-ext-cli 项目
• 每个与ServiceNow对话的工具都应该接受一个可选 instance 参数
• 通过MCP客户端（而不是直接调用处理程序函数）测试每个工具，以便执行完整的协议栈

许可证

麻省理工学院