{"id":28793114,"url":"https://github.com/modesty/fluent-mcp","last_synced_at":"2026-02-09T03:07:54.074Z","repository":{"id":299172165,"uuid":"1002259705","full_name":"modesty/fluent-mcp","owner":"modesty","description":"MCP server for Fluent (ServiceNow SDK)","archived":false,"fork":false,"pushed_at":"2025-07-14T02:35:11.000Z","size":624,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-14T03:00:10.127Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modesty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-15T04:21:39.000Z","updated_at":"2025-07-14T02:35:14.000Z","dependencies_parsed_at":"2025-06-15T05:38:22.643Z","dependency_job_id":"ceb4681d-7f8f-43a8-b80b-ecac65bd1ecf","html_url":"https://github.com/modesty/fluent-mcp","commit_stats":null,"previous_names":["modesty/fluent-mcp"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/modesty/fluent-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modesty%2Ffluent-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modesty%2Ffluent-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modesty%2Ffluent-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modesty%2Ffluent-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modesty","download_url":"https://codeload.github.com/modesty/fluent-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modesty%2Ffluent-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266303700,"owners_count":23908375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-18T01:05:14.520Z","updated_at":"2026-01-08T02:13:35.442Z","avatar_url":"https://github.com/modesty.png","language":"TypeScript","funding_links":[],"categories":["Productivity","📦 Other"],"sub_categories":["Helpdesk \u0026 Support"],"readme":"# Fluent MCP Server\n\nAn [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.\n\n## Key Features\n\n- **🤖 AI-Powered Error Analysis** - Intelligent diagnosis with root cause, solutions, and prevention tips (MCP Sampling)\n- **Complete SDK Coverage** - ServiceNow SDK commands: `init`, `build`, `install`, `dependencies`, `transform`, `download`, `clean`, `pack`\n- **Rich Resources** - API specifications, code snippets, instructions for 35+ metadata types\n- **Auto-Authentication** - Automatic auth profile detection and session management via environment variables\n- **Session-Aware** - Maintains working directory and auth context across commands\n\nThis MCP server implements the complete [Model Context Protocol](https://modelcontextprotocol.io) specification with the following capabilities:\n\n### Core\n\n- **Resources** - Provides 100+ resources across 35+ ServiceNow metadata types (API specs, instructions, snippets, prompts)\n- **Tools** - Exposes 9 ServiceNow SDK commands as MCP tools with full parameter validation\n- **Prompts** - Offers development workflow templates for common ServiceNow tasks\n- **Logging** - Structured logging for debugging and monitoring\n\n### Client Capabilities (used by this server)\n\nThe server leverages these MCP client capabilities when available:\n\n- **Roots** - Requests workspace roots from the client for context-aware operations\n  - Falls back to project root when client doesn't provide roots\n\n- **Sampling** (MCP 2024-11-05) - Leverages client LLM for intelligent error analysis when SDK commands fail\n  - Automatically analyzes command errors \u003e50 characters\n  - Provides structured diagnostics: root cause, solutions, prevention tips\n  - Configurable via `FLUENT_MCP_ENABLE_ERROR_ANALYSIS` environment variable\n\n- **Elicitation** (MCP 2024-11-05) - Interactive parameter collection for complex workflows\n  - **`init_fluent_app`** - Prompts for missing project parameters (workingDirectory, template, appName, etc.)\n  - Supports both creation and conversion workflows with smart validation\n  - Handles user acceptance/rejection of elicited data\n\n- **Session Management** - Tracks working directory per session for multi-project workflows\n- **Root Fallback** - Automatically falls back to MCP root context when no session directory is set\n- **Error Handling** - Comprehensive error messages with actionable guidance\n- **Type Safety** - Full TypeScript implementation with strict typing\n\n## Quick Start\n\n```bash\n# Test with MCP Inspector\nnpx @modelcontextprotocol/inspector npx @modesty/fluent-mcp\n\n# Or use in your MCP client (see Configuration below)\n```\n\n**Example prompt:**\n\n```text\nCreate a new Fluent app in ~/projects/time-off-tracker to manage employee PTO requests\n```\n\n## Available Tools\n\n### SDK Commands\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `sdk_info` | Get SDK version or help | `flag` (-v/-h), `command` (optional for -h) |\n| `get-api-spec` | Get API spec or list all metadata types | `metadataType` (optional, omit to list all) |\n| `init_fluent_app` | Initialize or convert ServiceNow app | `workingDirectory` (required), `template`, `from` (optional) |\n| `build_fluent_app` | Build the application | `debug` (optional) |\n| `deploy_fluent_app` | Deploy to ServiceNow instance | `auth` (auto-injected), `debug` (optional) |\n| `fluent_transform` | Convert XML to Fluent TypeScript | `from`, `auth` (auto-injected) |\n| `download_fluent_dependencies` | Download dependencies and type definitions | `auth` (auto-injected) |\n| `download_fluent_app` | Download metadata from instance | `directory`, `incremental` (optional) |\n| `clean_fluent_app` | Clean output directory | `source` (optional) |\n| `pack_fluent_app` | Create installable artifact | `source` (optional) |\n\n\u003e **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.\n\n## Resources\n\nStandardized URI patterns following MCP specification:\n\n| Resource Type | URI Pattern | Example | Purpose |\n|---------------|-------------|---------|----------|\n| **API Specs** | `sn-spec://{type}` | `sn-spec://business-rule` | API documentation and parameters |\n| **Instructions** | `sn-instruct://{type}` | `sn-instruct://script-include` | Best practices and guidance |\n| **Code Snippets** | `sn-snippet://{type}/{id}` | `sn-snippet://acl/0001` | Practical code examples |\n| **Prompts** | `sn-prompt://{id}` | `sn-prompt://coding_in_fluent` | Development guides |\n\n### Supported Metadata Types\n\n**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`\n\n**Table Types:** `column`, `column-generic`\n\n**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`\n\n## Configuration\n\n**Requirements:** Node.js 22.15.1+, npm 11.4.1+\n\n### MCP Client Setup\n\nAdd to your MCP client configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"fluent-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modesty/fluent-mcp\"],\n      \"env\": {\n        \"SN_INSTANCE_URL\": \"https://your-instance.service-now.com\",\n        \"SN_AUTH_TYPE\": \"basic\",\n        \"SN_USER_NAME\": \"local-username\",\n        \"SN_PASSWORD\": \"local-password\"\n      }\n    }\n  }\n}\n```\n\n**Client-Specific Locations:**\n\n- **Claude Desktop / macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **VSCode Copilot:** `.vscode/mcp.json` (use Command Palette: `MCP: Add Server...`)\n- **Cursor:** Settings → Features → MCP Settings\n- **Windsurf:** Settings → Cascade → MCP Servers → View raw config\n- **Gemini CLI:** `~/.gemini/settings.json`\n\n\u003e **VSCode note:** For VSCode, the JSON structure uses `\"mcp\": { \"servers\": { ... } }` instead of `\"mcpServers\"`.\n\n**Environment Variables:**\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `SN_INSTANCE_URL` | ServiceNow instance URL for auto-auth validation | - |\n| `SN_AUTH_TYPE` | Authentication method: `basic` or `oauth` | `oauth` |\n| `SN_USER_NAME` | Username for basic auth (informational) | - |\n| `SN_PASSWORD` | Password for basic auth (informational) | - |\n| `FLUENT_MCP_ENABLE_ERROR_ANALYSIS` | Enable AI error analysis | `true` |\n| `FLUENT_MCP_MIN_ERROR_LENGTH` | Minimum error length for analysis | `50` |\n\n\u003e **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.\n\n## Usage Examples\n\n### Typical Workflow\n\n1. **Initialize Project**\n\n   ```text\n   Create a new Fluent app in ~/projects/asset-tracker for IT asset management\n   ```\n\n2. **Develop with Resources**\n\n   ```text\n   Show me the business-rule API specification and provide an example snippet\n   ```\n\n3. **Build and Deploy**\n\n   ```text\n   Build the app with debug output, then deploy it\n   ```\n\n\u003e **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 \u003cinstance-url\u003e --type \u003cbasic|oauth\u003e --alias \u003calias\u003e`\n\n## Testing with MCP Inspector\n\nThe [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) provides a web interface for testing MCP servers.\n\n### Launch Inspector\n\n```bash\n# Test published package\nnpx @modelcontextprotocol/inspector npx @modesty/fluent-mcp\n\n# Or for local development\nnpm run build \u0026\u0026 npm run inspect\n```\n\n### Test Scenarios\n\n#### Scenario 1: Explore Business Rule Resources\n\n**Objective:** Access API specs and code snippets for business rules\n\n**Steps:**\n\n1. Launch Inspector and wait for server connection\n2. Navigate to **Resources** tab\n3. Find and click `sn-spec://business-rule` in the resource list\n4. Review the API specification showing all available methods and parameters\n5. Go back and search for `sn-snippet://business-rule/0001`\n6. Click the snippet to view a complete TypeScript example\n7. Verify content includes proper imports and follows Fluent patterns\n\n**Expected Results:**\n\n- API spec displays structured documentation with method signatures\n- Snippet shows runnable TypeScript code with ServiceNow metadata patterns\n- Content is properly formatted and readable\n\n#### Scenario 2: Test SDK Info Command\n\n**Objective:** Verify SDK version and help information retrieval\n\n**Steps:**\n\n1. Navigate to **Tools** tab\n2. Select `sdk_info` from the tool list\n3. **Test Version:**\n   - Set `flag` parameter to `-v`\n   - Click **Execute**\n   - Verify response shows version number (e.g., \"4.0.1\")\n4. **Test Help:**\n   - Set `flag` parameter to `-h`\n   - Set `command` parameter to `build`\n   - Click **Execute**\n   - Verify response shows build command documentation with options\n5. Monitor **Notifications** pane for command execution logs\n\n**Expected Results:**\n\n- Version command returns SDK version string\n- Help command returns detailed command documentation\n- List metadata (`-lm`) returns available Fluent metadata types\n- No errors in notifications pane\n- Commands execute within 2-3 seconds\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodesty%2Ffluent-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodesty%2Ffluent-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodesty%2Ffluent-mcp/lists"}