modesty/fluent-mcp

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@v4.13.6.
> **Note** : Since v0.6.0 the server speaks **both** MCP@2026-07-28 and MCP@2025-11-25 from one handler set — the stdio entry inspects the opening message and serves whichever era the client opens with. v0.5.1 is the last release built on the v1 MCP SDK (2025-11-25 only).
Key Features
- **SDK Command Tools** - sdk_info plus ServiceNow SDK command tools for init, build, install, dependencies, transform, download, clean, pack, explain, query, and cicd
- **Rich Resources** - API specifications, instructions, and code snippets for **75 ServiceNow metadata types**
- **API Documentation Lookup** - explain_fluent_api returns SDK docs for any Fluent API or guide — no project required
- **Lazy Auto-Authentication** - Detects and caches an auth profile only when an auth-requiring command or check_auth_status needs it
- **Explicit Project Context** - Resolves each project command from its workingDirectory argument, the initialized session, or FLUENT_MCP_WORKING_DIR, then fails with actionable guidance instead of guessing
- **MCPB Bundle** - Builds a self-contained .mcpb distribution with the server, resources, and production dependencies
- **Client-Friendly Schemas** - Optional inputs advertise their canonical value types while the enforced schema accepts null as an omitted-value compatibility form
This MCP server implements the Model Context Protocol specification with the following capabilities:
Core
- **Resources** - 300+ packaged resource documents across 75 ServiceNow metadata types (API specs, instructions, snippets, prompts)
- **Tools** - 13 ServiceNow SDK command tools plus 4 resource/auth tools (17 total), 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 logs are written to stderr; progress notifications are sent for long-running commands (any command with a 30s or longer timeout — deploy, build, transform, download, dependencies, query, pack, cicd) when the client supplies a progress token
Project Context & Sessions
The server requires **no client capabilities** and issues **no server→client requests**: Roots, Sampling, and Elicitation are not used (MCP 2026-07-28 removed server-initiated requests, and all input arrives with the tools/call arguments). Automatic workspace detection through Roots is gone for every client, including MCPB hosts.
- **Session Management** - Tracks the directory established by init_fluent_app for subsequent project commands
- **Working Directory Resolution** - workingDirectory tool argument → initialized session → FLUENT_MCP_WORKING_DIR → actionable failure. Accepted paths are non-empty absolute paths other than the filesystem root. The server never guesses from its process cwd or installed package directory. Clients must pass workingDirectory or configure FLUENT_MCP_WORKING_DIR when no session directory exists.
- **Non-interactive init_fluent_app** - Intent-specific arguments must be supplied with the call (creation: appName, packageName, scopeName, template; conversion: from); a missing argument fails with an error naming exactly what is absent. The tool does not prompt or elicit missing values.
- **Error Handling** - Comprehensive error messages with actionable guidance
- **Type Safety** - Full TypeScript implementation with strict typing
Protocol Behavior
- Dual-era stdio on @modelcontextprotocol/server@2.3.1: a 2026-07-28 opening (per-request _meta envelope, server/discover) and a 2025-11-25 initialize are both served from the same handler set; the SDK entry point pins one era per connection.
- The six cacheable results of 2026-07-28 (tools/list, prompts/list, resources/list, resources/templates/list, resources/read, server/discover) advertise ttlMs: 3600000 / cacheScope: 'public' — everything they return is static for the process lifetime.
- The server advertises instructions during initialization; tools/list is a side-effect-free read that returns tools in deterministic name order.
- Optional tool arguments advertise their canonical JSON types so clients render normal form fields. The enforced call schema additionally accepts null as an omitted value; workingDirectory also treats an empty string as omitted before applying the fallback chain.