servicenow-mcp-server 2.1.0

package/docs/RESOURCES_ARCHITECTURE.md

@@ -0,0 +1,392 @@
+# MCP Resources Architecture
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      MCP Client                              │
+│                  (Claude Code / CLI)                         │
+└───────────────────┬─────────────────────────────────────────┘
+                    │
+                    │ ListResources / ReadResource
+                    │
+┌───────────────────▼─────────────────────────────────────────┐
+│                   MCP Server                                 │
+│            (mcp-server-consolidated.js)                      │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │         Resource Request Handlers                     │  │
+│  │                                                       │  │
+│  │  ListResourcesRequestSchema  ──────┐                │  │
+│  │  ReadResourceRequestSchema   ──────┤                │  │
+│  └────────────────────────────────────┼────────────────┘  │
+│                                       │                     │
+│  ┌────────────────────────────────────▼────────────────┐  │
+│  │            resources.js                             │  │
+│  │                                                      │  │
+│  │  createResourceHandlers(                            │  │
+│  │    serviceNowClient,                                │  │
+│  │    configManager,                                   │  │
+│  │    tableMetadata                                    │  │
+│  │  )                                                   │  │
+│  │                                                      │  │
+│  │  ┌────────────────────────────────────────────┐    │  │
+│  │  │  listResources()                           │    │  │
+│  │  │  - Build resource list                     │    │  │
+│  │  │  - Include all instances                   │    │  │
+│  │  │  - Add metadata resources                  │    │  │
+│  │  └────────────────────────────────────────────┘    │  │
+│  │                                                      │  │
+│  │  ┌────────────────────────────────────────────┐    │  │
+│  │  │  readResource(uri)                         │    │  │
+│  │  │  1. Parse URI                              │    │  │
+│  │  │  2. Route to handler                       │    │  │
+│  │  │  3. Switch instance if needed              │    │  │
+│  │  │  4. Fetch data                             │    │  │
+│  │  │  5. Format with metadata                   │    │  │
+│  │  │  6. Restore original instance              │    │  │
+│  │  └────────────────────────────────────────────┘    │  │
+│  └──────────────────────────────────────────────────────┘  │
+└───────────────────┬─────────────────────────────────────────┘
+                    │
+        ┌───────────┼───────────┬────────────────┐
+        │           │           │                │
+        ▼           ▼           ▼                ▼
+┌──────────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────┐
+│ServiceNow    │ │Config    │ │Table         │ │Instance  │
+│Client        │ │Manager   │ │Metadata      │ │Switching │
+│              │ │          │ │              │ │          │
+│- getRecords  │ │- list    │ │- schemas     │ │- save    │
+│- getRecord   │ │- get     │ │- fields      │ │- switch  │
+│- setInstance │ │- switch  │ │- types       │ │- restore │
+└──────────────┘ └──────────┘ └──────────────┘ └──────────┘
+        │                                             │
+        └─────────────────────────────────────────────┘
+                              │
+                              ▼
+              ┌────────────────────────────┐
+              │   ServiceNow REST API       │
+              │   (Multiple Instances)      │
+              │                             │
+              │   - dev.service-now.com     │
+              │   - test.service-now.com    │
+              │   - prod.service-now.com    │
+              └─────────────────────────────┘
+```
+
+## Resource URI Routing
+
+```
+servicenow://instances
+    │
+    └──> configManager.listInstances()
+         Return all configured instances
+
+
+servicenow://tables
+    │
+    └──> tableMetadata
+         Return all table definitions
+
+
+servicenow://{instance}/info
+    │
+    ├──> configManager.getInstance(instance)
+    ├──> serviceNowClient.getCurrentInstance()
+    └──> Format server info + capabilities
+
+
+servicenow://{instance}/incidents
+    │
+    ├──> Switch to instance (if needed)
+    ├──> serviceNowClient.getRecords('incident', {...})
+    ├──> Format with metadata
+    └──> Restore original instance
+
+
+servicenow://{instance}/incidents/{number}
+    │
+    ├──> Switch to instance (if needed)
+    ├──> serviceNowClient.getRecords('incident', {query: 'number=...'})
+    ├──> Format single record with metadata
+    └──> Restore original instance
+
+
+servicenow://{instance}/update-sets/{sys_id}
+    │
+    ├──> Switch to instance (if needed)
+    ├──> serviceNowClient.getRecord('sys_update_set', sys_id)
+    ├──> serviceNowClient.getRecords('sys_update_xml', {query: 'update_set=...'})
+    ├──> Group by type, aggregate counts
+    ├──> Format detailed breakdown
+    └──> Restore original instance
+```
+
+## Data Flow
+
+### List Resources Request
+
+```
+Client Request
+    │
+    ▼
+MCP Server: ListResourcesRequestSchema
+    │
+    ▼
+resources.js: listResources()
+    │
+    ├──> Get current instance
+    ├──> Get all instances
+    ├──> Build resource list
+    │    ├── Global resources (instances, tables)
+    │    ├── Current instance resources
+    │    └── Other instance resources
+    │
+    ▼
+Return: { resources: [...] }
+```
+
+### Read Resource Request
+
+```
+Client Request: servicenow://dev/incidents
+    │
+    ▼
+MCP Server: ReadResourceRequestSchema
+    │
+    ▼
+resources.js: readResource(uri)
+    │
+    ├──> Parse URI
+    │    ├── Extract instance: "dev"
+    │    └── Extract resource: "incidents"
+    │
+    ├──> Save current instance
+    │
+    ├──> Switch to requested instance
+    │    └──> serviceNowClient.setInstance(dev)
+    │
+    ├──> Fetch data
+    │    └──> serviceNowClient.getRecords('incident', {
+    │         sysparm_query: 'active=true',
+    │         sysparm_limit: 25,
+    │         sysparm_fields: 'number,short_description,...'
+    │       })
+    │
+    ├──> Format response
+    │    └──> {
+    │         metadata: {timestamp, instance, description, count},
+    │         data: [...]
+    │       }
+    │
+    ├──> Restore original instance
+    │    └──> serviceNowClient.setInstance(original)
+    │
+    ▼
+Return: { contents: [{uri, mimeType, text}] }
+```
+
+## Instance Switching Flow
+
+```
+Request: servicenow://prod/incidents
+(Current instance: dev)
+
+1. Save current state
+   ┌──────────────────────┐
+   │ originalInstance =   │
+   │   name: 'dev'        │
+   │   url: 'dev.sn.com'  │
+   └──────────────────────┘
+
+2. Switch to requested instance
+   ┌──────────────────────┐
+   │ configManager.get    │
+   │   Instance('prod')   │
+   │                      │
+   │ serviceNowClient.    │
+   │   setInstance(...)   │
+   └──────────────────────┘
+
+3. Execute request
+   ┌──────────────────────┐
+   │ GET /api/now/table/  │
+   │   incident           │
+   │                      │
+   │ Host: prod.sn.com    │
+   │ Auth: prod creds     │
+   └──────────────────────┘
+
+4. Restore original instance
+   ┌──────────────────────┐
+   │ serviceNowClient.    │
+   │   setInstance(       │
+   │     originalInstance │
+   │   )                  │
+   └──────────────────────┘
+```
+
+## Error Handling Flow
+
+```
+Invalid URI: servicenow://invalid-format
+    │
+    ▼
+Parse URI (regex match fails)
+    │
+    ▼
+throw Error('Invalid resource URI format...')
+    │
+    ▼
+MCP Server catches error
+    │
+    ▼
+Return error response to client
+
+
+Resource not found: servicenow://dev/unknown
+    │
+    ▼
+Parse URI successfully
+    │
+    ▼
+No matching resource handler
+    │
+    ▼
+throw Error('Unknown resource path: unknown. Available: ...')
+    │
+    ▼
+MCP Server catches error
+    │
+    ▼
+Return error response with suggestions
+
+
+Instance not found: servicenow://nonexistent/incidents
+    │
+    ▼
+configManager.getInstance('nonexistent')
+    │
+    ▼
+throw Error('Instance "nonexistent" not found. Available: ...')
+    │
+    ▼
+MCP Server catches error
+    │
+    ▼
+Return error response with instance list
+```
+
+## Resource Response Format
+
+All resources return a consistent format:
+
+```javascript
+{
+  contents: [
+    {
+      uri: "servicenow://dev/incidents",
+      mimeType: "application/json",
+      text: JSON.stringify({
+        metadata: {
+          timestamp: "2025-10-06T12:00:00.000Z",
+          instance: "dev",
+          description: "Active incidents from dev",
+          record_count: 15
+        },
+        data: [
+          { /* incident 1 */ },
+          { /* incident 2 */ },
+          // ...
+        ]
+      }, null, 2)
+    }
+  ]
+}
+```
+
+## Performance Optimization
+
+```
+Resource Request: servicenow://dev/incidents
+    │
+    ├──> Field Selection
+    │    └──> sysparm_fields: 'number,short_description,state,...'
+    │        (Only essential fields, not all 100+ fields)
+    │
+    ├──> Limit Records
+    │    └──> sysparm_limit: 25
+    │        (Default limit prevents large payloads)
+    │
+    ├──> Query Filter
+    │    └──> sysparm_query: 'active=true'
+    │        (Server-side filtering)
+    │
+    └──> Caching Metadata
+         └──> Include timestamp for client caching decisions
+```
+
+## Extension Points
+
+Future resource types can be easily added:
+
+```javascript
+// In resources.js readResource()
+
+// Resource: servicenow://[instance]/problems
+if (resource === 'problems') {
+  const problems = await serviceNowClient.getRecords('problem', {
+    sysparm_query: 'active=true',
+    sysparm_limit: 25,
+    sysparm_fields: 'number,short_description,state,...'
+  });
+  return formatResource(problems, `Active problems from ${instanceName}`);
+}
+
+// Resource: servicenow://[instance]/catalog-items
+if (resource === 'catalog-items') {
+  const items = await serviceNowClient.getRecords('sc_cat_item', {
+    sysparm_query: 'active=true',
+    sysparm_limit: 50,
+    sysparm_fields: 'name,short_description,category,...'
+  });
+  return formatResource(items, `Catalog items from ${instanceName}`);
+}
+```
+
+## Integration with Tools
+
+Resources and Tools work together:
+
+```
+┌──────────────────────────────────────────────────────┐
+│                    MCP Client                         │
+└──────────────────┬───────────────────────────────────┘
+                   │
+        ┌──────────┴──────────┐
+        │                     │
+        ▼                     ▼
+┌──────────────┐      ┌─────────────┐
+│  Resources   │      │    Tools    │
+│ (Read-Only)  │      │ (Read/Write)│
+└──────┬───────┘      └──────┬──────┘
+       │                     │
+       │ GET data            │ Modify data
+       │                     │
+       ▼                     ▼
+┌─────────────────────────────────────┐
+│     ServiceNow REST API             │
+└─────────────────────────────────────┘
+
+Example workflow:
+1. Resource: Read servicenow://dev/incidents
+   → Get list of incidents
+
+2. Tool: SN-Update-Record
+   → Update specific incident
+
+3. Resource: Read servicenow://dev/incidents/{number}
+   → Verify update
+```
+
+This architecture provides a clean separation between read-only resources (cacheable, fast) and write tools (modify state, slower).

package/docs/RESOURCES_IMPLEMENTATION.md

@@ -0,0 +1,276 @@
+# MCP Resources Implementation
+
+## Overview
+
+This document describes the MCP Resources implementation for the ServiceNow MCP server. Resources provide read-only, cacheable access to ServiceNow data through a URI-based interface.
+
+## Implementation
+
+**File:** `/src/resources.js`
+
+The resources module exports factory functions that create resource handlers for the MCP server.
+
+### Integration
+
+To integrate with the MCP server (`src/mcp-server-consolidated.js`):
+
+```javascript
+import { createResourceHandlers } from './resources.js';
+
+// Inside createMcpServer function, after loading tableMetadata:
+const { listResources, readResource } = createResourceHandlers(
+  serviceNowClient,
+  configManager,
+  tableMetadata
+);
+
+// Register resource handlers
+server.setRequestHandler(ListResourcesRequestSchema, listResources);
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+  return await readResource(uri);
+});
+```
+
+## Resource URI Format
+
+All resources follow the pattern: `servicenow://[instance]/[resource]/[id]`
+
+### Global Resources
+
+Resources that don't require instance selection:
+
+- `servicenow://instances` - List all configured ServiceNow instances
+- `servicenow://tables` - List all available ServiceNow tables with metadata
+
+### Instance-Specific Resources
+
+Resources that query data from a specific instance:
+
+- `servicenow://{instance}/info` - Instance information and capabilities
+- `servicenow://{instance}/incidents` - List active incidents
+- `servicenow://{instance}/incidents/{number}` - Specific incident (e.g., INC0012345)
+- `servicenow://{instance}/users` - List active users
+- `servicenow://{instance}/update-sets` - List update sets in progress
+- `servicenow://{instance}/update-sets/{sys_id}` - Specific update set with contents
+- `servicenow://{instance}/groups` - List active user groups
+- `servicenow://{instance}/change-requests` - List active change requests
+
+## Features
+
+### 1. Multi-Instance Support
+
+Resources automatically route to the correct ServiceNow instance:
+
+```javascript
+// Access default instance
+servicenow://dev/incidents
+
+// Access prod instance
+servicenow://prod/incidents
+```
+
+The implementation handles instance switching and restoration automatically.
+
+### 2. Metadata Enrichment
+
+All resources return data wrapped with metadata:
+
+```json
+{
+  "metadata": {
+    "timestamp": "2025-10-06T12:00:00.000Z",
+    "instance": "dev",
+    "description": "Active incidents from dev",
+    "record_count": 15
+  },
+  "data": [...]
+}
+```
+
+### 3. Cacheability
+
+Resources are read-only and include timestamps, making them suitable for client-side caching.
+
+### 4. Update Set Inspection
+
+The update set resources provide detailed breakdowns:
+
+```javascript
+servicenow://dev/update-sets/abc123
+// Returns:
+{
+  "update_set": {
+    "sys_id": "abc123",
+    "name": "My Feature",
+    "state": "in progress",
+    ...
+  },
+  "total_records": 43,
+  "components": [
+    {
+      "type": "Business Rule",
+      "count": 5,
+      "items": ["Rule 1", "Rule 2", ...]
+    },
+    {
+      "type": "UI Policy",
+      "count": 3,
+      "items": [...]
+    }
+  ]
+}
+```
+
+## Example Usage
+
+### List All Resources
+
+```javascript
+// MCP Client
+const resources = await client.listResources();
+console.log(resources);
+// Shows all available resource URIs with descriptions
+```
+
+### Read Incidents from Dev Instance
+
+```javascript
+// MCP Client
+const incidents = await client.readResource({
+  uri: 'servicenow://dev/incidents'
+});
+
+console.log(incidents.contents[0].text);
+// {
+//   "metadata": {
+//     "timestamp": "2025-10-06T12:00:00.000Z",
+//     "instance": "dev",
+//     "description": "Active incidents from dev",
+//     "record_count": 15
+//   },
+//   "data": [
+//     {
+//       "number": "INC0012345",
+//       "short_description": "Server down",
+//       "state": "1",
+//       "priority": "1",
+//       ...
+//     }
+//   ]
+// }
+```
+
+### Read Specific Incident
+
+```javascript
+// MCP Client
+const incident = await client.readResource({
+  uri: 'servicenow://dev/incidents/INC0012345'
+});
+```
+
+### Inspect Update Set
+
+```javascript
+// MCP Client
+const updateSet = await client.readResource({
+  uri: 'servicenow://dev/update-sets/abc123def456'
+});
+
+// Returns detailed breakdown of update set contents grouped by type
+```
+
+## Error Handling
+
+The implementation provides clear error messages:
+
+- **Invalid URI format** - Returns format help
+- **Resource not found** - Specific error with available resources
+- **Instance not found** - Lists available instances
+- **ServiceNow API errors** - Forwarded with context
+
+## Performance Considerations
+
+### Default Limits
+
+- Incidents: 25 records
+- Users: 50 records
+- Update sets: 25 records
+- Groups: 50 records
+- Change requests: 25 records
+- Update set contents: 1000 records (with first 10 per type displayed)
+
+### Field Selection
+
+Resources request only essential fields to minimize payload size:
+
+```javascript
+sysparm_fields: 'number,short_description,state,priority,assigned_to,sys_created_on'
+```
+
+### Instance Switching
+
+The implementation saves and restores the current instance, ensuring thread safety in multi-client scenarios.
+
+## Future Enhancements
+
+Potential additions to the resources implementation:
+
+1. **Pagination Support** - Add offset/limit to resource URIs
+2. **Filtering** - Support query parameters in URIs
+3. **Additional Resources**:
+   - `servicenow://{instance}/problems` - List problems
+   - `servicenow://{instance}/catalog-items` - List service catalog items
+   - `servicenow://{instance}/workflows` - List workflows
+   - `servicenow://{instance}/business-rules` - List business rules
+
+4. **Resource Templates** - Dynamic resource generation based on table metadata
+
+5. **Aggregations** - Summary resources:
+   - `servicenow://{instance}/dashboard` - High-level metrics
+   - `servicenow://{instance}/stats/incidents` - Incident statistics
+
+## Testing
+
+Example manual test flow:
+
+```bash
+# Using MCP Inspector
+npx @modelcontextprotocol/inspector node src/stdio-server.js
+
+# List all resources
+> resources/list
+
+# Read instance info
+> resources/read servicenow://dev/info
+
+# Read incidents
+> resources/read servicenow://dev/incidents
+
+# Read specific incident
+> resources/read servicenow://dev/incidents/INC0012345
+
+# Read update set
+> resources/read servicenow://dev/update-sets/abc123
+```
+
+## Documentation
+
+- **API Reference**: See `docs/API_REFERENCE.md` for complete tool documentation
+- **Setup Guide**: See `docs/SETUP_GUIDE.md` for configuration
+- **Multi-Instance**: See `docs/MULTI_INSTANCE_CONFIGURATION.md` for instance setup
+
+## Summary
+
+The MCP Resources implementation provides:
+
+- **9+ resource types** for common ServiceNow data
+- **Multi-instance routing** with automatic switching
+- **Metadata enrichment** with timestamps and record counts
+- **Cacheable responses** suitable for client-side caching
+- **Error handling** with helpful messages
+- **Performance optimized** with field selection and limits
+- **Extensible design** for easy addition of new resources
+
+Resources complement the MCP tools by providing read-only access to frequently needed data without requiring explicit tool calls.