@tellagen/mcp-server 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +217 -0
- package/SKILL.md +289 -0
- package/dist/auth.d.ts +6 -0
- package/dist/auth.js +18 -0
- package/dist/auth.js.map +1 -0
- package/dist/client.d.ts +15 -0
- package/dist/client.js +53 -0
- package/dist/client.js.map +1 -0
- package/dist/errors.d.ts +8 -0
- package/dist/errors.js +30 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +28 -0
- package/dist/index.js.map +1 -0
- package/dist/server.d.ts +4 -0
- package/dist/server.js +45 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/findings.d.ts +3 -0
- package/dist/tools/findings.js +262 -0
- package/dist/tools/findings.js.map +1 -0
- package/dist/tools/incidents.d.ts +3 -0
- package/dist/tools/incidents.js +135 -0
- package/dist/tools/incidents.js.map +1 -0
- package/dist/tools/index.d.ts +4 -0
- package/dist/tools/index.js +10 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/investigations.d.ts +3 -0
- package/dist/tools/investigations.js +89 -0
- package/dist/tools/investigations.js.map +1 -0
- package/package.json +38 -0
package/README.md
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# @tellagen/mcp-server
|
|
2
|
+
|
|
3
|
+
MCP server for Tellagen — investigate incidents with AI agents.
|
|
4
|
+
|
|
5
|
+
Works with any MCP-compatible client: Claude Code, Cursor, VS Code Copilot, Windsurf.
|
|
6
|
+
|
|
7
|
+
## Quick start
|
|
8
|
+
|
|
9
|
+
### 1. Create an API key
|
|
10
|
+
|
|
11
|
+
In Tellagen, go to **Settings > API Keys** and create a key with both `incidents:read` and `incidents:write` scopes.
|
|
12
|
+
|
|
13
|
+
> **Important:** `incidents:write` does NOT imply `incidents:read`. You need both scopes for full investigation capabilities.
|
|
14
|
+
|
|
15
|
+
### 2. Add to your MCP client config
|
|
16
|
+
|
|
17
|
+
**Claude Code** (`~/.claude.json` or project `.mcp.json`):
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"mcpServers": {
|
|
22
|
+
"tellagen": {
|
|
23
|
+
"command": "npx",
|
|
24
|
+
"args": ["@tellagen/mcp-server"],
|
|
25
|
+
"env": {
|
|
26
|
+
"TELLAGEN_API_KEY": "tllg_...",
|
|
27
|
+
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**Cursor** (`.cursor/mcp.json`):
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"mcpServers": {
|
|
39
|
+
"tellagen": {
|
|
40
|
+
"command": "npx",
|
|
41
|
+
"args": ["@tellagen/mcp-server"],
|
|
42
|
+
"env": {
|
|
43
|
+
"TELLAGEN_API_KEY": "tllg_...",
|
|
44
|
+
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### 3. Investigate
|
|
52
|
+
|
|
53
|
+
Ask your AI agent: *"Investigate incident #42 on Tellagen"*
|
|
54
|
+
|
|
55
|
+
## Tools
|
|
56
|
+
|
|
57
|
+
### Read tools
|
|
58
|
+
|
|
59
|
+
| Tool | Description |
|
|
60
|
+
|------|-------------|
|
|
61
|
+
| `tellagen_get_incident` | Get incident details (severity, status, services, timestamps) |
|
|
62
|
+
| `tellagen_list_incidents` | List all incidents, optionally filtered by status |
|
|
63
|
+
| `tellagen_get_incident_timeline` | Get the timeline of events for an incident |
|
|
64
|
+
| `tellagen_list_investigation_runs` | List investigation runs for an incident |
|
|
65
|
+
| `tellagen_list_findings` | List findings for an incident, optionally filtered by run |
|
|
66
|
+
| `tellagen_get_finding` | Get a single finding with full details |
|
|
67
|
+
|
|
68
|
+
### Write tools
|
|
69
|
+
|
|
70
|
+
| Tool | Description |
|
|
71
|
+
|------|-------------|
|
|
72
|
+
| `tellagen_start_investigation` | Start a new investigation run on an incident |
|
|
73
|
+
| `tellagen_post_finding` | Post a structured finding to an active investigation |
|
|
74
|
+
| `tellagen_complete_investigation` | Mark an investigation as completed or failed |
|
|
75
|
+
| `tellagen_update_finding` | Update a finding's status (dismiss or restore) |
|
|
76
|
+
| `tellagen_promote_finding` | Promote a finding to the incident timeline |
|
|
77
|
+
|
|
78
|
+
## Composing with other MCP servers
|
|
79
|
+
|
|
80
|
+
The Tellagen MCP server is designed to work alongside vendor MCP servers for observability and source control. Install whichever match your stack:
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
{
|
|
84
|
+
"mcpServers": {
|
|
85
|
+
"tellagen": {
|
|
86
|
+
"command": "npx",
|
|
87
|
+
"args": ["@tellagen/mcp-server"],
|
|
88
|
+
"env": {
|
|
89
|
+
"TELLAGEN_API_KEY": "tllg_...",
|
|
90
|
+
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
91
|
+
}
|
|
92
|
+
},
|
|
93
|
+
"grafana": {
|
|
94
|
+
"command": "uvx",
|
|
95
|
+
"args": ["mcp-grafana"],
|
|
96
|
+
"env": {
|
|
97
|
+
"GRAFANA_URL": "https://yourcompany.grafana.net",
|
|
98
|
+
"GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_..."
|
|
99
|
+
}
|
|
100
|
+
},
|
|
101
|
+
"github": {
|
|
102
|
+
"command": "npx",
|
|
103
|
+
"args": ["@anthropic-ai/github-mcp-server"],
|
|
104
|
+
"env": {
|
|
105
|
+
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The agent uses Tellagen tools to manage the investigation lifecycle and vendor tools to gather evidence:
|
|
113
|
+
|
|
114
|
+
1. **Read** the incident from Tellagen
|
|
115
|
+
2. **Query** Grafana Loki for error logs, Prometheus for metrics
|
|
116
|
+
3. **Check** GitHub for recent deploys and code changes
|
|
117
|
+
4. **Post** findings back to Tellagen as they're discovered
|
|
118
|
+
5. **Complete** the investigation run
|
|
119
|
+
|
|
120
|
+
## Authentication
|
|
121
|
+
|
|
122
|
+
- API key is passed via `TELLAGEN_API_KEY` environment variable (never in args)
|
|
123
|
+
- The server validates the key on startup by calling `/api/v1/auth/me`
|
|
124
|
+
- All requests include `Authorization: Bearer tllg_...` header
|
|
125
|
+
- The MCP server acts as the API key's creating user
|
|
126
|
+
|
|
127
|
+
## Scopes
|
|
128
|
+
|
|
129
|
+
The API key needs both scopes:
|
|
130
|
+
|
|
131
|
+
| Scope | Required for |
|
|
132
|
+
|-------|-------------|
|
|
133
|
+
| `incidents:read` | Reading incidents, timelines, investigation runs, findings |
|
|
134
|
+
| `incidents:write` | Starting investigations, posting findings, promoting to timeline |
|
|
135
|
+
|
|
136
|
+
## Development
|
|
137
|
+
|
|
138
|
+
### Setup
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
npm install
|
|
142
|
+
npm run build
|
|
143
|
+
npm test
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### Running the dev server locally
|
|
147
|
+
|
|
148
|
+
1. **Build the project** (or use watch mode):
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
npm run build
|
|
152
|
+
# or, to rebuild on every change:
|
|
153
|
+
npm run dev
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
2. **Point your MCP client at the local build** instead of the published npm package.
|
|
157
|
+
|
|
158
|
+
**Claude Code** — add to `~/.claude.json` (global) or `.mcp.json` (per-project):
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"mcpServers": {
|
|
163
|
+
"tellagen": {
|
|
164
|
+
"command": "node",
|
|
165
|
+
"args": ["/absolute/path/to/tellagen-mcp-server/dist/index.js"],
|
|
166
|
+
"env": {
|
|
167
|
+
"TELLAGEN_API_KEY": "tllg_...",
|
|
168
|
+
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
**Cursor** — add to `.cursor/mcp.json`:
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"mcpServers": {
|
|
180
|
+
"tellagen": {
|
|
181
|
+
"command": "node",
|
|
182
|
+
"args": ["/absolute/path/to/tellagen-mcp-server/dist/index.js"],
|
|
183
|
+
"env": {
|
|
184
|
+
"TELLAGEN_API_KEY": "tllg_...",
|
|
185
|
+
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Replace `/absolute/path/to/tellagen-mcp-server` with the actual path to your clone.
|
|
193
|
+
|
|
194
|
+
3. **Restart the MCP client** so it picks up the new config. In Claude Code, run `/mcp` to verify the server is connected.
|
|
195
|
+
|
|
196
|
+
4. **Iterate:** if you're running `npm run dev`, every save recompiles. Restart the MCP connection (or restart your client) to pick up changes.
|
|
197
|
+
|
|
198
|
+
### Running tests
|
|
199
|
+
|
|
200
|
+
```bash
|
|
201
|
+
npm test # all tests
|
|
202
|
+
npx vitest run test/client.test.ts # single file
|
|
203
|
+
npx vitest # watch mode
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### Type-checking
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
npm run lint # tsc --noEmit
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Environment variables
|
|
213
|
+
|
|
214
|
+
| Variable | Required | Description |
|
|
215
|
+
|----------|----------|-------------|
|
|
216
|
+
| `TELLAGEN_API_KEY` | Yes | API key (format: `tllg_...`) |
|
|
217
|
+
| `TELLAGEN_API_URL` | Yes | API base URL (e.g., `https://yourcompany.api.tellagen.com`) |
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
# Tellagen MCP — AI Agent Skill Guide
|
|
2
|
+
|
|
3
|
+
You have access to the Tellagen MCP server. This guide teaches you how to use it — alone and combined with other MCP servers — to investigate and manage incidents.
|
|
4
|
+
|
|
5
|
+
## Core concept
|
|
6
|
+
|
|
7
|
+
Tellagen is an incident investigation platform. Your role is to act as an on-call AI investigator: read incidents, gather evidence from observability and source control systems, post structured findings, and promote key findings to the incident timeline so human responders see them in the war room.
|
|
8
|
+
|
|
9
|
+
## Tools available (12 total)
|
|
10
|
+
|
|
11
|
+
### Incidents
|
|
12
|
+
| Tool | Method | What it does |
|
|
13
|
+
|------|--------|-------------|
|
|
14
|
+
| `tellagen_get_incident` | GET | Read incident details — severity, status, services, timestamps, manager |
|
|
15
|
+
| `tellagen_list_incidents` | GET | List incidents, optionally filter by `active` / `resolved` / `all` |
|
|
16
|
+
| `tellagen_get_incident_timeline` | GET | Read the incident timeline — status changes, decisions, promoted findings |
|
|
17
|
+
| `tellagen_create_incident` | POST | Declare a new incident (all fields optional: service, severity, regions, gist, team_id, etc.) |
|
|
18
|
+
|
|
19
|
+
### Investigations
|
|
20
|
+
| Tool | Method | What it does |
|
|
21
|
+
|------|--------|-------------|
|
|
22
|
+
| `tellagen_start_investigation` | POST | Open an investigation run — returns a `run_id` you must use for all findings |
|
|
23
|
+
| `tellagen_list_investigation_runs` | GET | List runs for an incident (shows status, agent info, finding counts) |
|
|
24
|
+
| `tellagen_complete_investigation` | PATCH | Close a run as `completed` or `failed` (with `failure_reason`) |
|
|
25
|
+
|
|
26
|
+
### Findings
|
|
27
|
+
| Tool | Method | What it does |
|
|
28
|
+
|------|--------|-------------|
|
|
29
|
+
| `tellagen_post_finding` | POST | Post a structured finding to an active run |
|
|
30
|
+
| `tellagen_list_findings` | GET | List findings for an incident (optionally filter by run) |
|
|
31
|
+
| `tellagen_get_finding` | GET | Get full finding details including evidence refs |
|
|
32
|
+
| `tellagen_update_finding` | PATCH | Dismiss or restore a finding |
|
|
33
|
+
| `tellagen_promote_finding` | POST | Promote a finding to the incident timeline (creates a visible timeline event) |
|
|
34
|
+
|
|
35
|
+
## Investigation lifecycle
|
|
36
|
+
|
|
37
|
+
Every investigation follows this sequence. Do not skip steps.
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
1. tellagen_get_incident → understand what happened
|
|
41
|
+
2. tellagen_start_investigation → open a run, get run_id
|
|
42
|
+
3. [gather evidence] → use Grafana, GitHub, codebase, PagerDuty, etc.
|
|
43
|
+
4. tellagen_post_finding → post each finding as you discover it (do NOT batch)
|
|
44
|
+
5. tellagen_promote_finding → promote key findings to the timeline
|
|
45
|
+
6. tellagen_complete_investigation → close the run
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Rules
|
|
49
|
+
- **Post findings incrementally.** Every meaningful observation, correlation, or hypothesis gets its own finding posted immediately. Do not wait until the end.
|
|
50
|
+
- **One run per investigation session.** Start one run, post all findings to it, then complete it.
|
|
51
|
+
- **Always complete the run.** Even if you hit errors, call `tellagen_complete_investigation` with `status: "failed"` and a `failure_reason`.
|
|
52
|
+
|
|
53
|
+
## Posting findings
|
|
54
|
+
|
|
55
|
+
Every finding requires:
|
|
56
|
+
|
|
57
|
+
| Field | Type | Description |
|
|
58
|
+
|-------|------|-------------|
|
|
59
|
+
| `incident_id` | number | Which incident |
|
|
60
|
+
| `investigation_run_id` | string | Your active run ID |
|
|
61
|
+
| `finding_type` | enum | `observation`, `correlation`, `hypothesis`, `evidence`, `recommendation`, `negative` |
|
|
62
|
+
| `claim` | string | One-sentence statement of the finding |
|
|
63
|
+
| `evidence_summary` | string | Detailed explanation with supporting data |
|
|
64
|
+
| `confidence` | number | 0.0–1.0 (0.9+ near-certain, 0.5–0.7 plausible, <0.5 speculative) |
|
|
65
|
+
| `confidence_reason` | string | Why you have this confidence level |
|
|
66
|
+
|
|
67
|
+
Optional:
|
|
68
|
+
|
|
69
|
+
| Field | Type | Description |
|
|
70
|
+
|-------|------|-------------|
|
|
71
|
+
| `evidence_refs` | array | Sources consulted (see below) |
|
|
72
|
+
| `screenshots` | array | Standalone screenshots for this finding |
|
|
73
|
+
|
|
74
|
+
### Evidence refs
|
|
75
|
+
|
|
76
|
+
Each evidence ref links to a specific data source you queried:
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"source": "grafana-loki",
|
|
81
|
+
"query": "{app=\"checkout\"} |= \"error\" | json",
|
|
82
|
+
"result_summary": "Found 847 errors in last 30 minutes, 90% are 502 Bad Gateway from upstream payments service",
|
|
83
|
+
"url": "https://grafana.example.com/explore?...",
|
|
84
|
+
"screenshots": [
|
|
85
|
+
{
|
|
86
|
+
"url": "https://grafana.example.com/render/d-solo/abc/checkout?panelId=4&from=now-1h",
|
|
87
|
+
"caption": "Grafana panel showing 5xx spike at 14:32 UTC"
|
|
88
|
+
}
|
|
89
|
+
]
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Screenshots
|
|
94
|
+
|
|
95
|
+
Screenshots can be attached to individual evidence refs (source-specific) or at the top level of a finding (standalone). Each screenshot object:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"url": "https://...",
|
|
100
|
+
"base64": "<base64-encoded image data>",
|
|
101
|
+
"media_type": "image/png",
|
|
102
|
+
"caption": "What this screenshot shows"
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
All fields are optional, but provide at least `url` or `base64`. Use `url` when linking to a render endpoint (e.g., Grafana panel render). Use `base64` when you have raw image data from a screenshot tool.
|
|
107
|
+
|
|
108
|
+
Screenshots are also supported on `tellagen_promote_finding` — attach them so they appear on the timeline event in the war room.
|
|
109
|
+
|
|
110
|
+
## Choosing finding types
|
|
111
|
+
|
|
112
|
+
| Type | When to use | Example |
|
|
113
|
+
|------|-------------|---------|
|
|
114
|
+
| `observation` | Raw data point worth noting | "Error rate is 5x normal at 2.3%" |
|
|
115
|
+
| `correlation` | Two things that appear related | "Error spike started 4 minutes after deploy abc123" |
|
|
116
|
+
| `hypothesis` | Proposed explanation (may be wrong) | "The payments service OOM is likely caused by the connection pool leak in PR #891" |
|
|
117
|
+
| `evidence` | Proof that supports or refutes a hypothesis | "Thread dump confirms 2,400 idle connections held by HikariCP pool" |
|
|
118
|
+
| `recommendation` | Suggested action for responders | "Roll back deploy abc123 to restore payments service" |
|
|
119
|
+
| `negative` | Something you ruled out | "Database latency is normal — not a contributing factor" |
|
|
120
|
+
|
|
121
|
+
Post early and often. A `hypothesis` with 0.4 confidence is still valuable — it tells responders what you're thinking and what to check.
|
|
122
|
+
|
|
123
|
+
## Composing with other MCP servers
|
|
124
|
+
|
|
125
|
+
Tellagen handles the investigation lifecycle. Other MCP servers provide the evidence. Here's how to combine them.
|
|
126
|
+
|
|
127
|
+
### With Grafana MCP (`mcp-grafana`)
|
|
128
|
+
|
|
129
|
+
Grafana MCP gives you tools to search dashboards, query Prometheus/Loki, and list alert rules.
|
|
130
|
+
|
|
131
|
+
**Investigation pattern:**
|
|
132
|
+
|
|
133
|
+
1. Read the incident from Tellagen — note the affected service and timestamps
|
|
134
|
+
2. Use Grafana tools to search for relevant dashboards (`search_dashboards`)
|
|
135
|
+
3. Query Prometheus for metrics: error rates, latency percentiles, saturation (`query_prometheus`)
|
|
136
|
+
4. Query Loki for error logs around the incident timeframe (`query_loki`)
|
|
137
|
+
5. If Grafana provides panel render URLs or you capture screenshots, attach them to your findings
|
|
138
|
+
6. Post each query result as a finding with evidence refs back to Tellagen
|
|
139
|
+
|
|
140
|
+
**Example flow:**
|
|
141
|
+
```
|
|
142
|
+
tellagen_get_incident(incident_id=42)
|
|
143
|
+
→ "checkout service, sev1, started 14:30 UTC"
|
|
144
|
+
|
|
145
|
+
search_dashboards(query="checkout")
|
|
146
|
+
→ finds dashboard uid "abc123"
|
|
147
|
+
|
|
148
|
+
query_prometheus(query='rate(http_requests_total{service="checkout",code=~"5.."}[5m])')
|
|
149
|
+
→ 5xx rate jumped from 0.002 to 0.15 at 14:32
|
|
150
|
+
|
|
151
|
+
query_loki(query='{app="checkout"} |= "error" | json', start="2025-03-09T14:25:00Z", end="2025-03-09T14:45:00Z")
|
|
152
|
+
→ 847 errors, 90% are "connection refused" from payments upstream
|
|
153
|
+
|
|
154
|
+
tellagen_post_finding(
|
|
155
|
+
incident_id=42,
|
|
156
|
+
investigation_run_id="run-xyz",
|
|
157
|
+
finding_type="observation",
|
|
158
|
+
claim="HTTP 5xx rate spiked 75x at 14:32 UTC",
|
|
159
|
+
evidence_summary="checkout service 5xx rate went from 0.2% to 15%. 90% of errors are 502 Bad Gateway from upstream payments service.",
|
|
160
|
+
confidence=0.95,
|
|
161
|
+
confidence_reason="Direct metric observation from Prometheus, corroborated by Loki error logs",
|
|
162
|
+
evidence_refs=[
|
|
163
|
+
{
|
|
164
|
+
source: "grafana-prometheus",
|
|
165
|
+
query: "rate(http_requests_total{service='checkout',code=~'5..'}[5m])",
|
|
166
|
+
result_summary: "5xx rate jumped from 0.002 to 0.15 at 14:32 UTC",
|
|
167
|
+
url: "https://grafana.example.com/explore?...",
|
|
168
|
+
screenshots: [{
|
|
169
|
+
url: "https://grafana.example.com/render/d-solo/abc123/checkout?panelId=4&from=1709992500000&to=1709993700000&width=800&height=400",
|
|
170
|
+
caption: "5xx rate panel showing the spike"
|
|
171
|
+
}]
|
|
172
|
+
},
|
|
173
|
+
{
|
|
174
|
+
source: "grafana-loki",
|
|
175
|
+
query: "{app='checkout'} |= 'error' | json",
|
|
176
|
+
result_summary: "847 errors in 20-minute window. 90% are 'connection refused' from payments upstream",
|
|
177
|
+
url: "https://grafana.example.com/explore?..."
|
|
178
|
+
}
|
|
179
|
+
]
|
|
180
|
+
)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### With GitHub MCP (`@modelcontextprotocol/server-github`)
|
|
184
|
+
|
|
185
|
+
GitHub MCP lets you search code, list commits, read PRs, and check deployments.
|
|
186
|
+
|
|
187
|
+
**Investigation pattern:**
|
|
188
|
+
|
|
189
|
+
1. From the incident, identify the service and approximate start time
|
|
190
|
+
2. Search recent commits/PRs for the affected service around that time
|
|
191
|
+
3. Look at deployment events or release tags
|
|
192
|
+
4. Read changed files if a suspicious deploy is found
|
|
193
|
+
5. Post correlation findings linking deploys to the incident
|
|
194
|
+
6. Check for related issues or prior incidents
|
|
195
|
+
|
|
196
|
+
**Example findings from GitHub evidence:**
|
|
197
|
+
```
|
|
198
|
+
tellagen_post_finding(
|
|
199
|
+
finding_type="correlation",
|
|
200
|
+
claim="Deploy abc123 landed 4 minutes before the 5xx spike",
|
|
201
|
+
evidence_summary="PR #891 merged at 14:28 UTC, deployed at 14:28. Incident started at 14:32. The PR changes connection pool settings in payments-client.",
|
|
202
|
+
confidence=0.7,
|
|
203
|
+
confidence_reason="Strong temporal correlation, and the changed code touches the exact subsystem showing errors",
|
|
204
|
+
evidence_refs=[{
|
|
205
|
+
source: "github",
|
|
206
|
+
query: "commits to main between 14:00-14:35 in checkout-service repo",
|
|
207
|
+
result_summary: "1 deploy: commit abc123 from PR #891 'Tune HikariCP pool settings'",
|
|
208
|
+
url: "https://github.com/org/checkout-service/pull/891"
|
|
209
|
+
}]
|
|
210
|
+
)
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### With PagerDuty MCP
|
|
214
|
+
|
|
215
|
+
**Investigation pattern:**
|
|
216
|
+
|
|
217
|
+
1. Check which alerts fired around the incident start time
|
|
218
|
+
2. Look at alert history for the affected service — is this a repeat?
|
|
219
|
+
3. Identify who was paged and when
|
|
220
|
+
4. Post findings about alert patterns
|
|
221
|
+
|
|
222
|
+
### With Sentry / error tracking MCP
|
|
223
|
+
|
|
224
|
+
**Investigation pattern:**
|
|
225
|
+
|
|
226
|
+
1. Search for new error groups that appeared around incident start
|
|
227
|
+
2. Get error details — stack traces, affected users, frequency
|
|
228
|
+
3. Link specific errors to your hypothesis about root cause
|
|
229
|
+
|
|
230
|
+
### Multi-source investigation template
|
|
231
|
+
|
|
232
|
+
For a typical sev1/sev2, query sources in this order:
|
|
233
|
+
|
|
234
|
+
1. **Tellagen** — read the incident, check if there's a prior investigation
|
|
235
|
+
2. **Grafana/Prometheus** — check key metrics (error rate, latency, saturation) for the affected service
|
|
236
|
+
3. **Grafana/Loki** — pull error logs around the incident window
|
|
237
|
+
4. **GitHub** — find recent deploys to the affected service
|
|
238
|
+
5. **PagerDuty** — check what alerts fired
|
|
239
|
+
6. **Codebase** — if a suspicious deploy is found, read the changed code
|
|
240
|
+
|
|
241
|
+
Post findings after each source, not at the end. Your first finding might just be "error rate is elevated" — that's fine. Build the picture incrementally.
|
|
242
|
+
|
|
243
|
+
## Promoting to timeline
|
|
244
|
+
|
|
245
|
+
Not every finding belongs on the timeline. Promote findings that:
|
|
246
|
+
|
|
247
|
+
- Confirm or identify the root cause
|
|
248
|
+
- Record a critical decision or action taken
|
|
249
|
+
- Represent a key milestone (e.g., "service recovered at 15:12 UTC")
|
|
250
|
+
- Provide high-confidence recommendations for responders
|
|
251
|
+
|
|
252
|
+
When promoting, attach screenshots so the timeline event is self-contained:
|
|
253
|
+
|
|
254
|
+
```
|
|
255
|
+
tellagen_promote_finding(
|
|
256
|
+
finding_id=7,
|
|
257
|
+
title="Root cause: connection pool exhaustion after deploy abc123",
|
|
258
|
+
is_key=true,
|
|
259
|
+
screenshots=[{
|
|
260
|
+
url: "https://grafana.example.com/render/d-solo/abc123/checkout?panelId=4&from=...",
|
|
261
|
+
caption: "5xx rate panel showing spike and recovery after rollback"
|
|
262
|
+
}]
|
|
263
|
+
)
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## Creating incidents
|
|
267
|
+
|
|
268
|
+
When you detect something wrong (e.g., while monitoring dashboards), you can declare an incident directly:
|
|
269
|
+
|
|
270
|
+
```
|
|
271
|
+
tellagen_create_incident(
|
|
272
|
+
service="payments",
|
|
273
|
+
severity="sev2",
|
|
274
|
+
gist="5xx-spike",
|
|
275
|
+
regions=["us-east-1"],
|
|
276
|
+
create_slack_channel=true
|
|
277
|
+
)
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
Then immediately start investigating it.
|
|
281
|
+
|
|
282
|
+
## Common mistakes to avoid
|
|
283
|
+
|
|
284
|
+
- **Batching findings.** Post each finding as you discover it. Don't accumulate five findings and post them all at the end.
|
|
285
|
+
- **Forgetting to complete the run.** Always call `tellagen_complete_investigation`, even on failure.
|
|
286
|
+
- **Low-effort evidence refs.** Include the actual query you ran and a meaningful `result_summary`, not just "checked Grafana". Deep links in `url` let humans verify your work.
|
|
287
|
+
- **Promoting everything.** The timeline is for key events. A speculative hypothesis with 0.3 confidence doesn't belong there.
|
|
288
|
+
- **Skipping screenshots.** When you have access to Grafana render URLs or captured dashboard images, attach them. A panel screenshot showing the spike is worth more than a text description to a human responder in the war room.
|
|
289
|
+
- **Not using negative findings.** When you rule something out, post a `negative` finding. It prevents other investigators from re-checking the same thing.
|
package/dist/auth.d.ts
ADDED
package/dist/auth.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Validate the API key on startup by calling /api/v1/auth/me.
|
|
3
|
+
* Throws if the key is invalid or the API is unreachable.
|
|
4
|
+
*/
|
|
5
|
+
export async function validateAuth(client) {
|
|
6
|
+
try {
|
|
7
|
+
const resp = await client.get("/api/v1/auth/me");
|
|
8
|
+
const companyName = resp.user.company?.name ?? "unknown";
|
|
9
|
+
process.stderr.write(`Tellagen MCP: authenticated as ${resp.user.email} (${companyName})\n`);
|
|
10
|
+
}
|
|
11
|
+
catch (err) {
|
|
12
|
+
if (err instanceof Error) {
|
|
13
|
+
throw new Error(`Tellagen MCP: failed to authenticate — ${err.message}. Check TELLAGEN_API_KEY and TELLAGEN_API_URL.`);
|
|
14
|
+
}
|
|
15
|
+
throw err;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
//# sourceMappingURL=auth.js.map
|
package/dist/auth.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAsB;IACvD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,GAAG,CAAiB,iBAAiB,CAAC,CAAC;QACjE,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,IAAI,SAAS,CAAC;QACzD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kCAAkC,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,WAAW,KAAK,CACvE,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,0CAA0C,GAAG,CAAC,OAAO,gDAAgD,CACtG,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export interface ClientConfig {
|
|
2
|
+
apiUrl: string;
|
|
3
|
+
apiKey: string;
|
|
4
|
+
}
|
|
5
|
+
/** Thin HTTP wrapper for the Tellagen public API. */
|
|
6
|
+
export declare class TellagenClient {
|
|
7
|
+
private readonly baseUrl;
|
|
8
|
+
private readonly apiKey;
|
|
9
|
+
constructor(config: ClientConfig);
|
|
10
|
+
private headers;
|
|
11
|
+
private request;
|
|
12
|
+
get<T>(path: string): Promise<T>;
|
|
13
|
+
post<T>(path: string, body: unknown): Promise<T>;
|
|
14
|
+
patch<T>(path: string, body: unknown): Promise<T>;
|
|
15
|
+
}
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { TellagenAPIError } from "./errors.js";
|
|
2
|
+
/** Thin HTTP wrapper for the Tellagen public API. */
|
|
3
|
+
export class TellagenClient {
|
|
4
|
+
baseUrl;
|
|
5
|
+
apiKey;
|
|
6
|
+
constructor(config) {
|
|
7
|
+
this.baseUrl = config.apiUrl.replace(/\/+$/, "");
|
|
8
|
+
this.apiKey = config.apiKey;
|
|
9
|
+
}
|
|
10
|
+
headers(extra) {
|
|
11
|
+
return {
|
|
12
|
+
Authorization: `Bearer ${this.apiKey}`,
|
|
13
|
+
"Content-Type": "application/json",
|
|
14
|
+
...extra,
|
|
15
|
+
};
|
|
16
|
+
}
|
|
17
|
+
async request(method, path, body) {
|
|
18
|
+
const url = `${this.baseUrl}${path}`;
|
|
19
|
+
const init = {
|
|
20
|
+
method,
|
|
21
|
+
headers: this.headers(),
|
|
22
|
+
};
|
|
23
|
+
if (body !== undefined) {
|
|
24
|
+
init.body = JSON.stringify(body);
|
|
25
|
+
}
|
|
26
|
+
const res = await fetch(url, init);
|
|
27
|
+
if (!res.ok) {
|
|
28
|
+
let code = "unknown";
|
|
29
|
+
let message = `HTTP ${res.status}`;
|
|
30
|
+
try {
|
|
31
|
+
const errBody = (await res.json());
|
|
32
|
+
code = errBody.error ?? code;
|
|
33
|
+
message = errBody.message ?? message;
|
|
34
|
+
}
|
|
35
|
+
catch {
|
|
36
|
+
// Response was not JSON — use status text.
|
|
37
|
+
message = res.statusText || message;
|
|
38
|
+
}
|
|
39
|
+
throw new TellagenAPIError(res.status, code, message);
|
|
40
|
+
}
|
|
41
|
+
return (await res.json());
|
|
42
|
+
}
|
|
43
|
+
async get(path) {
|
|
44
|
+
return this.request("GET", path);
|
|
45
|
+
}
|
|
46
|
+
async post(path, body) {
|
|
47
|
+
return this.request("POST", path, body);
|
|
48
|
+
}
|
|
49
|
+
async patch(path, body) {
|
|
50
|
+
return this.request("PATCH", path, body);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
//# sourceMappingURL=client.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAO/C,qDAAqD;AACrD,MAAM,OAAO,cAAc;IACR,OAAO,CAAS;IAChB,MAAM,CAAS;IAEhC,YAAY,MAAoB;QAC9B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;IAEO,OAAO,CAAC,KAA8B;QAC5C,OAAO;YACL,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;YACtC,cAAc,EAAE,kBAAkB;YAClC,GAAG,KAAK;SACT,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,MAAc,EACd,IAAY,EACZ,IAAc;QAEd,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,GAAgB;YACxB,MAAM;YACN,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;SACxB,CAAC;QACF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAEnC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,IAAI,GAAG,SAAS,CAAC;YACrB,IAAI,OAAO,GAAG,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAGhC,CAAC;gBACF,IAAI,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;gBAC7B,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;gBAC3C,OAAO,GAAG,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC;YACtC,CAAC;YACD,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,GAAG,CAAI,IAAY;QACvB,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAa;QACvC,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,KAAK,CAAI,IAAY,EAAE,IAAa;QACxC,OAAO,IAAI,CAAC,OAAO,CAAI,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC;CACF"}
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** Structured error from the Tellagen API. */
|
|
2
|
+
export declare class TellagenAPIError extends Error {
|
|
3
|
+
readonly status: number;
|
|
4
|
+
readonly code: string;
|
|
5
|
+
constructor(status: number, code: string, message: string);
|
|
6
|
+
}
|
|
7
|
+
/** Format an API error into a user-friendly MCP tool error response. */
|
|
8
|
+
export declare function formatError(err: unknown): string;
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/** Structured error from the Tellagen API. */
|
|
2
|
+
export class TellagenAPIError extends Error {
|
|
3
|
+
status;
|
|
4
|
+
code;
|
|
5
|
+
constructor(status, code, message) {
|
|
6
|
+
super(message);
|
|
7
|
+
this.status = status;
|
|
8
|
+
this.code = code;
|
|
9
|
+
this.name = "TellagenAPIError";
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
/** Format an API error into a user-friendly MCP tool error response. */
|
|
13
|
+
export function formatError(err) {
|
|
14
|
+
if (err instanceof TellagenAPIError) {
|
|
15
|
+
return JSON.stringify({
|
|
16
|
+
error: true,
|
|
17
|
+
status: err.status,
|
|
18
|
+
code: err.code,
|
|
19
|
+
message: err.message,
|
|
20
|
+
});
|
|
21
|
+
}
|
|
22
|
+
if (err instanceof Error) {
|
|
23
|
+
return JSON.stringify({
|
|
24
|
+
error: true,
|
|
25
|
+
message: err.message,
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
return JSON.stringify({ error: true, message: String(err) });
|
|
29
|
+
}
|
|
30
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAEvB;IACA;IAFlB,YACkB,MAAc,EACd,IAAY,EAC5B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QAI5B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,GAAG,CAAC,OAAO;SACrB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC"}
|
package/dist/index.d.ts
ADDED