{"_id":"@cisc0/solarwinds-observability-mcp","_rev":"2-a3c1feb74e419ca064ee270b3d5c4303","name":"@cisc0/solarwinds-observability-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@cisc0/solarwinds-observability-mcp","version":"0.1.0","keywords":["mcp","modelcontextprotocol","solarwinds","observability","monitoring","apm","llm","ai"],"author":{"name":"Alex Tsysov"},"license":"MIT","_id":"@cisc0/solarwinds-observability-mcp@0.1.0","maintainers":[{"name":"cisc0","email":"tsysov@gmail.com"}],"homepage":"https://github.com/al-cisc0/solarwinds-observability-mcp#readme","bugs":{"url":"https://github.com/al-cisc0/solarwinds-observability-mcp/issues"},"bin":{"solarwinds-mcp":"dist/index.js"},"dist":{"shasum":"9453c0671b22059c0649513e919321b2552cdcf0","tarball":"https://registry.npmjs.org/@cisc0/solarwinds-observability-mcp/-/solarwinds-observability-mcp-0.1.0.tgz","fileCount":17,"integrity":"sha512-2kqczKIdJGVDUoUX04xVuTPbGkPA0Z4+IUb9WgdO8IrzClyLTKb9ONgzDvnGhDnC1bXxxYO2OB9or3zA0m9+Vg==","signatures":[{"sig":"MEYCIQDW0fExFOO8KntBPBBJtoVaXJb+0g232pyb+xr45ZOOIwIhAKxyuUUKOxnmPIn/2UIEeEcTBxJXvlpNyL2Be/q/1n4L","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":78412},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"b9ce0682fc81664d82b65405bc7aa59e98d18f7c","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"cisc0","email":"tsysov@gmail.com"},"repository":{"url":"git+https://github.com/al-cisc0/solarwinds-observability-mcp.git","type":"git"},"_npmVersion":"11.5.2","description":"MCP server for SolarWinds Observability platform integration","directories":{},"_nodeVersion":"20.19.4","dependencies":{"zod":"^3.24.1","axios":"^1.7.9","dotenv":"^16.4.7","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.5"},"_npmOperationalInternal":{"tmp":"tmp/solarwinds-observability-mcp_0.1.0_1760844979467_0.3784815222186162","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cisc0/solarwinds-observability-mcp","version":"0.1.1","description":"MCP server for SolarWinds Observability platform integration","main":"dist/index.js","type":"module","bin":{"solarwinds-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","prepublishOnly":"npm run build"},"keywords":["mcp","modelcontextprotocol","solarwinds","observability","monitoring","apm","llm","ai"],"author":{"name":"Alex Tsysov"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/al-cisc0/solarwinds-observability-mcp.git"},"bugs":{"url":"https://github.com/al-cisc0/solarwinds-observability-mcp/issues"},"homepage":"https://github.com/al-cisc0/solarwinds-observability-mcp#readme","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","axios":"^1.7.9","dotenv":"^16.4.7","zod":"^3.24.1"},"devDependencies":{"@types/node":"^22.10.5","tsx":"^4.19.2","typescript":"^5.7.2"},"_id":"@cisc0/solarwinds-observability-mcp@0.1.1","gitHead":"066054534750a23bc3698159a32544c39f6eb345","types":"./dist/index.d.ts","_nodeVersion":"20.19.4","_npmVersion":"11.5.2","dist":{"integrity":"sha512-ogyemkRZ0adOGyH0ywasHN4Wpcs1P4KKpp8RNT7TJ57eYbv7WqTUaUcY1KRg2j7G9TNiUfXzq21lLjdfIqql/Q==","shasum":"3c42ff563f69473f59ca099e1c3bec5dbb2c872e","tarball":"https://registry.npmjs.org/@cisc0/solarwinds-observability-mcp/-/solarwinds-observability-mcp-0.1.1.tgz","fileCount":17,"unpackedSize":78411,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICDf0NISsFeGoglLJdK76O9aIRwqfm+Z7BLY1+mkgnLhAiEA7SX94QiXBxm3gIYj4HgVcw8iwFY4hfpIqz2TfZJMQZ0="}]},"_npmUser":{"name":"cisc0","email":"tsysov@gmail.com"},"directories":{},"maintainers":[{"name":"cisc0","email":"tsysov@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/solarwinds-observability-mcp_0.1.1_1760845149989_0.31597730488421316"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-19T03:36:19.364Z","modified":"2025-10-19T03:39:10.420Z","0.1.0":"2025-10-19T03:36:19.661Z","0.1.1":"2025-10-19T03:39:10.211Z"},"bugs":{"url":"https://github.com/al-cisc0/solarwinds-observability-mcp/issues"},"author":{"name":"Alex Tsysov"},"license":"MIT","homepage":"https://github.com/al-cisc0/solarwinds-observability-mcp#readme","keywords":["mcp","modelcontextprotocol","solarwinds","observability","monitoring","apm","llm","ai"],"repository":{"type":"git","url":"git+https://github.com/al-cisc0/solarwinds-observability-mcp.git"},"description":"MCP server for SolarWinds Observability platform integration","maintainers":[{"name":"cisc0","email":"tsysov@gmail.com"}],"readme":"# SolarWinds Observability MCP Server\n\nAn MCP (Model Context Protocol) server implementation for integrating with SolarWinds Observability platform. This server provides tools for monitoring entities, managing alerts, searching logs, and analyzing distributed traces.\n\n## Features\n\n- **Entity Management**: List and retrieve details of monitored entities (hosts, applications, services, databases, networks)\n- **Metrics Collection**: Fetch performance metrics for specific entities with time range filtering\n- **Alert Management**: Create, update, delete, and list alert definitions\n- **Distributed Tracing**: Access and analyze trace data across services\n- **Log Search**: Search and retrieve logs with powerful query capabilities\n\n## Installation\n\n### Global Installation (Recommended)\n\nInstall the MCP server globally using npm:\n\n```bash\n# Install globally from npm\nnpm install -g @cisc0/solarwinds-observability-mcp\n\n# Or install from source\ngit clone https://github.com/al-cisc0/solarwinds-observability-mcp.git\ncd solarwinds-observability-mcp\nnpm install\nnpm run build\nnpm link\n```\n\n### Local Installation\n\nFor development or local use:\n\n```bash\ngit clone https://github.com/al-cisc0/solarwinds-observability-mcp.git\ncd solarwinds-observability-mcp\nnpm install\nnpm run build\n```\n\n## Configuration\n\nEdit your Claude configuration file at `~/.claude.json` and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"solarwinds-observability\": {\n      \"command\": \"solarwinds-mcp\",\n      \"env\": {\n        \"SOLARWINDS_API_TOKEN\": \"your-api-token-here\",\n        \"SOLARWINDS_ORG_ID\": \"your-org-id-here\",\n        \"SOLARWINDS_API_URL\": \"https://api.na-01.cloud.solarwinds.com\"\n      }\n    }\n  }\n}\n```\n\n**Important:**\n- Replace `your-api-token-here` with your actual SolarWinds API token\n- Adjust the API URL to match your SolarWinds region (e.g., `na-01`, `eu-01`)\n- Restart Claude Code after updating the configuration\n\n**Getting your API credentials:**\n1. Log in to your SolarWinds Observability portal\n2. Navigate to **Settings** → **API Tokens**\n3. Click **Create API Token**\n4. Copy the token immediately (you won't see it again!)\n\n## Building\n\n```bash\nnpm run build\n```\n\n## Running the Server\n\n### Development Mode\n```bash\nnpm run dev\n```\n\n### Production Mode\n```bash\nnpm run build\nnpm start\n```\n\n## Available Tools\n\n### Entity Operations\n\n- **get_entities**: List all monitored entities with optional type filtering\n- **get_entity**: Get detailed information about a specific entity\n\n### Metrics\n\n- **get_metrics**: Retrieve metrics for an entity with optional metric name and time range filtering\n\n### Alert Management\n\n- **get_alerts**: List alert definitions with optional active status filtering\n- **create_alert**: Create a new alert definition\n- **update_alert**: Update an existing alert\n- **delete_alert**: Remove an alert definition\n\n### Tracing\n\n- **get_traces**: List distributed traces with optional service and time filtering\n- **get_trace**: Get detailed span information for a specific trace\n\n### Logs\n\n- **search_logs**: Search logs using query expressions, source groups, time filtering and limit options\n  - Supports fulltext search via the `query` parameter\n  - Supports filtering by source groups via the `groups` parameter\n  - Supports time filtering via `startTime` and/or `endTime` parameters (ISO 8601 format)\n  - Can combine query, groups, and time filters for refined searches\n  - Automatically searches both live logs and archived logs based on time range\n\n- **list_log_archives**: List available log archive files for a specific time range\n  - Returns hourly compressed JSON archive files stored on Amazon S3\n  - Each archive includes download URL, file size, and archived timestamp\n  - Archives are retained for up to one year\n  - Use for downloading raw log data or bulk log analysis\n\n- **download_log_archive**: Download and decompress a log archive file\n  - Takes a download URL (from `list_log_archives`) and optional limit parameter\n  - Downloads the gzip-compressed archive from S3\n  - Automatically decompresses and parses the newline-delimited JSON format\n  - Returns parsed log entries with full details\n  - Supports limiting the number of entries processed (default: all entries)\n  - **⚠️ Important**: Download URLs expire after 24 hours - use them promptly after getting them from `list_log_archives`\n  - Useful for offline analysis or bulk log processing\n\n## Log Search, Archives, and Source Groups\n\nSolarWinds Observability supports comprehensive log management including real-time search, archive access, and source group filtering.\n\n### Log Archives\n\nSolarWinds Observability automatically archives logs every hour to compressed JSON files stored on Amazon S3. Archives are retained for up to one year and can be accessed in multiple ways:\n- **Searched automatically**: The `search_logs` tool searches both live and archived logs seamlessly\n- **Listed**: The `list_log_archives` tool provides pre-signed S3 URLs for raw archive files\n- **Downloaded and processed**: The `download_log_archive` tool downloads, decompresses, and parses archive files automatically\n\n### Source Groups\n\n**Source Groups** are logical collections of log sources that help segment large amounts of disparate data.\n\n### Query Syntax\n\nThe log search uses Apache Lucene-based query syntax with the following features:\n\n- **Fulltext search**: Search for keywords across all log messages\n- **Field filters**: Filter by specific fields (e.g., `level:error`, `hostname:prod-server`)\n- **Source groups**: Filter by predefined source groups using `group:groupname`\n- **Query grouping**: Use parentheses to group terms (e.g., `(error OR warning) AND group:production`)\n- **Boolean operators**: AND, OR, NOT for combining search terms\n\n### Combining Filters\n\nThe MCP server automatically combines your search parameters:\n\n**Groups:**\n- Multiple groups are combined with OR: `(group:staging OR group:production)`\n- Query and groups are combined with AND: `(group:staging OR group:production) AND error`\n\n**Time Filtering:**\n- `startTime` alone: Returns logs from that time onwards\n- `endTime` alone: Returns logs up to that time\n- Both together: Returns logs within that specific time range\n- Time format: ISO 8601 (e.g., `\"2025-10-18T22:30:00Z\"`)\n- Time filters work independently of query and groups filters\n\n## Example Usage\n\nOnce connected through an MCP client, you can use the tools like:\n\n```\n# List all hosts\nget_entities(type: \"host\")\n\n# Get metrics for a specific entity\nget_metrics(entityId: \"entity-123\", metricNames: [\"cpu.usage\", \"memory.usage\"])\n\n# Search logs with fulltext query\nsearch_logs(query: \"error level:error service:api\", limit: 50)\n\n# Search logs by source groups\nsearch_logs(groups: [\"production\", \"api-servers\"], limit: 50)\n\n# Search logs with both query and groups\nsearch_logs(\n  query: \"error\",\n  groups: [\"staging\"],\n  limit: 100\n)\n\n# Search logs from a specific time onwards\nsearch_logs(\n  query: \"error\",\n  startTime: \"2025-10-18T22:00:00Z\",\n  limit: 50\n)\n\n# Search logs up to a specific time\nsearch_logs(\n  groups: [\"production\"],\n  endTime: \"2025-10-18T23:00:00Z\",\n  limit: 50\n)\n\n# Search logs within a specific time range\nsearch_logs(\n  query: \"exception\",\n  startTime: \"2025-10-18T22:30:00Z\",\n  endTime: \"2025-10-18T23:00:00Z\",\n  limit: 100\n)\n\n# Combine all filters: query, groups, and time range\nsearch_logs(\n  query: \"error OR warning\",\n  groups: [\"staging\", \"production\"],\n  startTime: \"2025-10-18T22:00:00Z\",\n  endTime: \"2025-10-18T23:00:00Z\",\n  limit: 200\n)\n\n# List log archives for a time range\nlist_log_archives(\n  startTime: \"2025-10-18T14:00:00Z\",\n  endTime: \"2025-10-18T16:00:00Z\"\n)\n\n# Download and decompress a specific archive\ndownload_log_archive(\n  downloadUrl: \"https://ssp-prod-dc-01-log-archives.s3.us-east-2.amazonaws.com/...\",\n  limit: 1000  # Optional: limit number of entries to process\n)\n\n# Search archived logs (searches automatically - same as live logs)\nsearch_logs(\n  query: \"error\",\n  startTime: \"2025-10-17T00:00:00Z\",\n  endTime: \"2025-10-17T23:59:59Z\",\n  limit: 100\n)\n\n# Create an alert\ncreate_alert(\n  name: \"High CPU Usage\",\n  condition: \"cpu.usage > 90\",\n  severity: \"critical\",\n  enabled: true\n)\n```\n\n## API Types\n\nThe server uses TypeScript interfaces for strong typing:\n\n- `Entity`: Represents monitored infrastructure components\n- `MetricData`: Time-series metric data points\n- `AlertDefinition`: Alert configuration and rules\n- `Trace`: Distributed tracing spans\n- `LogEntry`: Structured log entries\n\n## Error Handling\n\nThe server includes comprehensive error handling with descriptive messages for:\n- API connection failures\n- Invalid parameters\n- Authentication issues\n- Rate limiting\n- Network timeouts\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # Main server implementation\n├── solarwinds-client.ts  # SolarWinds API client\n└── types.ts              # TypeScript type definitions\n```\n\n### Adding New Tools\n\n1. Define the tool schema in `index.ts`\n2. Add the tool to the tools list\n3. Implement the handler in the switch statement\n4. Add corresponding method in `solarwinds-client.ts`\n\n## License\n\nMIT","readmeFilename":"README.md"}