https://github.com/modesty/fluent-mcp
MCP server for Fluent (ServiceNow SDK)
https://github.com/modesty/fluent-mcp
Last synced: 4 months ago
JSON representation
MCP server for Fluent (ServiceNow SDK)
- Host: GitHub
- URL: https://github.com/modesty/fluent-mcp
- Owner: modesty
- License: mit
- Created: 2025-06-15T04:21:39.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-07-14T02:35:11.000Z (11 months ago)
- Last Synced: 2025-07-14T03:00:10.127Z (11 months ago)
- Language: TypeScript
- Size: 609 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-mcp - modesty/fluent-mcp
- awesome-mcp-servers - **Fluent-MCP** - MCP server for Fluent (ServiceNow SDK) providing access to ServiceNow SDK CLI, API specifications, code snippets, and more. `api` `http` `git` `github` (📦 Other)
README
# Fluent MCP Server
An [MCP server](https://modelcontextprotocol.io) that brings [ServiceNow Fluent SDK](https://www.servicenow.com/docs/bundle/yokohama-application-development/page/build/servicenow-sdk/concept/servicenow-fluent.html) capabilities to AI-assisted development environments. Enables natural language interaction with ServiceNow SDK commands, API specifications, code snippets, and development resources.
## Key Features
- **🤖 AI-Powered Error Analysis** - Intelligent diagnosis with root cause, solutions, and prevention tips (MCP Sampling)
- **Complete SDK Coverage** - ServiceNow SDK commands: `init`, `build`, `install`, `dependencies`, `transform`, `download`, `clean`, `pack`
- **Rich Resources** - API specifications, code snippets, instructions for 35+ metadata types
- **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 complete [Model Context Protocol](https://modelcontextprotocol.io) specification with the following capabilities:
### Core
- **Resources** - Provides 100+ resources across 35+ ServiceNow metadata types (API specs, instructions, snippets, prompts)
- **Tools** - Exposes 9 ServiceNow SDK commands as MCP tools with full parameter validation
- **Prompts** - Offers development workflow templates for common ServiceNow tasks
- **Logging** - Structured logging for debugging and monitoring
### 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
- **Sampling** (MCP 2024-11-05) - Leverages client LLM for intelligent error analysis when SDK commands fail
- Automatically analyzes command errors >50 characters
- Provides structured diagnostics: root cause, solutions, prevention tips
- Configurable via `FLUENT_MCP_ENABLE_ERROR_ANALYSIS` environment variable
- **Elicitation** (MCP 2024-11-05) - 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
```bash
# Test with MCP Inspector
npx @modelcontextprotocol/inspector npx @modesty/fluent-mcp
# Or use in your MCP client (see Configuration below)
```
**Example prompt:**
```text
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) |
| `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` (auto-injected), `debug` (optional) |
| `fluent_transform` | Convert XML to Fluent TypeScript | `from`, `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) |
> **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.
## 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:
```json
{
"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_ENABLE_ERROR_ANALYSIS` | Enable AI error analysis | `true` |
| `FLUENT_MCP_MIN_ERROR_LENGTH` | Minimum error length for analysis | `50` |
> **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. If no profile exists, you'll be prompted to run the auth command manually.
## Usage Examples
### Typical Workflow
1. **Initialize Project**
```text
Create a new Fluent app in ~/projects/asset-tracker for IT asset management
```
2. **Develop with Resources**
```text
Show me the business-rule API specification and provide an example snippet
```
3. **Build and Deploy**
```text
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 --type --alias `
## Testing with MCP Inspector
The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) provides a web interface for testing MCP servers.
### Launch Inspector
```bash
# 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:**
- 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
**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:**
- Version command returns SDK version string
- Help command returns detailed command documentation
- List metadata (`-lm`) returns available Fluent metadata types
- No errors in notifications pane
- Commands execute within 2-3 seconds
## License
MIT