Fluent (ServiceNow SDK)

Gerencie metadados, módulos, registros e testes do ServiceNow usando o Fluent, um DSL declarativo baseado em TypeScript. Suporta todos os comandos da CLI do SDK do ServiceNow.

Documentação

Fluent MCP Server

An MCP server and AI skill suite that brings ServiceNow Fluent SDK (@servicenow/sdk) capabilities, API specifications, code snippets, and security reviews to AI-assisted development environments.

Built for @servicenow/sdk@v4.14.0.

Key Features

  • 16 MCP Tools — 14 ServiceNow SDK CLI command tools (sdk_info, init, build, deploy, transform, dependencies, download, clean, pack, explain, query, cicd_fluent_app, cicd_fluent_test, fluent_exec_script) plus 2 knowledge/auth tools (get_fluent_knowledge, check_auth_status).
  • 76 ServiceNow Metadata Types — Packaged API specs (sn-spec://), authoring instructions (sn-instruct://), runnable snippets (sn-snippet://), and workflow prompts (coding_in_fluent, create_custom_ui).
  • AI Agent Skills — Built-in skills (fluent-cli, fluent-security-review, fluent-general-review, fluent-perf-review, and fluent-domain-separation-review) installable as a plugin for Claude Code, Codex, Copilot, and other skill-enabled agents.
  • Lazy Auto-Authentication — Resolves and caches an SDK auth profile matching SN_INSTANCE_URL on first use.
  • Explicit Working Directory Resolution — Resolves project paths in strict order: workingDirectory argument → session (init_fluent_app) → FLUENT_MCP_WORKING_DIR → actionable error. Never guesses from process.cwd().
  • Dual-Era MCP Protocol — Serves both current and legacy MCP protocol revisions over stdio from a single handler set, with zero server-initiated requests.

MCP Setup

Requirements: Node.js >=22.23.2 and npm >=10.9.8.

Add @modesty/fluent-mcp to your MCP client configuration:

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

Client Config Locations:

  • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Claude Code CLI: claude mcp add fluent-mcp -- npx -y @modesty/fluent-mcp
  • VS Code Copilot: .vscode/mcp.json (uses "mcp": { "servers": { ... } } instead of "mcpServers")
  • Cursor / Windsurf / Gemini CLI: Add under mcpServers in your client's MCP settings file

Environment Variables

VariableDescriptionDefault
FLUENT_MCP_WORKING_DIRFallback absolute path to your Fluent project—
SN_INSTANCE_URLServiceNow instance URL for automatic auth profile lookup. A matching profile is passed per call and never made your CLI default; the server never adds, deletes or selects a profile—
SN_AUTH_TYPEoauth or basicoauth
FLUENT_MCP_LOG_LEVELMinimum stderr log level (debug, info, notice, warning or warn, error; case-insensitive, an unknown value falls back to info with a warning)info
FLUENT_MCP_COMMAND_TIMEOUT_MSOperator override for CLI command timeout, in ms, digits only, at most 2147483647 (1e6, 1.5, 300000ms or a longer value are ignored)Per-tool
NO_TELEMETRYSet to 1 to disable @servicenow/sdk CLI telemetry—
SN_SDK_CREDENTIALS_DIRDirectory of the SDK's encrypted profile store credentials.enc (SDK v4.14.0+; an empty value is treated as unset)~/.now-sdk

Authentication Tip: The server only reads your auth profiles. To register an instance profile, run in a terminal: npx @servicenow/sdk auth --add <instance-url> --type <basic|oauth> --alias <alias> auth --add makes the new profile your CLI default; run npx @servicenow/sdk auth --use <previous alias> afterwards to keep the old one. Since @servicenow/sdk 4.14.0, profiles are stored encrypted in credentials.enc with only the key in the OS keychain. The first auth lookup migrates existing keychain profiles silently; afterwards, profiles added with an older now-sdk are not visible to this server. If the store cannot be decrypted, check_auth_status reports it, and you must run now-sdk auth --delete all in a terminal and add the profile again. Do not reset for any other store error: a file written by a newer now-sdk needs that newer SDK, and a keyring write failure needs the OS keyring unlocked. For headless CI/CD pipelines, set SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL along with SN_SDK_INSTANCE_URL and SN_SDK_USER/SN_SDK_USER_PWD or SN_SDK_OAUTH_CLIENT_ID/SN_SDK_OAUTH_CLIENT_SECRET.

MCPB Bundle (Optional)

Run npm run bundle to build a self-contained fluent-mcp-<version>.mcpb archive with dist/, res/, and production dependencies for MCPB-compatible desktop hosts. The dependencies are resolved fresh from the public npm registry, the same way an npm install of the package resolves them; an inherited registry setting, scoped ones included, is overridden, and the bundle fails if any package in its lockfile came from elsewhere, MCPB drops *.d.ts and package-lock.json by default, so the script re-includes the SDK's declarations, which a Fluent build type-checks against, and the lockfile. After packing it unpacks the archive and fails, deleting the bundle, unless the lockfile is there and the bundled SDK can build a fixture project that has no SDK of its own.


Skills (fluent-skillset)

This repository ships standalone AI agent skills under skills/ packaged as the fluent-skillset plugin.

Skill Plugin Installation

Agent / ToolInstallation
Claude CodeRun /plugin marketplace add modesty/fluent-mcp, then /plugin install fluent-skillset@modesty and /reload-plugins
GitHub CopilotRun gh skill install modesty/fluent-mcp <skill-name> (add --scope user for ~/.copilot/skills/), then /skills reload
CodexRun $skill-installer https://github.com/modesty/fluent-mcp/tree/main/skills/<skill-name>, then restart Codex
CursorSettings (Cmd+Shift+J) → Plugins → paste https://github.com/modesty/fluent-mcp.git → Add to Cursor
GrokRun grok plugin marketplace add modesty/fluent-mcp and grok plugin install fluent-skillset --trust
Windsurf / Other AgentsPrompt the agent: Please install these skills in my user level configuration from github: https://github.com/modesty/fluent-mcp/tree/main/skills (or copy skills/* into ~/.claude/skills/ or ~/.agents/skills/)

Available Skills & Intended Usage

SkillIntended Usage
fluent-cliFluent App Development & Live Instance Queries (No MCP Required). Guides the agent through npx @servicenow/sdk CLI workflows directly via bash: project orientation (now.config.json), progressive documentation lookup (explain --list → --peek → full topic), building/transforming metadata, and querying live ServiceNow tables (query <table> -q '<encoded-query>' -o json). Ideal for lightweight CLI environments where the MCP server is not attached.
fluent-security-reviewServiceNow App Security Review. Audits both Fluent (now.config.json with src/ and metadata/) and classic ServiceNow XML (update/, unload/) applications, organized by risk level (Critical (7), High (26), Medium (12), Low (1)) and backed by a deterministic scanner script (scan_security_checks.mjs). Produces a structured Markdown report with Exemplary Practices, prioritized Findings (P0–P4) with actionable fixes, and a final PASS / FAIL security review conclusion.
fluent-general-reviewServiceNow App General Best-Practice Review. Audits both Fluent (now.config.json) and classic ServiceNow XML (update/) applications against all 31 ServiceNow general best-practice checks across Scripting (15 checks) and Configuration (16 checks), backed by a deterministic scanner script (scan_general_checks.mjs).
fluent-perf-reviewServiceNow App Performance Review. Audits both Fluent (now.config.json) and classic ServiceNow XML (update/) applications against all 18 ServiceNow Performance checks across Scripting (12 checks) and Configuration (6 checks), plus general memory, CPU, and query efficiency. Backed by a deterministic scanner script (scan_perf_checks.mjs) that resolves Business Rule / transform timing across Now.include() and imported server modules, and detects dictionary type changes against a previous version (--baseline <dir>).
fluent-domain-separation-reviewServiceNow App Domain Separation / MSP Readiness Review. Specifically for apps that must run on domain-separated (MSP / multi-tenant) instances. Audits Fluent and classic XML apps against all 10 MSP & Domain Separation checks (msp_checks.md), backed by a deterministic scanner script (scan_msp_checks.mjs).

Available Tools (18)

SDK Command Tools (14)

ToolDescriptionKey Parameters
sdk_infoGet SDK version (-v) or command help (-h)flag, command
explain_fluent_apiLook up Fluent SDK docs for any API class, guide, or tag (no project required)topic, list, peek, format (pretty|raw), debug
init_fluent_appInitialize a new Fluent app or convert an existing app (non-interactive)workingDirectory, intent, appName, packageName, scopeName, template, from, auth, debug
build_fluent_appBuild the Fluent application packageworkingDirectory, sourceMap, debug
deploy_fluent_appDeploy/install the built package to a ServiceNow instanceworkingDirectory, auth, skipFlowActivation, async, debug
fluent_transformTransform local XML or instance records into Fluent .now.ts source codeworkingDirectory, from, directory, table, id, force, format, timeoutSeconds, auth, debug
download_fluent_dependenciesDownload application dependencies and script/table type definitionsworkingDirectory, auth, debug
download_fluent_appDownload application metadata from an instanceworkingDirectory, directory, source, incremental, timeoutSeconds, auth, debug
clean_fluent_appClean build output directoryworkingDirectory, source, debug
pack_fluent_appZip built application into an installable artifactworkingDirectory, source, debug
query_fluent_recordsRead-only Table REST query against an instance (returns JSON envelope); needs no Fluent projecttable, query, fields, limit, offset, displayValue, select, timeout, auth
cicd_fluent_appInstall, publish, or rollback an app via the sn_cicd APIworkingDirectory, action (install|publish|rollback), scope|appSysId, appVersion, wait, pollTimeout, output, select
cicd_fluent_testRun, watch, or fetch results/logs for ATF test suites and tests via sn_cicdtarget (testsuite|test), action (run|watch|result|logs), testSuiteSysId|testSuiteName, testSysId|testName, progressId, resultId, pattern, limit, wait, output, select
fluent_exec_scriptRun a server-side script on the instance like Scripts - Background (now-sdk exec; admin role, destructive — approve every run; a timeout does not stop the script)script|file (a .js file inside the project, ≤ 64 KB; run from a private copy and echoed with its SHA-256), workingDirectory, scope, reason, timeoutMs, serverLogs, select, auth

Knowledge & Authentication Tools (2)

ToolDescriptionKey Parameters
get_fluent_knowledgeGet the Fluent API specification (spec), authoring rules and pitfalls (instruct), or a runnable code snippet (snippet) for a metadata type; omit metadataType to list the types that have that kindkind (spec|instruct|snippet), metadataType (optional, one of the 76 types), snippetId (optional, snippets only)
check_auth_statusValidate and return the current ServiceNow instance authentication statusNone

Resources & Prompts

TypeURI / NamePurpose
API Specssn-spec://{metadataType}TypeScript API signatures and field schemas
Instructionssn-instruct://{metadataType}Best practices, constraints, and common pitfalls
Code Snippetssn-snippet://{metadataType}/{id}Practical, build-validated code examples
Promptscoding_in_fluent, create_custom_uiEnd-to-end authoring and custom UI guides

Supported Metadata Types (76)

  • Core (26): acl, application-menu, business-rule, client-script, cross-scope-privilege, data-policy, field-style, form, import-set, instance-scan, interceptor, list, property, role, scheduled-script, script-action, script-include, scripted-rest, sla, state-model, table, ui-action, ui-macro, ui-page, ui-policy, user-preference
  • Table & View (3): column, column-generic, database-view
  • Service Catalog (6): catalog-item, catalog-item-record-producer, catalog-ui-policy, catalog-client-script, catalog-variable, variable-set
  • Email (2): email-notification, inbound-email-action
  • Automation & Workflow (3): flow, custom-action, playbook
  • Integration & Connections (6): alias, alias-template, retry-policy, rest-message, data-lookup, graphql-api
  • AI & Now Assist (3): ai-agent, ai-agent-workflow, now-assist-skill-config
  • Service Portal (3): service-portal, sp-header-footer, sp-page-route-map
  • Workspace & Analytics (2): workspace, dashboard
  • Assessments (2): assessment, risk-assessment
  • ATF & Testing (20): 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-form-sp, atf-list, atf-reporting, atf-rest-api, atf-rest-assert-payload, atf-server, atf-server-catalog-item, atf-server-record, atf-ui-test-script, test-suite

Development

npm ci                        # Install dependencies
npm run build                 # Build production bundle to dist/
npm run dev                   # Build development bundle and start server
npm test                      # Run full test suite (node:test)
npm run lint                  # Lint TypeScript sources
npm run typecheck             # Type-check src/ and test/ (npm run typecheck:test)
npm run validate:specs        # Validate res/spec/*.md against SDK types
npm run validate:instructs    # Validate res/instruct/*.md against SDK explain corpus
npm run validate:snippets     # Compile all res/snippet/*.md via now-sdk build
npm run inspect               # Launch MCP Inspector against dist/index.js
npm run bundle                # Package self-contained .mcpb bundle

License

MIT