@tellagen/mcp-server 0.1.1 → 0.4.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.
Files changed (82) hide show
  1. package/README.md +231 -12
  2. package/SKILL.md +407 -13
  3. package/contracts/runbooks/manifest.json +47 -0
  4. package/contracts/runbooks/v1/fixtures/global-runbook.json +7 -0
  5. package/contracts/runbooks/v1/runbook-definition.schema.json +25 -0
  6. package/contracts/runbooks/v2/compiled-plan.schema.json +40 -0
  7. package/contracts/runbooks/v2/fixtures/filesystem-pressure.json +181 -0
  8. package/contracts/runbooks/v2/fixtures/grafana-error-rate-plan.json +50 -0
  9. package/contracts/runbooks/v2/fixtures/grafana-error-rate.json +58 -0
  10. package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +90 -0
  11. package/contracts/runbooks/v2/fixtures/timeline-event-with-blocks.json +61 -0
  12. package/contracts/runbooks/v2/runbook-definition.schema.json +377 -0
  13. package/contracts/runbooks/v2/timeline-event-blocks.schema.json +480 -0
  14. package/contracts/tellagen-runbook-contracts.json +8 -0
  15. package/dist/auth.d.ts +2 -1
  16. package/dist/auth.js +2 -1
  17. package/dist/auth.js.map +1 -1
  18. package/dist/client.d.ts +20 -0
  19. package/dist/client.js +81 -12
  20. package/dist/client.js.map +1 -1
  21. package/dist/diagnosis-structure.d.ts +1416 -0
  22. package/dist/diagnosis-structure.js +656 -0
  23. package/dist/diagnosis-structure.js.map +1 -0
  24. package/dist/errors.d.ts +2 -1
  25. package/dist/errors.js +4 -1
  26. package/dist/errors.js.map +1 -1
  27. package/dist/figures.d.ts +2336 -0
  28. package/dist/figures.js +1288 -0
  29. package/dist/figures.js.map +1 -0
  30. package/dist/image-info.d.ts +14 -0
  31. package/dist/image-info.js +65 -0
  32. package/dist/image-info.js.map +1 -0
  33. package/dist/index.js +2 -6
  34. package/dist/index.js.map +1 -1
  35. package/dist/server.js +63 -6
  36. package/dist/server.js.map +1 -1
  37. package/dist/source-links.d.ts +101 -0
  38. package/dist/source-links.js +374 -0
  39. package/dist/source-links.js.map +1 -0
  40. package/dist/start.d.ts +11 -0
  41. package/dist/start.js +14 -0
  42. package/dist/start.js.map +1 -0
  43. package/dist/tools/attachments.d.ts +19 -0
  44. package/dist/tools/attachments.js +177 -0
  45. package/dist/tools/attachments.js.map +1 -0
  46. package/dist/tools/causes.d.ts +50 -0
  47. package/dist/tools/causes.js +97 -0
  48. package/dist/tools/causes.js.map +1 -0
  49. package/dist/tools/context.d.ts +3 -0
  50. package/dist/tools/context.js +146 -0
  51. package/dist/tools/context.js.map +1 -0
  52. package/dist/tools/datasources.d.ts +3 -0
  53. package/dist/tools/datasources.js +325 -0
  54. package/dist/tools/datasources.js.map +1 -0
  55. package/dist/tools/diagnostics.d.ts +3 -0
  56. package/dist/tools/diagnostics.js +113 -0
  57. package/dist/tools/diagnostics.js.map +1 -0
  58. package/dist/tools/figures.d.ts +8 -0
  59. package/dist/tools/figures.js +209 -0
  60. package/dist/tools/figures.js.map +1 -0
  61. package/dist/tools/findings.js +84 -6
  62. package/dist/tools/findings.js.map +1 -1
  63. package/dist/tools/incidents.js +112 -3
  64. package/dist/tools/incidents.js.map +1 -1
  65. package/dist/tools/index.js +18 -0
  66. package/dist/tools/index.js.map +1 -1
  67. package/dist/tools/investigations.js +834 -12
  68. package/dist/tools/investigations.js.map +1 -1
  69. package/dist/tools/postmortem-runbooks.d.ts +786 -0
  70. package/dist/tools/postmortem-runbooks.js +330 -0
  71. package/dist/tools/postmortem-runbooks.js.map +1 -0
  72. package/dist/tools/source-links.d.ts +47 -0
  73. package/dist/tools/source-links.js +302 -0
  74. package/dist/tools/source-links.js.map +1 -0
  75. package/dist/tools/timeline.d.ts +3 -0
  76. package/dist/tools/timeline.js +333 -0
  77. package/dist/tools/timeline.js.map +1 -0
  78. package/dist/version.d.ts +2 -0
  79. package/dist/version.js +12 -0
  80. package/dist/version.js.map +1 -0
  81. package/package.json +4 -3
  82. package/server.json +15 -1
@@ -0,0 +1,480 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://tellagen.dev/contracts/timeline/v2/timeline-event-blocks.schema.json",
4
+ "title": "Tellagen timeline event blocks",
5
+ "description": "The blocks field of a timeline event: typed widgets that hold the numbers behind a note. Send it with the REST timeline create (POST /api/v1/incidents/{id}/timeline) or update (PATCH /api/v1/timeline/{id}); the MCP tools tellagen_post_timeline_event and tellagen_update_timeline_event pass it through. The server validates every block and answers one bad block with 400 invalid_block, a message, the path of the first bad field in field and up to ten bad fields in details.errors. An update that sends blocks replaces the whole array; [] removes them; leaving the field out keeps them. Strings are trimmed, one line and free of control characters (only source.query may hold line breaks; a diff line's text is the one string that is not trimmed, so it keeps its indentation, and it may hold tabs). The same blocks, except table and changes, are the figure of a Diagnosis chain step (causal_paths[].steps[].figure). Numbers are finite and between -1e12 and 1e12. An event carries at most 12 blocks and 64 KB of block JSON.",
6
+ "x-guidance": [
7
+ "Put the few numbers a responder scans for in one stats block: at most four, each with a short label, a value, a caption that says what it is measured on, and a tone.",
8
+ "Use a compare block for a metric that has a value before, a value after and a threshold (an SLO or alert line). Give the unit, say which direction is better, and put one row per host, route or query.",
9
+ "Use a trend block for a series over time. Send start and step_seconds together, reduce the range to at most 500 points, add at most three marks for the events that explain the shape, and fill source with the query that produced the series (kind, datasource, query, step, and artifact_id when you have it).",
10
+ "Use a table block for a ranked list (top queries, failing routes), a checks block for a recovery checklist with a result per check, and a changes block for a value that moved from one thing to another.",
11
+ "Use a range_overlap block when the cause is two ranges meeting (layout offsets, a maintenance window against an error spike, memory or port ranges): two to four rows with a from and a to, in one unit. Tellagen computes the overlap and zooms to it; send min and max for the whole range, and a window only to choose the zoom yourself.",
12
+ "Use a histogram block when an average hides a slow tail: bucket edges (3 to 61, increasing) and one count per bucket for before and for after, plus the threshold (an SLO). Tellagen computes p50, p95, p99 and the share over the threshold from the buckets, so send counts, never percentiles.",
13
+ "Use a run_history block for CI builds, scheduled jobs, canaries or deploys: runs oldest first, each with a ref, a result (success, failure, cancelled, pending) and the failing job, repo as owner/name so each run links to its page, marks for the change that introduced and the one that fixed it (between two neighbouring run refs, change_ref regression or fix), and an optional span with a label such as E2E Tests failed.",
14
+ "Use a diff block for the change that broke something or fixed it: the file path, the commit ref, the added and removed counts of the whole change, and at most 12 lines in hunks, each with op + or - and the text with its indentation. Do not send the whole diff.",
15
+ "Set example: true only on a block that stands in for data you did not read from a tool result (a demo or an illustration); a block built from a tool result never sets it.",
16
+ "Tone is a meaning, not decoration: good for a figure that is healthy or recovered, warn for one that needs attention, bad for one that is failing, neutral or no tone for a plain fact. Never use tone to emphasise.",
17
+ "A block owns its numbers. Do not repeat in the note a number that a block already shows; the note says what happened and why, the block says how much.",
18
+ "Never invent a number. Every value comes from a tool result you can cite; if you do not have it, leave that figure, row or block out. Write values as measured and keep units in the unit field, not in the number.",
19
+ "Place a block above the note with slot: summary, or under a heading of the note with anchor: the exact heading text (for example Verified outcome). Do not send both. Leave both out to place the block after the note.",
20
+ "Set postmortem: false only for a block that should stay out of the postmortem; leave the field out otherwise.",
21
+ "When the API answers 400 invalid_block, read field and details.errors, fix exactly those fields and send the event again once. Do not drop a block to get past an error unless the data it holds is not real."
22
+ ],
23
+ "type": "array",
24
+ "maxItems": 12,
25
+ "items": {"$ref": "#/$defs/block"},
26
+ "$defs": {
27
+ "block": {
28
+ "oneOf": [
29
+ {"$ref": "#/$defs/stats"},
30
+ {"$ref": "#/$defs/compare"},
31
+ {"$ref": "#/$defs/trend"},
32
+ {"$ref": "#/$defs/table"},
33
+ {"$ref": "#/$defs/checks"},
34
+ {"$ref": "#/$defs/changes"},
35
+ {"$ref": "#/$defs/range_overlap"},
36
+ {"$ref": "#/$defs/histogram"},
37
+ {"$ref": "#/$defs/run_history"},
38
+ {"$ref": "#/$defs/diff"}
39
+ ]
40
+ },
41
+ "slot": {"const": "summary", "description": "Draws the block above the note. Not together with anchor."},
42
+ "anchor": {"type": "string", "maxLength": 80, "description": "The text of a heading in the note; the block sits under it, or after the note when the heading is missing. Not together with slot."},
43
+ "postmortem": {"type": "boolean", "description": "false keeps the block out of the postmortem; absent means included."},
44
+ "example": {"type": "boolean", "description": "true marks the numbers as example data: the figure shows an Example data tag. Absent means real data."},
45
+ "repo": {"type": "string", "maxLength": 80, "pattern": "^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$", "description": "owner/name of a GitHub repository; the figure builds its links from it."},
46
+ "number": {"type": "number", "minimum": -1000000000000, "maximum": 1000000000000},
47
+ "threshold": {
48
+ "type": "object",
49
+ "additionalProperties": false,
50
+ "required": ["value"],
51
+ "properties": {
52
+ "value": {"$ref": "#/$defs/number"},
53
+ "label": {"type": "string", "maxLength": 80}
54
+ }
55
+ },
56
+ "source": {
57
+ "type": "object",
58
+ "description": "Provenance only. The counts stay in the block.",
59
+ "additionalProperties": false,
60
+ "properties": {
61
+ "kind": {"type": "string", "maxLength": 80},
62
+ "datasource": {"type": "string", "maxLength": 80},
63
+ "query": {"type": "string", "maxLength": 2000},
64
+ "from": {"type": "string", "maxLength": 80},
65
+ "to": {"type": "string", "maxLength": 80},
66
+ "step": {"type": "string", "maxLength": 80},
67
+ "artifact_id": {"type": "string", "maxLength": 80}
68
+ }
69
+ },
70
+ "stats": {
71
+ "type": "object",
72
+ "additionalProperties": false,
73
+ "required": ["type", "items"],
74
+ "properties": {
75
+ "type": {"const": "stats"},
76
+ "slot": {"$ref": "#/$defs/slot"},
77
+ "anchor": {"$ref": "#/$defs/anchor"},
78
+ "postmortem": {"$ref": "#/$defs/postmortem"},
79
+ "example": {"$ref": "#/$defs/example"},
80
+ "items": {
81
+ "type": "array",
82
+ "minItems": 1,
83
+ "maxItems": 4,
84
+ "items": {
85
+ "type": "object",
86
+ "additionalProperties": false,
87
+ "required": ["label", "value"],
88
+ "properties": {
89
+ "label": {"type": "string", "minLength": 1, "maxLength": 48},
90
+ "value": {"type": "string", "minLength": 1, "maxLength": 32},
91
+ "caption": {"type": "string", "maxLength": 64},
92
+ "tone": {"enum": ["good", "warn", "bad", "neutral"]}
93
+ }
94
+ }
95
+ }
96
+ }
97
+ },
98
+ "compare": {
99
+ "type": "object",
100
+ "additionalProperties": false,
101
+ "required": ["type", "rows"],
102
+ "properties": {
103
+ "type": {"const": "compare"},
104
+ "slot": {"$ref": "#/$defs/slot"},
105
+ "anchor": {"$ref": "#/$defs/anchor"},
106
+ "postmortem": {"$ref": "#/$defs/postmortem"},
107
+ "example": {"$ref": "#/$defs/example"},
108
+ "title": {"type": "string", "maxLength": 80},
109
+ "metric": {"type": "string", "maxLength": 32},
110
+ "unit": {"type": "string", "maxLength": 12},
111
+ "better": {"enum": ["lower", "higher"]},
112
+ "delta": {"enum": ["rel", "abs"]},
113
+ "max": {"type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000},
114
+ "threshold": {"$ref": "#/$defs/threshold"},
115
+ "rows": {
116
+ "type": "array",
117
+ "minItems": 1,
118
+ "maxItems": 8,
119
+ "items": {
120
+ "type": "object",
121
+ "additionalProperties": false,
122
+ "required": ["label", "before", "after"],
123
+ "properties": {
124
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
125
+ "mono": {"type": "boolean"},
126
+ "before": {"$ref": "#/$defs/number"},
127
+ "after": {"$ref": "#/$defs/number"},
128
+ "details": {
129
+ "type": "array",
130
+ "maxItems": 3,
131
+ "items": {
132
+ "type": "object",
133
+ "additionalProperties": false,
134
+ "required": ["label", "before", "after"],
135
+ "properties": {
136
+ "label": {"type": "string", "minLength": 1, "maxLength": 32},
137
+ "before": {"type": "string", "minLength": 1, "maxLength": 32},
138
+ "after": {"type": "string", "minLength": 1, "maxLength": 32}
139
+ }
140
+ }
141
+ }
142
+ }
143
+ }
144
+ }
145
+ }
146
+ },
147
+ "trend": {
148
+ "type": "object",
149
+ "additionalProperties": false,
150
+ "required": ["type", "series"],
151
+ "dependentRequired": {"start": ["step_seconds"], "step_seconds": ["start"]},
152
+ "properties": {
153
+ "type": {"const": "trend"},
154
+ "slot": {"$ref": "#/$defs/slot"},
155
+ "anchor": {"$ref": "#/$defs/anchor"},
156
+ "postmortem": {"$ref": "#/$defs/postmortem"},
157
+ "example": {"$ref": "#/$defs/example"},
158
+ "title": {"type": "string", "maxLength": 80},
159
+ "unit": {"type": "string", "maxLength": 12},
160
+ "series": {"type": "array", "minItems": 2, "maxItems": 500, "items": {"$ref": "#/$defs/number"}},
161
+ "start": {"type": "string", "format": "date-time"},
162
+ "step_seconds": {"type": "integer", "minimum": 1, "maximum": 86400},
163
+ "max": {"type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000},
164
+ "threshold": {"$ref": "#/$defs/threshold"},
165
+ "marks": {
166
+ "type": "array",
167
+ "maxItems": 3,
168
+ "items": {
169
+ "type": "object",
170
+ "additionalProperties": false,
171
+ "required": ["i", "label"],
172
+ "properties": {
173
+ "i": {"type": "integer", "minimum": 0, "description": "An index into series."},
174
+ "label": {"type": "string", "minLength": 1, "maxLength": 48}
175
+ }
176
+ }
177
+ },
178
+ "source": {
179
+ "type": "object",
180
+ "description": "Provenance only. The series stays in series.",
181
+ "additionalProperties": false,
182
+ "properties": {
183
+ "kind": {"type": "string", "maxLength": 80},
184
+ "datasource": {"type": "string", "maxLength": 80},
185
+ "query": {"type": "string", "maxLength": 2000},
186
+ "from": {"type": "string", "maxLength": 80},
187
+ "to": {"type": "string", "maxLength": 80},
188
+ "step": {"type": "string", "maxLength": 80},
189
+ "artifact_id": {"type": "string", "maxLength": 80}
190
+ }
191
+ }
192
+ }
193
+ },
194
+ "table": {
195
+ "type": "object",
196
+ "additionalProperties": false,
197
+ "required": ["type", "columns", "rows"],
198
+ "properties": {
199
+ "type": {"const": "table"},
200
+ "slot": {"$ref": "#/$defs/slot"},
201
+ "anchor": {"$ref": "#/$defs/anchor"},
202
+ "postmortem": {"$ref": "#/$defs/postmortem"},
203
+ "example": {"$ref": "#/$defs/example"},
204
+ "title": {"type": "string", "maxLength": 80},
205
+ "columns": {
206
+ "type": "array",
207
+ "minItems": 1,
208
+ "maxItems": 6,
209
+ "items": {
210
+ "type": "object",
211
+ "additionalProperties": false,
212
+ "required": ["label"],
213
+ "properties": {"label": {"type": "string", "minLength": 1, "maxLength": 80}}
214
+ }
215
+ },
216
+ "rows": {
217
+ "type": "array",
218
+ "minItems": 1,
219
+ "maxItems": 12,
220
+ "items": {
221
+ "type": "object",
222
+ "additionalProperties": false,
223
+ "required": ["cells"],
224
+ "properties": {
225
+ "cells": {
226
+ "type": "array",
227
+ "description": "Exactly one text per column; a cell may be an empty string.",
228
+ "items": {"type": "string", "maxLength": 64}
229
+ }
230
+ }
231
+ }
232
+ }
233
+ }
234
+ },
235
+ "checks": {
236
+ "type": "object",
237
+ "additionalProperties": false,
238
+ "required": ["type", "items"],
239
+ "properties": {
240
+ "type": {"const": "checks"},
241
+ "slot": {"$ref": "#/$defs/slot"},
242
+ "anchor": {"$ref": "#/$defs/anchor"},
243
+ "postmortem": {"$ref": "#/$defs/postmortem"},
244
+ "example": {"$ref": "#/$defs/example"},
245
+ "title": {"type": "string", "maxLength": 80},
246
+ "items": {
247
+ "type": "array",
248
+ "minItems": 1,
249
+ "maxItems": 12,
250
+ "items": {
251
+ "type": "object",
252
+ "additionalProperties": false,
253
+ "required": ["label", "state"],
254
+ "properties": {
255
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
256
+ "state": {"enum": ["pass", "fail", "pending", "skipped"]},
257
+ "detail": {"type": "string", "maxLength": 160}
258
+ }
259
+ }
260
+ }
261
+ }
262
+ },
263
+ "changes": {
264
+ "type": "object",
265
+ "additionalProperties": false,
266
+ "required": ["type", "rows"],
267
+ "properties": {
268
+ "type": {"const": "changes"},
269
+ "slot": {"$ref": "#/$defs/slot"},
270
+ "anchor": {"$ref": "#/$defs/anchor"},
271
+ "postmortem": {"$ref": "#/$defs/postmortem"},
272
+ "example": {"$ref": "#/$defs/example"},
273
+ "title": {"type": "string", "maxLength": 80},
274
+ "rows": {
275
+ "type": "array",
276
+ "minItems": 1,
277
+ "maxItems": 8,
278
+ "items": {
279
+ "type": "object",
280
+ "additionalProperties": false,
281
+ "required": ["label"],
282
+ "anyOf": [{"required": ["from"]}, {"required": ["to"]}],
283
+ "properties": {
284
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
285
+ "from": {"type": "string", "maxLength": 80},
286
+ "to": {"type": "string", "maxLength": 80},
287
+ "note": {"type": "string", "maxLength": 160}
288
+ }
289
+ }
290
+ }
291
+ }
292
+ },
293
+ "range_overlap": {
294
+ "type": "object",
295
+ "description": "Where two to four ranges meet. The overlap (where every row is in the same place) is computed, not sent.",
296
+ "additionalProperties": false,
297
+ "required": ["type", "rows"],
298
+ "dependentRequired": {"min": ["max"], "max": ["min"]},
299
+ "properties": {
300
+ "type": {"const": "range_overlap"},
301
+ "slot": {"$ref": "#/$defs/slot"},
302
+ "anchor": {"$ref": "#/$defs/anchor"},
303
+ "postmortem": {"$ref": "#/$defs/postmortem"},
304
+ "example": {"$ref": "#/$defs/example"},
305
+ "title": {"type": "string", "maxLength": 80},
306
+ "unit": {"type": "string", "maxLength": 12},
307
+ "min": {"$ref": "#/$defs/number", "description": "The start of the whole range shown in the overview strip. Both min and max, or neither; min is below max and every row lies inside them."},
308
+ "max": {"$ref": "#/$defs/number", "description": "The end of the whole range."},
309
+ "rows": {
310
+ "type": "array",
311
+ "minItems": 2,
312
+ "maxItems": 4,
313
+ "items": {
314
+ "type": "object",
315
+ "additionalProperties": false,
316
+ "required": ["label", "from", "to"],
317
+ "properties": {
318
+ "label": {"type": "string", "minLength": 1, "maxLength": 80},
319
+ "from": {"$ref": "#/$defs/number"},
320
+ "to": {"$ref": "#/$defs/number", "description": "Not below from."}
321
+ }
322
+ }
323
+ },
324
+ "window": {
325
+ "type": "array",
326
+ "minItems": 2,
327
+ "maxItems": 2,
328
+ "items": {"$ref": "#/$defs/number"},
329
+ "description": "[from, to] with from below to: the zoom. Absent: the figure zooms to the overlap."
330
+ }
331
+ }
332
+ },
333
+ "histogram": {
334
+ "type": "object",
335
+ "description": "A distribution before and after. p50, p95, p99 and the share over the threshold are computed from the buckets by linear interpolation.",
336
+ "additionalProperties": false,
337
+ "required": ["type", "edges", "before", "after"],
338
+ "properties": {
339
+ "type": {"const": "histogram"},
340
+ "slot": {"$ref": "#/$defs/slot"},
341
+ "anchor": {"$ref": "#/$defs/anchor"},
342
+ "postmortem": {"$ref": "#/$defs/postmortem"},
343
+ "example": {"$ref": "#/$defs/example"},
344
+ "title": {"type": "string", "maxLength": 80},
345
+ "unit": {"type": "string", "maxLength": 12},
346
+ "edges": {
347
+ "type": "array",
348
+ "minItems": 3,
349
+ "maxItems": 61,
350
+ "items": {"type": "number", "minimum": 0, "maximum": 1000000000000},
351
+ "description": "Bucket edges, strictly increasing: one more than there are buckets."
352
+ },
353
+ "before": {
354
+ "type": "array",
355
+ "minItems": 2,
356
+ "maxItems": 60,
357
+ "items": {"type": "number", "minimum": 0, "maximum": 1000000000000},
358
+ "description": "One count per bucket, adding up to more than 0."
359
+ },
360
+ "after": {
361
+ "type": "array",
362
+ "minItems": 2,
363
+ "maxItems": 60,
364
+ "items": {"type": "number", "minimum": 0, "maximum": 1000000000000},
365
+ "description": "One count per bucket, adding up to more than 0."
366
+ },
367
+ "threshold": {"$ref": "#/$defs/threshold"},
368
+ "source": {"$ref": "#/$defs/source"}
369
+ }
370
+ },
371
+ "run_history": {
372
+ "type": "object",
373
+ "description": "CI builds, jobs, canaries or deploys in order, with the changes that fall between them.",
374
+ "additionalProperties": false,
375
+ "required": ["type", "runs"],
376
+ "properties": {
377
+ "type": {"const": "run_history"},
378
+ "slot": {"$ref": "#/$defs/slot"},
379
+ "anchor": {"$ref": "#/$defs/anchor"},
380
+ "postmortem": {"$ref": "#/$defs/postmortem"},
381
+ "example": {"$ref": "#/$defs/example"},
382
+ "title": {"type": "string", "maxLength": 80},
383
+ "repo": {"$ref": "#/$defs/repo"},
384
+ "branch": {"type": "string", "maxLength": 80},
385
+ "runs": {
386
+ "type": "array",
387
+ "minItems": 2,
388
+ "maxItems": 30,
389
+ "description": "Oldest first. A ref is unique in the block.",
390
+ "items": {
391
+ "type": "object",
392
+ "additionalProperties": false,
393
+ "required": ["ref", "result"],
394
+ "properties": {
395
+ "ref": {"type": "string", "minLength": 1, "maxLength": 80, "description": "The run id; marks and span point at it."},
396
+ "result": {"enum": ["success", "failure", "cancelled", "pending"]},
397
+ "sha": {"type": "string", "maxLength": 64},
398
+ "at": {"type": "string", "format": "date-time"},
399
+ "trigger": {"type": "string", "maxLength": 32},
400
+ "job": {"type": "string", "maxLength": 80, "description": "The failing job."},
401
+ "url": {"type": "string", "maxLength": 500, "pattern": "^https://[^\\s]+$", "description": "Overrides the link built from repo and ref."}
402
+ }
403
+ }
404
+ },
405
+ "marks": {
406
+ "type": "array",
407
+ "maxItems": 4,
408
+ "items": {
409
+ "type": "object",
410
+ "additionalProperties": false,
411
+ "required": ["between", "change_ref"],
412
+ "properties": {
413
+ "between": {
414
+ "type": "array",
415
+ "minItems": 2,
416
+ "maxItems": 2,
417
+ "items": {"type": "string", "minLength": 1, "maxLength": 80},
418
+ "description": "The refs of two neighbouring runs, the second right after the first."
419
+ },
420
+ "change_ref": {"enum": ["regression", "fix", "change"], "description": "The role of the change in the run's change_refs."},
421
+ "sha": {"type": "string", "maxLength": 64},
422
+ "at": {"type": "string", "format": "date-time"},
423
+ "title": {"type": "string", "maxLength": 80}
424
+ }
425
+ }
426
+ },
427
+ "span": {
428
+ "type": "object",
429
+ "additionalProperties": false,
430
+ "required": ["from", "to", "label"],
431
+ "properties": {
432
+ "from": {"type": "string", "minLength": 1, "maxLength": 80},
433
+ "to": {"type": "string", "minLength": 1, "maxLength": 80, "description": "Not before from."},
434
+ "label": {"type": "string", "minLength": 1, "maxLength": 48}
435
+ }
436
+ }
437
+ }
438
+ },
439
+ "diff": {
440
+ "type": "object",
441
+ "description": "The change that broke or fixed something: the file, the commit, the size of the whole change and at most 12 of its lines.",
442
+ "additionalProperties": false,
443
+ "required": ["type", "path", "ref", "additions", "deletions", "hunks"],
444
+ "properties": {
445
+ "type": {"const": "diff"},
446
+ "slot": {"$ref": "#/$defs/slot"},
447
+ "anchor": {"$ref": "#/$defs/anchor"},
448
+ "postmortem": {"$ref": "#/$defs/postmortem"},
449
+ "example": {"$ref": "#/$defs/example"},
450
+ "title": {"type": "string", "maxLength": 80},
451
+ "path": {"type": "string", "minLength": 1, "maxLength": 200},
452
+ "repo": {"$ref": "#/$defs/repo"},
453
+ "ref": {"type": "string", "minLength": 1, "maxLength": 64, "description": "The commit."},
454
+ "at": {"type": "string", "format": "date-time", "description": "When it was committed."},
455
+ "additions": {"type": "integer", "minimum": 0, "maximum": 1000000},
456
+ "deletions": {"type": "integer", "minimum": 0, "maximum": 1000000},
457
+ "hunks": {
458
+ "type": "array",
459
+ "minItems": 1,
460
+ "maxItems": 6,
461
+ "x-maxLinesInAll": 12,
462
+ "description": "Hunks of lines, at most 12 lines in all (a JSON Schema cannot count across hunks; the API does). A line's text is not trimmed: leading spaces are indentation.",
463
+ "items": {
464
+ "type": "array",
465
+ "minItems": 1,
466
+ "items": {
467
+ "type": "object",
468
+ "additionalProperties": false,
469
+ "required": ["op", "text"],
470
+ "properties": {
471
+ "op": {"enum": ["+", "-"]},
472
+ "text": {"type": "string", "maxLength": 160}
473
+ }
474
+ }
475
+ }
476
+ }
477
+ }
478
+ }
479
+ }
480
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "upstream_repository": "https://github.com/tellagen/tellagen",
3
+ "upstream_commit": "6ec42d33dfb68dd376d31200bfcce7f419314136",
4
+ "upstream_worktree_dirty": true,
5
+ "contract_version": "2026-11-03.1",
6
+ "bundle_sha256": "5ae7a7fb01007f357ea04a10e002e0b8fbe01b3e59ae509ccc61bd63dc3e455c",
7
+ "bundle_path": "contracts/runbooks"
8
+ }
package/dist/auth.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { TellagenClient } from "./client.js";
2
2
  /**
3
- * Validate the API key on startup by calling /api/v1/auth/me.
3
+ * Validate the API key explicitly by calling /api/v1/auth/me.
4
+ * MCP startup intentionally does not call this function.
4
5
  * Throws if the key is invalid or the API is unreachable.
5
6
  */
6
7
  export declare function validateAuth(client: TellagenClient): Promise<void>;
package/dist/auth.js CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * Validate the API key on startup by calling /api/v1/auth/me.
2
+ * Validate the API key explicitly by calling /api/v1/auth/me.
3
+ * MCP startup intentionally does not call this function.
3
4
  * Throws if the key is invalid or the API is unreachable.
4
5
  */
5
6
  export async function validateAuth(client) {
package/dist/auth.js.map CHANGED
@@ -1 +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"}
1
+ {"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAaA;;;;GAIG;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 CHANGED
@@ -2,6 +2,19 @@ export interface ClientConfig {
2
2
  apiUrl: string;
3
3
  apiKey: string;
4
4
  }
5
+ export interface BinaryFetchOptions {
6
+ /** The most bytes read; a larger response is refused. */
7
+ maxBytes: number;
8
+ /** The Accept header. Defaults to any type. */
9
+ accept?: string;
10
+ }
11
+ export interface BinaryResponse {
12
+ bytes: Uint8Array;
13
+ /** The media type without parameters, lower case; empty when not sent. */
14
+ contentType: string;
15
+ etag?: string;
16
+ contentDisposition?: string;
17
+ }
5
18
  /** Thin HTTP wrapper for the Tellagen public API. */
6
19
  export declare class TellagenClient {
7
20
  private readonly baseUrl;
@@ -9,7 +22,14 @@ export declare class TellagenClient {
9
22
  constructor(config: ClientConfig);
10
23
  private headers;
11
24
  private request;
25
+ /**
26
+ * GET the bytes at an API path with the API key, for images and other
27
+ * files. A response larger than maxBytes is refused before it is read in
28
+ * full, and an error status is reported like any other API error.
29
+ */
30
+ getBinary(path: string, options: BinaryFetchOptions): Promise<BinaryResponse>;
12
31
  get<T>(path: string): Promise<T>;
13
32
  post<T>(path: string, body: unknown): Promise<T>;
33
+ put<T>(path: string, body: unknown): Promise<T>;
14
34
  patch<T>(path: string, body: unknown): Promise<T>;
15
35
  }