# 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