@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 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
@@ -0,0 +1,6 @@
1
+ import { TellagenClient } from "./client.js";
2
+ /**
3
+ * Validate the API key on startup by calling /api/v1/auth/me.
4
+ * Throws if the key is invalid or the API is unreachable.
5
+ */
6
+ export declare function validateAuth(client: TellagenClient): Promise<void>;
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
@@ -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"}
@@ -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"}
@@ -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"}
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};