@tellagen/mcp-server 0.4.2 → 0.5.1
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/LICENSE +21 -0
- package/README.md +337 -104
- package/SKILL.md +83 -17
- package/contracts/mcp-protocol.json +155 -0
- package/contracts/runbooks/manifest.json +26 -6
- package/contracts/runbooks/v2/cause-lead.guidance.json +37 -0
- package/contracts/runbooks/v2/client-protocol.json +926 -0
- package/contracts/runbooks/v2/client-writes.guidance.json +42 -0
- package/contracts/runbooks/v2/fixtures/timeline-event-blocks-rejected.json +30 -5
- package/contracts/runbooks/v2/result-summary.guidance.json +21 -0
- package/contracts/runbooks/v2/timeline-event-blocks.schema.json +18 -11
- package/contracts/tellagen-runbook-contracts.json +4 -4
- package/dist/active-run.d.ts +29 -0
- package/dist/active-run.js +67 -0
- package/dist/active-run.js.map +1 -0
- package/dist/bootstrap.d.ts +20 -0
- package/dist/bootstrap.js +29 -0
- package/dist/bootstrap.js.map +1 -0
- package/dist/cause-lead.d.ts +25 -0
- package/dist/cause-lead.js +145 -0
- package/dist/cause-lead.js.map +1 -0
- package/dist/cli/auth.d.ts +22 -0
- package/dist/cli/auth.js +207 -0
- package/dist/cli/auth.js.map +1 -0
- package/dist/cli/io.d.ts +16 -0
- package/dist/cli/io.js +53 -0
- package/dist/cli/io.js.map +1 -0
- package/dist/cli/listen-guard.d.ts +12 -0
- package/dist/cli/listen-guard.js +50 -0
- package/dist/cli/listen-guard.js.map +1 -0
- package/dist/cli/listen.d.ts +28 -0
- package/dist/cli/listen.js +205 -0
- package/dist/cli/listen.js.map +1 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +53 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/trace-hook.d.ts +23 -0
- package/dist/cli/trace-hook.js +99 -0
- package/dist/cli/trace-hook.js.map +1 -0
- package/dist/client.d.ts +92 -6
- package/dist/client.js +300 -23
- package/dist/client.js.map +1 -1
- package/dist/config.d.ts +17 -0
- package/dist/config.js +38 -0
- package/dist/config.js.map +1 -0
- package/dist/credentials.d.ts +120 -0
- package/dist/credentials.js +363 -0
- package/dist/credentials.js.map +1 -0
- package/dist/diagnosis-structure.d.ts +257 -197
- package/dist/diagnosis-structure.js +144 -1
- package/dist/diagnosis-structure.js.map +1 -1
- package/dist/diff-figure.d.ts +56 -0
- package/dist/diff-figure.js +276 -0
- package/dist/diff-figure.js.map +1 -0
- package/dist/errors.d.ts +21 -0
- package/dist/errors.js +60 -0
- package/dist/errors.js.map +1 -1
- package/dist/figures.d.ts +312 -232
- package/dist/figures.js +189 -47
- package/dist/figures.js.map +1 -1
- package/dist/guide-resources.d.ts +28 -0
- package/dist/guide-resources.js +81 -0
- package/dist/guide-resources.js.map +1 -0
- package/dist/heartbeat.d.ts +24 -0
- package/dist/heartbeat.js +94 -0
- package/dist/heartbeat.js.map +1 -0
- package/dist/home.d.ts +8 -0
- package/dist/home.js +14 -0
- package/dist/home.js.map +1 -0
- package/dist/identity.d.ts +32 -0
- package/dist/identity.js +83 -0
- package/dist/identity.js.map +1 -0
- package/dist/index.js +46 -14
- package/dist/index.js.map +1 -1
- package/dist/listen-config.d.ts +67 -0
- package/dist/listen-config.js +83 -0
- package/dist/listen-config.js.map +1 -0
- package/dist/listen-probe.d.ts +57 -0
- package/dist/listen-probe.js +158 -0
- package/dist/listen-probe.js.map +1 -0
- package/dist/listen-rules.d.ts +88 -0
- package/dist/listen-rules.js +252 -0
- package/dist/listen-rules.js.map +1 -0
- package/dist/listen-settings.d.ts +18 -0
- package/dist/listen-settings.js +50 -0
- package/dist/listen-settings.js.map +1 -0
- package/dist/listen-wrap.d.ts +21 -0
- package/dist/listen-wrap.js +52 -0
- package/dist/listen-wrap.js.map +1 -0
- package/dist/listener.d.ts +195 -0
- package/dist/listener.js +600 -0
- package/dist/listener.js.map +1 -0
- package/dist/open-run.d.ts +2 -0
- package/dist/open-run.js +5 -0
- package/dist/open-run.js.map +1 -0
- package/dist/prompts.d.ts +12 -0
- package/dist/prompts.js +37 -0
- package/dist/prompts.js.map +1 -0
- package/dist/redact.d.ts +13 -0
- package/dist/redact.js +76 -0
- package/dist/redact.js.map +1 -0
- package/dist/run-events.d.ts +54 -0
- package/dist/run-events.js +210 -0
- package/dist/run-events.js.map +1 -0
- package/dist/run-state.d.ts +221 -0
- package/dist/run-state.js +221 -0
- package/dist/run-state.js.map +1 -0
- package/dist/server.d.ts +22 -2
- package/dist/server.js +137 -29
- package/dist/server.js.map +1 -1
- package/dist/session.d.ts +99 -0
- package/dist/session.js +187 -0
- package/dist/session.js.map +1 -0
- package/dist/shell-rules.d.ts +49 -0
- package/dist/shell-rules.js +335 -0
- package/dist/shell-rules.js.map +1 -0
- package/dist/signin-index.d.ts +164 -0
- package/dist/signin-index.js +116 -0
- package/dist/signin-index.js.map +1 -0
- package/dist/signin.d.ts +169 -0
- package/dist/signin.js +541 -0
- package/dist/signin.js.map +1 -0
- package/dist/source-bases.d.ts +75 -0
- package/dist/source-bases.js +125 -0
- package/dist/source-bases.js.map +1 -0
- package/dist/start.d.ts +7 -6
- package/dist/start.js +14 -7
- package/dist/start.js.map +1 -1
- package/dist/tools/catalog.d.ts +44 -0
- package/dist/tools/catalog.js +105 -0
- package/dist/tools/catalog.js.map +1 -0
- package/dist/tools/causes.d.ts +6 -6
- package/dist/tools/causes.js +4 -5
- package/dist/tools/causes.js.map +1 -1
- package/dist/tools/context.js +5 -5
- package/dist/tools/context.js.map +1 -1
- package/dist/tools/datasources.js +71 -14
- package/dist/tools/datasources.js.map +1 -1
- package/dist/tools/diagnostics.js +2 -2
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/figures.d.ts +3 -2
- package/dist/tools/figures.js +38 -13
- package/dist/tools/figures.js.map +1 -1
- package/dist/tools/findings.d.ts +28 -0
- package/dist/tools/findings.js +75 -12
- package/dist/tools/findings.js.map +1 -1
- package/dist/tools/incidents.js +5 -5
- package/dist/tools/incidents.js.map +1 -1
- package/dist/tools/index.d.ts +19 -2
- package/dist/tools/index.js +115 -14
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/investigations.d.ts +54 -0
- package/dist/tools/investigations.js +372 -68
- package/dist/tools/investigations.js.map +1 -1
- package/dist/tools/next.d.ts +20 -0
- package/dist/tools/next.js +136 -0
- package/dist/tools/next.js.map +1 -0
- package/dist/tools/postmortem-runbooks.d.ts +52 -52
- package/dist/tools/postmortem-runbooks.js +3 -10
- package/dist/tools/postmortem-runbooks.js.map +1 -1
- package/dist/tools/resume.d.ts +5 -0
- package/dist/tools/resume.js +136 -0
- package/dist/tools/resume.js.map +1 -0
- package/dist/tools/signin.d.ts +12 -0
- package/dist/tools/signin.js +54 -0
- package/dist/tools/signin.js.map +1 -0
- package/dist/tools/source-links.d.ts +16 -0
- package/dist/tools/source-links.js +25 -13
- package/dist/tools/source-links.js.map +1 -1
- package/dist/tools/timeline.js +57 -11
- package/dist/tools/timeline.js.map +1 -1
- package/dist/trace-record.d.ts +36 -0
- package/dist/trace-record.js +283 -0
- package/dist/trace-record.js.map +1 -0
- package/dist/version.d.ts +10 -2
- package/dist/version.js +20 -1
- package/dist/version.js.map +1 -1
- package/package.json +23 -3
- package/server.json +9 -9
- package/contracts/runbooks/v1/fixtures/global-runbook.json +0 -7
- package/contracts/runbooks/v1/runbook-definition.schema.json +0 -25
- package/dist/auth.d.ts +0 -7
- package/dist/auth.js +0 -19
- package/dist/auth.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,49 +1,82 @@
|
|
|
1
1
|
# @tellagen/mcp-server
|
|
2
2
|
|
|
3
|
-
MCP server for Tellagen
|
|
3
|
+
An MCP server for [Tellagen](https://tellagen.com), the incident workspace for SRE and DevOps teams. It lets your own AI client (Claude Code, Codex, Cursor and other MCP clients) pick up an investigation, post findings with evidence, and write timeline events and postmortem proposals back to Tellagen. The server runs on your machine. Your client keeps the credentials for Grafana, GitHub and the other tools it reads from, and Tellagen never stores them.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
```bash
|
|
6
|
+
npx -y @tellagen/mcp-server
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Sign in with `npx @tellagen/mcp-server login`, or ask your client to sign in to Tellagen (see the quick start below). Without a sign-in the server still starts, and the first tool call tells you the steps. The MCP Registry name is `io.github.tellagen/mcp-server`.
|
|
10
|
+
|
|
11
|
+
Works with any MCP-compatible client: Claude Code, Codex, Cursor, VS Code Copilot, Windsurf.
|
|
6
12
|
|
|
7
13
|
## Quick start
|
|
8
14
|
|
|
9
|
-
### 1.
|
|
15
|
+
### 1. Sign in
|
|
16
|
+
|
|
17
|
+
Run `npx @tellagen/mcp-server login`, or ask your client to sign in to Tellagen (it calls `tellagen_sign_in`). The server shows a short code and opens your browser. Check that the code on the page matches, then approve. There is no key to copy.
|
|
18
|
+
|
|
19
|
+
- The key goes to your system keychain: the macOS Keychain, the Secret Service on Linux, or Windows Credential Manager. On a computer with no keychain it goes to a file that only your user can read (mode 600), and the server says so. It is never written anywhere else.
|
|
20
|
+
- Over SSH, or with no display, the server prints the address and the code and opens nothing. `--no-browser` does the same.
|
|
21
|
+
- The key is personal, works for 30 or 90 days, and one sign-in is kept for each workspace address.
|
|
22
|
+
- `npx @tellagen/mcp-server status` shows the sign-in.
|
|
23
|
+
- **Sign out.** `npx @tellagen/mcp-server logout` removes the key from this computer only. Tellagen keeps the key valid until it expires or you sign the client out on the server: in Tellagen, open **Settings > Local diagnosis**, find the client under **Connected clients**, and choose **Sign out**. That revokes the key.
|
|
10
24
|
|
|
11
|
-
|
|
25
|
+
`TELLAGEN_API_KEY` and `TELLAGEN_API_URL` still work, and they win over a stored sign-in (see "Use an API key instead" below).
|
|
12
26
|
|
|
13
|
-
|
|
27
|
+
### 2. Add the server to your client
|
|
14
28
|
|
|
15
|
-
|
|
29
|
+
Use `@latest` in every setup, so the client starts the newest release.
|
|
16
30
|
|
|
17
|
-
**Claude Code** (
|
|
31
|
+
**Claude Code with the plugin** (the easiest way; it also adds `/tellagen:connect` and `/tellagen:diagnose`):
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
/plugin marketplace add tellagen/tellagen-marketplace
|
|
35
|
+
/plugin install tellagen@tellagen-marketplace
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Then run `/tellagen:connect`.
|
|
39
|
+
|
|
40
|
+
**Claude Code without the plugin:**
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
claude mcp add tellagen -- npx -y @tellagen/mcp-server@latest
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Codex:**
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
codex mcp add tellagen -- npx -y @tellagen/mcp-server@latest
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**Cursor** (`.cursor/mcp.json`) and **Claude Desktop** (`claude_desktop_config.json`: `~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows; restart Claude Desktop after you edit it):
|
|
18
53
|
|
|
19
54
|
```json
|
|
20
55
|
{
|
|
21
56
|
"mcpServers": {
|
|
22
57
|
"tellagen": {
|
|
23
58
|
"command": "npx",
|
|
24
|
-
"args": ["-y", "@tellagen/mcp-server"]
|
|
25
|
-
"env": {
|
|
26
|
-
"TELLAGEN_API_KEY": "tllg_...",
|
|
27
|
-
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com",
|
|
28
|
-
"TELLAGEN_MCP_CLIENT": "claude"
|
|
29
|
-
}
|
|
59
|
+
"args": ["-y", "@tellagen/mcp-server@latest"]
|
|
30
60
|
}
|
|
31
61
|
}
|
|
32
62
|
}
|
|
33
63
|
```
|
|
34
64
|
|
|
35
|
-
|
|
65
|
+
Then ask the client to sign in to Tellagen. If you already have other servers in the file, add the `tellagen` entry to them.
|
|
66
|
+
|
|
67
|
+
**Update.** Restart the client: `@latest` then starts the newest release. If `npx` still starts an old copy from its cache, run `npx -y @tellagen/mcp-server@latest --version` once, then restart the client. With the plugin, open `/plugin` and update Tellagen.
|
|
68
|
+
|
|
69
|
+
**Use an API key instead.** In Tellagen, open **Settings > API Keys**, create a key with the **Local Diagnosis** preset (it sets `incidents:read` and `incidents:write`; `incidents:write` does not imply `incidents:read`, so a key made by hand needs both), and put the key and your workspace API address in the `env` block of the server:
|
|
36
70
|
|
|
37
71
|
```json
|
|
38
72
|
{
|
|
39
73
|
"mcpServers": {
|
|
40
74
|
"tellagen": {
|
|
41
75
|
"command": "npx",
|
|
42
|
-
"args": ["-y", "@tellagen/mcp-server"],
|
|
76
|
+
"args": ["-y", "@tellagen/mcp-server@latest"],
|
|
43
77
|
"env": {
|
|
44
78
|
"TELLAGEN_API_KEY": "tllg_...",
|
|
45
|
-
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
46
|
-
"TELLAGEN_MCP_CLIENT": "codex"
|
|
79
|
+
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
47
80
|
}
|
|
48
81
|
}
|
|
49
82
|
}
|
|
@@ -52,81 +85,205 @@ In Tellagen, go to **Settings > API Keys** and create a key with both `incidents
|
|
|
52
85
|
|
|
53
86
|
Optionally set `TELLAGEN_MCP_PROFILE_ID` to a stable opaque name for this local MCP profile (for example, `work-laptop-codex`). Tellagen uses it only to avoid borrowing access observations from another client profile; never put a username, filesystem path, or secret in it.
|
|
54
87
|
|
|
55
|
-
|
|
88
|
+
The server reads the name and version of your client (Claude Code, Codex, Cursor and so on) from the MCP handshake and sends them to Tellagen, so a run shows which client ran it. You do not set the client anywhere. `TELLAGEN_MCP_CLIENT` is deprecated: it is read for one more release, only when a client sends no name, and for a Tellagen workspace that still accepts only `codex` or `claude`.
|
|
89
|
+
|
|
90
|
+
### 3. Diagnose
|
|
91
|
+
|
|
92
|
+
In Tellagen, open the incident, go to the **Diagnosis** tab and choose **Run diagnosis**. The tab then says it is waiting for your client and shows one short command: `/tellagen:diagnose` in Claude Code (or choose **Open in Claude Code**), and "Diagnose the waiting Tellagen run." in any other client. **Copy the full prompt** gives the whole text. You do not need a run ID: the client calls `tellagen_next_investigation`, which finds the run that waits for it, and then picks it up. With several waiting runs you are asked which one.
|
|
93
|
+
|
|
94
|
+
You can also ask your client directly: *"Diagnose with Tellagen"* or *"Start a Tellagen diagnosis for incident #42"*. In a client that shows MCP prompts as commands, run the `diagnose` prompt (in Claude Code without the plugin: `/mcp__tellagen__diagnose`). If you do have a run ID, the client calls `tellagen_pick_up_investigation` with it.
|
|
95
|
+
|
|
96
|
+
After a restart of the client, ask it to continue. `tellagen_resume` picks the remembered run up again and lists what is already posted.
|
|
56
97
|
|
|
57
|
-
|
|
98
|
+
In **Settings > Local diagnosis**, under **For admins**, **Check MCP tools** gives a prompt with a `diagnostic_session_id` such as `diag_abc123`. That is a tool check, not a run: the client turns on the `settings` toolset, runs safe read-only checks and calls `tellagen_report_diagnostic_tools`.
|
|
58
99
|
|
|
59
|
-
###
|
|
100
|
+
### If something is not set up
|
|
60
101
|
|
|
61
|
-
|
|
102
|
+
The server always starts, so the client shows it as connected. What a tool call answers when it cannot work:
|
|
62
103
|
|
|
63
|
-
|
|
104
|
+
| Situation | The answer |
|
|
105
|
+
|-----------|------------|
|
|
106
|
+
| No sign-in and no `TELLAGEN_API_KEY` or `TELLAGEN_API_URL` | `tellagen_not_set_up`, with the steps to sign in (or to create a key and where to put it) |
|
|
107
|
+
| Tellagen refuses the key (wrong, revoked or expired) | HTTP 401, with the steps to replace the key |
|
|
108
|
+
| The seat of the key's owner is paused | `seat_access_suspended`, with who can restore it |
|
|
64
109
|
|
|
65
|
-
|
|
110
|
+
The server asks Tellagen once, right after the MCP handshake, whether the key works. It does not wait for the answer, so a slow or unreachable API never keeps the client from listing the tools. A key that was refused is asked about again after 15 seconds, so a restored seat needs no restart. No message contains the key.
|
|
66
111
|
|
|
67
112
|
## Tools
|
|
68
113
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
|
76
|
-
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
|
101
|
-
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `tellagen_complete_investigation` |
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
|
118
|
-
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
114
|
+
The server offers 50 tools, all with the prefix `tellagen_`, in five toolsets. A tool that reads never changes anything. A person, not an API key, accepts or rejects a root cause in Tellagen: no tool can do it.
|
|
115
|
+
|
|
116
|
+
### Toolsets
|
|
117
|
+
|
|
118
|
+
A client pays for every tool it lists, in the model's context. So the server lists only the sets a task needs. `diagnosis` and `incidents` are on when you choose nothing.
|
|
119
|
+
|
|
120
|
+
| Your task | Toolsets |
|
|
121
|
+
|-----------|----------|
|
|
122
|
+
| Diagnose an incident | `diagnosis,incidents` (the default) |
|
|
123
|
+
| Edit the timeline of an incident | add `timeline` |
|
|
124
|
+
| Answer a postmortem revision request or a runbook analysis request | add `postmortem` |
|
|
125
|
+
| Run **Check MCP tools** from Tellagen settings, or inspect a run | add `settings` |
|
|
126
|
+
| Everything | `all` |
|
|
127
|
+
|
|
128
|
+
Choose the sets with the `--toolsets` argument or the `TELLAGEN_TOOLSETS` variable, as a comma-separated list:
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
"args": ["-y", "@tellagen/mcp-server", "--toolsets", "diagnosis,incidents,timeline"]
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The model can also turn a set on in a running session with `tellagen_enable_toolset`; the server then tells the client that the tool list changed. Tools are always listed in the same order, and every tool carries the MCP annotations `readOnlyHint`, `destructiveHint` and `idempotentHint`. In the tables below, "reads" changes nothing, "adds" creates a record or moves a run forward, and "changes" overwrites fields of a record or ends a run.
|
|
135
|
+
|
|
136
|
+
### `diagnosis`
|
|
137
|
+
|
|
138
|
+
Run a diagnosis from pickup to completion. On by default.
|
|
139
|
+
|
|
140
|
+
| Tool | Effect | Purpose |
|
|
141
|
+
|------|--------|---------|
|
|
142
|
+
| `tellagen_next_investigation` | reads | Find the run that waits for a client, so nobody pastes a run ID |
|
|
143
|
+
| `tellagen_pick_up_investigation` | adds | Attach this session to a run, report the client, the model and the data sources it can reach, and get the context bundle |
|
|
144
|
+
| `tellagen_resume` | adds | Continue the run this computer was working on, after a restart of the client |
|
|
145
|
+
| `tellagen_get_incident_context` | reads | Re-read the context bundle of a run you already picked up |
|
|
146
|
+
| `tellagen_post_trace_step` | adds | Post or update a readable progress step, with the guidance basis |
|
|
147
|
+
| `tellagen_post_runbook_check_attempt` | adds | Post an attempt at one frozen runbook check and source |
|
|
148
|
+
| `tellagen_update_cause` | changes | Post or update a cause under test while the run is live |
|
|
149
|
+
| `tellagen_post_finding` | adds | Post one finding with its evidence refs, screenshots and links |
|
|
150
|
+
| `tellagen_update_finding` | changes | Dismiss a finding or restore it to draft |
|
|
151
|
+
| `tellagen_build_figure` | reads | Turn numbers from a tool result into a figure that Tellagen draws, and check it against the limits |
|
|
152
|
+
| `tellagen_build_source_link` | reads | Build the link or the copyable command for an evidence ref (Grafana, GitHub, Kubernetes) |
|
|
153
|
+
| `tellagen_get_context_attachment` | reads | Read one screenshot that a responder attached to a run |
|
|
154
|
+
| `tellagen_get_investigation_coverage` | reads | Check which frozen checks and evidence are still missing before you complete |
|
|
155
|
+
| `tellagen_post_timeline_event` | adds | Add a timestamped fact to the timeline, optionally with figures |
|
|
156
|
+
| `tellagen_complete_investigation` | changes | Complete or fail a run with the result summary (the cause chain, what was ruled out, coverage, unknowns and change refs) |
|
|
157
|
+
|
|
158
|
+
### `incidents`
|
|
159
|
+
|
|
160
|
+
Read and edit incidents, services and impact, search, start a run, and read the runs and findings of an incident. On by default.
|
|
161
|
+
|
|
162
|
+
| Tool | Effect | Purpose |
|
|
163
|
+
|------|--------|---------|
|
|
164
|
+
| `tellagen_list_incidents` | reads | Find an incident ID: list incidents, optionally by status |
|
|
165
|
+
| `tellagen_get_incident` | reads | Read one incident (severity, status, services, timestamps, manager) |
|
|
166
|
+
| `tellagen_get_incident_timeline` | reads | Read the timeline of an incident |
|
|
167
|
+
| `tellagen_create_incident` | adds | Create an incident when the user asks for one |
|
|
168
|
+
| `tellagen_update_incident` | changes | Change fields of an incident (title, status, severity, team, impact summary, links, timestamps) |
|
|
169
|
+
| `tellagen_search` | reads | Search incidents, timeline events, issues and services when you do not know an ID |
|
|
170
|
+
| `tellagen_list_services` | reads | List the services in the catalog |
|
|
171
|
+
| `tellagen_get_service` | reads | Read one service |
|
|
172
|
+
| `tellagen_get_impact_summary` | reads | Read the customer-impact summary of an incident |
|
|
173
|
+
| `tellagen_list_affected_customers` | reads | List the customers an incident affected |
|
|
174
|
+
| `tellagen_start_investigation` | adds | Start a run when no run ID was given; also starts a follow-up of an earlier run |
|
|
175
|
+
| `tellagen_list_investigation_runs` | reads | List the runs of an incident |
|
|
176
|
+
| `tellagen_get_investigation_workspace` | reads | Read all runs, findings, trace and review state of an incident |
|
|
177
|
+
| `tellagen_list_findings` | reads | List the findings of an incident or run |
|
|
178
|
+
| `tellagen_get_finding` | reads | Read one finding with all its evidence refs |
|
|
179
|
+
|
|
180
|
+
### `timeline`
|
|
181
|
+
|
|
182
|
+
Read and edit timeline events and comments, and promote a finding to the timeline.
|
|
183
|
+
|
|
184
|
+
| Tool | Effect | Purpose |
|
|
185
|
+
|------|--------|---------|
|
|
186
|
+
| `tellagen_get_timeline_event` | reads | Read one timeline event |
|
|
187
|
+
| `tellagen_update_timeline_event` | changes | Change a timeline event |
|
|
188
|
+
| `tellagen_list_timeline_comments` | reads | List the comments on a timeline event |
|
|
189
|
+
| `tellagen_add_timeline_comment` | adds | Comment on a timeline event |
|
|
190
|
+
| `tellagen_promote_finding` | adds | Promote a finding to the incident timeline |
|
|
191
|
+
|
|
192
|
+
### `postmortem`
|
|
193
|
+
|
|
194
|
+
Postmortem revision proposals, legacy imports and runbook candidates.
|
|
195
|
+
|
|
196
|
+
| Tool | Effect | Purpose |
|
|
197
|
+
|------|--------|---------|
|
|
198
|
+
| `tellagen_get_postmortem_revision_request` | reads | Read the draft, evidence and requested changes of a revision request |
|
|
199
|
+
| `tellagen_submit_postmortem_revision_proposal` | adds | Store a proposed postmortem for human review |
|
|
200
|
+
| `tellagen_post_postmortem` | adds | Legacy import: create an immutable postmortem version |
|
|
201
|
+
| `tellagen_update_postmortem` | adds | Legacy import: create the next major postmortem version |
|
|
202
|
+
| `tellagen_get_postmortem_analysis_request` | reads | Read the document and evidence of a standalone runbook analysis request |
|
|
203
|
+
| `tellagen_submit_postmortem_runbook_candidates` | adds | Submit zero to three runbook candidates for review |
|
|
204
|
+
|
|
205
|
+
### `settings`
|
|
206
|
+
|
|
207
|
+
Setup checks and run inspection.
|
|
208
|
+
|
|
209
|
+
| Tool | Effect | Purpose |
|
|
210
|
+
|------|--------|---------|
|
|
211
|
+
| `tellagen_probe_datasource` | reads | Check the local setup of a datasource before you query it |
|
|
212
|
+
| `tellagen_get_diagnostic_session` | reads | Read an MCP diagnostic session (a `diag_*` ID) |
|
|
213
|
+
| `tellagen_report_diagnostic_tools` | adds | Report which MCP tools are visible and usable |
|
|
214
|
+
| `tellagen_list_trace_steps` | reads | List the steps already posted, to avoid repeating work when you resume |
|
|
215
|
+
| `tellagen_list_runbooks` | reads | List the runbooks that matched a run |
|
|
216
|
+
| `tellagen_list_investigation_runbook_waivers` | reads | List the checks a responder waived |
|
|
217
|
+
| `tellagen_update_investigation_scope` | changes | Change the target services, aliases and time range of the investigation |
|
|
218
|
+
|
|
219
|
+
### Always listed
|
|
220
|
+
|
|
221
|
+
| Tool | Effect | Purpose |
|
|
222
|
+
|------|--------|---------|
|
|
223
|
+
| `tellagen_enable_toolset` | reads | Turn on another toolset in the running session |
|
|
224
|
+
| `tellagen_sign_in` | adds | Sign the person in with the browser; shows a code and stores the key in the system keychain |
|
|
225
|
+
|
|
226
|
+
## Commands
|
|
227
|
+
|
|
228
|
+
| Command | What it does |
|
|
229
|
+
|---------|--------------|
|
|
230
|
+
| `login` | Sign in with the browser. `--url` picks the Tellagen API address, `--no-browser` prints the address and code only |
|
|
231
|
+
| `logout` | Remove the key from this computer (`--all` for every workspace). It does not sign the client out on the server |
|
|
232
|
+
| `status` | Show the sign-in. `--line` prints one sentence for a client hook, or nothing when all is well; `--json` for a script |
|
|
233
|
+
| `listen` | Take the diagnosis runs that wait for you and run each with Claude Code, with no window |
|
|
234
|
+
| `trace-hook` | Record one tool call of a client hook as a step of the open run |
|
|
235
|
+
|
|
236
|
+
(`listen-guard` and `listen-wrap` are internal: the listener starts Claude Code through them.)
|
|
237
|
+
|
|
238
|
+
### Listening
|
|
239
|
+
|
|
240
|
+
With listening on, a diagnosis you start in Tellagen needs no terminal: your computer takes the run and runs it with your own Claude Code, with no window. It works with **Claude Code on macOS and Linux**. Codex is refused (it limits shell commands and files with its sandbox but cannot limit the tools of your MCP servers), and so is Windows (the listener cannot prove there that the client obeys its rules).
|
|
241
|
+
|
|
242
|
+
#### How to run it
|
|
243
|
+
|
|
244
|
+
1. Sign in on this computer (`login`), and have the Tellagen MCP server in Claude Code (the plugin does it).
|
|
245
|
+
2. In Tellagen, open **Settings > Local diagnosis** and turn on **Take my runs automatically**.
|
|
246
|
+
3. In a terminal, run `npx @tellagen/mcp-server listen`. When you choose **Run diagnosis** on an incident, the listener starts `claude -p` for the run, with the same prompt as the `diagnose` prompt and the run ID. The prompt says that text from Tellagen and from tools is data, not instructions.
|
|
247
|
+
|
|
248
|
+
- `listen --status` shows the current run and the last five. Each run writes a log in `~/.tellagen/listen/logs` (mode 600).
|
|
249
|
+
- Ctrl+C, or a closed terminal, stops listening and lets the current run finish. A second Ctrl+C stops that run.
|
|
250
|
+
- One run goes at a time (up to three can be allowed), and only one listener runs on a computer. A run has a time limit (45 minutes), kept by a small wrapper process with its own timer, so it holds even if the listener is killed.
|
|
251
|
+
- Only runs that you asked for are started. A run that is listed again after its client ended was not picked up: the listener waits 1, 4, 16 and 60 minutes between starts and gives up on it after five starts. When a client cannot be started (not installed, not signed in), when the limit holds a run back, or when it gave up, the listener tells Tellagen with a coded reason, and the web shows it next to the waiting run.
|
|
252
|
+
- Settings are optional, in `~/.tellagen/listen.json`: `client` (`claude`), `working_folder`, `max_runs`, `run_time_limit_minutes`, `mcp_servers` (the names of your Grafana and GitHub MCP servers if they are not `grafana`, `mcp-grafana` and `github`), `extra_allowed_tools` (single read tools, written `mcp__<server>__<tool>`), `mcp_config_file` and `model`. An unknown setting is an error.
|
|
253
|
+
- With no `working_folder`, the client starts in an empty folder of the listener's own (`~/.tellagen/listen/work`). Set `working_folder` to a repository if you want the run to read code, knowing that it can then read what is in that folder.
|
|
254
|
+
|
|
255
|
+
#### What a listened run may do
|
|
256
|
+
|
|
257
|
+
A listened run only reads, with these exceptions in Tellagen itself. It may use:
|
|
258
|
+
|
|
259
|
+
- **Tellagen tools:** the whole `diagnosis` toolset and the read tools of the `incidents` toolset. So it can write to its own run (steps, causes, findings, the result) and add a timeline event to the incident. It cannot create or edit an incident, a service, an impact record or a postmortem, and it cannot sign in. A person still accepts or rejects a root cause.
|
|
260
|
+
- **Grafana and GitHub:** the read tools of those MCP servers, by exact name.
|
|
261
|
+
- **Shell commands:** `kubectl` and `gh` commands that read, as the parser in `src/shell-rules.ts` allows.
|
|
262
|
+
|
|
263
|
+
The shell rule refuses by default at every level:
|
|
264
|
+
|
|
265
|
+
1. Any shell syntax is refused: a quote, `$`, `;`, `|`, `&`, `<`, `>`, a bracket, a star, a tilde, a backslash, a tab or line break, and a leading `VAR=value`. There are no pipes and no text filters.
|
|
266
|
+
2. The program is `kubectl` or `gh`, by name, with no path.
|
|
267
|
+
3. The verb is from a fixed list. For `kubectl`: `get`, `describe`, `logs`, `top`, `events`, `rollout history`, `version` (with or without `--client`), `api-resources`, `api-versions` and `cluster-info` (with no word after it). For `gh`: `pr view|list|diff|checks|status`, `issue view|list|status`, `run view|list`, `workflow view|list`, `release view|list`, `repo view|list`, `search code|commits|issues|prs|repos`, and `auth status` with no flag.
|
|
268
|
+
4. Each flag is from a fixed list for that verb, with a value that matches a pattern. A flag that is not listed is refused. Never listed: the server, identity and credentials (`-s`, `--server`, `--kubeconfig`, `--context`, `--cluster`, `--user`, `--token`, `--as`, `--as-group`, `--insecure-skip-tls-verify`, the certificate flags, `--hostname`), anything that writes a file or a folder, `--raw`, `-f`, `-k`, and every watch or follow that never ends (`-w`, `--watch`, `--follow`, `rollout status`, `gh pr checks --watch`).
|
|
269
|
+
5. `kubectl get`, `describe`, `events --for` and `rollout history` may name only these kinds, in lower case, and EVERY resource argument is checked (`kubectl top` takes pods and nodes only): pods, deployments, replica sets, stateful sets, daemon sets, jobs, cron jobs, services, endpoints, ingresses, nodes, namespaces, events, horizontal pod autoscalers, pod disruption budgets, persistent volume claims and volumes, and network policies. `all`, config maps, secrets, service accounts, roles, bindings, certificate requests and custom resources are refused. A word that names a secret, token or credential is refused anywhere.
|
|
270
|
+
6. In `gh`, the argument of `view`, `diff` and `checks` is a number, a branch or a tag, never an address. `gh api`, `gh secret`, `gh ssh-key`, `gh gpg-key` and `gh auth` beyond a plain `gh auth status` are refused.
|
|
271
|
+
|
|
272
|
+
**How the client is held to it.** The listener starts Claude Code with `--permission-mode dontAsk`, never with a mode that skips permission prompts. A `PreToolUse` hook on the shell tool runs the same rule (`listen-guard`) before every shell call, and the client has no allow rule for the shell at all: the call runs only when the hook prints an explicit pass. A crash, a timeout or a missing hook means no pass, and the client refuses. The MCP tools it may use are listed by exact name, and a short deny list stays as an outer layer. The tests run one table of good and bad commands against the parser and against what the client is given, so the two cannot drift apart.
|
|
273
|
+
|
|
274
|
+
**Checks at the start.** Before a client is started for the first time, and again when its version changes, the listener runs a canary. It puts a stand-in `kubectl` first on the client's PATH and asks the client to make two shell calls: one the rule passes and one it refuses (`kubectl get pods --server=https://canary.invalid`). It reads the guard's log and checks what the stand-in saw: the passed command must have run, and the refused one must not have. If the client did not call the guard, or ran what the guard refused, the listener will not start it. This costs one short model call. Run the listener from the installed package: the guard is part of the built server.
|
|
275
|
+
|
|
276
|
+
Before it starts, and again before each run, the listener reads the allow rules in your own Claude Code settings (the user settings, `CLAUDE_CONFIG_DIR`, the settings of the working folder and of every folder above it, and the managed settings file). Your rules would be added to its own, and a shell rule of yours would let a shell call through without the hook, so it refuses to start a run when one goes beyond its list, names the rule, and says how to fix it. Set `working_folder` to a folder whose settings are clean, or narrow the rule; a rule in your user settings applies in every folder.
|
|
277
|
+
|
|
278
|
+
### Recording steps from a hook
|
|
279
|
+
|
|
280
|
+
`trace-hook` reads the event of a client hook on standard input and posts one trace step for the open run: the tool, the query or command (tokens and passwords masked), the time range when there is one, how long it took, the size of the result and its first 300 characters. It never sends the whole result. The model cannot see the id of a tool call, so the hook leaves the step id in the remembered-run file and the server names it in the next tool answer; the model adds its outcome with `tellagen_post_trace_step` and that `step_id`, or `recorded:latest` for the newest recorded step. It does nothing when no run is open, when the server does not list `recorded_steps_v1`, or when `TELLAGEN_RECORD_STEPS=0`; it stops after two seconds and always exits with 0, so it never holds a tool call. The Tellagen plugin for Claude Code installs the hooks and has the option to turn the recording off; its README ([tellagen-plugin](https://github.com/Tellagen/tellagen-plugin#hooks)) says what the hook sends.
|
|
124
281
|
|
|
125
282
|
## Auditable runbook guidance
|
|
126
283
|
|
|
127
|
-
|
|
284
|
+
A `tellagen_post_trace_step` call needs a stable `step_id`. The `guidance` basis is optional: when you leave it out, Tellagen records your own judgment with the step title as the reason. When a runbook guided the check, copy the exact frozen values from the pickup/context response: `request.skills[].id` → `runbook_id`, `request.skills[].version` → `version`, and optionally `request.skills[].sections[].id` → `section_id`.
|
|
128
285
|
|
|
129
|
-
|
|
286
|
+
When pickup returns `request.protocol_version: "runbook_plan_v2"`, use `tellagen_post_runbook_check_attempt` for compiled checks and copy the exact frozen `runbook_id`, `runbook_version`, `check_id`, and matching `source_resolution_id`.
|
|
130
287
|
|
|
131
288
|
```json
|
|
132
289
|
{
|
|
@@ -197,11 +354,7 @@ The Tellagen MCP server is designed to work alongside vendor MCP servers for obs
|
|
|
197
354
|
"mcpServers": {
|
|
198
355
|
"tellagen": {
|
|
199
356
|
"command": "npx",
|
|
200
|
-
"args": ["-y", "@tellagen/mcp-server"]
|
|
201
|
-
"env": {
|
|
202
|
-
"TELLAGEN_API_KEY": "tllg_...",
|
|
203
|
-
"TELLAGEN_API_URL": "https://yourcompany.api.tellagen.com"
|
|
204
|
-
}
|
|
357
|
+
"args": ["-y", "@tellagen/mcp-server@latest"]
|
|
205
358
|
},
|
|
206
359
|
"grafana": {
|
|
207
360
|
"command": "uvx",
|
|
@@ -212,8 +365,8 @@ The Tellagen MCP server is designed to work alongside vendor MCP servers for obs
|
|
|
212
365
|
}
|
|
213
366
|
},
|
|
214
367
|
"github": {
|
|
215
|
-
"command": "
|
|
216
|
-
"args": ["
|
|
368
|
+
"command": "docker",
|
|
369
|
+
"args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
|
|
217
370
|
"env": {
|
|
218
371
|
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
|
|
219
372
|
}
|
|
@@ -222,9 +375,11 @@ The Tellagen MCP server is designed to work alongside vendor MCP servers for obs
|
|
|
222
375
|
}
|
|
223
376
|
```
|
|
224
377
|
|
|
378
|
+
The Tellagen entry needs no `env` after you sign in. The tokens in the Grafana and GitHub entries are those servers' own credentials: your client keeps them, and Tellagen never sees them. (`github` here is the official GitHub MCP server, run with Docker; use whichever server and way of running it you prefer.)
|
|
379
|
+
|
|
225
380
|
The agent uses Tellagen tools to manage the investigation lifecycle and vendor tools to gather evidence:
|
|
226
381
|
|
|
227
|
-
1. **Pick up** the Tellagen run
|
|
382
|
+
1. **Pick up** the Tellagen run that waits for the client (`tellagen_next_investigation`, then `tellagen_pick_up_investigation`)
|
|
228
383
|
2. **Read** the returned context bundle, including runbooks and investigation scope
|
|
229
384
|
3. **Probe** Grafana setup with `tellagen_probe_datasource` before querying evidence
|
|
230
385
|
4. **Post trace steps** before and after meaningful checks, preserving the same exact guidance basis for each stable step ID
|
|
@@ -233,7 +388,7 @@ The agent uses Tellagen tools to manage the investigation lifecycle and vendor t
|
|
|
233
388
|
7. **Post** findings back to Tellagen as they're discovered, reusing trace evidence identifiers
|
|
234
389
|
8. **Complete** the investigation run with a concise RCA summary
|
|
235
390
|
|
|
236
|
-
`tellagen_probe_datasource` reads Tellagen's metadata-only datasource catalog, checks that required local env vars such as `
|
|
391
|
+
`tellagen_probe_datasource` reads Tellagen's metadata-only datasource catalog, checks that required local env vars such as `GRAFANA_SERVICE_ACCOUNT_TOKEN` are present, and calls Grafana `/api/health`. `GRAFANA_URL` is optional: it is used when Tellagen sends no Grafana address, or several and none is picked. For Grafana the answer lists every known address as `addresses[]` with its `source` (`pickup`, `GRAFANA_URL` or `datasource`), marks the one it called with `used`, and says with `token_sent` whether the service account token went to it. The token goes only to `GRAFANA_URL`, the address you paired with it. With only an address from Tellagen, the probe calls `/api/health` with no token and says so, and a `GRAFANA_URL` that is not an http or https address is reported as an error. It returns statuses, missing env var names, and HTTP status only; it does not store or return token values.
|
|
237
392
|
|
|
238
393
|
## Source links and the diagnosis structure
|
|
239
394
|
|
|
@@ -245,10 +400,14 @@ Tellagen shows a source on every proof in the Diagnosis tab. Evidence refs (`tel
|
|
|
245
400
|
| `command` | A copyable read-only command (up to 1000 characters) for Kubernetes and other local sources that have no browser link. Tellagen redacts credentials and drops a longer command. |
|
|
246
401
|
| `datasource` | The data source name or uid the evidence came from. |
|
|
247
402
|
|
|
248
|
-
`tellagen_build_source_link` takes the Grafana address
|
|
403
|
+
`tellagen_build_source_link` takes the Grafana address in this order: the `source_bases` that Tellagen sends with the pickup answer and the context read of the run (the enabled Grafana and GitHub addresses of the workspace, remembered with the run, also after a restart or `tellagen_resume`), then `GRAFANA_URL` in the MCP client environment, then the `base_url` of the Tellagen Grafana datasource (Tellagen shows connector settings to settings managers only). With several Grafana addresses in the pickup, pass `connector` with the name of one. A signed-in client therefore needs no `GRAFANA_URL`; set it only when Tellagen sends no Grafana address (or several and you pass no `connector`). A GitHub link uses the GitHub address from the pickup (a GitHub Enterprise server, for example) when the repository belongs to it, and an explicit `github_url` wins. Only http and https addresses are used, credentials, query and fragment are removed, and a copyable command or a file path is never turned into a link. An older Tellagen sends no `source_bases`, and then the order is `GRAFANA_URL`, then the datasource, as before. Explore links use Grafana's `left` parameter and the same builder as the Tellagen web app (shared test vectors keep them identical). The time range defaults to the incident window when you pass `investigation_run_id`. It never puts credentials in a link and makes no network call except to the Tellagen API.
|
|
249
404
|
|
|
250
405
|
`tellagen_complete_investigation` also accepts the causal chain with `finding_ids` (the numeric ids that `tellagen_post_finding` returns), one `figure` per step (a timeline block of any type except `table` and `changes`, validated before the request is sent; see Figures), `ruled_out[]`, `coverage[]`, `unknowns[]` and `change_refs[]` (see Change refs). `tellagen_post_trace_step` accepts `outcome` (supports, rules_out, nothing_notable, inconclusive, unavailable) and `cause_key`. `tellagen_update_cause` posts the causes you are testing while the run is live (`PUT /api/v1/investigation-runs/{id}/causes/{key}`, at most 8 per run); it is sent only when the run advertises `diagnosis_structure_v1`, otherwise the result carries an `mcp_notice` and nothing is sent. The response carries the backend `warnings[]` verbatim and a one-line `warnings_summary` the agent can act on.
|
|
251
406
|
|
|
407
|
+
### Short headlines and real questions
|
|
408
|
+
|
|
409
|
+
The headline claim (`conclusion.sentence` of `result_summary`) states one cause in 15 words or fewer. The `claim` of a `gap` finding that blocks the diagnosis is one real question that ends with a question mark. For example, a good headline is "The checkout pool size of 5 ran out of database connections at 14:02." and a good question is "Did the 14:02 deploy of the billing service lower the retry limit?". Tellagen accepts any text and answers a longer headline with the warning `headline_too_long` and a gap claim that is not a question with `question_not_a_question`. The tool descriptions and the skill guide give the rule, and the server adds an `mcp_notice` to the response of `tellagen_complete_investigation` and `tellagen_post_finding` when the text breaks it. The notice is advice: the call is sent unchanged, and it works the same against an older Tellagen.
|
|
410
|
+
|
|
252
411
|
### Capability negotiation
|
|
253
412
|
|
|
254
413
|
At pickup the MCP server advertises, in `protocol_capabilities`, the runbook v2 bundle plus three optional capabilities. Tellagen lists the ones it accepts in the top-level `server_capabilities` of the pickup (and of `tellagen_get_incident_context`), for example `["diagnosis_structure_v1", "diagnosis_changes_v1", "run_images_v1"]`.
|
|
@@ -259,6 +418,10 @@ At pickup the MCP server advertises, in `protocol_capabilities`, the runbook v2
|
|
|
259
418
|
| `diagnosis_changes_v1` | `change_refs`, and the `ci_run`, `deployment` and `release` link kinds | enables the warning `regression_source_missing` |
|
|
260
419
|
| `run_images_v1` | (nothing extra) it reads screenshots with `tellagen_get_context_attachment` | the web says the client reads images; without it the responder is told the agent gets each caption and a link |
|
|
261
420
|
|
|
421
|
+
One more capability is the server's alone: Tellagen lists `diff_lines_v1` in `server_capabilities` when a diff figure may carry unchanged lines (`op: "context"`) and line numbers (`old_no`, `new_no`). The MCP does not advertise it. Without it, a diff goes out with only its `+` and `-` lines and no numbers (an older Tellagen would drop the whole figure), and the tool result carries an `mcp_notice`. `tellagen_build_figure` takes the `run_id` for this check; the timeline tools go by the latest pickup of the process.
|
|
422
|
+
|
|
423
|
+
Likewise Tellagen lists `figure_extras_v1` when a `stats` figure may carry a `title` and more than four items, and a `run_history` figure may carry `runs_not_shown`. Without it the MCP cuts a stats figure to its first four items and drops the title and `runs_not_shown`, and the tool result carries an `mcp_notice`; `tellagen_build_figure` says so in `notes`. `tellagen_build_figure` takes the `run_id` for this check, and the timeline tools and `tellagen_complete_investigation` apply it to the figures they send.
|
|
424
|
+
|
|
262
425
|
The fields behind a capability go **only** to a run whose response lists it in `server_capabilities`. Against an older Tellagen they are removed before the request leaves, the call still succeeds, and the tool result carries an `mcp_notice` naming what was not sent. A run this process did not pick up is checked once through `GET /api/v1/investigations/{id}/context`.
|
|
263
426
|
|
|
264
427
|
### Change refs
|
|
@@ -292,7 +455,7 @@ Each ref needs one of `ref`, `sha`, `title` or `links`; the MCP refuses an unkno
|
|
|
292
455
|
|
|
293
456
|
| Type | Step figure | Timeline block | Limits |
|
|
294
457
|
| --- | --- | --- | --- |
|
|
295
|
-
| `stats` | yes | yes | 1 to
|
|
458
|
+
| `stats` | yes | yes | 1 to 8 items (4 or fewer is best; the first four are tiles), optional `title` up to 80 characters; with `figure_extras_v1` only |
|
|
296
459
|
| `compare` | yes | yes | 1 to 8 rows, 3 details per row |
|
|
297
460
|
| `trend` | yes | yes | 2 to 500 points, 3 marks; raw samples are put on an even grid |
|
|
298
461
|
| `table` | no | yes | 1 to 6 columns, 1 to 12 rows |
|
|
@@ -300,8 +463,8 @@ Each ref needs one of `ref`, `sha`, `title` or `links`; the MCP refuses an unkno
|
|
|
300
463
|
| `changes` | no | yes | 1 to 8 rows |
|
|
301
464
|
| `range_overlap` | yes | yes | 2 to 4 rows `{label, from, to}`, optional `min`/`max` and `window`; the overlap is computed by Tellagen |
|
|
302
465
|
| `histogram` | yes | yes | 3 to 61 `edges`, one count per bucket in `before` and `after`; the builder also takes Prometheus cumulative `le` buckets |
|
|
303
|
-
| `run_history` | yes | yes | 2 to 30 runs oldest first, 4 marks, a span; the builder also takes the GitHub Actions run list (`github_runs`) and places marks by sha |
|
|
304
|
-
| `diff` | yes | yes | `path`, `ref`, `additions`, `deletions`, 1 to 6 hunks and 12 lines in all; the builder also takes a unified `patch` |
|
|
466
|
+
| `run_history` | yes | yes | 2 to 30 runs oldest first, `runs_not_shown` (how many runs of a longer history were left out; with `figure_extras_v1` only), 4 marks, a span; the builder also takes the GitHub Actions run list (`github_runs`) and places marks by sha |
|
|
467
|
+
| `diff` | yes | yes | `path`, `ref`, `additions`, `deletions`, 1 to 6 hunks and 12 changed lines in all (a short change is sent whole, each removed line next to its replacement); with `diff_lines_v1` also unchanged lines and line numbers; the builder also takes a unified `patch` and `select_hunks` |
|
|
305
468
|
|
|
306
469
|
A step figure is at most 16 KB. The builder never sets `example` (demo data). The tool listing shows the four newer types by type only to keep it small; their fields are in `resource://tellagen/figure-guide`, and the tool checks them in full when it runs. A Tellagen that does not know a figure type yet answers a timeline block with `400 invalid_block`, and drops a step figure with the completion warning `figure_invalid`.
|
|
307
470
|
|
|
@@ -333,16 +496,66 @@ The pickup bundle may carry `attachments` (the run's screenshots and a `safety_n
|
|
|
333
496
|
|
|
334
497
|
## Authentication
|
|
335
498
|
|
|
336
|
-
- API key
|
|
337
|
-
- MCP
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
499
|
+
- The API key comes from `TELLAGEN_API_KEY`, or from the system keychain after a sign-in (see "Quick start"). It is never passed in args. It is never written to a log, an error, a tool result or the remembered-run file.
|
|
500
|
+
- The MCP handshake performs no network request. Right after it, the server asks Tellagen once whether the key works; see "If something is not set up".
|
|
501
|
+
- All requests include the `Authorization: Bearer tllg_...` header.
|
|
502
|
+
- The MCP server acts as the API key's creating user.
|
|
503
|
+
|
|
504
|
+
## What the server sends about the client
|
|
505
|
+
|
|
506
|
+
Every request carries these headers, so Tellagen can show which client is connected:
|
|
507
|
+
|
|
508
|
+
| Header | Value |
|
|
509
|
+
|--------|-------|
|
|
510
|
+
| `X-Tellagen-Client` | The client name from the MCP handshake, for example `claude-code` (Tellagen shows it as "Claude Code") |
|
|
511
|
+
| `X-Tellagen-Client-Version` | The client version from the handshake |
|
|
512
|
+
| `X-Tellagen-Server-Version` | The version of this MCP server |
|
|
513
|
+
| `X-Tellagen-Computer` | The computer name |
|
|
514
|
+
| `X-Tellagen-Client-Session` | A random ID of this server process |
|
|
515
|
+
|
|
516
|
+
The pickup sends the same facts in its body, plus the model name when the model states it (`model`) and the data sources the client can reach (`available_sources`). An older Tellagen workspace that accepts only `codex` or `claude` as the client name fails on another name; the server then sends the pickup once more with the old short name. A workspace that names an unknown field gets the old pickup body. In both cases the answer says so in `mcp_notice`, and a real error is never replaced.
|
|
517
|
+
|
|
518
|
+
## The remembered run
|
|
519
|
+
|
|
520
|
+
At pickup the server writes the active run to `~/.tellagen/state/<workspace>.json`, with owner-only permissions (file `0600`, folder `0700`). The file holds the run ID, the incident ID, the pickup time, the server capabilities, the session ID and process ID, and the client name. It holds no key, no token and no evidence. `TELLAGEN_STATE_DIR` moves the folder.
|
|
521
|
+
|
|
522
|
+
- The run ID is optional on the run tools. Left out, a tool uses the active run.
|
|
523
|
+
- The file is removed when the run completes, fails, is cancelled or is taken over.
|
|
524
|
+
- After a restart, the server instructions say that a run is open, and `tellagen_resume` continues it. If the run ended in the meantime, `tellagen_resume` says so and removes the file.
|
|
525
|
+
- If another session on the same computer holds the run, the tool asks before this session joins.
|
|
526
|
+
|
|
527
|
+
## Timeouts, retries and repeats
|
|
528
|
+
|
|
529
|
+
- One attempt of a call to Tellagen may take 30 seconds (120 seconds for a finding with screenshots). A call with all its repeats ends after 60 seconds (150 seconds for a finding with screenshots).
|
|
530
|
+
- On a network error, a timeout, and HTTP 429, 502, 503 and 504 the server repeats a call up to 3 times, with a growing delay, and waits as long as `Retry-After` says (30 seconds at most).
|
|
531
|
+
- Only a call that is safe to repeat is repeated: a read, a cause (stored by its key), a trace step (stored by its `step_id`), a pickup, and a finding, which carries an `Idempotency-Key` header made from its content. A completion and other writes are sent once.
|
|
532
|
+
- Base64 screenshots are measured before anything is sent: 20 for one finding, 10 MB each, 15 MB together.
|
|
533
|
+
|
|
534
|
+
## Heartbeat, notes and the end of a run
|
|
535
|
+
|
|
536
|
+
- While a run is active and Tellagen lists `client_heartbeat_v1`, the server sends a heartbeat every 30 seconds. A failed heartbeat never fails a tool call; after three in a row the next tool answer says so in one line.
|
|
537
|
+
- If another client holds the run, the pickup answers with a question for the person. Only after a yes is the pickup repeated with `takeover: true`. A client that supports MCP elicitation shows the question itself.
|
|
538
|
+
- When an answer from Tellagen carries notes from a responder (`responder_notes_v1`), they come first in the tool result, quoted, with the author and the time. A note is a request from a person in the workspace; it is shown to the model and is never run by this server.
|
|
539
|
+
- When Tellagen says that the run was cancelled, has ended or was taken over, the tool result says so first, and the remembered run is removed.
|
|
540
|
+
|
|
541
|
+
## Instructions and resources
|
|
542
|
+
|
|
543
|
+
The server instructions are short (under 600 words): how to start, the order of a run, what the server does by itself and the rules that always hold. The detail is in resources that the model reads when it needs them. The pickup answer names the ones that apply to the run in `mcp_resources`.
|
|
544
|
+
|
|
545
|
+
| Resource | Content |
|
|
546
|
+
|----------|---------|
|
|
547
|
+
| `resource://tellagen/guide/findings` | Finding fields, types, roles, evidence refs and screenshots |
|
|
548
|
+
| `resource://tellagen/guide/completion` | The steps before completion, the result summary, the cause chain, change refs and warnings |
|
|
549
|
+
| `resource://tellagen/guide/runbook-checks` | The guidance basis of a trace step and structured runbook checks |
|
|
550
|
+
| `resource://tellagen/figure-guide` | Which figure fits which question, and the limits |
|
|
551
|
+
| `resource://tellagen/guide/sources` | Working with Grafana, GitHub and other MCP servers |
|
|
552
|
+
| `resource://tellagen/guide/postmortem` | Postmortem proposals, legacy imports and runbook candidates |
|
|
553
|
+
| `resource://tellagen/guide/tool-check` | Answering a tool check session |
|
|
554
|
+
| `resource://tellagen/skill-guide` | The whole guide |
|
|
342
555
|
|
|
343
556
|
## Scopes
|
|
344
557
|
|
|
345
|
-
|
|
558
|
+
A key that you make by hand needs both scopes (the **Local Diagnosis** preset in the key dialog sets them; a key from the browser sign-in has them already):
|
|
346
559
|
|
|
347
560
|
| Scope | Required for |
|
|
348
561
|
|-------|-------------|
|
|
@@ -419,6 +632,19 @@ npx vitest run test/client.test.ts # single file
|
|
|
419
632
|
npx vitest # watch mode
|
|
420
633
|
```
|
|
421
634
|
|
|
635
|
+
### Continuous integration and releases
|
|
636
|
+
|
|
637
|
+
Every pull request and every push to `master` runs `.github/workflows/ci.yml`: install, typecheck, the tests, the build, and a smoke test that starts the built server with no key (`npm run smoke`).
|
|
638
|
+
|
|
639
|
+
To release a version:
|
|
640
|
+
|
|
641
|
+
0. Raise the pinned contract bundle if Tellagen published a new one: `npm run contracts:update -- <contracts folder of a Tellagen checkout>`, then `npm test` (the `contracts` job must be green).
|
|
642
|
+
1. Set the version in `package.json`, `package-lock.json`, `server.json` and `src/version.ts` (a test keeps them equal).
|
|
643
|
+
2. Add a `## <version> - <date>` section to `CHANGELOG.md` (a test requires a section for the current version).
|
|
644
|
+
3. Merge, then push the tag `v<version>` on a commit of `master`. `.github/workflows/release.yml` refuses a tag that is not on `master`, that does not match the version, or whose changelog heading has no date. It runs the tests in a job with no publish rights. A second job publishes to npm with provenance and creates the GitHub release from the changelog section.
|
|
645
|
+
|
|
646
|
+
The release needs npm trusted publishing for the repository, or an `NPM_TOKEN` repository secret.
|
|
647
|
+
|
|
422
648
|
### Type-checking
|
|
423
649
|
|
|
424
650
|
```bash
|
|
@@ -429,8 +655,15 @@ npm run lint # tsc --noEmit
|
|
|
429
655
|
|
|
430
656
|
| Variable | Required | Description |
|
|
431
657
|
|----------|----------|-------------|
|
|
432
|
-
| `TELLAGEN_API_KEY` |
|
|
433
|
-
| `TELLAGEN_API_URL` |
|
|
434
|
-
| `
|
|
658
|
+
| `TELLAGEN_API_KEY` | No | API key (format: `tllg_...`). Wins over a stored sign-in. With neither, the server starts and each tool explains the setup |
|
|
659
|
+
| `TELLAGEN_API_URL` | No | API base URL (e.g., `https://yourcompany.api.tellagen.com`) |
|
|
660
|
+
| `TELLAGEN_TOOLSETS` | No | Comma-separated toolsets to list: `diagnosis`, `incidents`, `timeline`, `postmortem`, `settings`, or `all`. Defaults to `diagnosis,incidents`. The `--toolsets` argument wins |
|
|
661
|
+
| `TELLAGEN_HOME` | No | Folder for the sign-in index, the key file where there is no keychain, and the listener settings and logs. Defaults to `~/.tellagen` |
|
|
662
|
+
| `TELLAGEN_SIGN_IN_URL` | No | The Tellagen API address that starts a sign-in. Defaults to the address in `TELLAGEN_API_URL`, else `https://api.tellagen.com` |
|
|
663
|
+
| `TELLAGEN_CREDENTIAL_STORE` | No | `file` stores a sign-in key in the owner-only key file and never in the system keychain (for a test or a CI job) |
|
|
664
|
+
| `TELLAGEN_STRICT_FIELDS` | No | `0` stops the server from asking Tellagen to refuse unknown request fields |
|
|
665
|
+
| `TELLAGEN_RECORD_STEPS` | No | `0` turns `trace-hook` off |
|
|
666
|
+
| `TELLAGEN_STATE_DIR` | No | Folder of the remembered-run file. Defaults to `~/.tellagen/state` |
|
|
667
|
+
| `TELLAGEN_MCP_CLIENT` | No | Deprecated. `codex` or `claude`; used only when the client sends no name in the handshake, and for an older Tellagen workspace |
|
|
435
668
|
| `TELLAGEN_MCP_PROFILE_ID` | No | Stable opaque profile ID used to scope local MCP access observations |
|
|
436
|
-
| `GRAFANA_URL` | No | Grafana address
|
|
669
|
+
| `GRAFANA_URL` | No | Grafana address, for `tellagen_probe_datasource` and `tellagen_build_source_link`. Used when Tellagen sends no Grafana address with the pickup, or several and none is picked; the Tellagen datasource `base_url` comes after it. The probe sends the service account token only to this address |
|