201 lines
7.0 KiB
Markdown
201 lines
7.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
InfluxDB MCP Server - A Model Context Protocol server that enables AI assistants to interact with InfluxDB v2 time-series databases. Built with TypeScript, using the MCP SDK, axios for HTTP, and zod for validation.
|
|
|
|
## Build and Development Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build TypeScript to JavaScript
|
|
npm run build
|
|
|
|
# Watch mode for development (rebuilds on file changes)
|
|
npm run watch
|
|
|
|
# Run the compiled server
|
|
npm start
|
|
|
|
# Run with custom environment variables
|
|
INFLUX_URL=http://localhost:8086 INFLUX_TOKEN=your_token INFLUX_ORG=your_org node dist/index.js
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
### Three-Layer Structure
|
|
|
|
1. **index.ts** - MCP Server Implementation
|
|
- Defines MCP resources (read-only URIs like `influx://health`, `influx://buckets`)
|
|
- Defines MCP tools (actions like `query_flux`, `write_data`, `create_bucket`)
|
|
- Handles tool execution and resource reading via request handlers
|
|
- Environment variable validation using Zod schema
|
|
- Startup health check verifies InfluxDB connection before serving
|
|
|
|
2. **influx-client.ts** - InfluxDB REST API Client
|
|
- Axios-based HTTP client with token authentication
|
|
- Methods for all InfluxDB v2 API endpoints (query, write, buckets, orgs, tasks, dashboards)
|
|
- Query response parsing from JSON format
|
|
- Centralized error formatting via `formatError()` static method
|
|
- Schema discovery using Flux `schema.measurements()`, `schema.measurementTagKeys()`, `schema.measurementFieldKeys()`
|
|
|
|
3. **types.ts** - TypeScript Type Definitions
|
|
- Complete interfaces for all InfluxDB entities
|
|
- InfluxConfig, HealthStatus, Organization, Bucket, Task, Dashboard
|
|
- QueryResult, QueryTable for query responses
|
|
- BucketSchema, Measurement, FieldInfo for schema discovery
|
|
- WritePrecision type: 'ns' | 'us' | 'ms' | 's'
|
|
|
|
### Communication Flow
|
|
|
|
```
|
|
MCP Client → stdio → InfluxDBMCPServer → InfluxDBClient → InfluxDB REST API
|
|
```
|
|
|
|
The server runs on stdio (stdin/stdout) for MCP protocol communication. All logging goes to stderr to avoid interfering with the protocol.
|
|
|
|
## Key Implementation Details
|
|
|
|
### Environment Configuration
|
|
|
|
Required environment variables validated at startup:
|
|
- `INFLUX_URL` - InfluxDB server URL (must be valid URL)
|
|
- `INFLUX_TOKEN` - Authentication token (required)
|
|
- `INFLUX_ORG` - Organization name (optional, can be provided per-request)
|
|
|
|
Configuration is validated using Zod schema in `loadConfig()` function.
|
|
|
|
### MCP Resources vs Tools
|
|
|
|
**Resources** are read-only URIs that expose InfluxDB state:
|
|
- `influx://health` - Server health
|
|
- `influx://buckets` - All buckets
|
|
- `influx://buckets/{id}` - Specific bucket
|
|
- `influx://orgs` - All organizations
|
|
- `influx://tasks` - Scheduled tasks
|
|
- `influx://dashboards` - Dashboards
|
|
|
|
**Tools** are actions that can modify state or query data:
|
|
- `query_flux` - Execute Flux queries (requires query string, optional org)
|
|
- `write_data` - Write line protocol data (requires bucket, org, data, optional precision)
|
|
- `create_bucket` - Create bucket (requires name, org_id, optional retention_seconds, description)
|
|
- `delete_bucket` - Delete bucket (requires bucket_id)
|
|
- `list_measurements` - List measurements in bucket (requires bucket, optional start/stop)
|
|
- `get_bucket_schema` - Get schema info (requires bucket, optional start/stop)
|
|
|
|
### Error Handling Pattern
|
|
|
|
All errors are centralized through `InfluxDBClient.formatError()`:
|
|
- Axios errors → extracted response message or request error
|
|
- InfluxDB API errors → formatted with status code and message
|
|
- All errors wrapped in `McpError` with appropriate error codes
|
|
|
|
### Query Response Parsing
|
|
|
|
InfluxDB returns JSON when Accept header is `application/json`. The `parseQueryResponse()` method in influx-client.ts handles multiple response formats:
|
|
- Array of records
|
|
- Single object
|
|
- Nested structure with `records` array
|
|
|
|
Returns structured `QueryResult` with tables containing columns and records.
|
|
|
|
### Schema Discovery Implementation
|
|
|
|
`getBucketSchema()` performs multiple queries:
|
|
1. Lists all measurements using `schema.measurements()`
|
|
2. For each measurement, queries tags and fields in parallel
|
|
3. Combines results into structured `BucketSchema`
|
|
|
|
Time ranges default to -7d for schema, -30d for measurements.
|
|
|
|
## Line Protocol Format
|
|
|
|
When writing data, use InfluxDB line protocol:
|
|
```
|
|
measurement[,tag=value...] field=value[,field=value...] [timestamp]
|
|
```
|
|
|
|
Examples:
|
|
```
|
|
temperature,location=office value=22.5
|
|
cpu,host=server1 usage=45.2 1672531200000000000
|
|
weather,location=garden temperature=22.5,humidity=65.2
|
|
```
|
|
|
|
## TypeScript Configuration
|
|
|
|
- Target: ES2022
|
|
- Module: Node16 (ES modules with .js extensions in imports)
|
|
- Strict mode enabled
|
|
- Source maps and declarations generated
|
|
- Output: `dist/` directory
|
|
|
|
All imports must use `.js` extension (e.g., `import { X } from './types.js'`) even though source files are `.ts`.
|
|
|
|
## Common Development Tasks
|
|
|
|
### Adding a New MCP Tool
|
|
|
|
1. Add tool definition to `ListToolsRequestSchema` handler in index.ts
|
|
2. Add case to switch statement in `CallToolRequestSchema` handler
|
|
3. Implement method in InfluxDBClient if calling new InfluxDB API
|
|
4. Add types to types.ts if needed
|
|
|
|
### Adding a New MCP Resource
|
|
|
|
1. Add resource definition to `ListResourcesRequestSchema` handler
|
|
2. Add URI handling in `ReadResourceRequestSchema` handler
|
|
3. Implement method in InfluxDBClient to fetch data
|
|
4. Return formatted JSON response
|
|
|
|
### Testing Changes
|
|
|
|
After modifying code:
|
|
1. Run `npm run build` to compile
|
|
2. Test with: `INFLUX_URL=... INFLUX_TOKEN=... INFLUX_ORG=... node dist/index.js`
|
|
3. Server will log connection success to stderr
|
|
4. Test in Claude Desktop or other MCP client
|
|
|
|
## Flux Query Language Notes
|
|
|
|
Flux is InfluxDB's query language. Common patterns:
|
|
|
|
```flux
|
|
// Basic range query
|
|
from(bucket: "my-bucket")
|
|
|> range(start: -1h)
|
|
|> filter(fn: (r) => r._measurement == "cpu")
|
|
|
|
// Aggregation
|
|
from(bucket: "my-bucket")
|
|
|> range(start: -24h)
|
|
|> aggregateWindow(every: 1h, fn: mean)
|
|
|
|
// Schema discovery
|
|
import "influxdata/influxdb/schema"
|
|
schema.measurements(bucket: "my-bucket", start: -30d)
|
|
```
|
|
|
|
Time formats: Relative (`-1h`, `-7d`, `-30d`) or absolute (`2024-01-01T00:00:00Z`)
|
|
|
|
## Important Constraints
|
|
|
|
- **Bucket Creation**: Requires organization ID (not name). Use `getOrgByName()` or read `influx://orgs` resource first.
|
|
- **Query Organization**: If `INFLUX_ORG` not set in environment, must provide `org` parameter to `query_flux` tool.
|
|
- **Write Precision**: Defaults to nanoseconds ('ns'). Timestamps must match specified precision.
|
|
- **Server Communication**: MCP protocol on stdout/stdin, all logs to stderr.
|
|
- **No Pagination**: Large result sets not automatically paginated. Users should specify appropriate time ranges.
|
|
|
|
## Code Style
|
|
|
|
- Use async/await for all I/O operations
|
|
- Validate inputs before processing
|
|
- Return structured JSON for tool responses
|
|
- Include descriptive error messages
|
|
- TypeScript strict mode compliance
|
|
- ES modules with explicit .js imports
|