Skip to content
This repository was archived by the owner on Oct 25, 2026. It is now read-only.

Commit 84612a0

Browse files
thenodonthenodon
authored
Merge pull request #5 from thenodon/authentication
feat: add prompts
2 parents 71267f7 + 626d18c commit 84612a0

6 files changed

Lines changed: 1020 additions & 99 deletions

File tree

‎PROMPTS_GUIDE.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
MCP Prompts Guide
2+
-----
3+
4+
This document provides detailed documentation for the 5 MCP prompts in the Parseable MCP server.
5+
6+
# What are MCP Prompts?
7+
8+
MCP Prompts are pre-built, multi-step workflows that guide AI agents through common tasks.
9+
Instead of calling individual tools manually, prompts provide a structured approach to accomplishing complex operations.
10+
11+
When an AI agent receives a prompt, it gets detailed instructions on:
12+
- Which tools to call
13+
- In what order
14+
- What to analyze
15+
- What to report back
16+
17+
When using prompt, we can use natural language to ask questions related to our data:
18+
- "Check the health of the otellogs stream"
19+
- "Find errors in network_logstream from yesterday"
20+
- "Compare otellogs and monitor_logstream"
21+
- "Investigate the severity_text field"
22+
- "Find anomalies in the last 24 hours"
23+
24+
---
25+
# Available Prompts
26+
Agents can use the following pre-built prompts to guide their analysis:
27+
28+
## 1. analyze-errors
29+
30+
**Purpose:** Find and analyze error logs in a data stream.
31+
32+
**When to use:**
33+
- Investigating system errors or failures
34+
- Understanding error patterns over time
35+
- Troubleshooting production issues
36+
37+
**Required Arguments:**
38+
- `streamName` - Name of the data stream to analyze
39+
- `startTime` - Start time in ISO 8601 format (e.g., "2026-02-13T00:00:00Z")
40+
- `endTime` - End time in ISO 8601 format
41+
42+
**Optional Arguments:**
43+
- `errorField` - Specific field to check for errors (default: "body")
44+
45+
**What it does:**
46+
1. Gets the stream schema to understand available fields
47+
2. Queries for errors using pattern matching (error, exception, failed)
48+
3. Analyzes error distribution over time
49+
4. Identifies common error patterns and messages
50+
5. Provides recommendations for investigation
51+
52+
**Usage:**
53+
```
54+
"Find errors in the otellogs stream from yesterday"
55+
"Analyze errors in network_logstream from the last 24 hours"
56+
```
57+
58+
---
59+
## 2. stream-health-check
60+
61+
**Purpose:** Perform a comprehensive health assessment of a data stream.
62+
63+
**When to use:**
64+
- Regular stream monitoring
65+
- Checking if data ingestion is working
66+
- Verifying stream configuration
67+
- Identifying potential issues
68+
69+
**Required Arguments:**
70+
- `streamName` - Name of the data stream to check
71+
72+
**What it does:**
73+
1. Gets stream information (creation time, event timestamps)
74+
2. Gets stream statistics (ingestion rates, storage)
75+
3. Gets stream schema
76+
4. Analyzes:
77+
- Stream activity status (active/inactive)
78+
- Data freshness (time since last event)
79+
- Ingestion rates (events per day/hour)
80+
- Storage efficiency
81+
5. Reports warnings or concerns
82+
6. Provides optimization recommendations
83+
84+
**Usage:**
85+
```
86+
"Check the health of the otellogs stream"
87+
"Is the network_logstream receiving data?"
88+
```
89+
90+
---
91+
## 3. investigate-field
92+
93+
**Purpose:** Deep dive into a specific field's values and patterns.
94+
95+
**When to use:**
96+
- Understanding field distributions
97+
- Data quality analysis
98+
- Finding most common values
99+
- Checking for nulls or empty values
100+
101+
**Required Arguments:**
102+
- `streamName` - Name of the data stream
103+
- `fieldName` - Name of the field to investigate
104+
- `startTime` - Start time in ISO 8601 format
105+
- `endTime` - End time in ISO 8601 format
106+
107+
**What it does:**
108+
1. Verifies the field exists in the schema
109+
2. Counts total occurrences and unique values
110+
3. Gets top 20 most common values with counts
111+
4. Checks for null/empty values
112+
5. Calculates percentages
113+
6. Provides data quality assessment
114+
7. Recommends filters or queries
115+
116+
**Usage:**
117+
```
118+
"Investigate the severity_text field in otellogs"
119+
"Show me the distribution of the status field"
120+
"What are the most common values for service_name?"
121+
```
122+
123+
---
124+
## 4. compare-streams
125+
126+
**Purpose:** Compare metrics across multiple data streams.
127+
128+
**When to use:**
129+
- Comparing production vs staging streams
130+
- Understanding which streams are most active
131+
- Capacity planning
132+
- Identifying underutilized streams
133+
134+
**Required Arguments:**
135+
- `stream1` - First data stream name
136+
- `stream2` - Second data stream name
137+
138+
**Optional Arguments:**
139+
- `stream3` - Optional third data stream name
140+
141+
**What it does:**
142+
1. Gets info and stats for each stream
143+
2. Compares:
144+
- Total events (lifetime count)
145+
- Storage usage
146+
- Ingestion rates (events per day)
147+
- Data freshness (last event time)
148+
- Activity levels
149+
3. Creates comparison table
150+
4. Identifies which stream is most active
151+
5. Highlights concerning trends
152+
6. Provides recommendations
153+
154+
**Usage:**
155+
```
156+
"Compare otellogs and network_logstream"
157+
"Which stream is more active: prod-logs or staging-logs?"
158+
"Compare the top 3 streams by size"
159+
```
160+
161+
---
162+
## 5. find-anomalies
163+
164+
**Purpose:** Detect unusual patterns, spikes, or drops in event volumes.
165+
166+
**When to use:**
167+
- Detecting system anomalies
168+
- Finding traffic spikes
169+
- Identifying data ingestion issues
170+
- Monitoring for unusual activity
171+
172+
**Required Arguments:**
173+
- `streamName` - Name of the data stream to analyze
174+
- `startTime` - Start time in ISO 8601 format
175+
- `endTime` - End time in ISO 8601 format
176+
177+
**Optional Arguments:**
178+
- `groupBy` - Time grouping: "hour" or "day" (default: "hour")
179+
180+
**What it does:**
181+
1. Queries event counts are grouped by time (hour or day)
182+
2. Calculates average event count (baseline)
183+
3. Identifies spikes (significantly higher counts)
184+
4. Identifies drops (significantly lower counts or gaps)
185+
5. Investigates anomalous periods
186+
6. Provides timeline with highlighted anomalies
187+
7. Suggests potential causes
188+
8. Recommends follow-up actions
189+
190+
**Usage:**
191+
```
192+
"Find anomalies in otellogs from the last week"
193+
"Are there any spikes in network_logstream today?"
194+
"Detect unusual patterns in the last 24 hours"
195+
```
196+
197+
---
198+
# Using Prompts with AI Agents
199+
200+
## In AI Agent Conversations
201+
202+
When using MCP-compatible clients, you can reference prompts using natural language:
203+
204+
**Health Checks:**
205+
- "Check the health of otellogs"
206+
- "Is network_logstream working?"
207+
- "Run a health check on all my streams"
208+
209+
**Error Analysis:**
210+
- "Find errors in the last hour"
211+
- "Analyze errors in otellogs from yesterday"
212+
- "Show me all failed requests"
213+
214+
**Field Investigation:**
215+
- "What are the common values for severity_text?"
216+
- "Investigate the user_id field"
217+
- "Show me the distribution of status codes"
218+
219+
**Stream Comparison:**
220+
- "Compare otellogs and network_logstream"
221+
- "Which stream has more data?"
222+
- "Compare all production streams"
223+
224+
**Anomaly Detection:**
225+
- "Find any unusual activity"
226+
- "Are there spikes in the last 24 hours?"
227+
- "Detect anomalies this week"
228+
229+
230+
## Testing Prompts
231+
232+
To test prompts, see [TESTING.md](TESTING.md) for the complete testing guide using the stdio test script.
233+
234+
---
235+
# Best Practices
236+
237+
## Time Ranges
238+
239+
- Start with shorter time ranges (1-24 hours) for faster results
240+
- Expand to longer ranges if needed
241+
- Use ISO 8601 format: `2026-02-14T00:00:00Z`
242+
243+
## Field Names
244+
245+
- Use `get_data_stream_schema` first to see available fields
246+
- Field names are case-sensitive and fields with special characters like `.` or `-` must be quoted with backticks.
247+
- Common fields: `body`, `severity_text`, `p_timestamp`
248+
249+
## Stream Names
250+
251+
- Use exact stream names (case-sensitive)
252+
- List streams with `get_data_streams` tool if unsure
253+
- Stream names in prompts must match exactly
254+
255+
## Performance
256+
257+
- **analyze-errors**: Limit to 100-1000 results
258+
- **investigate-field**: Works best with shorter time ranges
259+
- **find-anomalies**: Use `groupBy=day` for long time ranges
260+
- **compare-streams**: Compare 2-3 streams at a time
261+
262+
---
263+
# Troubleshooting
264+
265+
**"Stream not found"**
266+
- Verify stream name with `get_data_streams` tool
267+
- Check spelling and case sensitivity
268+
269+
**"No data returned"**
270+
- Verify time range contains data
271+
- Check stream has events in that period
272+
- Use `get_data_stream_info` to see first/last event times
273+
274+
**"Field not found"**
275+
- Use `get_data_stream_schema` to see available fields
276+
- Check field name spelling and case
277+
278+
**Slow responses**
279+
- Reduce time range
280+
- Use hourly grouping instead of minute-level queries
281+
- For anomalies, use `groupBy=day` for long ranges
282+
283+
---
284+
# Next Steps
285+
286+
1. Review [TESTING.md](TESTING.md) to test prompts
287+
2. Configure Claude Desktop or another MCP client
288+
3. Try prompts with natural language
289+
4. Customize prompts in `prompts/prompts.go` for your needs
290+
5. Create new prompts for your specific use cases
291+
292+
---
293+
# Customizing Prompts
294+
295+
Prompts are defined in `prompts/prompts.go`. You can:
296+
297+
- Modify SQL queries in existing prompts
298+
- Change default values (e.g., error patterns, field names)
299+
- Add new arguments
300+
- Create entirely new prompts
301+
302+
Each prompt is a function that returns instructions for the AI agent. The agent then uses the MCP tools to execute those instructions.
303+

0 commit comments

Comments
 (0)