Fluent MCP Server

一个MCP服务器，它将ServiceNow Fluent SDK的功能带入AI辅助开发环境。支持与ServiceNow SDK命令、API规范、代码片段和开发资源进行自然语言交互。

主要特性

• 🤖 AI驱动错误分析 - 智能诊断，包括根本原因、解决方案和预防建议（MCP采样）
• 完整的SDK覆盖 - 所有ServiceNow SDK命令：auth, init, build, install, dependencies, transform, download, clean, pack
• 丰富的资源 - API规范、代码片段、针对35种以上元数据类型的指南
• 多环境认证 - 支持basic和oauth认证，并具有配置文件管理
• 会话感知 - 在命令之间维护工作目录上下文

此MCP服务器实现了完整的模型上下文协议规范，具有以下功能：

核心功能

• 资源 - 提供跨越35种以上ServiceNow元数据类型（API规范、指南、代码片段、提示）的100多种资源
• 工具 - 将10个ServiceNow SDK命令作为MCP工具暴露，并具有完整的参数验证
• 提示 - 提供常见ServiceNow任务的开发工作流程模板
• 根目录 - 支持MCP根目录协议以实现工作空间感知操作

扩展功能

• 采样（MCP 2024-11-05） - 当SDK命令失败时，利用客户端LLM进行智能错误分析

  • 自动分析超过50字符的命令错误
  • 提供结构化诊断：根本原因、解决方案、预防建议
  • 通过FLUENT_MCP_ENABLE_ERROR_ANALYSIS环境变量配置

• 提取（MCP 2024-11-05） - 复杂工作流的交互式参数收集

  • init_fluent_app - 提示缺失的项目参数（workingDirectory, template, appName等）
  • 支持创建和转换工作流的智能验证
  • 处理用户对提取数据的接受或拒绝

• 会话管理 - 跟踪每个会话的工作目录以支持多项目工作流

• 根目录回退 - 当未设置会话目录时自动回退到MCP根目录上下文

• 错误处理 - 全面的错误消息并提供可操作的指导

• 类型安全 - 完整的TypeScript实现，具有严格的类型检查

快速开始

# 使用MCP Inspector测试
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# 或在您的MCP客户端中使用（参见配置部分）

示例提示：

在~/projects/time-off-tracker创建一个新的Fluent应用来管理员工PTO请求

可用工具

SDK命令

工具	描述	关键参数
sdk_info	获取SDK版本、帮助或调试信息	flag (-v/-h/-d), command (可选)
manage_fluent_auth	管理实例认证配置文件	add, list, delete, use, type (basic/oauth)
init_fluent_app	初始化或转换ServiceNow应用	workingDirectory (必需), template, from (可选)
build_fluent_app	构建应用	debug (可选)
deploy_fluent_app	部署到ServiceNow实例	auth (可选), debug (可选)
fluent_transform	将XML转换为Fluent TypeScript	from, auth (可选)
download_fluent_dependencies	下载依赖项和类型定义	auth (可选)
download_fluent_app	从实例下载元数据	directory, incremental (可选)
clean_fluent_app	清理输出目录	source (可选)
pack_fluent_app	创建可安装的工件	source (可选)

注意： manage_fluent_auth, init_fluent_app 和 download_fluent_dependencies 是交互式命令。使用init_fluent_app来建立后续命令的工作目录上下文。

资源

遵循MCP规范的标准URI模式：

资源类型	URI模式	示例	目的
API规范	sn-spec://{type}	sn-spec://business-rule	API文档和参数
指南	sn-instruct://{type}	sn-instruct://script-include	最佳实践和指导
代码片段	sn-snippet://{type}/{id}	sn-snippet://acl/0001	实用代码示例
提示	sn-prompt://{id}	sn-prompt://coding_in_fluent	开发指南

支持的元数据类型

核心类型： acl, application-menu, business-rule, client-script, cross-scope-privilege, form, list, property, role, scheduled-script, script-action, script-include, scripted-rest, service-portal, table, ui-action, ui-page, user-preference

表类型： column, column-generic

ATF（自动化测试框架）： atf-appnav, atf-catalog-action, atf-catalog-validation, atf-catalog-variable, atf-email, atf-form, atf-form-action, atf-form-declarative-action, atf-form-field, atf-reporting, atf-rest-api, atf-rest-assert-payload, atf-server, atf-server-catalog-item, atf-server-record

配置

需求： Node.js 22.15.1+, npm 11.4.1+

MCP客户端设置

添加到您的MCP客户端配置文件：

{
  "mcpServers": {
    "fluent-mcp": {
      "command": "npx",
      "args": ["-y", "@modesty/fluent-mcp"],
      "env": {
        "SN_INSTANCE_URL": "https://your-instance.service-now.com",
        "SN_AUTH_TYPE": "oauth"
      }
    }
  }
}

客户端特定位置：

• Claude Desktop / macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• VSCode Copilot: .vscode/mcp.json（使用命令面板：MCP: 添加服务器...）
• Cursor: 设置 → 功能 → MCP设置
• Windsurf: 设置 → 级联 → MCP服务器 → 查看原始配置
• Gemini CLI: ~/.gemini/settings.json

VSCode注意事项： 对于VSCode，JSON结构使用的是"mcp": { "servers": { ... } }而不是"mcpServers"。

环境变量：

• SN_INSTANCE_URL - ServiceNow实例URL（可选，可以使用认证配置文件代替）
• SN_AUTH_TYPE - 认证方法：basic或oauth（可选）
• FLUENT_MCP_ENABLE_ERROR_ANALYSIS - 启用AI错误分析（默认：true）
• FLUENT_MCP_MIN_ERROR_LENGTH - 分析的最小错误长度（默认：50）

使用示例

典型工作流程

1. 设置认证

   为https://dev12345.service-now.com创建一个新的认证配置文件，别名为dev-instance
   

2. 初始化项目

   在~/projects/asset-tracker创建一个新的Fluent应用用于IT资产管理
   

3. 使用资源开发

   显示业务规则API规范并提供一个示例片段
   

4. 构建和部署

   使用调试输出构建应用，然后部署到dev-instance
   

使用MCP Inspector测试

MCP Inspector提供了测试MCP服务器的Web界面。

启动Inspector

# 测试已发布的包
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# 或对于本地开发
npm run build && npm run inspect

测试场景

场景1：探索业务规则资源

目标： 访问业务规则的API规范和代码片段

步骤：

1. 启动Inspector并等待服务器连接
2. 导航到资源标签页
3. 在资源列表中找到并点击sn-spec://business-rule
4. 查看显示的所有可用方法和参数的API规范
5. 返回并搜索sn-snippet://business-rule/0001
6. 点击片段查看完整的TypeScript示例
7. 验证内容包括正确的导入并遵循Fluent模式

预期结果：

• API规范显示结构化的文档和方法签名
• 片段显示可运行的TypeScript代码，带有ServiceNow元数据模式
• 内容格式正确且易于阅读

场景2：测试SDK Info命令

目标： 验证SDK版本和帮助信息检索

步骤：

1. 导航到工具标签页
2. 从工具列表中选择sdk_info
3. 测试版本：
   • 将flag参数设置为-v
   • 点击执行
   • 验证响应显示版本号（例如，“4.0.1”）
4. 测试帮助：
   • 将flag参数设置为-h
   • 将command参数设置为build
   • 点击执行
   • 验证响应显示带有选项的构建命令文档
5. 监控通知面板中的命令执行日志

预期结果：

• 版本命令返回SDK版本字符串
• 帮助命令返回详细的命令文档
• 通知面板中无错误
• 命令在2-3秒内执行

许可

MIT