servicenow-mcp-server 2.1.0

package/docs/RESOURCES_SUMMARY.md

@@ -0,0 +1,104 @@
+# MCP Resources Summary
+
+## Implementation Complete
+
+MCP Resources have been successfully implemented for the ServiceNow MCP server.
+
+## Files Created
+
+1. **`/src/resources.js`** - Resource handlers implementation
+2. **`/docs/RESOURCES_IMPLEMENTATION.md`** - Complete documentation
+
+## Integration Required
+
+Add to `/src/mcp-server-consolidated.js`:
+
+```javascript
+import { createResourceHandlers } from './resources.js';
+
+// After loading tableMetadata:
+const { listResources, readResource } = createResourceHandlers(
+  serviceNowClient,
+  configManager,
+  tableMetadata
+);
+
+// Replace existing resource handlers with:
+server.setRequestHandler(ListResourcesRequestSchema, listResources);
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+  return await readResource(uri);
+});
+```
+
+## Resource URIs Implemented
+
+### Global Resources
+- `servicenow://instances` - All configured instances
+- `servicenow://tables` - All available tables with metadata
+
+### Instance Resources
+- `servicenow://{instance}/info` - Instance info & capabilities
+- `servicenow://{instance}/incidents` - Active incidents (25)
+- `servicenow://{instance}/incidents/{number}` - Specific incident
+- `servicenow://{instance}/users` - Active users (50)
+- `servicenow://{instance}/update-sets` - Update sets in progress (25)
+- `servicenow://{instance}/update-sets/{sys_id}` - Update set contents & breakdown
+- `servicenow://{instance}/groups` - User groups (50)
+- `servicenow://{instance}/change-requests` - Active change requests (25)
+
+## Key Features
+
+1. **Multi-Instance Support** - Automatic instance routing
+2. **Metadata Enrichment** - All responses include timestamp, instance, count
+3. **Cacheable** - Read-only with timestamps for client caching
+4. **Error Handling** - Clear error messages with suggestions
+5. **Performance Optimized** - Field selection, default limits
+6. **Update Set Inspection** - Detailed component breakdown by type
+
+## Example Response Format
+
+```json
+{
+  "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",
+      "assigned_to": {"value": "abc123", "display_value": "John Doe"},
+      "sys_created_on": "2025-10-05 14:23:15"
+    }
+  ]
+}
+```
+
+## Testing
+
+Use MCP Inspector to test:
+
+```bash
+npx @modelcontextprotocol/inspector node src/stdio-server.js
+
+# Commands:
+resources/list
+resources/read servicenow://dev/info
+resources/read servicenow://dev/incidents
+resources/read servicenow://dev/update-sets/abc123
+```
+
+## Documentation
+
+See `/docs/RESOURCES_IMPLEMENTATION.md` for complete details including:
+- Integration instructions
+- URI format specification
+- Feature descriptions
+- Error handling
+- Performance considerations
+- Future enhancements

package/docs/SETUP_GUIDE.md

@@ -0,0 +1,104 @@
+# ServiceNow MCP Server Setup Guide
+
+## Two Server Modes
+
+This MCP server can run in two different modes:
+
+### 1. HTTP/SSE Mode (Port 3000) - For Claude Code & Testing
+- **File**: `src/server.js`
+- **Port**: 3000 (configurable via PORT env var)
+- **Usage**: Claude Code integration, API testing, web-based access
+- **Start Command**: `npm start:http` or `npm run dev`
+- **Endpoint**: http://localhost:3000/mcp
+
+### 2. STDIO Mode - For Claude Desktop App
+- **File**: `src/stdio-server.js`
+- **Usage**: Claude Desktop app integration
+- **Start Command**: `npm start:stdio`
+- **No port required** (uses standard input/output)
+
+## Configuration for Claude Desktop
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "servicenow": {
+      "command": "node",
+      "args": ["/Users/nczitzer/WebstormProjects/mcp-servicenow-nodejs/src/stdio-server.js"],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://dev276360.service-now.com",
+        "SERVICENOW_USERNAME": "admin",
+        "SERVICENOW_PASSWORD": "$h4fG+9nAGeU"
+      }
+    }
+  }
+}
+```
+
+## Configuration for Claude Code
+
+The HTTP server runs automatically on port 3000 when you use:
+```bash
+npm start
+# or
+npm run dev
+```
+
+## Running Both Simultaneously
+
+You can run both servers at the same time:
+
+1. **Terminal 1** - HTTP Server for Claude Code:
+```bash
+npm start:http
+```
+
+2. **Claude Desktop** - Will automatically start stdio server when needed
+
+## Testing the Servers
+
+### Test HTTP Server:
+```bash
+# Health check
+curl http://localhost:3000/health
+
+# Test MCP endpoint
+curl -X GET http://localhost:3000/mcp
+```
+
+### Test STDIO Server:
+```bash
+# Run directly to see output
+node src/stdio-server.js
+# Press Ctrl+C to exit
+```
+
+## Common Issues
+
+1. **Port 3000 already in use**: Kill existing process:
+```bash
+pkill -f "node src/server.js"
+```
+
+2. **Claude Desktop not connecting**:
+- Restart Claude Desktop after updating config
+- Check the path in config matches your actual path
+- Ensure credentials in config are correct
+
+3. **Both trying to use same port**:
+- HTTP server uses port 3000
+- STDIO server doesn't use any port
+- They can run simultaneously without conflict
+
+## Environment Variables
+
+Make sure your `.env` file contains:
+```
+SERVICENOW_INSTANCE_URL=https://dev276360.service-now.com
+SERVICENOW_USERNAME=admin
+SERVICENOW_PASSWORD=$h4fG+9nAGeU
+PORT=3000
+DEBUG=true
+```