elasticsearch-mcp-vsee 0.3.0 → 0.5.0

package/README.md

@@ -1,83 +1,107 @@
-# Elasticsearch MCP
+# Elasticsearch MCP (VSee Fork)
 
-> **Model Context Protocol server for Elasticsearch integration with comprehensive security and performance features**
+> **Modified MCP server with hardcoded schemas matching VSee's Elasticsearch indexes. Specialized analytics tools optimized for stats-* indices.**
 
-[![npm version](https://badge.fury.io/js/elasticsearch-mcp.svg)](https://www.npmjs.com/package/elasticsearch-mcp)
+[![npm version](https://badge.fury.io/js/elasticsearch-mcp-vsee.svg)](https://www.npmjs.com/package/elasticsearch-mcp-vsee)
 [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Elasticsearch](https://img.shields.io/badge/Elasticsearch-005571?logo=elasticsearch&logoColor=white)](https://www.elastic.co/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**elasticsearch-mcp** is a Model Context Protocol (MCP) server that provides standardized, secure tools for interacting with Elasticsearch clusters. Built with TypeScript and optimized for Elastic Cloud environments, it offers comprehensive data management capabilities with enterprise-grade security features.
+**elasticsearch-mcp-vsee** is a modified Model Context Protocol (MCP) server that provides specialized analytics tools for Elasticsearch clusters, optimized for VSee's stats-* indices. This fork features hardcoded schemas and field names that match VSee's specific Elasticsearch index structure, enabling specialized tools for account/group analytics, visit trends, platform breakdowns, and rating distributions. Built with TypeScript and optimized for Elastic Cloud environments, it offers comprehensive analytics capabilities with enterprise-grade security features.
 
 ## 🚀 Features
 
 - **🔐 Secure by Design**: Input validation, script sanitization, injection prevention
 - **☁️ Elastic Cloud Ready**: Native support for cloud ID and API key authentication  
-- **⚡ High Performance**: Streaming for large datasets, connection pooling, health monitoring
-- **🛠️ Comprehensive Tools**: 7 essential tools covering all major Elasticsearch operations
+- **⚡ High Performance**: Connection pooling, optimized query execution, efficient aggregations
+- **🛠️ Comprehensive Tools**: 11 specialized tools for analytics, summaries, and data exploration
 - **📊 Advanced Querying**: Full Elasticsearch DSL support with aggregations and highlighting
-- **📁 Data Export**: Stream large datasets to CSV with compression support
 - **🔍 Smart Validation**: Zod-based schemas with security-first validation
 - **📝 Full TypeScript**: Complete type safety with strict null checks
 
-## 📦 Installation
+## 🎯 Purpose
 
-```bash
-npm install elasticsearch-mcp
-```
+This MCP server is designed for **VSee's Open WebUI deployment** to provide specialized analytics tools for querying VSee's Elasticsearch `stats-*` indices. It integrates with VSee's Open WebUI infrastructure via MCPO (MCP OpenAPI bridge) to expose Elasticsearch analytics capabilities to LLMs.
 
-## 🏃‍♂️ Quick Start
+## 📦 Usage with VSee's Open WebUI Deployment
 
-### 1. Basic Setup
+This MCP server is automatically loaded by VSee's Open WebUI deployment through the MCP configuration. It connects to VSee's Elasticsearch deployment to provide analytics on visit statistics, account/group metrics, platform breakdowns, and more.
 
-```bash
-# Set your Elasticsearch credentials
-export ELASTIC_CLOUD_ID="your-cloud-id"
-export ELASTIC_API_KEY="your-api-key"
+### Configuration
 
-# Start the MCP server
-npx elasticsearch-mcp
-```
-
-### 2. Using with Claude Desktop
-
-Add to your Claude Desktop MCP configuration:
+The MCP server is configured in `vsee/mcp/config.json`:
 
 ```json
 {
   "mcpServers": {
-    "elasticsearch-mcp": {
+    "elasticsearch": {
       "command": "npx",
-      "args": ["elasticsearch-mcp"],
+      "args": ["-y", "elasticsearch-mcp-vsee"],
       "env": {
-        "ELASTIC_CLOUD_ID": "your-cloud-id",
-        "ELASTIC_API_KEY": "your-api-key"
+        "ELASTIC_NODE": "https://omtm.es.us-east-1.aws.found.io",
+        "ELASTIC_USERNAME": "your-username",
+        "ELASTIC_PASSWORD": "your-password",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
       }
     }
   }
 }
 ```
 
-### 3. Using with any MCP Client
+The Open WebUI deployment automatically loads this configuration and starts the MCP server via MCPO, making all 11 tools available to the LLM for querying Elasticsearch data.
 
-```typescript
-import { ElasticMCPServer } from 'elasticsearch-mcp';
+## 🔄 Updating and Publishing
 
-const server = new ElasticMCPServer();
-await server.start();
-```
+### Making Changes
+
+1. **Develop locally**: Make changes to the code in `elasticsearch-mcp/`
+2. **Test your changes**: Use `npm run test:tools` to test against your Elasticsearch instance
+3. **Build**: Run `npm run build` to compile TypeScript
+4. **Publish**: Publish to npm with `npm publish --access public`
+   - Make sure to increment the version in `package.json` first
+
+### Updating VSee's Deployment
+
+After publishing a new version to npm:
+
+1. **Update `vsee/mcp/config.json`**: Change the package version in the `args` array:
+   ```json
+   {
+     "mcpServers": {
+       "elasticsearch": {
+         "command": "npx",
+         "args": ["-y", "elasticsearch-mcp-vsee@0.5.0"],  // Update version here
+         "env": {
+           ...
+         }
+       }
+     }
+   }
+   ```
+
+2. **Restart the MCPO service**: The MCPO container will automatically download and use the new version on restart:
+   ```bash
+   docker compose -f docker-compose.vsee.yaml restart mcpo
+   ```
+
+3. **Verify**: Check that the new version is loaded by examining the MCPO logs or testing the tools in Open WebUI.
+
+**Note**: You can also use `@latest` to always pull the latest version, but specifying a version number is recommended for production stability.
 
 ## 🛠️ Available Tools
 
 | Tool | Description | Use Cases |
 |------|-------------|-----------|
-| `fetch_indices` | List and filter Elasticsearch indices | Index management, monitoring |
-| `search_elasticsearch` | Advanced search with aggregations | Data analysis, querying |
-| `create_index` | Create indices with mappings/settings | Schema management |
-| `insert_data` | Insert documents with validation | Data ingestion |
-| `update_document` | Update documents with scripts | Data modification |
-| `delete_document` | Delete by ID or query | Data cleanup |
-| `export_to_csv` | Stream data to CSV files | Reporting, data export |
+| `search_elasticsearch` | Advanced search with aggregations | Custom queries, data analysis |
+| `get_index_fields` | Discover index fields and types | Schema exploration, field discovery |
+| `top_change` | Find top accounts or groups with highest visit increase/decrease | Trend analysis, account/group monitoring |
+| `period_summary` | Weekly/monthly/yearly summaries by subscription | Period-based reporting |
+| `get_account_summary` | Comprehensive statistics for a specific account | Account analytics, performance review |
+| `get_group_summary` | Group statistics with account breakdown | Group management, resource allocation |
+| `get_platform_breakdown` | Platform or platform version breakdown (provider/patient, platform/version) | Platform adoption, device preferences, version analysis |
+| `get_rating_distribution` | Rating histograms with statistics | Satisfaction analysis |
+| `get_visit_trends` | Time series visit trends (daily/weekly/monthly) | Trend visualization |
+| `get_dashboard_summary` | High-level dashboard metrics overview | Executive dashboards, KPIs |
 
 ## 📋 Tool Examples
 
@@ -113,59 +137,59 @@ await server.start();
 }
 ```
 
-### Export Large Dataset
+### Get Account Summary
 
 ```json
 {
-  "tool": "export_to_csv",
+  "tool": "get_account_summary",
   "arguments": {
-    "index": "user-analytics",
-    "query": {
-      "bool": {
-        "filter": [
-          { "term": { "status": "active" } },
-          { "range": { "last_login": { "gte": "2024-01-01" } } }
-        ]
-      }
-    },
-    "fields": ["user_id", "email", "last_login", "country"],
-    "filename": "active_users_2024.csv",
-    "compress": true,
-    "maxRows": 100000
+    "account": "example-customer",
+    "startDate": "now-1y",
+    "endDate": "now"
   }
 }
 ```
 
-### Create Index with Schema
+### Get Top Accounts by Growth
 
 ```json
 {
-  "tool": "create_index",
+  "tool": "top_change",
   "arguments": {
-    "name": "product-catalog",
-    "mappings": {
-      "properties": {
-        "name": { "type": "text", "analyzer": "standard" },
-        "price": { "type": "float" },
-        "category": { "type": "keyword" },
-        "created_at": { "type": "date" },
-        "tags": { "type": "keyword" },
-        "description": { "type": "text" }
-      }
-    },
-    "settings": {
-      "number_of_shards": 1,
-      "number_of_replicas": 1,
-      "analysis": {
-        "analyzer": {
-          "product_analyzer": {
-            "type": "standard",
-            "stopwords": "_english_"
-          }
-        }
-      }
-    },
-    "aliases": ["products", "catalog"]
+    "groupBy": "account",
+    "direction": "increase",
+    "topN": 10,
+    "currentPeriodDays": 30,
+    "previousPeriodDays": 30
+  }
+}
+```
+
+### Get Platform Breakdown
+
+```json
+{
+  "tool": "get_platform_breakdown",
+  "arguments": {
+    "role": "provider",
+    "breakdownType": "version",
+    "topN": 10,
+    "startDate": "now-30d",
+    "endDate": "now"
+  }
+}
+```
+
+### Get Visit Trends
+
+```json
+{
+  "tool": "get_visit_trends",
+  "arguments": {
+    "interval": "daily",
+    "startDate": "now-30d",
+    "endDate": "now",
+    "groupBy": "subscription"
   }
 }
 ```
@@ -174,36 +198,25 @@ await server.start();
 
 ### Environment Variables
 
+The MCP server reads configuration from environment variables. These are set in `vsee/mcp/config.json` under the `env` section:
+
 | Variable | Description | Required | Example |
 |----------|-------------|----------|---------|
-| `ELASTIC_CLOUD_ID` | Elastic Cloud deployment ID | Yes* | `deployment:dXMtY2VudHJhbDE=` |
-| `ELASTIC_API_KEY` | Elasticsearch API key | Yes* | `VnVhQ2ZHY0JDZGJrU...` |
-| `ELASTIC_NODE` | Self-hosted Elasticsearch URL | Yes* | `https://localhost:9200` |
-| `ELASTIC_USERNAME` | Basic auth username | No | `elastic` |
-| `ELASTIC_PASSWORD` | Basic auth password | No | `changeme` |
-| `LOG_LEVEL` | Logging level | No | `info` |
-| `LOG_FORMAT` | Log output format | No | `text` |
-| `MAX_CONCURRENT_REQUESTS` | Request concurrency limit | No | `10` |
-
-*Either `ELASTIC_CLOUD_ID` or `ELASTIC_NODE` is required
+| `ELASTIC_NODE` | Elasticsearch URL | Yes | `https://omtm.es.us-east-1.aws.found.io` |
+| `ELASTIC_USERNAME` | Basic auth username | Yes | `your-username` |
+| `ELASTIC_PASSWORD` | Basic auth password | Yes | `your-password` |
+| `NODE_TLS_REJECT_UNAUTHORIZED` | Disable TLS verification (for self-signed certs) | No | `"0"` |
 
-### Configuration File
+### Alternative: Elastic Cloud Authentication
 
-Create `.env` file:
+If using Elastic Cloud with cloud ID and API key:
 
-```bash
-# Elastic Cloud (recommended)
-ELASTIC_CLOUD_ID=your-deployment-id
-ELASTIC_API_KEY=your-api-key
-
-# Logging
-LOG_LEVEL=info
-LOG_FORMAT=json
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ELASTIC_CLOUD_ID` | Elastic Cloud deployment ID | Yes* |
+| `ELASTIC_API_KEY` | Elasticsearch API key | Yes* |
 
-# Performance
-MAX_CONCURRENT_REQUESTS=10
-REQUEST_TIMEOUT_MS=30000
-```
+*Either `ELASTIC_CLOUD_ID` + `ELASTIC_API_KEY` OR `ELASTIC_NODE` + `ELASTIC_USERNAME` + `ELASTIC_PASSWORD` is required
 
 ## 🔒 Security Features
 
@@ -239,13 +252,11 @@ REQUEST_TIMEOUT_MS=30000
                        ┌─────────────┐
                        │   Tools     │
                        │             │
-                       │ • fetch     │
                        │ • search    │
-                       │ • create    │
-                       │ • insert    │
-                       │ • update    │
-                       │ • delete    │
-                       │ • export    │
+                       │ • fields    │
+                       │ • summaries │
+                       │ • trends    │
+                       │ • analytics │
                        └─────────────┘
 ```
 
@@ -253,14 +264,14 @@ REQUEST_TIMEOUT_MS=30000
 
 ### Benchmarks
 - **Search**: <500ms average response time
-- **Large Exports**: 10K+ documents/second with streaming
+- **Aggregations**: Optimized for large-scale analytics
 - **Memory Usage**: <100MB for typical operations
 - **Concurrent Requests**: Up to 10 simultaneous operations
 
 ### Optimization Features
 - **Connection Pooling**: Reuses Elasticsearch connections
-- **Streaming**: Memory-efficient processing of large datasets
-- **Compression**: Reduces export file sizes by 70%+
+- **Optimized Queries**: Efficient aggregation pipelines
+- **Smart Caching**: Reduced redundant queries
 - **Health Monitoring**: Automatic reconnection on failures
 
 ## 🔧 Development
@@ -268,25 +279,26 @@ REQUEST_TIMEOUT_MS=30000
 ### Setup Development Environment
 
 ```bash
-# Clone repository
-git clone https://github.com/RajwardhanShinde/elk-mcp.git
-cd elk-mcp
-
 # Install dependencies
 npm install
 
-# Set up environment
-cp .env.example .env
-# Edit .env with your Elasticsearch credentials
+# Set up environment variables
+export ELASTIC_NODE="https://your-elasticsearch-url"
+export ELASTIC_USERNAME="your-username"
+export ELASTIC_PASSWORD="your-password"
+export NODE_TLS_REJECT_UNAUTHORIZED="0"  # If needed for self-signed certs
 
 # Run in development mode
 npm run dev
 
-# Run tests
-npm test
+# Test tools against live Elasticsearch
+npm run test:tools
 
 # Build for production
 npm run build
+
+# Publish new version (after incrementing version in package.json)
+npm publish --access public
 ```
 
 ### Project Structure
@@ -301,30 +313,16 @@ elasticsearch-mcp/
 │   ├── config.ts        # Configuration management
 │   ├── logger.ts        # Structured logging
 │   └── server.ts        # Main MCP server
-├── tests/               # Comprehensive test suite
-├── docs/                # Documentation
+├── tests/               # Test suite
+├── TEST_GUIDE.md        # Testing guide
+├── OPENWEBUI_TEST_PROMPTS.md  # Example prompts for Open WebUI
 └── build/               # Compiled output
 ```
 
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-### Development Workflow
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes with tests
-4. Ensure all tests pass
-5. Submit a pull request
-
 ## 📚 Documentation
 
-- [Quick Start Guide](docs/guides/quick-start.md)
-- [API Reference](docs/api/tools.md)
-- [Configuration Guide](docs/api/configuration.md)
-- [Elastic Cloud Setup](docs/guides/elastic-cloud-setup.md)
-- [Troubleshooting](docs/guides/troubleshooting.md)
-- [Examples](docs/examples/)
+- [Testing Guide](TEST_GUIDE.md) - How to test all tools
+- [Open WebUI Test Prompts](OPENWEBUI_TEST_PROMPTS.md) - Example prompts for testing in Open WebUI
 
 ## 🐛 Troubleshooting
 
@@ -351,25 +349,23 @@ curl -H "Authorization: ApiKey $ELASTIC_API_KEY" \\
 - Validate required fields
 - Review field name restrictions
 
-See [Troubleshooting Guide](docs/guides/troubleshooting.md) for more details.
-
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## 🏷️ Version History
 
-- **v0.1.0** - Initial release with 7 core tools
+- **v0.5.0** - Added `find_entities_by_metric` tool with multi-metric filtering support, updated default limits
+- **v0.4.0** - Tool consolidation: merged 14 tools into 11 specialized analytics tools
+- **v0.3.0** - Specialized analytics tools for stats-* indices
 - Full changelog: [CHANGELOG.md](CHANGELOG.md)
 
 ## 🔗 Links
 
-- [npm Package](https://www.npmjs.com/package/elasticsearch-mcp)
-- [GitHub Repository](https://github.com/RajwardhanShinde/elk-mcp)
-- [Issue Tracker](https://github.com/RajwardhanShinde/elk-mcp/issues)
+- [npm Package](https://www.npmjs.com/package/elasticsearch-mcp-vsee)
 - [Elasticsearch Documentation](https://www.elastic.co/guide/)
 - [Model Context Protocol](https://modelcontextprotocol.io/)
 
 ---
 
-**Built with ❤️ for the Elasticsearch and MCP communities**
+**Built for VSee by VSee**

package/build/server.d.ts

@@ -5,14 +5,17 @@ export declare class ElasticMCPServer {
     private elasticsearch;
     private errorHandler;
     private isShuttingDown;
-    private fetchIndicesTool;
-    private createIndexTool;
-    private insertDataTool;
-    private updateDocumentTool;
-    private deleteDocumentTool;
     private searchElasticsearchTool;
-    private exportToCSVTool;
     private getIndexFieldsTool;
+    private topChangeTool;
+    private periodSummaryTool;
+    private getAccountSummaryTool;
+    private getGroupSummaryTool;
+    private getPlatformBreakdownTool;
+    private getRatingDistributionTool;
+    private getVisitTrendsTool;
+    private getDashboardSummaryTool;
+    private findEntitiesByMetricTool;
     constructor();
     private setupHandlers;
     private setupGracefulShutdown;

package/build/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAmBA,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAS;IAG/B,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,uBAAuB,CAA0B;IACzD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,kBAAkB,CAAqB;;IAkC/C,OAAO,CAAC,aAAa;IAiXrB,OAAO,CAAC,qBAAqB;IAoCvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAsBA,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,cAAc,CAAS;IAG/B,OAAO,CAAC,uBAAuB,CAA0B;IACzD,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,qBAAqB,CAAwB;IACrD,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,wBAAwB,CAA2B;IAC3D,OAAO,CAAC,yBAAyB,CAA4B;IAC7D,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,uBAAuB,CAA0B;IACzD,OAAO,CAAC,wBAAwB,CAA2B;;IAqC3D,OAAO,CAAC,aAAa;IAihBrB,OAAO,CAAC,qBAAqB;IAoCvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAED,eAAe,gBAAgB,CAAC"}