@influxdata/influxdb3-mcp-server 1.3.0

package/build/tools/categories/health.tools.js

@@ -0,0 +1,75 @@
+/**
+ * Health and Monitoring Tools
+ */
+import { z } from "zod";
+export function createHealthTools(influxService) {
+    return [
+        {
+            name: "health_check",
+            description: "Check current connection status to the InfluxDB instance. Returns connection status, configuration, and available endpoint results. Health assessment is flexible - if any check passes (client initialization, /health endpoint, or /ping), the instance is considered healthy. Available checks depend on the InfluxDB product type and token configuration.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                additionalProperties: false,
+            },
+            zodSchema: z.object({}),
+            handler: async () => {
+                try {
+                    const connectionInfo = influxService.getConnectionInfo();
+                    const influxType = influxService["baseConnection"]?.["config"]?.influx?.type ||
+                        "unknown";
+                    let healthStatus = null;
+                    let pingResult = null;
+                    let hasAnySuccess = false;
+                    try {
+                        healthStatus = await influxService.getHealthStatus();
+                        if (healthStatus.status === "pass")
+                            hasAnySuccess = true;
+                    }
+                    catch (_error) { }
+                    try {
+                        pingResult = await influxService.ping();
+                        if (pingResult.ok === true)
+                            hasAnySuccess = true;
+                    }
+                    catch (_error) { }
+                    if (connectionInfo.isDataClientInitialized)
+                        hasAnySuccess = true;
+                    const healthInfo = {
+                        timestamp: new Date().toISOString(),
+                        connection: {
+                            status: hasAnySuccess ? "healthy" : "failed",
+                            url: connectionInfo.url,
+                            hasToken: connectionInfo.hasToken,
+                            database: connectionInfo.database,
+                            type: influxType,
+                        },
+                        health: healthStatus,
+                        ping: pingResult,
+                    };
+                    const statusText = hasAnySuccess ? "✅ HEALTHY" : "❌ FAILED";
+                    const detailsText = JSON.stringify(healthInfo, null, 2);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `InfluxDB Health Check: ${statusText}\n\nNote: Health assessment is based on available endpoints for your InfluxDB product type and token configuration. If any check passes, the instance is considered operational.\n\nConnection Details:\n${detailsText}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error during health check: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+    ];
+}

package/build/tools/categories/help.tools.js

@@ -0,0 +1,104 @@
+/**
+ * Help and Documentation Tools
+ */
+import { z } from "zod";
+export function createHelpTools(influxService) {
+    return [
+        {
+            name: "load_database_context",
+            description: "Check for and load custom database context if available. Always check this first as it can significantly speed up analysis and clarify data nuances. User-provided context is optional but when present, it contains valuable information about database structure, business context, or personal notes that can guide more accurate analysis.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                additionalProperties: false,
+            },
+            zodSchema: z.object({}),
+            handler: async (_args) => {
+                try {
+                    const contextFile = await influxService.contextFile.loadContextFile();
+                    if (!contextFile) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No custom context file found.
+
+User-provided context is optional. If users want to provide context, they can:
+1. Create a file in /context/ folder (any .json, .txt, .md file)
+2. Or create a file with 'context' in the name (.json, .txt, .md)
+
+Context can include anything helpful:
+- Database schema and measurement descriptions
+- Business context or data purposes
+- Simple notes about their setup
+- Personal context ("I'm tracking my daily activities")
+
+Proceed with database exploration using available tools.`,
+                                },
+                            ],
+                        };
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Custom context loaded from: ${contextFile.name}.${contextFile.extension}
+
+${contextFile.content}
+
+Use this context to guide subsequent database operations and analysis.`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error loading context: ${error.message}
+
+Context is optional - proceed with database exploration using available tools.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "get_help",
+            description: "Get help and troubleshooting guidance for InfluxDB operations. Supports specific categories or keyword search.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                additionalProperties: false,
+            },
+            zodSchema: z.object({}),
+            handler: async (_args) => {
+                try {
+                    const helpContent = influxService.help.getHelp();
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: helpContent,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error getting help: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+    ];
+}

package/build/tools/categories/query.tools.js

@@ -0,0 +1,180 @@
+/**
+ * Query and Schema Tools
+ */
+import { z } from "zod";
+export function createQueryTools(influxService) {
+    return [
+        {
+            name: "execute_query",
+            description: `Execute a SQL query against an InfluxDB database (all versions). Returns results in the specified format (defaults to JSON).
+
+Large Dataset Warning: InfluxDB might contain massive time-series data. Always use COUNT(*) first to check size, then LIMIT/OFFSET for large results (>1000 rows).
+
+Cloud Dedicated/Clustered & Cloud Serverless (v3) Requirements:
+- GROUP BY: Include all group columns in SELECT (e.g., SELECT place, COUNT(*) ... GROUP BY place)
+- Aggregations: Cast and alias COUNT (e.g., CAST(COUNT(*) AS DOUBLE) AS count)
+- Note: Both products require CAST for all aggregation functions (COUNT, SUM, AVG, MIN, MAX) to ensure results appear properly in response`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    database: {
+                        type: "string",
+                        description: "Name of the database/bucket to query",
+                    },
+                    query: {
+                        type: "string",
+                        description: "SQL query to execute.",
+                    },
+                    format: {
+                        type: "string",
+                        enum: ["json", "csv", "parquet", "jsonl", "pretty"],
+                        description: "Output format for query results",
+                        default: "json",
+                    },
+                },
+                required: ["database", "query"],
+                additionalProperties: false,
+            },
+            zodSchema: z.object({
+                database: z.string().describe("Name of the database/bucket to query"),
+                query: z.string().describe("SQL query to execute"),
+                format: z
+                    .enum(["json", "csv", "parquet", "jsonl", "pretty"])
+                    .optional()
+                    .default("json"),
+            }),
+            handler: async (args) => {
+                try {
+                    const result = await influxService.query.executeQuery(args.query, args.database, {
+                        format: args.format,
+                    });
+                    let resultText = "";
+                    if (args.format === "json") {
+                        resultText = `Query executed successfully:\n${JSON.stringify(result, null, 2)}`;
+                    }
+                    else {
+                        resultText = `Query executed successfully (${args.format} format):\n${result}`;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: resultText,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "get_measurements",
+            description: "Get a list of all measurements (tables) in a database/bucket (all versions). Uses the InfluxDB information_schema.columns to discover tables.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    database: {
+                        type: "string",
+                        description: "Name of the database/bucket to list measurements from",
+                    },
+                },
+                required: ["database"],
+                additionalProperties: false,
+            },
+            zodSchema: z.object({
+                database: z
+                    .string()
+                    .describe("Name of the database/bucket to list measurements from"),
+            }),
+            handler: async (args) => {
+                try {
+                    const measurements = await influxService.query.getMeasurements(args.database);
+                    const measurementList = measurements.map((m) => m.name).join(", ");
+                    const count = measurements.length;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Found ${count} measurement${count !== 1 ? "s" : ""} in database '${args.database}':\n${measurementList || "None"}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "get_measurement_schema",
+            description: "Get the schema (column information) for a specific measurement/table (all versions). Shows column names, types, and categories (time/tag/field).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    database: {
+                        type: "string",
+                        description: "Name of the database/bucket containing the measurement",
+                    },
+                    measurement: {
+                        type: "string",
+                        description: "Name of the measurement to describe",
+                    },
+                },
+                required: ["database", "measurement"],
+                additionalProperties: false,
+            },
+            zodSchema: z.object({
+                database: z
+                    .string()
+                    .describe("Name of the database/bucket containing the measurement"),
+                measurement: z.string().describe("Name of the measurement to describe"),
+            }),
+            handler: async (args) => {
+                try {
+                    const schema = await influxService.query.getMeasurementSchema(args.measurement, args.database);
+                    const columnInfo = schema.columns
+                        .map((col) => `  - ${col.name}: ${col.type} (${col.category})`)
+                        .join("\n");
+                    const count = schema.columns.length;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Schema for measurement '${args.measurement}' in database '${args.database}':\n${count} column${count !== 1 ? "s" : ""}:\n${columnInfo}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+    ];
+}

package/build/tools/categories/schema.tools.js

@@ -0,0 +1,308 @@
+/**
+ * Schema Management Tools for InfluxDB Cloud Serverless
+ *
+ * Provides tools for managing measurement schemas in Cloud Serverless buckets.
+ * These tools are only available for Cloud Serverless instances with explicit schema type.
+ * Explicit schema type is not implemented in v3 InfluxDB cloud serverless as of now.
+ */
+import { z } from "zod";
+export function createSchemaTools(influxService) {
+    return [
+        {
+            name: "serverless_list_schemas",
+            description: "List all measurement schemas in a Cloud Serverless bucket. Only available for buckets with explicit schema type. Shows schema names, column definitions, and metadata.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    bucketName: {
+                        type: "string",
+                        description: "Name of the bucket to list schemas from",
+                    },
+                },
+                required: ["bucketName"],
+                additionalProperties: false,
+            },
+            zodSchema: z.object({
+                bucketName: z
+                    .string()
+                    .describe("Name of the bucket to list schemas from"),
+            }),
+            handler: async (args) => {
+                try {
+                    const schemas = await influxService.schema.listSchemas(args.bucketName);
+                    const schemaList = schemas.map((schema) => schema.name).join(", ");
+                    const count = schemas.length;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Found ${count} schema${count !== 1 ? "s" : ""} in bucket '${args.bucketName}':\n${schemaList || "None"}\n\nSchema details:\n${JSON.stringify(schemas, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "serverless_get_schema",
+            description: "Get detailed information about a specific measurement schema in a Cloud Serverless bucket. Shows column definitions, data types, and schema metadata.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    bucketName: {
+                        type: "string",
+                        description: "Name of the bucket containing the schema",
+                    },
+                    schemaName: {
+                        type: "string",
+                        description: "Name of the measurement schema to retrieve",
+                    },
+                },
+                required: ["bucketName", "schemaName"],
+                additionalProperties: false,
+            },
+            zodSchema: z.object({
+                bucketName: z
+                    .string()
+                    .describe("Name of the bucket containing the schema"),
+                schemaName: z
+                    .string()
+                    .describe("Name of the measurement schema to retrieve"),
+            }),
+            handler: async (args) => {
+                try {
+                    const schema = await influxService.schema.getSchema(args.bucketName, args.schemaName);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Schema '${args.schemaName}' details:\n\n${JSON.stringify(schema, null, 2)}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "serverless_create_schema",
+            description: "Create a new measurement schema in a Cloud Serverless bucket with explicit schema type. Define columns with their types (tag, field, timestamp) and data types.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    bucketName: {
+                        type: "string",
+                        description: "Name of the bucket to create the schema in",
+                    },
+                    schemaName: {
+                        type: "string",
+                        description: "Name of the measurement schema to create",
+                    },
+                    columns: {
+                        type: "array",
+                        description: "Array of column definitions for the schema",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: {
+                                    type: "string",
+                                    description: "Column name",
+                                },
+                                type: {
+                                    type: "string",
+                                    enum: ["tag", "field", "timestamp"],
+                                    description: "Column type: tag (indexed metadata), field (actual data), or timestamp",
+                                },
+                                dataType: {
+                                    type: "string",
+                                    enum: ["string", "float", "integer", "boolean", "time"],
+                                    description: "Data type for the column (required for field columns, optional for others)",
+                                },
+                            },
+                            required: ["name", "type"],
+                            additionalProperties: false,
+                        },
+                        minItems: 1,
+                    },
+                },
+                required: ["bucketName", "schemaName", "columns"],
+                additionalProperties: false,
+            },
+            zodSchema: z.object({
+                bucketName: z
+                    .string()
+                    .describe("Name of the bucket to create the schema in"),
+                schemaName: z
+                    .string()
+                    .describe("Name of the measurement schema to create"),
+                columns: z
+                    .array(z.object({
+                    name: z.string().describe("Column name"),
+                    type: z
+                        .enum(["tag", "field", "timestamp"])
+                        .describe("Column type"),
+                    dataType: z
+                        .enum(["string", "float", "integer", "boolean", "time"])
+                        .optional()
+                        .describe("Data type for the column"),
+                }))
+                    .min(1)
+                    .describe("Array of column definitions"),
+            }),
+            handler: async (args) => {
+                try {
+                    const config = {
+                        name: args.schemaName,
+                        bucketName: args.bucketName,
+                        columns: args.columns,
+                    };
+                    await influxService.schema.createSchema(config);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Schema '${args.schemaName}' created successfully in bucket '${args.bucketName}'`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+        {
+            name: "serverless_update_schema",
+            description: "Add new columns to an existing measurement schema in a Cloud Serverless bucket. IMPORTANT: You can only ADD new columns, not modify existing ones. The endpoint requires ALL columns (existing + new) to be sent. Use get_schema first to retrieve current columns, then include them along with new columns in this update.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    bucketName: {
+                        type: "string",
+                        description: "Name of the bucket containing the schema",
+                    },
+                    schemaName: {
+                        type: "string",
+                        description: "Current name of the measurement schema to update",
+                    },
+                    columns: {
+                        type: "array",
+                        description: "Complete array of ALL column definitions (existing columns + new columns to add). Must include all current columns plus any new ones you want to add.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                name: {
+                                    type: "string",
+                                    description: "Column name",
+                                },
+                                type: {
+                                    type: "string",
+                                    enum: ["tag", "field", "timestamp"],
+                                    description: "Column type: tag (indexed metadata), field (actual data), or timestamp",
+                                },
+                                dataType: {
+                                    type: "string",
+                                    enum: ["string", "float", "integer", "boolean", "time"],
+                                    description: "Data type for the column",
+                                },
+                            },
+                            required: ["name", "type"],
+                            additionalProperties: false,
+                        },
+                    },
+                },
+                required: ["bucketName", "schemaName"],
+                additionalProperties: false,
+            },
+            zodSchema: z.object({
+                bucketName: z
+                    .string()
+                    .describe("Name of the bucket containing the schema"),
+                schemaName: z
+                    .string()
+                    .describe("Current name of the measurement schema to update"),
+                columns: z
+                    .array(z.object({
+                    name: z.string().describe("Column name"),
+                    type: z
+                        .enum(["tag", "field", "timestamp"])
+                        .describe("Column type"),
+                    dataType: z
+                        .enum(["string", "float", "integer", "boolean", "time"])
+                        .optional()
+                        .describe("Data type for the column"),
+                }))
+                    .optional()
+                    .describe("Updated array of column definitions"),
+            }),
+            handler: async (args) => {
+                try {
+                    const success = await influxService.schema.updateSchema(args.bucketName, args.schemaName, {
+                        columns: args.columns,
+                    });
+                    if (success) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Schema '${args.schemaName}' updated successfully. New columns have been added to the existing schema.`,
+                                },
+                            ],
+                        };
+                    }
+                    else {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Failed to update schema '${args.schemaName}'.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            },
+        },
+    ];
+}