Fluent (ServiceNow SDK)
Gestiona metadatos, módulos, registros y pruebas de ServiceNow usando Fluent, un DSL declarativo basado en TypeScript. Soporta todos los comandos CLI del SDK de ServiceNow.
Documentación
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, andfluent-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_URLon first use. - Explicit Working Directory Resolution — Resolves project paths in strict order:
workingDirectoryargument → session (init_fluent_app) →FLUENT_MCP_WORKING_DIR→ actionable error. Never guesses fromprocess.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
mcpServersin your client's MCP settings file
Environment Variables
| Variable | Description | Default |
|---|---|---|
FLUENT_MCP_WORKING_DIR | Fallback absolute path to your Fluent project | — |
SN_INSTANCE_URL | ServiceNow 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_TYPE | oauth or basic | oauth |
FLUENT_MCP_LOG_LEVEL | Minimum 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_MS | Operator 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_TELEMETRY | Set to 1 to disable @servicenow/sdk CLI telemetry | — |
SN_SDK_CREDENTIALS_DIR | Directory 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 --addmakes the new profile your CLI default; runnpx @servicenow/sdk auth --use <previous alias>afterwards to keep the old one. Since@servicenow/sdk4.14.0, profiles are stored encrypted incredentials.encwith only the key in the OS keychain. The first auth lookup migrates existing keychain profiles silently; afterwards, profiles added with an oldernow-sdkare not visible to this server. If the store cannot be decrypted,check_auth_statusreports it, and you must runnow-sdk auth --delete allin a terminal and add the profile again. Do not reset for any other store error: a file written by a newernow-sdkneeds that newer SDK, and a keyring write failure needs the OS keyring unlocked. For headless CI/CD pipelines, setSN_SDK_NODE_ENV=SN_SDK_CI_INSTALLalong withSN_SDK_INSTANCE_URLandSN_SDK_USER/SN_SDK_USER_PWDorSN_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 / Tool | Installation |
|---|---|
| Claude Code | Run /plugin marketplace add modesty/fluent-mcp, then /plugin install fluent-skillset@modesty and /reload-plugins |
| GitHub Copilot | Run gh skill install modesty/fluent-mcp <skill-name> (add --scope user for ~/.copilot/skills/), then /skills reload |
| Codex | Run $skill-installer https://github.com/modesty/fluent-mcp/tree/main/skills/<skill-name>, then restart Codex |
| Cursor | Settings (Cmd+Shift+J) → Plugins → paste https://github.com/modesty/fluent-mcp.git → Add to Cursor |
| Grok | Run grok plugin marketplace add modesty/fluent-mcp and grok plugin install fluent-skillset --trust |
| Windsurf / Other Agents | Prompt 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
| Skill | Intended Usage |
|---|---|
fluent-cli | Fluent 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-review | ServiceNow 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-review | ServiceNow 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-review | ServiceNow 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-review | ServiceNow 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)
| Tool | Description | Key Parameters |
|---|---|---|
sdk_info | Get SDK version (-v) or command help (-h) | flag, command |
explain_fluent_api | Look up Fluent SDK docs for any API class, guide, or tag (no project required) | topic, list, peek, format (pretty|raw), debug |
init_fluent_app | Initialize a new Fluent app or convert an existing app (non-interactive) | workingDirectory, intent, appName, packageName, scopeName, template, from, auth, debug |
build_fluent_app | Build the Fluent application package | workingDirectory, sourceMap, debug |
deploy_fluent_app | Deploy/install the built package to a ServiceNow instance | workingDirectory, auth, skipFlowActivation, async, debug |
fluent_transform | Transform local XML or instance records into Fluent .now.ts source code | workingDirectory, from, directory, table, id, force, format, timeoutSeconds, auth, debug |
download_fluent_dependencies | Download application dependencies and script/table type definitions | workingDirectory, auth, debug |
download_fluent_app | Download application metadata from an instance | workingDirectory, directory, source, incremental, timeoutSeconds, auth, debug |
clean_fluent_app | Clean build output directory | workingDirectory, source, debug |
pack_fluent_app | Zip built application into an installable artifact | workingDirectory, source, debug |
query_fluent_records | Read-only Table REST query against an instance (returns JSON envelope); needs no Fluent project | table, query, fields, limit, offset, displayValue, select, timeout, auth |
cicd_fluent_app | Install, publish, or rollback an app via the sn_cicd API | workingDirectory, action (install|publish|rollback), scope|appSysId, appVersion, wait, pollTimeout, output, select |
cicd_fluent_test | Run, watch, or fetch results/logs for ATF test suites and tests via sn_cicd | target (testsuite|test), action (run|watch|result|logs), testSuiteSysId|testSuiteName, testSysId|testName, progressId, resultId, pattern, limit, wait, output, select |
fluent_exec_script | Run 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)
| Tool | Description | Key Parameters |
|---|---|---|
get_fluent_knowledge | Get 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 kind | kind (spec|instruct|snippet), metadataType (optional, one of the 76 types), snippetId (optional, snippets only) |
check_auth_status | Validate and return the current ServiceNow instance authentication status | None |
Resources & Prompts
| Type | URI / Name | Purpose |
|---|---|---|
| API Specs | sn-spec://{metadataType} | TypeScript API signatures and field schemas |
| Instructions | sn-instruct://{metadataType} | Best practices, constraints, and common pitfalls |
| Code Snippets | sn-snippet://{metadataType}/{id} | Practical, build-validated code examples |
| Prompts | coding_in_fluent, create_custom_ui | End-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