servicenow-mcp-server 2.1.0

package/docs/QUICK_REFERENCE.md

@@ -0,0 +1,395 @@
+# ServiceNow MCP Tools - Quick Reference Card
+
+## 🚀 New Convenience Tools (10)
+
+### Incident Tools
+```javascript
+// Add comment (customer-visible)
+SN-Add-Comment({ incident_number: "INC0012345", comment: "..." })
+
+// Add work notes (internal)
+SN-Add-Work-Notes({ incident_number: "INC0012345", work_notes: "..." })
+
+// Assign to user/group (auto-resolves names)
+SN-Assign-Incident({ incident_number: "INC0012345", assigned_to: "John Smith", assignment_group: "IT Support" })
+
+// Resolve (state → 6)
+SN-Resolve-Incident({ incident_number: "INC0012345", resolution_notes: "...", resolution_code: "Solved (Permanently)" })
+
+// Close (state → 7)
+SN-Close-Incident({ incident_number: "INC0012345", close_notes: "...", close_code: "Solved (Permanently)" })
+```
+
+### Change Request Tools
+```javascript
+// Add comment
+SN-Add-Change-Comment({ change_number: "CHG0012345", comment: "..." })
+
+// Assign to user/group
+SN-Assign-Change({ change_number: "CHG0012345", assigned_to: "Jane Doe", assignment_group: "Change Advisory Board" })
+
+// Approve
+SN-Approve-Change({ change_number: "CHG0012345", approval_comments: "..." })
+```
+
+### Problem Tools
+```javascript
+// Add comment
+SN-Add-Problem-Comment({ problem_number: "PRB0012345", comment: "..." })
+
+// Close (state → 3)
+SN-Close-Problem({ problem_number: "PRB0012345", resolution_notes: "...", resolution_code: "..." })
+```
+
+---
+
+## 📋 Core CRUD Tools (6)
+
+```javascript
+// Query any table
+SN-Query-Table({ table_name: "incident", query: "state=1^priority=1", limit: 25 })
+
+// Create record
+SN-Create-Record({ table_name: "incident", data: { short_description: "..." } })
+
+// Get single record
+SN-Get-Record({ table_name: "incident", sys_id: "...", fields: "number,state,priority" })
+
+// Update record
+SN-Update-Record({ table_name: "incident", sys_id: "...", data: { state: 6 } })
+
+// Get table schema
+SN-Get-Table-Schema({ table_name: "incident" })
+
+// List available tables
+SN-List-Available-Tables({ category: "core_itsm" })
+```
+
+---
+
+## 🔄 Update Set Management (6)
+
+```javascript
+// Set current update set (AUTOMATED!)
+SN-Set-Update-Set({ update_set_sys_id: "..." })
+
+// Get current update set
+SN-Get-Current-Update-Set()
+
+// List update sets
+SN-List-Update-Sets({ query: "state=in progress", limit: 25 })
+
+// Move records to update set
+SN-Move-Records-To-Update-Set({ update_set_id: "...", source_update_set: "Default" })
+
+// Clone update set
+SN-Clone-Update-Set({ source_update_set_id: "...", new_name: "..." })
+
+// Inspect update set contents
+SN-Inspect-Update-Set({ update_set: "...", show_components: true })
+```
+
+---
+
+## 🔧 Workflow Tools (4)
+
+```javascript
+// Create complete workflow
+SN-Create-Workflow({
+  name: "My Workflow",
+  table: "incident",
+  activities: [...],
+  transitions: [...],
+  publish: true
+})
+
+// Create activity
+SN-Create-Activity({ workflow_version_sys_id: "...", name: "...", script: "..." })
+
+// Create transition
+SN-Create-Transition({ from_activity_sys_id: "...", to_activity_sys_id: "..." })
+
+// Publish workflow
+SN-Publish-Workflow({ version_sys_id: "...", start_activity_sys_id: "..." })
+```
+
+---
+
+## 📦 Batch Operations (2)
+
+```javascript
+// Batch create with references
+SN-Batch-Create({
+  operations: [
+    { table: "sc_cat_item", data: {...}, save_as: "item" },
+    { table: "item_option_new", data: { cat_item: "${item}" } }
+  ],
+  transaction: true
+})
+
+// Batch update
+SN-Batch-Update({
+  updates: [
+    { table: "incident", sys_id: "...", data: { state: 6 } },
+    { table: "incident", sys_id: "...", data: { state: 6 } }
+  ],
+  stop_on_error: false
+})
+```
+
+---
+
+## 🎯 Specialized Tools (16)
+
+### ITSM Convenience
+```javascript
+SN-List-Incidents({ state: "1", priority: 1, limit: 25 })
+SN-Create-Incident({ short_description: "..." })
+SN-Get-Incident({ sys_id: "..." })
+SN-List-ChangeRequests({ state: "Pending Approval" })
+SN-List-Problems({ state: "Open" })
+```
+
+### User/Group Management
+```javascript
+SN-List-SysUsers({ query: "active=true", limit: 25 })
+SN-List-SysUserGroups({ query: "active=true" })
+SN-List-CmdbCis({ query: "..." })
+```
+
+### Application Scope
+```javascript
+SN-Set-Current-Application({ app_sys_id: "..." })
+```
+
+### Schema Discovery
+```javascript
+SN-Discover-Table-Schema({
+  table_name: "incident",
+  include_type_codes: true,
+  include_relationships: true
+})
+
+SN-Explain-Field({ table: "incident", field: "priority", include_examples: true })
+```
+
+### Configuration Validation
+```javascript
+SN-Validate-Configuration({
+  catalog_item: "...",
+  checks: {
+    variables: { check_linked: true, check_types: true },
+    ui_policies: { check_conditions: true }
+  }
+})
+```
+
+### Script Execution
+```javascript
+// Execute background script (AUTOMATED via sys_trigger!)
+SN-Execute-Background-Script({
+  script: "gs.info('Hello World');",
+  description: "Test script",
+  execution_method: "trigger"  // Default, most reliable
+})
+
+// Create fix script (manual execution)
+SN-Create-Fix-Script({
+  script_name: "fix_data",
+  script_content: "...",
+  auto_delete: false
+})
+```
+
+---
+
+## 🌐 Multi-Instance Support
+
+All tools support the `instance` parameter:
+
+```javascript
+// Route to specific instance
+SN-Query-Table({
+  table_name: "incident",
+  query: "state=1",
+  instance: "dev"  // Routes to dev instance
+})
+
+// Default instance (from config)
+SN-Query-Table({
+  table_name: "incident",
+  query: "state=1"
+  // Uses default instance
+})
+
+// Switch instance
+SN-Set-Instance({ instance_name: "dev" })
+
+// Get current instance
+SN-Get-Current-Instance()
+```
+
+---
+
+## 📊 Tool Count Summary
+
+| Category | Tools | Notes |
+|----------|-------|-------|
+| **Core CRUD** | 6 | Generic table operations |
+| **Update Sets** | 6 | Automated set management |
+| **Workflows** | 4 | Complete workflow creation |
+| **Batch Ops** | 2 | Multi-record operations |
+| **ITSM Convenience** | 10 | **NEW!** Incident/Change/Problem |
+| **Specialized** | 16 | Users, schema, validation, scripts |
+| **TOTAL** | **44** | Up from 34 |
+
+---
+
+## 🎯 Common Workflows
+
+### Complete Incident Resolution
+```javascript
+// 1. List open incidents
+SN-List-Incidents({ state: "1", limit: 10 })
+
+// 2. Add work notes
+SN-Add-Work-Notes({ incident_number: "INC0012345", work_notes: "Investigating..." })
+
+// 3. Assign to engineer
+SN-Assign-Incident({ incident_number: "INC0012345", assigned_to: "John Smith" })
+
+// 4. Add customer comment
+SN-Add-Comment({ incident_number: "INC0012345", comment: "Working on fix" })
+
+// 5. Resolve
+SN-Resolve-Incident({
+  incident_number: "INC0012345",
+  resolution_notes: "Fixed",
+  resolution_code: "Solved (Permanently)"
+})
+
+// 6. Close
+SN-Close-Incident({
+  incident_number: "INC0012345",
+  close_notes: "Confirmed",
+  close_code: "Solved (Permanently)"
+})
+```
+
+### Change Management
+```javascript
+// 1. Assign for review
+SN-Assign-Change({ change_number: "CHG0012345", assigned_to: "Jane Doe" })
+
+// 2. Add review comment
+SN-Add-Change-Comment({ change_number: "CHG0012345", comment: "Review complete" })
+
+// 3. Approve
+SN-Approve-Change({ change_number: "CHG0012345", approval_comments: "Approved" })
+```
+
+### Update Set Workflow
+```javascript
+// 1. Create update set
+SN-Create-Record({
+  table_name: "sys_update_set",
+  data: { name: "My Feature", description: "..." }
+})
+
+// 2. Set as current (AUTOMATED!)
+SN-Set-Update-Set({ update_set_sys_id: "..." })
+
+// 3. Make changes (auto-captured)
+SN-Create-Record({ table_name: "sys_properties", data: {...} })
+
+// 4. Verify capture
+SN-Inspect-Update-Set({ update_set: "..." })
+
+// 5. Clone for backup
+SN-Clone-Update-Set({ source_update_set_id: "...", new_name: "Backup" })
+```
+
+---
+
+## ⚡ Performance Tips
+
+### Use Batch Operations
+```javascript
+// ❌ Slow: 10 individual calls
+for (let i = 0; i < 10; i++) {
+  SN-Update-Record({ table_name: "incident", sys_id: ids[i], data: { state: 6 } })
+}
+
+// ✅ Fast: 1 batch call
+SN-Batch-Update({
+  updates: ids.map(id => ({ table: "incident", sys_id: id, data: { state: 6 } }))
+})
+```
+
+### Limit Fields Returned
+```javascript
+// ❌ Returns all fields
+SN-Query-Table({ table_name: "incident", limit: 100 })
+
+// ✅ Returns only needed fields
+SN-Query-Table({
+  table_name: "incident",
+  fields: "number,state,priority,short_description",
+  limit: 100
+})
+```
+
+### Use Convenience Tools
+```javascript
+// ❌ 3 tool calls
+SN-Query-Table({ table_name: "incident", query: "number=INC0012345" })
+// Extract sys_id
+SN-Update-Record({ table_name: "incident", sys_id: "...", data: { comments: "..." } })
+
+// ✅ 1 tool call (66% faster)
+SN-Add-Comment({ incident_number: "INC0012345", comment: "..." })
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Record Not Found
+```
+Error: Incident INC0012345 not found
+→ Verify incident number is correct
+→ Check instance (dev vs prod)
+→ Ensure you have permissions
+```
+
+### User/Group Not Found
+```
+Error: User "John Smith" not found
+→ Verify name exactly matches ServiceNow
+→ Try using sys_id instead
+→ Use SN-List-SysUsers to search
+```
+
+### Permission Denied
+```
+Error: 403 Forbidden
+→ Check user roles (admin, itil, etc.)
+→ Verify table ACLs
+→ See docs/403_TROUBLESHOOTING.md
+```
+
+---
+
+## 📚 Documentation
+
+- **Complete Guide:** `/docs/CONVENIENCE_TOOLS.md`
+- **API Reference:** `/docs/API_REFERENCE.md`
+- **Setup Guide:** `/docs/SETUP_GUIDE.md`
+- **Quick Summary:** `/CONVENIENCE_TOOLS_SUMMARY.md`
+- **This Card:** `/QUICK_REFERENCE.md`
+
+---
+
+**Version:** 2.0
+**Total Tools:** 44
+**Last Updated:** 2025-10-06

package/docs/README.md

@@ -0,0 +1,75 @@
+# ServiceNow MCP Server - Documentation
+
+Complete documentation for the ServiceNow MCP Server v2.0.
+
+---
+
+## 📚 Documentation Index
+
+### Getting Started
+
+- **[API Reference](API_REFERENCE.md)** - Complete reference for all MCP tools
+- **[Setup Guide](SETUP_GUIDE.md)** - Installation and configuration
+- **[Multi-Instance Configuration](MULTI_INSTANCE_CONFIGURATION.md)** - Connect to multiple ServiceNow instances
+
+### Guides
+
+- **[Instance Switching Guide](INSTANCE_SWITCHING_GUIDE.md)** - How to route requests between instances
+- **[403 Troubleshooting](403_TROUBLESHOOTING.md)** - Fix permission errors
+
+### Research & Technical Deep-Dives
+
+The **[research/](research/)** folder contains technical research, breakthrough discoveries, and architectural analysis:
+
+- **Flow Designer feasibility analysis**
+- **Background script execution breakthroughs**
+- **Workflow vs Flow Designer comparison**
+- **Architecture evolution**
+- **Change logs and testing recommendations**
+
+---
+
+## Quick Links
+
+**Main Documentation:** `../README.md`
+**Source Code:** `../src/`
+**Configuration:** `../config/`
+
+---
+
+## Documentation Organization
+
+```
+docs/
+├── README.md                          # This file
+├── API_REFERENCE.md                   # Complete API documentation
+├── SETUP_GUIDE.md                     # Setup instructions
+├── MULTI_INSTANCE_CONFIGURATION.md    # Multi-instance setup
+├── INSTANCE_SWITCHING_GUIDE.md        # Instance routing guide
+├── 403_TROUBLESHOOTING.md             # Permission troubleshooting
+└── research/                          # Technical research & discoveries
+    ├── FLOW_DESIGNER_MCP_FEASIBILITY.md
+    ├── BACKGROUND_SCRIPT_EXECUTION.md
+    ├── UI_API_BREAKTHROUGH.md
+    ├── WORKFLOW_CREATION.md
+    └── ... (more research docs)
+```
+
+---
+
+## Contributing
+
+When adding new documentation:
+
+1. **Operational Docs** → Place in `docs/` root
+2. **Research/Analysis** → Place in `docs/research/`
+3. **Update this README** with links to new docs
+
+---
+
+## Support
+
+For issues or questions:
+- Check the troubleshooting guides
+- Review research docs for technical details
+- See main README.md for project overview