elasticsearch-mcp-vsee 0.2.2 → 0.4.0

package/README.md

@@ -1,29 +1,28 @@
-# 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**: 10 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
 
 ```bash
-npm install elasticsearch-mcp
+npm install elasticsearch-mcp-vsee
 ```
 
 ## 🏃‍♂️ Quick Start
@@ -36,7 +35,7 @@ export ELASTIC_CLOUD_ID="your-cloud-id"
 export ELASTIC_API_KEY="your-api-key"
 
 # Start the MCP server
-npx elasticsearch-mcp
+npx elasticsearch-mcp-vsee
 ```
 
 ### 2. Using with Claude Desktop
@@ -46,9 +45,9 @@ Add to your Claude Desktop MCP configuration:
 ```json
 {
   "mcpServers": {
-    "elasticsearch-mcp": {
+    "elasticsearch-mcp-vsee": {
       "command": "npx",
-      "args": ["elasticsearch-mcp"],
+      "args": ["elasticsearch-mcp-vsee"],
       "env": {
         "ELASTIC_CLOUD_ID": "your-cloud-id",
         "ELASTIC_API_KEY": "your-api-key"
@@ -61,7 +60,7 @@ Add to your Claude Desktop MCP configuration:
 ### 3. Using with any MCP Client
 
 ```typescript
-import { ElasticMCPServer } from 'elasticsearch-mcp';
+import { ElasticMCPServer } from 'elasticsearch-mcp-vsee';
 
 const server = new ElasticMCPServer();
 await server.start();
@@ -71,13 +70,16 @@ await server.start();
 
 | 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 +115,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"
   }
 }
 ```
@@ -239,13 +241,11 @@ REQUEST_TIMEOUT_MS=30000
                        ┌─────────────┐
                        │   Tools     │
                        │             │
-                       │ • fetch     │
                        │ • search    │
-                       │ • create    │
-                       │ • insert    │
-                       │ • update    │
-                       │ • delete    │
-                       │ • export    │
+                       │ • fields    │
+                       │ • summaries │
+                       │ • trends    │
+                       │ • analytics │
                        └─────────────┘
 ```
 
@@ -253,14 +253,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
@@ -359,12 +359,13 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 🏷️ Version History
 
-- **v0.1.0** - Initial release with 7 core tools
+- **v0.3.0** - Specialized analytics tools for stats-* indices (14 tools)
+- **v0.1.0** - Initial release
 - Full changelog: [CHANGELOG.md](CHANGELOG.md)
 
 ## 🔗 Links
 
-- [npm Package](https://www.npmjs.com/package/elasticsearch-mcp)
+- [npm Package](https://www.npmjs.com/package/elasticsearch-mcp-vsee)
 - [GitHub Repository](https://github.com/RajwardhanShinde/elk-mcp)
 - [Issue Tracker](https://github.com/RajwardhanShinde/elk-mcp/issues)
 - [Elasticsearch Documentation](https://www.elastic.co/guide/)

package/build/server.d.ts

@@ -5,13 +5,16 @@ 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;
     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":"AAkBA,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;;IAiCzC,OAAO,CAAC,aAAa;IAkVrB,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":"AAqBA,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;;IAoCzD,OAAO,CAAC,aAAa;IAkcrB,OAAO,CAAC,qBAAqB;IAoCvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAED,eAAe,gBAAgB,CAAC"}