itglue-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viyu Networks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,382 @@
+# ITGlue MCP Server
+
+Model Context Protocol (MCP) server for ITGlue - enables Claude Code to access ITGlue documentation through natural language queries.
+
+## 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
+
+**Tier 3: Detail Retrieval** - Full data
+- `itglue_get_password` - Retrieve password values (audit logged)
+- `itglue_get_flexible_asset` - Get full flexible asset details
+
+### 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
+
+### 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)
+
+## Installation
+
+### Prerequisites
+- Node.js 18 or higher
+- ITGlue API key (from Settings → API Keys in ITGlue)
+- [Claude Code](https://claude.ai/claude-code) installed
+
+### Quick Start (npm)
+
+```bash
+npm install -g itglue-mcp
+```
+
+### Configuration
+
+Add the MCP server to your Claude Code configuration (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "itglue": {
+      "command": "npx",
+      "args": ["-y", "itglue-mcp"],
+      "env": {
+        "ITGLUE_API_KEY": "your-api-key-here",
+        "ITGLUE_REGION": "US"
+      }
+    }
+  }
+}
+```
+
+**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
+
+**Region options:** `US`, `EU`, or `AU`
+
+### Development Installation
+
+For local development or contributing:
+
+```bash
+# Clone the repository
+git clone https://github.com/suleman-viyu/itglue-mcp.git
+cd itglue-mcp
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link globally for development
+npm link
+
+# 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"
+      }
+    }
+  }
+}
+```
+
+### Testing Installation
+
+```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
+```
+
+## Usage Examples
+
+### With Claude Code
+
+Once configured, use natural language to query ITGlue:
+
+```
+User: "Show me all organizations in ITGlue"
+→ Uses itglue_search_organizations
+
+User: "List servers for Acme Corp"
+→ Uses itglue_search_organizations (name="Acme Corp")
+→ Then itglue_list_configurations (organization_id=...)
+
+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]
+```
+
+### Direct MCP Protocol Testing
+
+```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
+
+# 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
+```
+
+## Configuration
+
+### 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`
+
+### On-Premise Installations
+
+For on-premise ITGlue installations, add the `ITGLUE_BASE_URL` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "itglue": {
+      "command": "npx",
+      "args": ["-y", "itglue-mcp"],
+      "env": {
+        "ITGLUE_API_KEY": "your-on-prem-api-key",
+        "ITGLUE_BASE_URL": "https://your-itglue-server.com/api"
+      }
+    }
+  }
+}
+```
+
+**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 Considerations
+
+### Audit Logging
+
+All password access is logged to stderr with HIGH severity:
+```json
+{
+  "timestamp": "2026-02-10T21:30:00.000Z",
+  "severity": "HIGH",
+  "operation": "PASSWORD_ACCESS",
+  "resourceType": "password",
+  "resourceId": "12345",
+  "organizationId": "67890"
+}
+```
+
+### Sensitive Data Handling
+
+- ✅ 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
+
+### 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
+
+### "Authentication failed. Please check your ITGLUE_API_KEY"
+
+Your API key is invalid or expired. Generate a new key from ITGlue Settings.
+
+### "Network error: Unable to connect to ITGlue API"
+
+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
+
+### Rate Limiting
+
+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`
+
+### Enable Debug Logging
+
+```bash
+export ITGLUE_DEBUG=true
+node dist/index.js
+```
+
+Debug messages will appear in stderr.
+
+## Performance
+
+### Caching Strategy
+
+| 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.
+
+### Running Tests
+
+```bash
+npm test
+```
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Support
+
+For issues, questions, or feature requests:
+- File an issue on GitHub
+- Contact: Viyu Networks
+
+## Resources
+
+- [ITGlue API Documentation](https://api.itglue.com/developer/)
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+
+---
+
+Built with ❤️ by Suleman @ Viyu

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * ITGlue MCP Server
+ * Model Context Protocol server for ITGlue API access
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}