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.

Key Features

• 17 MCP Tools — 13 ServiceNow SDK CLI command tools (sdk_info, init, build, deploy, transform, dependencies, download, clean, pack, explain, query, cicd_fluent_app, cicd_fluent_test) plus 4 resource/auth tools (get-api-spec, get-snippet, get-instruct, check_auth_status).
• 75 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 and fluent-security-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

Authentication Tip: To register an instance profile manually, run: npx @servicenow/sdk auth --add <instance-url> --type <basic|oauth> --alias <alias> 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.

Skills (fluent-skillset)

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

Skill Plugin Installation

Available Skills & Intended Usage

Available Tools (17)

SDK Command Tools (13)

Resource & Authentication Tools (4)

Resources & Prompts

Supported Metadata Types (75)

• Core (25): 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-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