itglue-mcp 1.0.0 → 1.2.0

package/README.md

@@ -1,67 +1,38 @@
-# ITGlue MCP Server
+# ITGlue MCP Server for Claude Code
 
-Model Context Protocol (MCP) server for ITGlue - enables Claude Code to access ITGlue documentation through natural language queries.
+Access your entire ITGlue documentation library from Claude Code using natural language. Built for MSP engineers who are tired of switching between their terminal and ITGlue's web UI.
 
-## Overview
-
-MSPs (Managed Service Providers) use ITGlue as their central documentation platform, storing critical information about 50-200+ client organizations including passwords, server configurations, network diagrams, vendor contacts, and SOPs. This MCP server eliminates context switching between terminal/IDE and ITGlue's web interface.
-
-**Benefits:**
-- ✅ Natural language queries for ITGlue data
-- ✅ Reduced Mean Time to Resolution (MTTR) with instant credential access
-- ✅ AI-assisted documentation discovery
-- ✅ Audit trails for compliance (password access logging)
-- ✅ Smart caching and rate limiting
-- ✅ Multi-region support (US/EU/AU)
-
-## Features
-
-### Progressive Disclosure Architecture
-Following the claude-mem pattern for token efficiency:
-
-**Tier 1: Discovery** - Lightweight summaries
-- `itglue_search_organizations` - Find organizations by name/ID
-- `itglue_list_organization_types` - Get org types
-- `itglue_search_global` - Cross-entity search
-
-**Tier 2: Entity Navigation** - Scoped queries
-- `itglue_list_configurations` - List servers/workstations/devices
-- `itglue_list_passwords` - List passwords (metadata only, no values)
-- `itglue_list_flexible_assets` - List custom documentation
-- `itglue_list_documents` - List documents
+```
+You:   "Find the firewall password for Acme Corp"
+Claude: Searches organizations → finds Acme → lists passwords → retrieves credential
+        (audit logged, 15 seconds total)
+```
 
-**Tier 3: Detail Retrieval** - Full data
-- `itglue_get_password` - Retrieve password values (audit logged)
-- `itglue_get_flexible_asset` - Get full flexible asset details
+## What This Does
 
-### Security Features
-- 🔒 All password access is audit logged to stderr
-- 🔒 No sensitive data in logs (automatic sanitization)
-- 🔒 API keys never exposed in responses
-- 🔒 Audit trail for compliance requirements
+This package connects [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to your ITGlue account. Once installed, you can ask Claude to look up organizations, pull server configs, retrieve passwords, run compliance audits, and generate account review reports - all without leaving your terminal.
 
-### Performance Features
-- ⚡ Smart caching (5min for orgs, 1min for configs/docs)
-- ⚡ Rate limiting (8 req/sec with 20% safety margin)
-- ⚡ Automatic retry with exponential backoff
-- ⚡ Multi-region support (US/EU/AU)
+**Who it's for:** MSP engineers, IT administrators, and service desk teams who use ITGlue as their documentation platform.
 
-## Installation
+**What you get:**
+- 19 tools for querying ITGlue data through natural language
+- 5 pre-built Skills that automate common MSP workflows
+- Standalone HTML report generation for QBRs and account reviews
+- Security audit logging on every password access
+- Smart caching and rate limiting so you don't hit ITGlue's API limits
 
-### Prerequisites
-- Node.js 18 or higher
-- ITGlue API key (from Settings → API Keys in ITGlue)
-- [Claude Code](https://claude.ai/claude-code) installed
+## Setup (3 Steps)
 
-### Quick Start (npm)
+### 1. Get Your ITGlue API Key
 
-```bash
-npm install -g itglue-mcp
-```
+1. Log into ITGlue
+2. Go to **Account > Settings > API Keys**
+3. Click **Generate New API Key**
+4. Copy the key (it starts with `ITG.`)
 
-### Configuration
+### 2. Add to Claude Code
 
-Add the MCP server to your Claude Code configuration (`~/.claude/settings.json`):
+Open your Claude Code configuration file (`~/.claude.json`) and add the MCP server:
 
 ```json
 {
@@ -70,7 +41,7 @@ Add the MCP server to your Claude Code configuration (`~/.claude/settings.json`)
       "command": "npx",
       "args": ["-y", "itglue-mcp"],
       "env": {
-        "ITGLUE_API_KEY": "your-api-key-here",
+        "ITGLUE_API_KEY": "ITG.your-key-here",
         "ITGLUE_REGION": "US"
       }
     }
@@ -78,108 +49,147 @@ Add the MCP server to your Claude Code configuration (`~/.claude/settings.json`)
 }
 ```
 
-**Get your API key:**
-1. Log into ITGlue
-2. Go to Settings → API Keys
-3. Create a new API key
-4. Copy and add to your configuration
+Set `ITGLUE_REGION` to `US`, `EU`, or `AU` depending on your ITGlue instance.
 
-**Region options:** `US`, `EU`, or `AU`
+### 3. Restart Claude Code
 
-### Development Installation
+Restart Claude Code (or start a new session). You should now have access to all ITGlue tools. Test it:
 
-For local development or contributing:
+```
+You: "Check ITGlue health"
+```
 
-```bash
-# Clone the repository
-git clone https://github.com/suleman-viyu/itglue-mcp.git
-cd itglue-mcp
+If you see a healthy status, you're all set.
 
-# Install dependencies
-npm install
+## Installing the Skills
 
-# Build the project
-npm run build
+The package ships with **5 Skills** - guided workflows that Claude follows to complete common MSP tasks. Skills are optional but dramatically speed up repetitive work.
 
-# Link globally for development
-npm link
+Install them globally (available in every Claude Code session):
 
-# Configure Claude Code to use local build
-# Update ~/.claude/settings.json:
-{
-  "mcpServers": {
-    "itglue": {
-      "command": "node",
-      "args": ["/absolute/path/to/itglue-mcp/dist/index.js"],
-      "env": {
-        "ITGLUE_API_KEY": "your-api-key-here",
-        "ITGLUE_REGION": "US"
-      }
-    }
-  }
-}
+```bash
+npx itglue-mcp --install-skills
 ```
 
-### Testing Installation
+Or install into a specific project:
 
 ```bash
-# Test that the server is accessible
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx itglue-mcp
-
-# You should see a list of 14 available tools
+npx itglue-mcp --install-skills /path/to/your/project
 ```
 
-## Usage Examples
+This works on macOS, Linux, and Windows.
 
-### With Claude Code
+### Available Skills
 
-Once configured, use natural language to query ITGlue:
+| Skill | What It Does | Time Savings |
+|-------|-------------|-------------|
+| **Account Review** | Generates a standalone HTML report covering asset inventory, credential hygiene, compliance posture, and action items. Aligned with ITIL v4 and NIST standards. Output is ready for ConnectWise tickets or QBR presentations. | 4-8 hrs → 5-10 min |
+| **Find Password** | Finds and retrieves a specific credential using natural language. Handles ambiguous names, multiple matches, and organization lookup automatically. | 5-10 min → <1 min |
+| **Incident Response** | Pulls everything you need during an outage: affected asset details, network interfaces, related systems, credentials, emergency contacts, and relevant docs - all in parallel. | 5-15 min → <2 min |
+| **Compliance Audit** | Runs password rotation checks, asset documentation audits, staleness detection, and data quality scoring. Produces a prioritized findings report. | 4-8 hrs → 5-10 min |
+| **Client Onboard** | Walks through a standardized onboarding checklist for new clients, verifying what's documented and identifying gaps in contacts, locations, credentials, infrastructure, and SOPs. | 8-16 hrs → 2-3 hrs |
+
+### Using a Skill
+
+Just describe what you need and Claude will activate the right skill:
 
 ```
-User: "Show me all organizations in ITGlue"
-→ Uses itglue_search_organizations
+You: "Run an account review for Contoso and generate an HTML report"
+     → Activates the Account Review skill
 
-User: "List servers for Acme Corp"
-→ Uses itglue_search_organizations (name="Acme Corp")
-→ Then itglue_list_configurations (organization_id=...)
+You: "Get me the WiFi password for Acme Corp"
+     → Activates the Find Password skill
 
-User: "Find the admin password for Contoso's firewall"
-→ Uses itglue_search_organizations (name="Contoso")
-→ Then itglue_list_passwords (organization_id=...)
-→ Then itglue_get_password (password_id=...) [AUDIT LOGGED]
+You: "Server down at Contoso - pull everything"
+     → Activates the Incident Response skill
 ```
 
-### Direct MCP Protocol Testing
+## Usage Examples
 
-```bash
-# Search for an organization
-echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"itglue_search_organizations","arguments":{"name":"Acme"}}}' | node dist/index.js
+Once the MCP server is connected, just talk to Claude naturally:
+
+### Look Up Client Information
+```
+"Show me all organizations in ITGlue"
+"List the servers for Acme Corp"
+"What contacts do we have for Contoso?"
+"Show me Acme's office locations"
+```
+
+### Retrieve Credentials
+```
+"Find the domain admin password for Acme Corp"
+"Get the firewall credentials for Contoso"
+"What's the WiFi password at the Dallas office?"
+```
+All password retrievals are audit logged automatically.
 
-# List configurations for an organization
-echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"itglue_list_configurations","arguments":{"organization_id":"12345"}}}' | node dist/index.js
+### Run Reports and Audits
+```
+"Generate a full report for Acme Corp"
+"Run a compliance check on Contoso's passwords and configurations"
+"Find stale documentation for Acme Corp"
+"Check data quality for organization 12345"
 ```
 
-## Configuration
+### Incident Response
+```
+"Server is down at Acme Corp - get me everything"
+"Network outage at Contoso, pull all firewall info and contacts"
+```
+
+## What's Included (19 Tools)
+
+### Finding Things
+| Tool | What It Does |
+|------|-------------|
+| `itglue_search_organizations` | Search for organizations by name |
+| `itglue_list_organization_types` | List available organization types |
+| `itglue_search_global` | Search across all ITGlue entities at once |
+
+### Browsing Client Data
+| Tool | What It Does |
+|------|-------------|
+| `itglue_list_configurations` | List servers, workstations, network devices, printers |
+| `itglue_list_passwords` | List stored credentials (names and categories only, no values) |
+| `itglue_list_flexible_assets` | List custom documentation types (SSL certs, licenses, etc.) |
+| `itglue_list_documents` | List uploaded documents |
+| `itglue_list_contacts` | List contacts with titles, emails, and phone numbers |
+| `itglue_list_locations` | List physical office locations and addresses |
+| `itglue_list_attachments` | List file attachments on any resource |
+| `itglue_list_configuration_interfaces` | List network interfaces with IPs and MACs |
+| `itglue_get_related_items` | Show relationships between assets |
+
+### Retrieving Details
+| Tool | What It Does |
+|------|-------------|
+| `itglue_get_password` | Retrieve an actual password value (audit logged) |
+| `itglue_get_flexible_asset` | Get full details of a flexible asset |
+
+### Auditing and Reporting
+| Tool | What It Does |
+|------|-------------|
+| `itglue_compliance_check` | Audit passwords, configs, docs, and warranties for compliance issues |
+| `itglue_detect_staleness` | Find passwords, configs, and docs that haven't been updated |
+| `itglue_validate_data` | Score data quality (completeness, duplicates, relationships) |
+| `itglue_generate_report` | Generate summary, full, security, or asset-inventory reports |
+| `itglue_health_check` | Test API connectivity, authentication, and server health |
+
+## Configuration Options
 
 ### Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `ITGLUE_API_KEY` | ✅ Yes | - | API key from ITGlue Settings → API Keys |
-| `ITGLUE_REGION` | No | `US` | API region: `US`, `EU`, or `AU` |
-| `ITGLUE_CACHE_TTL` | No | `300` | Cache TTL in seconds (5 minutes) |
-| `ITGLUE_RATE_LIMIT` | No | `8` | Max requests per second |
-| `ITGLUE_DEBUG` | No | `false` | Enable debug logging to stderr |
-
-### Regional Endpoints
-
-- **US**: `https://api.itglue.com`
-- **EU**: `https://api.eu.itglue.com`
-- **AU**: `https://api.au.itglue.com`
+| `ITGLUE_API_KEY` | Yes | - | Your ITGlue API key (starts with `ITG.`) |
+| `ITGLUE_REGION` | No | `US` | `US`, `EU`, or `AU` |
+| `ITGLUE_CACHE_TTL` | No | `300` | How long to cache results (seconds) |
+| `ITGLUE_RATE_LIMIT` | No | `8` | Max API requests per second |
+| `ITGLUE_DEBUG` | No | `false` | Enable verbose debug logging |
 
-### On-Premise Installations
+### On-Premise ITGlue
 
-For on-premise ITGlue installations, add the `ITGLUE_BASE_URL` environment variable:
+If you run ITGlue on-premise, add your server URL:
 
 ```json
 {
@@ -188,7 +198,7 @@ For on-premise ITGlue installations, add the `ITGLUE_BASE_URL` environment varia
       "command": "npx",
       "args": ["-y", "itglue-mcp"],
       "env": {
-        "ITGLUE_API_KEY": "your-on-prem-api-key",
+        "ITGLUE_API_KEY": "your-on-prem-key",
         "ITGLUE_BASE_URL": "https://your-itglue-server.com/api"
       }
     }
@@ -196,65 +206,12 @@ For on-premise ITGlue installations, add the `ITGLUE_BASE_URL` environment varia
 }
 ```
 
-**Note:** On-premise installations use standard JSON headers instead of JSON:API headers. The server automatically detects and adapts based on the `ITGLUE_BASE_URL` setting.
-
-## Development
-
-### Project Structure
-
-```
-src/
-├── index.ts                  # MCP server entry point
-├── lib/
-│   ├── api-client.ts         # ITGlue API client with rate limiting + caching
-│   ├── rate-limiter.ts       # Queue-based rate limiting (8 req/sec)
-│   ├── cache.ts              # LRU cache with TTL
-│   ├── error-handler.ts      # Error transformation
-│   └── audit-logger.ts       # Security audit logging
-├── tools/
-│   ├── organizations.ts      # Organization discovery
-│   ├── search.ts             # Global search
-│   ├── configurations.ts     # Configuration listing
-│   ├── passwords.ts          # Password management (audit logged)
-│   ├── flexible-assets.ts    # Flexible asset management
-│   └── documents.ts          # Document listing
-└── types/
-    ├── itglue.ts             # ITGlue API types
-    └── mcp.ts                # MCP tool types
-```
-
-### Available Scripts
-
-```bash
-npm run build          # Build TypeScript to dist/
-npm run dev            # Watch mode for development
-npm run test           # Run tests
-npm run test:watch     # Watch mode for tests
-npm run lint           # Lint TypeScript files
-npm run clean          # Remove dist/ directory
-```
-
-### Testing
-
-Run the test suite:
-```bash
-npm test
-```
-
-Test rate limiting:
-```bash
-# Make 20 rapid requests - should throttle to ~2.5 seconds
-for i in {1..20}; do
-  echo '{"jsonrpc":"2.0","id":'$i',"method":"tools/call","params":{"name":"itglue_search_organizations","arguments":{"limit":1}}}' | node dist/index.js &
-done
-wait
-```
+## Security
 
-## Security Considerations
+### Password Access Logging
 
-### Audit Logging
+Every password retrieval is logged to stderr with a timestamp, operation type, and resource IDs:
 
-All password access is logged to stderr with HIGH severity:
 ```json
 {
   "timestamp": "2026-02-10T21:30:00.000Z",
@@ -266,117 +223,94 @@ All password access is logged to stderr with HIGH severity:
 }
 ```
 
-### Sensitive Data Handling
+### Data Protection
+- API keys are never included in responses or tool output
+- Password values are never cached (all other data caches for 1-5 minutes)
+- Sensitive fields are automatically redacted from debug logs
+- All connections use HTTPS
 
-- ✅ API keys are never logged or exposed in responses
-- ✅ Password values are redacted from logs
-- ✅ Sensitive fields (api_key, secret, token) are automatically sanitized
-- ✅ Passwords are never cached
+### Recommendations
+- Use an ITGlue API key with the minimum permissions your workflows need
+- Review audit logs periodically to monitor password access
+- Store your API key in environment variables, not in committed files
 
-### Best Practices
-
-1. **Store API keys securely** - Use environment variables, never commit to git
-2. **Review audit logs** - Monitor password access for unauthorized use
-3. **Use least privilege** - ITGlue API keys should have minimal necessary permissions
-4. **Rotate keys regularly** - Change API keys periodically
-
-## Troubleshooting
-
-### "ITGLUE_API_KEY environment variable is required"
-
-Set your API key:
-```bash
-export ITGLUE_API_KEY="your-api-key"
-```
-
-Get your API key from: ITGlue → Settings → API Keys
+## Performance
 
-### "Authentication failed. Please check your ITGLUE_API_KEY"
+The server handles rate limiting and caching automatically so you don't have to think about it:
 
-Your API key is invalid or expired. Generate a new key from ITGlue Settings.
+- **Rate limit**: 8 requests/second (ITGlue allows 10; we stay under with a safety margin)
+- **Retry**: Failed requests automatically retry with exponential backoff (5s, 10s, 20s)
+- **Caching**: Organizations cache for 5 minutes, configurations/documents for 1 minute, passwords are never cached
 
-### "Network error: Unable to connect to ITGlue API"
+## Troubleshooting
 
-Check:
-1. Internet connection is working
-2. `ITGLUE_REGION` matches your ITGlue account (US/EU/AU)
-3. No firewall blocking access to api.itglue.com
+| Problem | Fix |
+|---------|-----|
+| `ITGLUE_API_KEY environment variable is required` | Add your API key to the `env` block in your Claude Code config |
+| `Authentication failed` | Your API key is invalid or expired. Generate a new one in ITGlue > Settings > API Keys |
+| `Network error: Unable to connect` | Check that `ITGLUE_REGION` matches your account (US/EU/AU) and you have internet access |
+| Tools not showing up in Claude Code | Restart Claude Code after updating your config. Run `"Check ITGlue health"` to verify |
+| Rate limit errors | The server retries automatically. If persistent, lower `ITGLUE_RATE_LIMIT` to `5` |
 
-### Rate Limiting
+For debug output, set `ITGLUE_DEBUG` to `true` in your env config. Logs go to stderr.
 
-If you see "Rate limit exceeded" errors:
-1. The server automatically retries with exponential backoff
-2. Reduce `ITGLUE_RATE_LIMIT` environment variable (default: 8)
-3. Enable debug logging: `ITGLUE_DEBUG=true`
+## Development
 
-### Enable Debug Logging
+### Building from Source
 
 ```bash
-export ITGLUE_DEBUG=true
-node dist/index.js
+npm install itglue-mcp
+cd node_modules/itglue-mcp
+npm install
+npm run build
 ```
 
-Debug messages will appear in stderr.
-
-## Performance
-
-### Caching Strategy
+To use your local build instead of the npm package:
 
-| Resource Type | TTL | Reason |
-|---------------|-----|--------|
-| Organizations | 5 minutes | Rarely change |
-| Org Types | 10 minutes | Static data |
-| Configurations | 1 minute | Change occasionally |
-| Documents | 1 minute | Change occasionally |
-| Passwords | Never cached | Security requirement |
-| Search Results | Never cached | Dynamic queries |
-
-### Rate Limiting
-
-- **ITGlue Limit**: 3000 requests / 5 minutes = 10 req/sec
-- **Our Limit**: 8 req/sec (20% safety margin)
-- **Algorithm**: Sliding window with queue-based throttling
-
-### Token Efficiency
-
-Progressive disclosure reduces token usage by 90%+:
-- **Tier 1**: Get lightweight summaries (100-200 tokens)
-- **Tier 2**: Scoped queries (200-500 tokens)
-- **Tier 3**: Only fetch full details when needed (500-2000 tokens)
-
-## Contributing
-
-### Adding New Tools
-
-1. Create tool file in `src/tools/`
-2. Define Zod schema for parameters
-3. Implement handler function
-4. Add to `src/index.ts` tool list and routing
-
-See `src/tools/organizations.ts` for reference implementation.
+```json
+{
+  "mcpServers": {
+    "itglue": {
+      "command": "node",
+      "args": ["/absolute/path/to/itglue-mcp/dist/index.js"],
+      "env": {
+        "ITGLUE_API_KEY": "your-api-key",
+        "ITGLUE_REGION": "US"
+      }
+    }
+  }
+}
+```
 
-### Running Tests
+### Scripts
 
 ```bash
-npm test
+npm run build        # Compile TypeScript
+npm run dev          # Watch mode
+npm test             # Run test suite
+npm run lint         # Lint source files
 ```
 
-## License
-
-MIT License - See LICENSE file for details
+### Contributing
 
-## Support
+1. Create a tool file in `src/tools/`
+2. Define a Zod schema for the parameters
+3. Implement the handler function
+4. Register it in `src/index.ts`
 
-For issues, questions, or feature requests:
-- File an issue on GitHub
-- Contact: Viyu Networks
+See `src/tools/organizations.ts` for a reference implementation.
 
-## Resources
+## Links
 
 - [ITGlue API Documentation](https://api.itglue.com/developer/)
-- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
-- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- [npm Package](https://www.npmjs.com/package/itglue-mcp)
+
+## License
+
+MIT - see [LICENSE](LICENSE)
 
 ---
 
-Built with ❤️ by Suleman @ Viyu
+Built for Productivity by sully