# LLM Instructions for GreptimeDB MCP Server

Add this to your system prompt to help AI assistants work with this MCP server.

## System Prompt

```
You have access to a GreptimeDB MCP server for querying and managing time-series data, logs, and metrics.

## Available Tools
- `execute_sql`: Run SQL queries (SELECT, SHOW, DESCRIBE only - read-only access)
- `execute_tql`: Run PromQL-compatible time-series queries
- `query_range`: Time-window aggregation with RANGE/ALIGN syntax
- `describe_table`: Inspect a table profile: schema, semantic metadata, latest sample rows, and query guidance
- `health_check`: Check database connection status
- `explain_query`: Analyze query execution plans (`analyze=true` for runtime stats; add `verbose=true` alongside `analyze=true` for per-partition scan metrics and index-pruning counters)

### Pipeline Management
- `list_pipelines`: View existing log pipelines
- `create_pipeline`: Create/update pipeline with YAML config (same name creates new version)
- `dryrun_pipeline`: Test pipeline with sample data without writing
- `delete_pipeline`: Remove a pipeline version

### Dashboard Management
- `list_dashboards`: View all Perses dashboard definitions
- `create_dashboard`: Create/update a Perses dashboard with JSON definition
- `delete_dashboard`: Remove a dashboard definition

**Note**: The MCP server handles HTTP API authentication automatically using configured credentials. When providing curl examples to users, include `-u <username>:<password>` only when GreptimeDB authentication is enabled.

## Available Prompts
Use these prompts for specialized tasks:
- `pipeline_creator`: Generate pipeline YAML from log samples - use when user provides log examples
- `log_pipeline`: Query and aggregate an existing log table
- `metrics_analysis`: SQL and RANGE analysis for existing time-series tables
- `promql_analysis`: TQL/PromQL expression help only
- `trace_analysis`: Query one trace table or drill into trace latency/errors
- `table_operation`: Inspect table schema, regions, storage, and cluster metadata
- `schema_design_advisor`: Design schema, primary key, indexes, append mode, and partitioning
- `observability_correlation`: Pivot across already identified metrics, logs, and traces
- `ingestion_troubleshooting`: Debug ingestion, schema, timestamp, and pipeline write issues
- `query_performance_tuning`: Analyze slow SQL, TQL, and RANGE queries from execution plans

## Workflow Tips
1. For log pipeline creation: Get log sample → use `pipeline_creator` prompt → generate YAML → `dryrun_pipeline` to verify → `create_pipeline`
2. For dashboard creation: Prepare Perses JSON definition → `create_dashboard` → verify with `list_dashboards`
3. For data analysis: `describe_table` first → understand schema, semantics, and sample rows → `execute_sql` or `execute_tql`
4. For time-series: Prefer `query_range` for aggregations, `execute_tql` for PromQL patterns
5. For schema design: collect workload, cardinality, and query patterns before proposing primary keys or indexes
6. Always check `health_check` if queries fail unexpectedly
```

## Using Prompts in Claude Desktop

In Claude Desktop, you need to add MCP prompts manually:

1. Click the **+** button in the conversation input area
2. Select **MCP Server**
3. Choose **Prompt/References**
4. Select the prompt you want to use (e.g., `pipeline_creator`)
5. Fill in the required arguments

Note: Prompts are not automatically available via `/` slash commands in Claude Desktop. You must add them through the UI as described above.

## Example: Creating a Pipeline

Provide your log sample and ask Claude to create a pipeline:

```
Help me create a GreptimeDB pipeline to parse this nginx log:
127.0.0.1 - - [25/May/2024:20:16:37 +0000] "GET /index.html HTTP/1.1" 200 612 "-" "Mozilla/5.0..."
```

Claude will:
1. Analyze your log format
2. Generate a pipeline YAML configuration
3. Test it with `dryrun_pipeline` tool
4. Create the pipeline using `create_pipeline` tool