graylog-mcp-server 1.0.0 → 2.0.0

package/README.md

@@ -1,94 +1,185 @@
 # Graylog MCP Server
 
-A minimal MCP (Model Context Protocol) server in JavaScript that integrates with Graylog.
+An MCP (Model Context Protocol) server for Graylog that enables AI assistants to search logs, filter by fields, view surrounding context, list streams, and discover field values.
 
 ## Features
 
-- JavaScript MCP server
-- Tools: `fetch_graylog_messages` (query Graylog and return messages)
+- **Multi-connection support** — configure and switch between multiple Graylog instances
+- **Log search with filters** — query logs with field-level filters (env, level, source, logger_name, etc.)
+- **Exact match by default** — queries use exact matching unless explicitly set to fuzzy/wildcard
+- **Surrounding messages** — view messages around a specific log entry by message ID or timestamp
+- **Pagination** — page through large result sets
+- **Stream listing** — list all available Graylog streams
+- **Field value discovery** — find distinct values for any field (top N by count)
+- **Default fields** — returns only key fields by default, reducing noise from internal Graylog fields
 
 ## Requirements
 
 - Node.js 18+
+- Graylog 6.x (tested on 6.2.10)
 
 ## Installation
 
 ```bash
-git clone git@github.com:lcaliani/graylog-mcp.git
+git clone git@github.com:jagadeesh52423/graylog-mcp.git
 cd graylog-mcp
 npm install
 ```
 
 ## Configuration
 
-Set the following environment variables so the server can connect to Graylog:
+Create a config file at `~/.graylog-mcp/config.json`:
 
-- `BASE_URL`: Graylog base URL, e.g. `https://graylog.example.com`
-- `API_TOKEN`: Graylog API token (used as the username, with password `token`)
-
-> :exclamation: Suggestion: add these variables to your respective MCP client configuration file or app. Example in **Cursor** more below.
+```json
+{
+  "connections": {
+    "nonprod": {
+      "baseUrl": "http://your-graylog-server:9000",
+      "apiToken": "your_graylog_api_token"
+    },
+    "prod": {
+      "baseUrl": "http://prod-graylog:9000",
+      "apiToken": "your_prod_api_token"
+    }
+  }
+}
+```
 
+You can add multiple named connections and switch between them at runtime.
 
-## Use with an MCP client (Cursor/Claude Desktop)
+## Use with an MCP Client
 
-1. Add this server to your MCP client configuration, poiting to the mcp entrypoint file (`src/index.js`). Common locations:
+Add this server to your MCP client configuration. Common locations:
 
-- Cursor: `~/.cursor/mcp.json`
-- Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Claude Desktop (Linux): `~/.config/claude-desktop/claude_desktop_config.json`
+- **Claude Code**: `~/.claude/mcp.json`
+- **Cursor**: `~/.cursor/mcp.json`
+- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-Example config in **Cursor**:
+Example config using npx (recommended):
 
 ```json
 {
   "mcpServers": {
-    "simple-graylog-mcp": {
-      "command": "node",
-      "args": [
-        "/path/to/graylog-mcp/src/index.js"
-      ],
-      "env": {
-        "BASE_URL": "http://your.graylog.server.net.br:9000",
-        "API_TOKEN": "your_graylog_api_token"
-      }
+    "graylog": {
+      "command": "npx",
+      "args": ["graylog-mcp-server"]
     }
   }
 }
 ```
 
-2. After that, your client is already able to use the `fetch_graylog_messages` tool. Example prompt:
+Or with a local clone:
 
-```
-Search for the latest 20 error logs of the example application, given that they occurred in the last 15 minutes.
+```json
+{
+  "mcpServers": {
+    "graylog": {
+      "command": "node",
+      "args": ["/path/to/graylog-mcp/src/index.js"]
+    }
+  }
+}
 ```
 
-This should be enough for the tool to be used, but if wanted, you can also explicitly "force" the use of the tool. Example prompt:
+## Available Tools
 
-```
-Search for the latest 20 error logs of the example application, given that they occurred in the last 15 minutes.
+### list_connections
 
-use simple-graylog-mcp
-```
+List all configured Graylog connections.
 
+### use_connection
 
-## Available tools
+Connect to a specific Graylog instance by name. Must be called before using other tools.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Connection name from config |
 
 ### fetch_graylog_messages
 
-Fetch messages from Graylog.
+Search and fetch log messages from Graylog.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | No | `*` | Search query |
+| `filters` | object | No | | Field filters (e.g. `{"env": "marketplace_loki", "level": 7}`) |
+| `exactMatch` | boolean | No | `true` | Wrap query in quotes for exact match. Set `false` for fuzzy/wildcard |
+| `searchTimeRangeInSeconds` | number | No | `900` | Relative time range in seconds |
+| `pageSize` | number | No | `50` | Messages per page |
+| `page` | number | No | `1` | Page number |
+| `fields` | string | No | default set | Comma-separated fields, or `*` for all |
+
+**Default fields returned:** `timestamp`, `gl2_message_id`, `source`, `env`, `level`, `message`, `logger_name`, `thread_name`, `PODNAME`
+
+### get_surrounding_messages
+
+View messages around a specific log entry. Useful for understanding context.
 
-Parameters:
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `messageId` | string | No* | | `gl2_message_id` of the target message (preferred) |
+| `messageTimestamp` | string | No* | | ISO timestamp (fallback) |
+| `surroundingSeconds` | number | No | `5` | Time window (± seconds) |
+| `query` | string | No | `*` | Additional query filter |
+| `filters` | object | No | | Field filters |
+| `exactMatch` | boolean | No | `true` | Exact match for query |
+| `limit` | number | No | `50` | Max messages to return |
+| `fields` | string | No | default set | Comma-separated fields, or `*` for all |
 
-- `query` (string): Search query. Example: `level:ERROR AND service:api`.
-- `searchTimeRangeInSeconds` (number, optional): Relative time range in seconds. Default: `900` (15 minutes).
-- `searchCountLimit` (number, optional): Max number of messages. Default: `50`.
-- `fields` (string, optional): Comma-separated fields to include. Default: `*`.
+*Either `messageId` or `messageTimestamp` must be provided.
+
+### list_streams
+
+List all available Graylog streams in the active connection. No parameters required.
+
+### list_field_values
+
+Discover distinct values for a field, sorted by message count (descending).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `field` | string | Yes | | Field name (e.g. `source`, `env`, `logger_name`) |
+| `query` | string | No | `*` | Scope the results |
+| `filters` | object | No | | Field filters to narrow scope |
+| `exactMatch` | boolean | No | `true` | Exact match for query |
+| `timeRangeInSeconds` | number | No | `3600` | Time range |
+| `limit` | number | No | `20` | Max distinct values |
+
+## Example Prompts
+
+```
+Connect to nonprod and show me the latest error logs from prefr-management in marketplace_loki
+```
+
+```
+List all available sources in the last hour
+```
+
+```
+Show me the surrounding messages for this log entry: 01KH5PDR893AZJQBYJJ87AQTW5
+```
+
+```
+What environments are available?
+```
+
+## Project Structure
+
+```
+src/
+├── index.js    — Server bootstrap, routing, and handlers
+├── config.js   — Connection config and default fields
+├── query.js    — Query building, Graylog API client, message extraction
+└── tools.js    — Tool schema definitions
+```
 
 ## Troubleshooting
 
-- Ensure `BASE_URL` and `API_TOKEN` are set.
-- Verify Node.js version is 18+.
-- Run `npm install` if dependencies are missing.
+- Ensure `~/.graylog-mcp/config.json` exists with valid connections
+- Verify Node.js version is 18+ (`node --version`)
+- Run `npm install` if dependencies are missing
+- Use `list_connections` to verify your config is loaded
+- Use `use_connection` before any search tools
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "graylog-mcp-server",
-    "version": "1.0.0",
-    "description": "MCP server for fetching data from Graylog",
+    "version": "2.0.0",
+    "description": "MCP server for Graylog — search logs, filter by fields, view surrounding messages, list streams, and discover field values",
     "main": "src/index.js",
     "type": "module",
     "scripts": {
@@ -14,10 +14,20 @@
         "mcp",
         "graylog",
         "logging",
-        "model-context-protocol"
+        "model-context-protocol",
+        "log-search",
+        "observability"
     ],
-    "author": "Leo Ruellas",
+    "author": "Jagadeesh Pulamarasetti",
     "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/jagadeesh52423/graylog-mcp.git"
+    },
+    "bugs": {
+        "url": "https://github.com/jagadeesh52423/graylog-mcp/issues"
+    },
+    "homepage": "https://github.com/jagadeesh52423/graylog-mcp#readme",
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.18.0",
         "axios": "^1.12.2",