GitHub - modesty/fluent-mcp: MCP server for Fluent (ServiceNow SDK) (original) (raw)

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.

Key Features

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

Core

Extended Capabilities

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, help, or debug info flag (-v/-h/-d), command (optional)
manage_fluent_auth Manage instance authentication profiles add, list, delete, use, type (basic/oauth)
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 auth (optional), debug (optional)
fluent_transform Convert XML to Fluent TypeScript from, auth (optional)
download_fluent_dependencies Download dependencies and type definitions auth (optional)
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)

Note: manage_fluent_auth, init_fluent_app, and download_fluent_dependencies are interactive commands. Use init_fluent_app to establish working directory context for subsequent commands.

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

Core Types: 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

Table Types: column, column-generic

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-reporting, atf-rest-api, atf-rest-assert-payload, atf-server, atf-server-catalog-item, atf-server-record

Configuration

Requirements: Node.js 22.15.1+, npm 11.4.1+

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": "oauth" } } } }

Client-Specific Locations:

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

Environment Variables:

Usage Examples

Typical Workflow

  1. Setup Authentication
Create a new auth profile for https://dev12345.service-now.com with alias dev-instance
  1. Initialize Project
Create a new Fluent app in ~/projects/asset-tracker for IT asset management
  1. Develop with Resources
Show me the business-rule API specification and provide an example snippet
  1. Build and Deploy
Build the app with debug output, then deploy to dev-instance

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:

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

Expected Results:

Scenario 2: Test SDK Info Command

Objective: Verify SDK version and help information retrieval

Steps:

  1. Navigate to Tools tab
  2. Select sdk_info from the tool list
  3. Test Version:
    • Set flag parameter to -v
    • Click Execute
    • Verify response shows version number (e.g., "4.0.1")
  4. Test Help:
    • Set flag parameter to -h
    • Set command parameter to build
    • Click Execute
    • Verify response shows build command documentation with options
  5. Monitor Notifications pane for command execution logs

Expected Results:

License

MIT