@influxdata/influxdb3-mcp-server 1.3.0

package/build/services/help.service.js

@@ -0,0 +1,241 @@
+/**
+ * InfluxDB Help Service
+ *
+ * Provides help content for InfluxDB operations. Simple in-memory text content
+ * that LLMs can easily navigate and extract relevant information from.
+ */
+export class HelpService {
+    /**
+     * Get InfluxDB help content
+     */
+    getHelp() {
+        return INFLUXDB_HELP_CONTENT;
+    }
+}
+const INFLUXDB_HELP_CONTENT = `
+INFLUXDB MCP SERVER HELP
+
+=== LINE PROTOCOL WRITING ===
+
+Line Protocol Format:
+measurement,tag1=value1,tag2=value2 field1=value1,field2=value2 timestamp
+
+Examples:
+- temperature,location=office value=23.5 1640995200000000000
+- sensor_data,device=sensor1,location=room1 temperature=22.5,humidity=45.2,status="ok"
+- cpu_usage,host=server1,region=us-east cpu_percent=85.2,memory_percent=67.1 1640995200000000000
+
+Rules:
+- Tags are indexed metadata (strings only), fields contain actual data
+- Tag values cannot contain spaces, use quotes for field string values
+- Timestamp is optional (nanoseconds since Unix epoch)
+- Escape special characters in tag values: spaces, commas, equals signs
+- Multiple measurements can be written in one call (separate by newlines)
+
+Common Errors:
+- Missing field (at least one field required)
+- Invalid timestamp format
+- Unescaped special characters in tag values
+- Retention period violations (Cloud instances): Writing data outside retention window
+
+=== QUERYING DATA ===
+
+SQL Syntax for InfluxDB v3:
+SELECT field1, field2 FROM measurement WHERE time >= 'timestamp' AND tag1 = 'value'
+
+Time Filtering:
+- WHERE time >= '2024-01-01T00:00:00Z'
+- WHERE time >= now() - interval '1 hour'
+- WHERE time BETWEEN '2024-01-01' AND '2024-01-02'
+
+Common Queries:
+- List measurements: SELECT DISTINCT table_name FROM information_schema.measurements
+- Get schema: DESCRIBE measurement_name
+- Recent data: SELECT * FROM measurement ORDER BY time DESC LIMIT 10
+- Aggregates: SELECT AVG(field1), MAX(field2) FROM measurement WHERE time >= now() - interval '1 day'
+
+Cloud Dedicated & Cloud Serverless Additional Requirements:
+- CAST aggregations: Use CAST(COUNT(*) AS DOUBLE), CAST(AVG(field) AS DOUBLE), etc.
+- GROUP BY compliance: Include all grouped columns in SELECT clause
+- Information schema: Use SELECT DISTINCT table_name FROM information_schema.columns WHERE table_schema = 'iox'
+- Schema queries: SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'measurement' AND table_schema = 'iox'
+- Required for: COUNT, SUM, AVG, MIN, MAX aggregation functions
+- Without CAST: Aggregations may return empty results or be missing from response
+
+Cloud Examples with CAST:
+- Count records: SELECT building, CAST(COUNT(*) AS DOUBLE) AS count FROM sensors GROUP BY building
+- Averages: SELECT region, CAST(AVG(cpu_usage) AS DOUBLE) AS avg_cpu FROM metrics GROUP BY region
+- Mixed aggregations: SELECT service, CAST(SUM(requests) AS DOUBLE) AS total_requests, CAST(AVG(response_time) AS DOUBLE) AS avg_response FROM app_metrics GROUP BY service
+
+Performance Tips:
+- Always include time filters for better performance
+- Use specific field names instead of SELECT *
+- Index on tags for filtering, not fields
+- Use LIMIT for large datasets to avoid memory issues
+- Test with COUNT(*) first to check data size before complex queries
+
+=== TOKEN MANAGEMENT ===
+
+Token Types:
+1. Operator Token: Super admin with full system access (only one per instance)
+2. Named Admin Tokens: Administrative access, can manage resource tokens but not other admin tokens
+3. Resource Tokens: Limited to specific databases with read/write permissions
+
+Available Operations:
+- Create named admin tokens: create_admin_token tool
+- Create resource tokens: create_resource_token tool  
+- List admin tokens: list_admin_tokens tool (filter by name)
+- List resource tokens: list_resource_tokens tool (filter by name, database, order by various fields)
+- Delete any token: delete_token tool (provide exact token name)
+- Regenerate operator token: regenerate_operator_token tool (⚠️ DANGEROUS - see admin tokens section)
+
+Security Best Practices:
+- Use resource tokens for applications (principle of least privilege)
+- Named admin tokens for administrative tasks including resource token management
+- Operator token only for critical system operations and admin token management
+- Set expiration times when possible (resource tokens support expiry_secs)
+- Rotate tokens regularly
+- Store tokens securely (environment variables, not in code)
+
+Token Permissions Format:
+- Operator: "*:*:*" (all permissions including admin token management)
+- Named Admin: "*:*:*" (all permissions except managing other admin tokens)
+- Resource: "database1:read,write" or "database1:read" etc.
+
+=== ADMIN TOKENS ===
+
+Admin Token Types:
+1. Operator Token: Super admin with full permissions including admin token management
+2. Named Admin Tokens: Administrative permissions, can manage resource tokens but not other admin tokens
+
+Named Admin Token Operations:
+- Create: Use create_admin_token tool (optionally provide name)
+- List: Use list_admin_tokens tool (can filter by token name - partial match)
+- Delete: Use delete_token tool (provide exact token name)
+
+Operator Token Operations:
+- Regenerate: Use regenerate_operator_token tool (⚠️ USE WITH EXTREME CAUTION)
+
+Key Differences:
+- Operator token: Can create/delete/manage ALL tokens (admin and resource tokens)
+- Named admin tokens: Full database and system access, can manage resource tokens but cannot manage other admin tokens
+- Both have "*:*:*" permissions but operator has additional admin token management capabilities
+
+Use Cases for Named Admin Tokens:
+- Database management
+- User administration
+- Resource token management (create, list, delete resource tokens)
+- System configuration
+- Backup operations
+- Dedicated token management role (create a named admin specifically for managing resource tokens)
+
+⚠️ OPERATOR TOKEN REGENERATION WARNING:
+The regenerate_operator_token tool will:
+- Invalidate the current operator token immediately
+- Generate a new operator token  
+- Require updating INFLUX_TOKEN environment variable
+- Require restarting the MCP server
+- Cannot be undone (irreversible operation)
+Use only when absolutely necessary and ensure you can update the environment!
+
+=== RESOURCE TOKENS ===
+
+Resource Token Operations:
+- Create: Use create_resource_token tool with specific databases and actions
+- List: Use list_resource_tokens tool with filtering options:
+  * Filter by database name (partial match)
+  * Filter by token name (partial match)  
+  * Order by: created_at, token_id, or name
+  * Order direction: ASC or DESC (default ASC)
+- Delete: Use delete_token tool (provide exact token name)
+
+Scope to specific databases with limited permissions.
+
+Permission Examples:
+- Read-only: databases=["mydb"], actions=["read"]
+- Write-only: databases=["mydb"], actions=["write"]  
+- Full access: databases=["mydb"], actions=["read", "write"]
+- Multi-database: databases=["db1", "db2"], actions=["read", "write"]
+
+Best Practices:
+- Use separate tokens for different applications
+- Grant minimal required permissions
+- Set expiration times for temporary access (expiry_secs parameter)
+- Use descriptive names for token identification
+
+=== DATABASE MANAGEMENT ===
+
+Database Operations:
+- Create: Use create_database tool (provide database name, optional configuration parameters)
+- Update: Use update_database tool (Cloud Dedicated and Cloud Serverless only - see parameters below)
+- List: Use list_databases tool (no parameters - shows all databases)
+- Delete: Use delete_database tool (provide exact database name - PERMANENT, no recovery)
+
+Cloud Dedicated Parameters (create_database and update_database):
+- maxTables: Maximum number of tables (default: 500)
+- maxColumnsPerTable: Maximum columns per table (default: 200)
+- retentionPeriod: Retention period in nanoseconds (default: 0 = no expiration)
+
+Cloud Serverless Parameters (create_database and update_database):
+- description: Bucket description for documentation
+- retentionPeriod: Retention period in nanoseconds (default: 30 days)
+- newName: New bucket name (update_database only - for renaming buckets)
+
+Naming Rules:
+- Alphanumeric characters, dashes (-), underscores (_), forward slashes (/)
+- Must start with letter or number
+- Maximum 64 characters
+- Case sensitive
+
+Database Structure:
+- Contains measurements (tables)
+- Each measurement has tags (indexed) and fields (data)
+- Schema evolves dynamically with data (all InfluxDB versions)
+
+Best Practices:
+- Use descriptive database names
+- Separate different data types into different databases
+- Consider retention policies for large datasets
+- Regular backups before deletion operations
+
+Note: The list_databases tool returns all available databases with their details.
+No filtering or querying parameters are supported - it shows the complete list.
+
+=== TROUBLESHOOTING ===
+
+Connection Issues:
+1. Use health_check tool for comprehensive instance status (flexible assessment based on available endpoints)
+2. Verify INFLUX_URL environment variable
+3. Confirm INFLUX_TOKEN has proper permissions
+4. Test network connectivity to InfluxDB server
+
+Health Check Notes:
+- Different InfluxDB product types support different endpoints
+- Cloud Dedicated does not have /health endpoint available
+- Different tokens may have not access to certain endpoints
+- If ANY check passes (connection, /health, /ping), instance is considered operational
+
+Authentication Errors:
+- Token expired or invalid
+- Insufficient permissions for operation
+- Token not properly configured for target database
+
+Query Errors:
+- Invalid SQL syntax (InfluxDB uses SQL, not InfluxQL)
+- Missing time filters causing performance issues
+- Incorrect measurement or field names
+- Wrong database specified
+
+Write Errors:
+- Invalid line protocol format
+- Missing required fields
+- Tag value formatting issues
+- Database doesn't exist
+- Retention period violations (Cloud instances): Data timestamp outside allowed retention window
+
+Performance Issues:
+- Add time range filters to queries
+- Use appropriate aggregation functions
+- Index usage (tags vs fields)
+- Consider data retention policies
+`;

package/build/services/http-client.service.js

@@ -0,0 +1,109 @@
+/**
+ * HTTP Client Service
+ *
+ * Simple axios-based HTTP client for making authenticated requests to InfluxDB API
+ */
+import axios from "axios";
+import { InfluxProductType } from "../helpers/enums/influx-product-types.enum.js";
+import { Agent } from "https";
+export class HttpClientService {
+    axiosInstance;
+    constructor(baseURL, token, influxType) {
+        const axiosConfig = {
+            baseURL: baseURL?.replace(/\/$/, ""),
+            timeout: 30000,
+            headers: this.createAuthHeaders(token, influxType),
+        };
+        if (influxType === InfluxProductType.Clustered) {
+            axiosConfig.httpsAgent = new Agent({
+                rejectUnauthorized: false,
+            });
+        }
+        this.axiosInstance = axios.create(axiosConfig);
+        this.axiosInstance.interceptors.response.use((response) => {
+            return response;
+        }, (error) => {
+            return Promise.reject(error);
+        });
+    }
+    /**
+     * Create authentication headers with appropriate format for InfluxDB type
+     */
+    createAuthHeaders(token, influxType) {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        if (token?.trim()) {
+            if (influxType === InfluxProductType.CloudServerless) {
+                headers["Authorization"] = `Token ${token}`;
+            }
+            else {
+                headers["Authorization"] = `Bearer ${token}`;
+            }
+        }
+        return headers;
+    }
+    /**
+     * Make a GET request
+     */
+    async get(url, config) {
+        const response = await this.axiosInstance.get(url, config);
+        return response.data;
+    }
+    /**
+     * Make a POST request
+     */
+    async post(url, data, config) {
+        const response = await this.axiosInstance.post(url, data, config);
+        return response.data;
+    }
+    /**
+     * Make a PUT request
+     */
+    async put(url, data, config) {
+        const response = await this.axiosInstance.put(url, data, config);
+        return response.data;
+    }
+    /**
+     * Make a DELETE request
+     */
+    async delete(url, config) {
+        const deleteConfig = {
+            ...config,
+            headers: {
+                ...config?.headers,
+                Connection: "close",
+            },
+        };
+        try {
+            const response = await this.axiosInstance.delete(url, deleteConfig);
+            return response.data;
+        }
+        catch (error) {
+            if (error.message?.includes("aborted")) {
+                return {};
+            }
+            throw error;
+        }
+    }
+    /**
+     * Make a PATCH request
+     */
+    async patch(url, data, config) {
+        const response = await this.axiosInstance.patch(url, data, config);
+        return response.data;
+    }
+    /**
+     * Get the underlying axios instance for advanced usage
+     */
+    getAxiosInstance() {
+        return this.axiosInstance;
+    }
+    /**
+     * Create a configured instance for InfluxDB API calls
+     */
+    static createInfluxClient(baseUrl, token, influxType) {
+        return new HttpClientService(baseUrl, token, influxType);
+    }
+}

package/build/services/influxdb-master.service.js

@@ -0,0 +1,117 @@
+/**
+ * Master InfluxDB Service
+ *
+ * Orchestrates all specialized InfluxDB services and provides a unified interface
+ */
+import { BaseConnectionService, } from "./base-connection.service.js";
+import { QueryService } from "./query.service.js";
+import { WriteService } from "./write.service.js";
+import { DatabaseManagementService } from "./database-management.service.js";
+import { TokenManagementService } from "./token-management.service.js";
+import { CloudTokenManagementService } from "./cloud-token-management.service.js";
+import { SchemaManagementService } from "./serverless-schema-management.service.js";
+import { HelpService } from "./help.service.js";
+import { ContextFileService } from "./context-file.service.js";
+export class InfluxDBMasterService {
+    baseConnection;
+    queryService;
+    writeService;
+    databaseService;
+    tokenService;
+    cloudTokenService;
+    schemaService;
+    helpService;
+    contextFileService;
+    constructor(config) {
+        this.baseConnection = new BaseConnectionService(config);
+        this.queryService = new QueryService(this.baseConnection);
+        this.writeService = new WriteService(this.baseConnection);
+        this.databaseService = new DatabaseManagementService(this.baseConnection);
+        this.tokenService = new TokenManagementService(this.baseConnection);
+        this.cloudTokenService = new CloudTokenManagementService(this.baseConnection);
+        this.schemaService = new SchemaManagementService(this.baseConnection);
+        this.helpService = new HelpService();
+        this.contextFileService = new ContextFileService();
+    }
+    // ===== Connection & Health Methods =====
+    /**
+     * Get connection information
+     */
+    getConnectionInfo() {
+        return this.baseConnection.getConnectionInfo();
+    }
+    /**
+     * Ping InfluxDB instance and return version/type info
+     */
+    async ping() {
+        return this.baseConnection.ping();
+    }
+    /**
+     * Get health status
+     */
+    async getHealthStatus() {
+        return this.baseConnection.getHealthStatus();
+    }
+    // ===== Query Service Access =====
+    get query() {
+        return this.queryService;
+    }
+    // ===== Write Service Access =====
+    get write() {
+        return this.writeService;
+    }
+    // ===== Database Management Service Access =====
+    get database() {
+        return this.databaseService;
+    }
+    // ===== Token Management Service Access =====
+    get token() {
+        return this.tokenService;
+    }
+    /**
+     * Get the token management service instance
+     */
+    getTokenManagementService() {
+        return this.tokenService;
+    }
+    // ===== Cloud Token Management Service Access =====
+    get cloudToken() {
+        return this.cloudTokenService;
+    }
+    /**
+     * Get the cloud token management service instance
+     */
+    getCloudTokenManagementService() {
+        return this.cloudTokenService;
+    }
+    // ===== Schema Management Service Access =====
+    get schema() {
+        return this.schemaService;
+    }
+    /**
+     * Get the schema management service instance
+     */
+    getSchemaManagementService() {
+        return this.schemaService;
+    }
+    // ===== Help Service Access =====
+    get help() {
+        return this.helpService;
+    }
+    // ===== Context File Service Access =====
+    get contextFile() {
+        return this.contextFileService;
+    }
+    /**
+     * Get the context file service instance
+     */
+    getContextFileService() {
+        return this.contextFileService;
+    }
+    /**
+     * Get the main client instance (for advanced operations)
+     */
+    getClient() {
+        return this.baseConnection.getClient();
+    }
+}