@tocharianou/mcp-server-kibana 0.6.1

package/README.md

@@ -0,0 +1,530 @@
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/tocharianou-mcp-server-kibana-badge.png)](https://mseep.ai/app/tocharianou-mcp-server-kibana)
+
+# Kibana MCP Server
+[![npm version](https://badge.fury.io/js/@tocharianou%2Fmcp-server-kibana.svg)](https://www.npmjs.com/package/@tocharianou/mcp-server-kibana)
+[![Downloads](https://img.shields.io/npm/dm/@tocharianou/mcp-server-kibana.svg)](https://www.npmjs.com/package/@tocharianou/mcp-server-kibana)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.TocharianOU/kibana)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/TocharianOU/mcp-server-kibana)
+
+> **API Specification**
+>
+> This project is based on the official Elastic Kibana API documentation and uses the OpenAPI YAML specification from Elastic Stack 8.x (ES8) to dynamically retrieve and manage all Kibana API endpoints. For the latest details, see the [Kibana API documentation](https://www.elastic.co/docs/api/doc/kibana/).
+
+A Kibana MCP server implementation that allows any MCP-compatible client (such as Claude Desktop) to access your Kibana instance via natural language or programmatic requests.
+
+**Key Features:**
+- Dynamic API discovery from Kibana OpenAPI specification
+- Comprehensive Kibana management (dashboards, visualizations, saved objects)
+- Health monitoring and dependency analysis
+- Dual transport modes (stdio and HTTP)
+- Full integration with Elastic Stack ecosystem
+
+**This project is community-maintained and is not an official product of Elastic or MCP.**
+
+> **💡 Companion Project**
+>
+> For complete Elastic Stack integration, pair this with [**Elasticsearch MCP Server**](https://github.com/TocharianOU/elasticsearch-mcp) for direct Elasticsearch data operations. Together, they provide comprehensive observability and data management capabilities for your Elastic Stack environment.
+
+---
+
+## 🚀 Installation
+
+### Quick Install
+```bash
+# Global installation (recommended)
+npm install -g @tocharianou/mcp-server-kibana
+
+# Or local installation
+npm install @tocharianou/mcp-server-kibana
+```
+
+### Alternative: From Source
+```bash
+git clone https://github.com/TocharianOU/mcp-server-kibana.git
+cd mcp-server-kibana
+npm install
+npm run build
+```
+
+---
+
+## 🎯 Quick Start
+
+### Method 1: Direct CLI Usage
+
+#### Using Basic Authentication
+```bash
+# Set your Kibana credentials and run
+KIBANA_URL=http://your-kibana-server:5601 \
+KIBANA_USERNAME=your-username \
+KIBANA_PASSWORD=your-password \
+npx @tocharianou/mcp-server-kibana
+```
+
+#### Using Cookie Authentication
+```bash
+# Set your Kibana session cookies and run
+KIBANA_URL=http://your-kibana-server:5601 \
+KIBANA_COOKIES="sid=your-session-id; security-session=your-security-session" \
+npx @tocharianou/mcp-server-kibana
+```
+
+#### Using API Key Authentication
+
+```bash
+# Set your Kibana API Key and run
+KIBANA_URL=http://your-kibana-server:5601 \
+KIBANA_API_KEY=your-base64-encoded-api-key \
+npx @tocharianou/mcp-server-kibana
+```
+
+### Method 2: Claude Desktop Integration (Recommended)
+
+Add to your Claude Desktop configuration file:
+
+**Config file locations:**
+
+- **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+#### Using Basic Authentication
+
+```json
+{
+  "mcpServers": {
+    "kibana-mcp-server": {
+      "command": "npx",
+      "args": ["@tocharianou/mcp-server-kibana"],
+      "env": {
+        "KIBANA_URL": "http://your-kibana-server:5601",
+        "KIBANA_USERNAME": "your-username",
+        "KIBANA_PASSWORD": "your-password",
+        "KIBANA_DEFAULT_SPACE": "default",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+      }
+    }
+  }
+}
+```
+
+#### Using Cookie Authentication
+
+```json
+{
+  "mcpServers": {
+    "kibana-mcp-server": {
+      "command": "npx",
+      "args": ["@tocharianou/mcp-server-kibana"],
+      "env": {
+        "KIBANA_URL": "http://your-kibana-server:5601",
+        "KIBANA_COOKIES": "sid=your-session-id; security-session=your-security-session",
+        "KIBANA_DEFAULT_SPACE": "default",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+      }
+    }
+  }
+}
+```
+
+#### Using API Key Authentication
+
+```json
+{
+  "mcpServers": {
+    "kibana-mcp-server": {
+      "command": "npx",
+      "args": ["@tocharianou/mcp-server-kibana"],
+      "env": {
+        "KIBANA_URL": "http://your-kibana-server:5601",
+        "KIBANA_API_KEY": "your-base64-encoded-api-key",
+        "KIBANA_DEFAULT_SPACE": "default",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+      }
+    }
+  }
+}
+```
+
+### Method 3: Using Environment File
+
+```bash
+# Create .env file
+cat > kibana-mcp.env << EOF
+KIBANA_URL=http://your-kibana-server:5601
+KIBANA_USERNAME=your-username
+KIBANA_PASSWORD=your-password
+NODE_TLS_REJECT_UNAUTHORIZED=0
+EOF
+
+# Run with environment file
+env $(cat kibana-mcp.env | xargs) npx @tocharianou/mcp-server-kibana
+```
+
+### Method 4: Streamable HTTP Mode (NEW in v0.4.0)
+
+Run the server as a standalone HTTP service for remote access and API integration:
+
+```bash
+# Start HTTP server (default port 3000)
+MCP_TRANSPORT=http \
+KIBANA_URL=http://your-kibana-server:5601 \
+KIBANA_USERNAME=your-username \
+KIBANA_PASSWORD=your-password \
+npx @tocharianou/mcp-server-kibana
+
+# Or with custom port and host
+MCP_TRANSPORT=http \
+MCP_HTTP_PORT=9000 \
+MCP_HTTP_HOST=0.0.0.0 \
+KIBANA_URL=http://your-kibana-server:5601 \
+KIBANA_USERNAME=your-username \
+KIBANA_PASSWORD=your-password \
+npx @tocharianou/mcp-server-kibana
+```
+
+**HTTP Mode Features:**
+
+- Exposes MCP server at `http://host:port/mcp` endpoint
+- Health check available at `http://host:port/health`
+- Session-based connection management
+- Supports both POST (JSON-RPC requests) and GET (SSE streams)
+- Compatible with any HTTP client or MCP SDK
+
+**Example HTTP client usage:**
+
+```javascript
+// Initialize connection
+const response = await fetch('http://localhost:3000/mcp', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    jsonrpc: '2.0',
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'my-client', version: '1.0.0' }
+    },
+    id: 1
+  })
+});
+
+const sessionId = response.headers.get('mcp-session-id');
+
+// Subsequent requests include session ID
+const toolsResponse = await fetch('http://localhost:3000/mcp', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'mcp-session-id': sessionId
+  },
+  body: JSON.stringify({
+    jsonrpc: '2.0',
+    method: 'tools/list',
+    params: {},
+    id: 2
+  })
+});
+```
+
+---
+
+## Features
+
+### Core Features
+
+- Connect to local or remote Kibana instances
+- **Dual transport modes**:
+  - **Stdio transport** (default) - For Claude Desktop and local MCP clients
+  - **Streamable HTTP transport** (NEW in v0.4.0) - For remote access, API integration, and web applications
+- **Dual authentication support**:
+  - Cookie-based authentication (recommended for browser sessions)
+  - Basic authentication (username/password)
+- SSL/TLS and custom CA certificate support
+- Multi-space support for enterprise Kibana environments
+- Exposes Kibana API endpoints as both tools and resources
+- Search, view, and execute Kibana APIs from MCP clients
+- Type-safe, extensible, and easy to integrate
+- **Session management** with automatic UUID generation for HTTP mode
+- **Health check endpoint** for monitoring and load balancing
+
+### Visualization Layer (VL) Features
+
+- **Complete CRUD operations** for Kibana saved objects
+- **Universal saved object management** - works with all object types
+- **Intelligent parameter handling** - supports multiple input formats (arrays, JSON strings, comma-separated)
+- **Optimized search** with pagination support and performance tips
+- **Bulk operations** for efficient mass updates and deletions
+- **Version control** with optimistic concurrency for safe updates
+- **Reference management** for object relationships
+- **Multi-format type support** - flexible input parsing for better UX
+
+---
+
+## Directory Structure
+
+```
+├── index.ts                # Server entry point
+├── src/
+│   ├── types.ts            # Type definitions and schemas
+│   ├── base-tools.ts       # Tool registration and API logic
+│   ├── prompts.ts          # Prompt registration (expert & resource helper)
+│   ├── resources.ts        # Resource registration (API paths/URIs)
+│   ├── vl_search_tools.ts  # Visualization Layer - Search tools
+│   ├── vl_get_tools.ts     # Visualization Layer - Get tools
+│   ├── vl_create_tools.ts  # Visualization Layer - Create tools
+│   ├── vl_update_tools.ts  # Visualization Layer - Update tools
+│   └── vl_delete_tools.ts  # Visualization Layer - Delete tools
+├── kibana-openapi-source.yaml # Kibana API OpenAPI index
+├── README.md               # English documentation
+├── README_zh.md            # Chinese documentation
+```
+
+---
+
+## Resources
+
+| Resource URI                                   | Description                                        |
+|------------------------------------------------|----------------------------------------------------|
+| `kibana-api://paths`                           | Returns all available Kibana API endpoints (can filter with `search` param) |
+| `kibana-api://path/{method}/{encoded_path}`    | Returns details for a specific API endpoint        |
+
+**Examples:**
+
+- `kibana-api://paths?search=saved_objects`
+- `kibana-api://path/GET/%2Fapi%2Fstatus`
+
+---
+
+## Tools
+
+### Base Tools
+
+| Tool Name                   | Description                                        | Input Parameters                                                    |
+|-----------------------------|----------------------------------------------------|---------------------------------------------------------------------|
+| `get_status`                | Get the current status of the Kibana server        | `space` (optional string) - Target Kibana space                    |
+| `execute_kb_api`            | Execute a custom Kibana API request                | `method` (GET/POST/PUT/DELETE), `path` (string), `body` (optional), `params` (optional), `space` (optional string) |
+| `get_available_spaces`      | Get available Kibana spaces and current context    | `include_details` (optional boolean) - Include full space details  |
+| `search_kibana_api_paths`   | Search Kibana API endpoints by keyword             | `search` (string)                                                   |
+| `list_all_kibana_api_paths` | List all Kibana API endpoints                      | None                                                                |
+| `get_kibana_api_detail`     | Get details for a specific Kibana API endpoint     | `method` (string), `path` (string)                                  |
+
+### Visualization Layer (VL) Tools - Saved Objects Management
+
+| Tool Name                      | Description                                        | Input Parameters                                                    |
+|--------------------------------|----------------------------------------------------|---------------------------------------------------------------------|
+| `vl_search_saved_objects`      | Search for Kibana saved objects (universal)       | `types` (required array), `search` (optional), `fields` (optional), `perPage` (optional), `page` (optional), `space` (optional) |
+| `vl_get_saved_object`          | Get a single saved object by type and ID          | `type` (required), `id` (required), `useResolve` (optional), `space` (optional) |
+| `vl_create_saved_object`       | Create a new saved object (universal)             | `type` (required), `attributes` (required), `id` (optional), `overwrite` (optional), `references` (optional), `space` (optional) |
+| `vl_update_saved_object`       | Update a single saved object                      | `type` (required), `id` (required), `attributes` (required), `references` (optional), `version` (optional), `space` (optional) |
+| `vl_bulk_update_saved_objects` | Update multiple saved objects in bulk             | `objects` (required array), `space` (optional) |
+| `vl_bulk_delete_saved_objects` | Delete multiple saved objects in bulk             | `objects` (required array), `force` (optional), `space` (optional) |
+
+**Supported Saved Object Types:** `dashboard`, `visualization`, `index-pattern`, `search`, `config`, `lens`, `map`, `tag`, `canvas-workpad`, `canvas-element`
+
+---
+
+## Prompts
+
+| Prompt Name              | Description                                                                 |
+|-------------------------|-----------------------------------------------------------------------------|
+| `kibana-tool-expert`    | Tool expert mode (highly recommended in Claude Desktop), supports intelligent analysis, search, execution, and explanation of Kibana APIs via tools. Recommended for most users. |
+| `kibana-resource-helper`| Resource helper mode, guides how to access and use Kibana API info via resource URIs. Suitable for clients that only support resource access or need raw API metadata. |
+
+---
+
+## Configuration
+
+Configure the server via environment variables:
+
+### Kibana Connection Settings
+
+| Variable Name                    | Description                                         | Required |
+|----------------------------------|-----------------------------------------------------|----------|
+| `KIBANA_URL`                     | Kibana server address (e.g. <http://localhost:5601>)   | Yes      |
+| `KIBANA_API_KEY`                 | Kibana API Key (base64 encoded, for API key auth)  | No*      |
+| `KIBANA_USERNAME`                | Kibana username (for basic auth)                   | No*      |
+| `KIBANA_PASSWORD`                | Kibana password (for basic auth)                   | No*      |
+| `KIBANA_COOKIES`                 | Kibana session cookies (for cookie auth)           | No*      |
+| `KIBANA_DEFAULT_SPACE`           | Default Kibana space (default: 'default')          | No       |
+| `KIBANA_CA_CERT`                 | CA certificate path (optional, for SSL verification) | No       |
+| `KIBANA_TIMEOUT`                 | Request timeout in ms (default 30000)                | No       |
+| `KIBANA_MAX_RETRIES`             | Max request retries (default 3)                      | No       |
+| `NODE_TLS_REJECT_UNAUTHORIZED`   | Set to `0` to disable SSL certificate validation (use with caution) | No |
+
+*One of the following authentication methods must be provided: `KIBANA_API_KEY`, `KIBANA_COOKIES`, or both `KIBANA_USERNAME` and `KIBANA_PASSWORD`. Priority order: API Key > Basic Auth > Cookies.
+
+### Transport Mode Settings (NEW in v0.4.0)
+
+| Variable Name     | Description                                    | Default   | Values          |
+|-------------------|------------------------------------------------|-----------|-----------------|
+| `MCP_TRANSPORT`   | Transport mode selection                       | `stdio`   | `stdio`, `http` |
+| `MCP_HTTP_PORT`   | HTTP server port (when using HTTP transport)   | `3000`    | 1-65535         |
+| `MCP_HTTP_HOST`   | HTTP server host (when using HTTP transport)   | `localhost` | Any valid host  |
+
+**Transport Mode Details:**
+
+- **Stdio mode** (default): For Claude Desktop and local MCP clients
+- **HTTP mode**: Runs as a standalone HTTP server for remote access, API integration, and web applications
+
+---
+
+## 📦 Package Information
+
+- **NPM Package**: [@tocharianou/mcp-server-kibana](https://www.npmjs.com/package/@tocharianou/mcp-server-kibana)
+- **GitHub Repository**: [TocharianOU/mcp-server-kibana](https://github.com/TocharianOU/mcp-server-kibana)
+- **Node.js**: >= 18.0.0
+- **Package Size**: ~685KB (6.4MB unpacked)
+
+---
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### "import: command not found" error
+
+```bash
+# Make sure you're using the latest version
+npm install -g @tocharianou/mcp-server-kibana@latest
+
+# Or try using node directly
+node $(which mcp-server-kibana)
+```
+
+#### Connection issues
+
+- Verify Kibana URL is accessible
+- Check authentication credentials
+- For SSL issues, try setting `NODE_TLS_REJECT_UNAUTHORIZED=0`
+
+#### Claude Desktop not detecting the server
+
+- Restart Claude Desktop after config changes
+- Check config file syntax with a JSON validator
+- Verify environment variables are set correctly
+
+---
+
+## Example Queries
+
+### Basic Queries
+
+- "What is the status of my Kibana server?"
+- "What is the status of my Kibana server in the 'marketing' space?"
+- "List all available Kibana spaces I can access."
+- "List all available Kibana API endpoints."
+- "Show details for the POST /api/saved_objects/_find endpoint."
+- "Execute a custom API request for /api/status."
+
+### Saved Objects Management
+
+- "Search for all dashboards in Kibana"
+- "Find visualizations containing 'nginx' in the title"
+- "Get dashboard with ID 'my-dashboard-123'"
+- "Create a new dashboard with title 'Sales Overview'"
+- "Update the description of visualization 'viz-456'"
+- "Delete multiple old dashboards by their IDs"
+- "Search for lens visualizations in the 'analytics' space"
+- "Find all canvas workpads created this month"
+- "Get the first 10 index patterns with only title and description fields"
+- "Bulk update multiple dashboard titles"
+- "Search across multiple object types: dashboards and visualizations"
+- "Create a new index pattern for 'logs-*' with timestamp field"
+
+---
+
+## Two Prompt Modes in Claude Desktop
+
+When using this server with Claude Desktop, two different prompt interaction modes are supported:
+
+### 1. Tool-based Prompt Mode
+
+- **How it works:** Claude Desktop can directly call server tools (including base tools like `get_status`, `execute_api`, and VL tools like `vl_search_saved_objects`, `vl_create_saved_object`) to answer your questions or perform actions.
+- **Best for:** Users who want a conversational, guided experience. The server will automatically search, execute, and explain Kibana APIs and manage saved objects.
+- **Example:** "Show all dashboards containing 'sales'" or "Create a new visualization for web analytics"
+- **Testing tip:** Select the `kibana-tool-expert` prompt in Claude Desktop for integration testing, then start using it.
+
+### 2. Resource-based Prompt Mode
+
+- **How it works:** Claude Desktop interacts with the server via resource URIs (such as `kibana-api://paths` or `kibana-api://path/GET/%2Fapi%2Fstatus`), and the server returns structured data for Claude to parse.
+- **Best for:** Advanced users, MCP clients that only support resource access, or programming scenarios needing raw API metadata.
+- **Example:** "Get resource kibana-api://paths?search=dashboard"
+
+**Note:** The two endpoints in `resources` (`kibana-api://paths` and `kibana-api://path/{method}/{encoded_path}`) have corresponding base tools (`list_all_kibana_api_paths`, `get_kibana_api_detail`). This design ensures compatibility with MCP clients that cannot intelligently select multiple resources, making it easier for tools like Claude Desktop to interact with Kibana.
+
+**Tip:** Most users are recommended to use tool mode for a more natural and powerful experience; resource mode offers maximum flexibility for advanced and compatibility use cases.
+
+---
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Build the server:
+
+```bash
+npm run build
+```
+
+Auto-rebuild in development mode:
+
+```bash
+npm run watch
+```
+
+Run in different modes:
+
+```bash
+# Stdio mode (default)
+npm start
+
+# HTTP mode
+npm run start:http
+
+# Development with TypeScript
+npm run start:ts
+
+# HTTP mode with TypeScript
+npm run start:http:ts
+```
+
+---
+
+## Debugging
+
+Since the MCP server communicates via stdio, debugging can be inconvenient. It is recommended to use MCP Inspector:
+
+```bash
+npm run inspector
+```
+
+After starting, Inspector will provide a browser-accessible debugging tool URL.
+
+---
+
+## Community
+
+This project is community-maintained. Contributions and feedback are welcome! Please be respectful and inclusive in all communications, and follow the [Elastic Community Code of Conduct](https://www.elastic.co/community/codeofconduct).
+
+---
+
+## License
+
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## Troubleshooting
+
+- Check if MCP configuration is correct
+- Ensure the Kibana address is accessible
+- Verify authentication credentials have sufficient permissions
+- If using a custom CA, ensure the certificate path is correct and readable
+- If using `NODE_TLS_REJECT_UNAUTHORIZED=0`, be aware of security risks
+- Check error messages output in the terminal

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerCreationOptions } from "./src/types.js";
+export declare function createKibanaMcpServer(options: ServerCreationOptions): Promise<McpServer>;