Fluent (ServiceNow SDK)

Kelola metadata, modul, rekaman, dan tes ServiceNow menggunakan Fluent, DSL deklaratif berbasis TypeScript. Mendukung semua perintah CLI SDK ServiceNow.

GitHub

Dokumentasi

Fluent MCP Server

An MCP server that brings ServiceNow Fluent SDK capabilities to AI-assisted development environments. Enables natural language interaction with ServiceNow SDK commands, API specifications, code snippets, and development resources.

Built for @servicenow/sdk 4.8.0.

Key Features

Complete SDK Coverage - ServiceNow SDK commands: init, build, install, dependencies, transform, download, clean, pack, explain, query
Rich Resources - API specifications, instructions, and code snippets for 64 ServiceNow metadata types
API Documentation Lookup - explain_fluent_api returns SDK docs for any Fluent API or guide — no project required
Auto-Authentication - Automatic auth profile detection and session management via environment variables
Session-Aware - Maintains working directory and auth context across commands

This MCP server implements the Model Context Protocol specification with the following capabilities:

Core

Resources - 300+ resources across 64 ServiceNow metadata types (API specs, instructions, snippets, prompts)
Tools - 11 ServiceNow SDK commands plus resource-lookup tools, with full parameter validation. Read tools (get-api-spec, get-snippet, get-instruct, check_auth_status) declare an outputSchema and return structuredContent for programmatic consumers
Prompts - Development workflow templates for common ServiceNow tasks (coding_in_fluent, create_custom_ui)
Logging & Progress - Structured logging for debugging and monitoring; progress notifications for long-running commands (build, install, transform, download) when the client supplies a progress token

Client Capabilities (used by this server)

The server leverages these MCP client capabilities when available:

Roots - Requests workspace roots from the client for context-aware operations
- Falls back to project root when client doesn't provide roots
Elicitation - Interactive parameter collection for complex workflows
- init_fluent_app - Prompts for missing project parameters (workingDirectory, template, appName, etc.)
- Supports both creation and conversion workflows with smart validation
- Handles user acceptance/rejection of elicited data
Session Management - Tracks working directory per session for multi-project workflows
Root Fallback - Automatically falls back to MCP root context when no session directory is set
Error Handling - Comprehensive error messages with actionable guidance
Type Safety - Full TypeScript implementation with strict typing

Quick Start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# Or use in your MCP client (see Configuration below)

Example prompt:

Create a new Fluent app in ~/projects/time-off-tracker to manage employee PTO requests

Available Tools

SDK Commands

Tool	Description	Key Parameters
`sdk_info`	Get SDK version or help	`flag` (-v/-h), `command` (optional for -h)
`get-api-spec`	Get API spec or list all metadata types	`metadataType` (optional, omit to list all)
`explain_fluent_api`	Look up Fluent SDK documentation for any API or guide. No Fluent project required.	`topic` (optional API/guide name or tag keyword — required unless `list=true`), `list` (boolean — list topics), `peek` (boolean — brief summary), `format` (`pretty`\|`raw`), `source` (optional project path override), `debug` (optional)
`init_fluent_app`	Initialize or convert ServiceNow app	`workingDirectory` (required), `template`, `from` (optional)
`build_fluent_app`	Build the application	`debug` (optional)
`deploy_fluent_app`	Deploy to ServiceNow instance. Supports `--skip-flow-activation`.	`auth` (auto-injected), `debug` (optional), `skipFlowActivation` (optional)
`fluent_transform`	Convert XML to Fluent TypeScript	`from`, `table` (comma-separated, transform by hierarchy), `id` (specific record, with `table`), `auth` (auto-injected)
`download_fluent_dependencies`	Download dependencies and type definitions	`auth` (auto-injected)
`download_fluent_app`	Download metadata from instance	`directory`, `incremental` (optional)
`clean_fluent_app`	Clean output directory	`source` (optional)
`pack_fluent_app`	Create installable artifact	`source` (optional)
`query_fluent_records`	Read-only Table REST query against an instance (returns a JSON envelope)	`table` (required), `query` (required encoded query), `fields`, `limit`, `offset`, `displayValue`, `auth` (auto-injected)

Note: Authentication is automatically configured at startup via environment variables. The auth parameter is auto-injected from the session for commands that require instance access. Use init_fluent_app to establish working directory context for subsequent commands.

Looking up Fluent APIs with `explain_fluent_api`

explain_fluent_api wraps now-sdk explain and returns SDK documentation for any Fluent API class or topic guide. It works from any directory — no Fluent project required.

Invocation	Result
`explain_fluent_api({ topic: 'BusinessRule' })`	Full API reference for `BusinessRule`
`explain_fluent_api({ topic: 'BusinessRule', peek: true })`	Brief summary of `BusinessRule`
`explain_fluent_api({ topic: 'BusinessRule', format: 'raw' })`	Full API reference as plain markdown (good for piping into other tools)
`explain_fluent_api({ list: true })`	Full topic index (all APIs and guides)
`explain_fluent_api({ list: true, topic: 'atf' })`	Topic index filtered to entries matching `atf`

topic matches an API name (e.g. BusinessRule, Acl), a guide name (e.g. business-rule-guide, atf-guide), or a tag keyword (e.g. flow, atf, email). The SDK resolves by exact name first, then by tag.

Resources

Standardized URI patterns following MCP specification:

Resource Type	URI Pattern	Example	Purpose
API Specs	`sn-spec://{type}`	`sn-spec://business-rule`	API documentation and parameters
Instructions	`sn-instruct://{type}`	`sn-instruct://script-include`	Best practices and guidance
Code Snippets	`sn-snippet://{type}/{id}`	`sn-snippet://acl/0001`	Practical code examples
Prompts	`sn-prompt://{id}`	`sn-prompt://coding_in_fluent`	Development guides

Supported Metadata Types

64 metadata types across the following categories:

Core Types: acl, application-menu, business-rule, client-script, cross-scope-privilege, data-policy, form, import-set, instance-scan, list, property, role, scheduled-script, script-action, script-include, scripted-rest, sla, table, ui-action, ui-page, ui-policy, user-preference

Table Types: column, column-generic

Service Catalog: catalog-item, catalog-item-record-producer, catalog-ui-policy, catalog-client-script, catalog-variable, variable-set

Email: email-notification, inbound-email-action

Automation & Workflow: flow, custom-action, playbook

Integration & Connections: alias, alias-template, retry-policy, rest-message, data-lookup

AI & Now Assist: ai-agent, ai-agent-workflow, now-assist-skill-config

Service Portal: service-portal, sp-header-footer, sp-page-route-map

Workspace & Analytics: workspace, dashboard

ATF (Automated Test Framework): 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-reporting, atf-rest-api, atf-rest-assert-payload, atf-server, atf-server-catalog-item, atf-server-record

What's new in 4.8.x

This release of the MCP server tracks @servicenow/sdk 4.8.0 and adds support for the following Fluent APIs and SDK enhancements:

New metadata type: playbook — the PlaybookDefinition API (sys_pd_process_definition, from @servicenow/sdk/automation) for guided, record-driven multi-step processes with lanes, activities, triggers, and inputs/outputs.
New metadata type: rest-message — the RestMessage API (sys_rest_message) for outbound HTTP integrations with shared auth/headers and callable functions.
New metadata types: alias and alias-template — the Alias (sys_alias) and AliasTemplate (sys_alias_templates) APIs for Connection & Credential aliases and reusable connection-setup templates.
New metadata type: retry-policy — the RetryPolicy API (sys_retry_policy) controlling transient-failure handling for connections (fixed-interval, exponential-backoff, or Retry-After).
New metadata type: data-lookup — the DataLookup API (dl_definition) that auto-copies field values from a matcher table to a source record.
Declarative deletion (Now.del()) — top-level statement to remove records by coalesce keys or sys_id.
Type enhancements — $override on DataPolicy/UserPreference; $meta.installMethod on Record/Acl/Alias/UserPreference; ACL field accepts known field names, system columns, or '*'; Table accessibleFrom now defaults to 'public'.
New CLI tool — query_fluent_records wraps now-sdk query for read-only Table REST queries (JSON envelope output).

Previously (4.7.x)

This release of the MCP server tracks @servicenow/sdk 4.8.0 and adds support for the following Fluent APIs and SDK enhancements:

New metadata type: data-policy — the DataPolicy API (sys_data_policy2) for server-side mandatory/read-only field enforcement that cannot be bypassed via API, import, or web service.
Flow error handling & parallelism — wfa.flowLogic.tryCatch, wfa.flowLogic.doInParallel, and wfa.flowLogic.appendToFlowVariables (append to Array.Object flow variables).
Flow stages — declare stages with FlowStage({ label, value, … }) and activate them in the body via wfa.stage(...) for progress tracking.
Table augments — add columns to an existing platform/cross-scope table via Table({ augments: '<table>', schema }); added columns must be u_-prefixed.
AI Agent — new agentDescriptor; dataAccess accepts roleMap (role names) or roleList (role sys_ids).
NASK — securityControls accepts roleMap (role names) alongside roleRestrictions (role sys_ids).
Universal field override ($override) — escape hatch on Fluent constructors to set unmodeled columns by DB column name.
Protection policy — protectionPolicy documented on sys_policy-backed APIs (Action, Subflow, business rules, scripted REST, etc.).
CLI — fluent_transform gains --table/--id (transform by table hierarchy); init gains the typescript.vue template; OAuth client_credentials for CI/CD via SN_SDK_* env vars (see Configuration).
MCP — read tools now return structuredContent (with declared outputSchema); long-running commands emit progress notifications.

Previously (4.6.0)

Added custom-action, inbound-email-action, sp-header-footer, and sp-page-route-map metadata types; the declarative Form API; subflow-of-subflow and custom actions in flows; AIAF auto-ACL generation; NASK output/input-type enhancements; Table dictionary overrides; and a project-free explain command with tag search, --list, --peek, and --format=raw.

Configuration

Requirements: Node.js 20.18.0+, npm 11.4.1+, @servicenow/sdk 4.8.0

MCP Client Setup

Add to your MCP client configuration file:

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

Client-Specific Locations:

Claude Desktop / macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
VSCode Copilot: .vscode/mcp.json (use Command Palette: MCP: Add Server...)
Cursor: Settings → Features → MCP Settings
Windsurf: Settings → Cascade → MCP Servers → View raw config
Gemini CLI: ~/.gemini/settings.json

VSCode note: For VSCode, the JSON structure uses "mcp": { "servers": { ... } } instead of "mcpServers".

Environment Variables:

Variable	Description	Default
`SN_INSTANCE_URL`	ServiceNow instance URL for auto-auth validation	-
`SN_AUTH_TYPE`	Authentication method: `basic` or `oauth`	`oauth`
`SN_USER_NAME`	Username for basic auth (informational)	-
`SN_PASSWORD`	Password for basic auth (informational)	-
`FLUENT_MCP_LOG_TO_STDERR`	Also mirror logs to stderr (`1`/`true`/`yes`) for headless debugging	off

Note: The server automatically detects existing auth profiles matching SN_INSTANCE_URL at startup. If a matching profile is found, it's stored in the session and auto-injected into SDK commands. A new profile is added automatically only when it can complete non-interactively (basic auth with SN_USER_NAME/SN_USERNAME + SN_PASSWORD); otherwise the server emits a single notice with the manual auth --add command to run.

Logging

Once connected, the server sends all logs to the MCP client as notifications/message (the standard MCP logging channel), so they render with the correct severity in your client's UI. Only pre-connection bootstrap lines are written to stderr. Set FLUENT_MCP_LOG_TO_STDERR=1 to additionally mirror every log line to stderr when running headless or debugging outside an MCP client. Use the client's logging/setLevel request to adjust verbosity at runtime (default info; set debug to see raw SDK CLI output).

CI/CD (non-interactive) authentication — SDK v4.7.0+

For headless pipelines, the ServiceNow SDK CLI reads credentials directly from SN_SDK_* environment variables (the MCP server inherits and passes these through to spawned commands — no extra configuration needed). Set SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL to enable CI mode, then:

Variable	Required	Value
`SN_SDK_NODE_ENV`	yes	`SN_SDK_CI_INSTALL`
`SN_SDK_AUTH_TYPE`	for oauth	`basic` (default) or `oauth`
`SN_SDK_INSTANCE_URL`	yes	Full instance URL
`SN_SDK_USER` / `SN_SDK_USER_PWD`	basic	Username / password
`SN_SDK_OAUTH_CLIENT_ID` / `SN_SDK_OAUTH_CLIENT_SECRET`	oauth	OAuth `client_credentials` app credentials

OAuth uses the client_credentials grant against /oauth_token.do. See the SDK's ci-integration guide (via explain_fluent_api) for instance setup details.

Usage Examples

Typical Workflow

Initialize Project

Create a new Fluent app in ~/projects/asset-tracker for IT asset management

Develop with Resources

Show me the business-rule API specification and provide an example snippet

Build and Deploy

Build the app with debug output, then deploy it

Note: Authentication is automatically configured via environment variables (SN_INSTANCE_URL, SN_AUTH_TYPE). If you need to set up a new auth profile, run: npx @servicenow/sdk auth --add <instance-url> --type <basic|oauth> --alias <alias>

Testing with MCP Inspector

The MCP Inspector provides a web interface for testing MCP servers.

Launch Inspector

# Test published package
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp

# Or for local development
npm run build && npm run inspect

Test Scenarios

Scenario 1: Explore Business Rule Resources

Objective: Access API specs and code snippets for business rules

Steps:

Launch Inspector and wait for server connection
Navigate to Resources tab
Find and click sn-spec://business-rule in the resource list
Review the API specification showing all available methods and parameters
Go back and search for sn-snippet://business-rule/0001
Click the snippet to view a complete TypeScript example
Verify content includes proper imports and follows Fluent patterns

Expected Results:

API spec displays structured documentation with method signatures
Snippet shows runnable TypeScript code with ServiceNow metadata patterns
Content is properly formatted and readable

Scenario 2: Test SDK Info Command

Objective: Verify SDK version and help information retrieval