caelario-mcp 0.1.5 → 0.1.7
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 +57 -42
- package/package.json +55 -55
- package/server.json +32 -32
- package/src/install.js +123 -105
- package/src/onboarding.js +49 -0
- package/src/server.js +246 -195
package/README.md
CHANGED
|
@@ -1,42 +1,57 @@
|
|
|
1
|
-
# Caelario MCP
|
|
2
|
-
|
|
3
|
-
MCP server for social media data from Instagram, TikTok, YouTube, X and
|
|
4
|
-
Facebook. Run extractions, search and discovery, batches, schedules, saved
|
|
5
|
-
results and usage workflows through Caelario.
|
|
6
|
-
|
|
7
|
-
Source: <https://github.com/chunkydonut21/caelario-mcp>
|
|
8
|
-
|
|
9
|
-
The official local server gives Codex and Claude Code typed tools for capability
|
|
10
|
-
discovery, immediate and durable extraction, result pagination, and credit
|
|
11
|
-
estimates.
|
|
12
|
-
|
|
13
|
-
##
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
1
|
+
# Caelario MCP
|
|
2
|
+
|
|
3
|
+
MCP server for social media data from Instagram, TikTok, YouTube, X and
|
|
4
|
+
Facebook. Run extractions, search and discovery, batches, schedules, saved
|
|
5
|
+
results and usage workflows through Caelario.
|
|
6
|
+
|
|
7
|
+
Source: <https://github.com/chunkydonut21/caelario-mcp>
|
|
8
|
+
|
|
9
|
+
The official local server gives Codex and Claude Code typed tools for capability
|
|
10
|
+
discovery, immediate and durable extraction, result pagination, and credit
|
|
11
|
+
estimates.
|
|
12
|
+
|
|
13
|
+
## New to Caelario?
|
|
14
|
+
|
|
15
|
+
[Open the guided setup](https://app.caelario.com/connect). Create a free account
|
|
16
|
+
with Google or email, choose Codex or Claude Code, and create a connection key.
|
|
17
|
+
The page shows each step and helps you check the connection. New accounts start
|
|
18
|
+
with 200 free credits.
|
|
19
|
+
|
|
20
|
+
The installer opens this setup page automatically when you do not already have
|
|
21
|
+
a key. Paste the key only into its secure terminal prompt, never into AI chat.
|
|
22
|
+
|
|
23
|
+
## Install for Codex
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx -y caelario-mcp@latest install codex
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Install for Claude Code
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npx -y caelario-mcp@latest install claude
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The installer prompts for a Caelario workspace API key and registers the stdio
|
|
36
|
+
server at user scope. It does not ask for Instagram, TikTok, YouTube, X, or
|
|
37
|
+
Facebook credentials; provider identities are managed by Caelario.
|
|
38
|
+
|
|
39
|
+
After installation, restart the client and ask:
|
|
40
|
+
|
|
41
|
+
> Use Caelario to get Nike's Instagram profile and 10 recent posts.
|
|
42
|
+
|
|
43
|
+
The package requires Node.js 20 or newer. See
|
|
44
|
+
<https://caelario.com/mcp-server> for security, billing, and tool details.
|
|
45
|
+
|
|
46
|
+
If a request times out, reuse the `idempotency_key` returned in the tool error
|
|
47
|
+
with identical arguments. This recovers the original request instead of starting
|
|
48
|
+
another paid extraction. The default HTTP timeout is 120 seconds; failed job
|
|
49
|
+
results include their error and remain marked as not ready.
|
|
50
|
+
|
|
51
|
+
The connector is released under the MIT License. Caelario's hosted API,
|
|
52
|
+
provider implementations, acquisition infrastructure, and managed identities
|
|
53
|
+
are separate proprietary services and are not included in this package.
|
|
54
|
+
|
|
55
|
+
The npm artifact also includes official MCP Registry metadata under
|
|
56
|
+
`io.github.chunkydonut21/caelario`. npm publication must happen before the
|
|
57
|
+
separate Registry publication step.
|
package/package.json
CHANGED
|
@@ -1,55 +1,55 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "caelario-mcp",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"mcpName": "io.github.chunkydonut21/caelario",
|
|
5
|
-
"description": "MCP server for social media data from Instagram, TikTok, YouTube, X and Facebook. Run extractions, batches, schedules, saved results and usage workflows through Caelario.",
|
|
6
|
-
"type": "module",
|
|
7
|
-
"license": "MIT",
|
|
8
|
-
"homepage": "https://caelario.com/mcp-server",
|
|
9
|
-
"repository": {
|
|
10
|
-
"type": "git",
|
|
11
|
-
"url": "git+https://github.com/chunkydonut21/caelario-mcp.git"
|
|
12
|
-
},
|
|
13
|
-
"bugs": {
|
|
14
|
-
"url": "https://github.com/chunkydonut21/caelario-mcp/issues"
|
|
15
|
-
},
|
|
16
|
-
"publishConfig": {
|
|
17
|
-
"access": "public"
|
|
18
|
-
},
|
|
19
|
-
"bin": {
|
|
20
|
-
"caelario-mcp": "bin/caelario-mcp.js"
|
|
21
|
-
},
|
|
22
|
-
"files": [
|
|
23
|
-
"bin",
|
|
24
|
-
"src",
|
|
25
|
-
"README.md",
|
|
26
|
-
"server.json"
|
|
27
|
-
],
|
|
28
|
-
"engines": {
|
|
29
|
-
"node": ">=20"
|
|
30
|
-
},
|
|
31
|
-
"scripts": {
|
|
32
|
-
"test": "node --test test/*.test.js",
|
|
33
|
-
"pack:check": "npm pack --dry-run --cache .npm-cache"
|
|
34
|
-
},
|
|
35
|
-
"dependencies": {
|
|
36
|
-
"@modelcontextprotocol/server": "^2.
|
|
37
|
-
"zod": "^4.
|
|
38
|
-
},
|
|
39
|
-
"devDependencies": {
|
|
40
|
-
"@modelcontextprotocol/client": "^2.
|
|
41
|
-
},
|
|
42
|
-
"keywords": [
|
|
43
|
-
"caelario",
|
|
44
|
-
"mcp",
|
|
45
|
-
"model-context-protocol",
|
|
46
|
-
"social-data",
|
|
47
|
-
"instagram",
|
|
48
|
-
"tiktok",
|
|
49
|
-
"youtube",
|
|
50
|
-
"facebook",
|
|
51
|
-
"twitter",
|
|
52
|
-
"codex",
|
|
53
|
-
"claude"
|
|
54
|
-
]
|
|
55
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "caelario-mcp",
|
|
3
|
+
"version": "0.1.7",
|
|
4
|
+
"mcpName": "io.github.chunkydonut21/caelario",
|
|
5
|
+
"description": "MCP server for social media data from Instagram, TikTok, YouTube, X and Facebook. Run extractions, batches, schedules, saved results and usage workflows through Caelario.",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"homepage": "https://caelario.com/mcp-server",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/chunkydonut21/caelario-mcp.git"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/chunkydonut21/caelario-mcp/issues"
|
|
15
|
+
},
|
|
16
|
+
"publishConfig": {
|
|
17
|
+
"access": "public"
|
|
18
|
+
},
|
|
19
|
+
"bin": {
|
|
20
|
+
"caelario-mcp": "bin/caelario-mcp.js"
|
|
21
|
+
},
|
|
22
|
+
"files": [
|
|
23
|
+
"bin",
|
|
24
|
+
"src",
|
|
25
|
+
"README.md",
|
|
26
|
+
"server.json"
|
|
27
|
+
],
|
|
28
|
+
"engines": {
|
|
29
|
+
"node": ">=20"
|
|
30
|
+
},
|
|
31
|
+
"scripts": {
|
|
32
|
+
"test": "node --test test/*.test.js",
|
|
33
|
+
"pack:check": "npm pack --dry-run --cache .npm-cache"
|
|
34
|
+
},
|
|
35
|
+
"dependencies": {
|
|
36
|
+
"@modelcontextprotocol/server": "^2.4.0",
|
|
37
|
+
"zod": "^4.6.7"
|
|
38
|
+
},
|
|
39
|
+
"devDependencies": {
|
|
40
|
+
"@modelcontextprotocol/client": "^2.4.0"
|
|
41
|
+
},
|
|
42
|
+
"keywords": [
|
|
43
|
+
"caelario",
|
|
44
|
+
"mcp",
|
|
45
|
+
"model-context-protocol",
|
|
46
|
+
"social-data",
|
|
47
|
+
"instagram",
|
|
48
|
+
"tiktok",
|
|
49
|
+
"youtube",
|
|
50
|
+
"facebook",
|
|
51
|
+
"twitter",
|
|
52
|
+
"codex",
|
|
53
|
+
"claude"
|
|
54
|
+
]
|
|
55
|
+
}
|
package/server.json
CHANGED
|
@@ -1,32 +1,32 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
-
"name": "io.github.chunkydonut21/caelario",
|
|
4
|
-
"title": "Caelario",
|
|
5
|
-
"description": "MCP server for Instagram, TikTok, YouTube, X and Facebook data extraction and automation.",
|
|
6
|
-
"websiteUrl": "https://caelario.com/mcp-server",
|
|
7
|
-
"repository": {
|
|
8
|
-
"url": "https://github.com/chunkydonut21/caelario-mcp",
|
|
9
|
-
"source": "github",
|
|
10
|
-
"id": "1346708115"
|
|
11
|
-
},
|
|
12
|
-
"version": "0.1.
|
|
13
|
-
"packages": [
|
|
14
|
-
{
|
|
15
|
-
"registryType": "npm",
|
|
16
|
-
"identifier": "caelario-mcp",
|
|
17
|
-
"version": "0.1.
|
|
18
|
-
"transport": {
|
|
19
|
-
"type": "stdio"
|
|
20
|
-
},
|
|
21
|
-
"environmentVariables": [
|
|
22
|
-
{
|
|
23
|
-
"description": "
|
|
24
|
-
"isRequired": true,
|
|
25
|
-
"format": "string",
|
|
26
|
-
"isSecret": true,
|
|
27
|
-
"name": "CAELARIO_API_KEY"
|
|
28
|
-
}
|
|
29
|
-
]
|
|
30
|
-
}
|
|
31
|
-
]
|
|
32
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.chunkydonut21/caelario",
|
|
4
|
+
"title": "Caelario",
|
|
5
|
+
"description": "MCP server for Instagram, TikTok, YouTube, X and Facebook data extraction and automation.",
|
|
6
|
+
"websiteUrl": "https://caelario.com/mcp-server",
|
|
7
|
+
"repository": {
|
|
8
|
+
"url": "https://github.com/chunkydonut21/caelario-mcp",
|
|
9
|
+
"source": "github",
|
|
10
|
+
"id": "1346708115"
|
|
11
|
+
},
|
|
12
|
+
"version": "0.1.7",
|
|
13
|
+
"packages": [
|
|
14
|
+
{
|
|
15
|
+
"registryType": "npm",
|
|
16
|
+
"identifier": "caelario-mcp",
|
|
17
|
+
"version": "0.1.7",
|
|
18
|
+
"transport": {
|
|
19
|
+
"type": "stdio"
|
|
20
|
+
},
|
|
21
|
+
"environmentVariables": [
|
|
22
|
+
{
|
|
23
|
+
"description": "Get your Caelario account and connection key at https://app.caelario.com/connect. The browser setup guides you through registration and connection.",
|
|
24
|
+
"isRequired": true,
|
|
25
|
+
"format": "string",
|
|
26
|
+
"isSecret": true,
|
|
27
|
+
"name": "CAELARIO_API_KEY"
|
|
28
|
+
}
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|
package/src/install.js
CHANGED
|
@@ -1,105 +1,123 @@
|
|
|
1
|
-
import { spawnSync } from "node:child_process";
|
|
2
|
-
import process from "node:process";
|
|
3
|
-
import readline from "node:readline";
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
const
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
if (!
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
if (origin.
|
|
16
|
-
throw new Error("the Caelario API URL must
|
|
17
|
-
}
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
const
|
|
23
|
-
"mcp", "
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
"
|
|
27
|
-
"--
|
|
28
|
-
"
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
if (
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
}
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
2
|
+
import process from "node:process";
|
|
3
|
+
import readline from "node:readline";
|
|
4
|
+
import { SETUP_URL, setupInstructions, openSetupPage, verifyWorkspaceKey } from "./onboarding.js";
|
|
5
|
+
|
|
6
|
+
const CLIENTS = new Set(["codex", "claude"]);
|
|
7
|
+
const KEY_PATTERN = /^[A-Za-z0-9._-]{16,256}$/;
|
|
8
|
+
|
|
9
|
+
export function registrationCommand(client, apiKey, apiUrl = "https://api.caelario.com", platform = process.platform) {
|
|
10
|
+
if (!CLIENTS.has(client)) throw new Error("client must be codex or claude");
|
|
11
|
+
if (!KEY_PATTERN.test(apiKey)) throw new Error("the Caelario API key format is invalid");
|
|
12
|
+
const origin = new URL(apiUrl);
|
|
13
|
+
if (!["http:", "https:"].includes(origin.protocol)) throw new Error("the Caelario API URL requires HTTP or HTTPS");
|
|
14
|
+
if (/[&|<>^%!()\r\n]/.test(origin.origin)) throw new Error("the Caelario API origin contains unsafe launcher characters");
|
|
15
|
+
if (origin.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname)) {
|
|
16
|
+
throw new Error("the Caelario API URL must use HTTPS");
|
|
17
|
+
}
|
|
18
|
+
if (origin.pathname !== "/" || origin.search || origin.hash || origin.username || origin.password) {
|
|
19
|
+
throw new Error("the Caelario API URL must contain only an origin");
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const launcher = platform === "win32"
|
|
23
|
+
? ["cmd", "/c", "npx", "-y", "caelario-mcp", "serve"]
|
|
24
|
+
: ["npx", "-y", "caelario-mcp", "serve"];
|
|
25
|
+
const common = [
|
|
26
|
+
"mcp", "add",
|
|
27
|
+
...(client === "claude" ? ["--scope", "user"] : []),
|
|
28
|
+
"caelario",
|
|
29
|
+
"--env", `CAELARIO_API_URL=${origin.origin}`,
|
|
30
|
+
"--env", `CAELARIO_API_KEY=${apiKey}`,
|
|
31
|
+
"--",
|
|
32
|
+
...launcher,
|
|
33
|
+
];
|
|
34
|
+
return { command: client, args: common };
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export async function installClient(
|
|
38
|
+
client,
|
|
39
|
+
{
|
|
40
|
+
apiKey = process.env.CAELARIO_API_KEY,
|
|
41
|
+
apiUrl = process.env.CAELARIO_API_URL || "https://api.caelario.com",
|
|
42
|
+
platform = process.platform,
|
|
43
|
+
spawn = spawnSync,
|
|
44
|
+
openBrowser = openSetupPage,
|
|
45
|
+
prompt = promptSecret,
|
|
46
|
+
verifyKey = verifyWorkspaceKey,
|
|
47
|
+
write = (text) => process.stderr.write(text),
|
|
48
|
+
interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY),
|
|
49
|
+
} = {},
|
|
50
|
+
) {
|
|
51
|
+
if (!CLIENTS.has(client)) throw new Error("client must be codex or claude");
|
|
52
|
+
let key = apiKey?.trim();
|
|
53
|
+
if (!key) {
|
|
54
|
+
write(`${setupInstructions(client)}\n\n`);
|
|
55
|
+
if (interactive) {
|
|
56
|
+
write("Opening your browser setup page...\n");
|
|
57
|
+
openBrowser();
|
|
58
|
+
}
|
|
59
|
+
key = await prompt("Finish setup in your browser, then paste your connection key here: ");
|
|
60
|
+
}
|
|
61
|
+
const registration = registrationCommand(client, key, apiUrl, platform);
|
|
62
|
+
write("Checking your Caelario connection key...\n");
|
|
63
|
+
await verifyKey(key, apiUrl);
|
|
64
|
+
const completed = spawn(registration.command, registration.args, {
|
|
65
|
+
stdio: "inherit",
|
|
66
|
+
windowsHide: true,
|
|
67
|
+
shell: platform === "win32",
|
|
68
|
+
});
|
|
69
|
+
if (completed.error?.code === "ENOENT") {
|
|
70
|
+
throw new Error(`${client === "codex" ? "Codex" : "Claude Code"} CLI was not found. Install it, then run this command again.`);
|
|
71
|
+
}
|
|
72
|
+
if (completed.error) throw new Error("The assistant client could not be started. Check its installation and run this command again.");
|
|
73
|
+
if (completed.status !== 0) {
|
|
74
|
+
throw new Error(`${client === "codex" ? "Codex" : "Claude Code"} rejected the MCP registration (exit ${completed.status ?? "unknown"})`);
|
|
75
|
+
}
|
|
76
|
+
write(`Caelario is connected to ${client === "codex" ? "Codex" : "Claude Code"}. Restart the client, then ask it to use Caelario.\n`);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
async function promptSecret(prompt) {
|
|
80
|
+
if (!process.stdin.isTTY || !process.stderr.isTTY) {
|
|
81
|
+
throw new Error(`Open ${SETUP_URL} to create your account and connection key. Run the installer in an interactive terminal, or set CAELARIO_API_KEY in your private MCP configuration.`);
|
|
82
|
+
}
|
|
83
|
+
process.stderr.write(prompt);
|
|
84
|
+
process.stdin.setRawMode?.(true);
|
|
85
|
+
process.stdin.resume();
|
|
86
|
+
process.stdin.setEncoding("utf8");
|
|
87
|
+
let value = "";
|
|
88
|
+
return new Promise((resolve, reject) => {
|
|
89
|
+
const finish = (error) => {
|
|
90
|
+
process.stdin.setRawMode?.(false);
|
|
91
|
+
process.stdin.pause();
|
|
92
|
+
process.stdin.removeListener("data", onData);
|
|
93
|
+
process.stderr.write("\n");
|
|
94
|
+
if (error) reject(error); else resolve(value);
|
|
95
|
+
};
|
|
96
|
+
const onData = (chunk) => {
|
|
97
|
+
for (const character of chunk) {
|
|
98
|
+
if (character === "\r" || character === "\n") return finish();
|
|
99
|
+
if (character === "\u0003") return finish(new Error("installation cancelled"));
|
|
100
|
+
if (character === "\u007f" || character === "\b") {
|
|
101
|
+
value = value.slice(0, -1);
|
|
102
|
+
continue;
|
|
103
|
+
}
|
|
104
|
+
value += character;
|
|
105
|
+
}
|
|
106
|
+
};
|
|
107
|
+
process.stdin.on("data", onData);
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export function printHelp() {
|
|
112
|
+
const output = [
|
|
113
|
+
"Caelario MCP",
|
|
114
|
+
"",
|
|
115
|
+
" npx -y caelario-mcp install codex Register for Codex (user-wide)",
|
|
116
|
+
" npx -y caelario-mcp install claude Register for Claude Code (user-wide)",
|
|
117
|
+
" npx -y caelario-mcp serve Run the stdio server",
|
|
118
|
+
"",
|
|
119
|
+
setupInstructions(),
|
|
120
|
+
];
|
|
121
|
+
readline.clearLine(process.stderr, 0);
|
|
122
|
+
process.stderr.write(`${output.join("\n")}\n`);
|
|
123
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
|
|
3
|
+
export const SETUP_URL = "https://app.caelario.com/connect";
|
|
4
|
+
export const SIGNUP_URL = "https://app.caelario.com/sign-up";
|
|
5
|
+
|
|
6
|
+
export function setupInstructions(client = "codex") {
|
|
7
|
+
const label = client === "claude" ? "Claude Code" : "Codex";
|
|
8
|
+
return [
|
|
9
|
+
"Caelario connects social media data to your AI assistant.",
|
|
10
|
+
"",
|
|
11
|
+
`1. Open ${SETUP_URL}`,
|
|
12
|
+
"2. Create a free account (or sign in), then create your connection key.",
|
|
13
|
+
`3. Return here, paste the key when asked, then restart ${label}.`,
|
|
14
|
+
"",
|
|
15
|
+
"The browser setup page guides you through every step. Keep the key out of chat.",
|
|
16
|
+
].join("\n");
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export function openSetupPage() {
|
|
20
|
+
const [command, args] = process.platform === "win32"
|
|
21
|
+
? ["rundll32.exe", ["url.dll,FileProtocolHandler", SETUP_URL]]
|
|
22
|
+
: process.platform === "darwin" ? ["open", [SETUP_URL]] : ["xdg-open", [SETUP_URL]];
|
|
23
|
+
try {
|
|
24
|
+
const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
|
|
25
|
+
child.on("error", () => {});
|
|
26
|
+
child.unref();
|
|
27
|
+
} catch { /* The printed URL remains usable when a browser cannot be opened. */ }
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export async function verifyWorkspaceKey(apiKey, apiUrl) {
|
|
31
|
+
let response;
|
|
32
|
+
try {
|
|
33
|
+
response = await fetch(new URL("/v1/account", apiUrl), {
|
|
34
|
+
headers: { "X-API-Key": apiKey, Accept: "application/json" },
|
|
35
|
+
redirect: "manual",
|
|
36
|
+
signal: AbortSignal.timeout(20_000),
|
|
37
|
+
});
|
|
38
|
+
} catch {
|
|
39
|
+
throw new Error("Could not reach Caelario to check the key. Check your connection and run the installer again.");
|
|
40
|
+
}
|
|
41
|
+
if (response.status === 401 || response.status === 403) {
|
|
42
|
+
throw new Error(`Caelario did not accept that key. Open ${SETUP_URL}, copy your full connection key and try again.`);
|
|
43
|
+
}
|
|
44
|
+
if (!response.ok) throw new Error("Caelario could not verify the key right now. Please try again shortly.");
|
|
45
|
+
const account = await response.json().catch(() => null);
|
|
46
|
+
if (!account || typeof account.organization_id !== "string") {
|
|
47
|
+
throw new Error("Caelario returned an unexpected response while checking the key. Please try again shortly.");
|
|
48
|
+
}
|
|
49
|
+
}
|
package/src/server.js
CHANGED
|
@@ -1,195 +1,246 @@
|
|
|
1
|
-
import { randomUUID } from "node:crypto";
|
|
2
|
-
import process from "node:process";
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
const
|
|
10
|
-
const
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
if (
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
});
|
|
43
|
-
const
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
112
|
-
}
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
const
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
}
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
tool("
|
|
182
|
-
tool("
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
tool("
|
|
188
|
-
tool("
|
|
189
|
-
tool("
|
|
190
|
-
|
|
191
|
-
}
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import process from "node:process";
|
|
3
|
+
import { readFileSync } from "node:fs";
|
|
4
|
+
import { McpServer } from "@modelcontextprotocol/server";
|
|
5
|
+
import { serveStdio } from "@modelcontextprotocol/server/stdio";
|
|
6
|
+
import * as z from "zod/v4";
|
|
7
|
+
import { SETUP_URL } from "./onboarding.js";
|
|
8
|
+
|
|
9
|
+
const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
|
|
10
|
+
const TERMINAL = new Set(["completed", "failed", "cancelled"]);
|
|
11
|
+
const operation = z.string().min(1).max(64).describe("Operation returned by discover_platforms");
|
|
12
|
+
const platform = z.string().min(1).max(32).describe("Platform returned by discover_platforms");
|
|
13
|
+
const id = z.string().regex(/^[A-Za-z0-9_-]{1,128}$/);
|
|
14
|
+
|
|
15
|
+
function apiConfiguration() {
|
|
16
|
+
const apiKey = (process.env.CAELARIO_API_KEY || "").trim();
|
|
17
|
+
if (!apiKey) throw new Error(`Create a free Caelario account and connection key at ${SETUP_URL}, then run npx -y caelario-mcp@latest install codex (or install claude). Paste the key into the installer, never into chat.`);
|
|
18
|
+
const baseUrl = new URL(process.env.CAELARIO_API_URL || "https://api.caelario.com");
|
|
19
|
+
if (!["https:", "http:"].includes(baseUrl.protocol)) throw new Error("CAELARIO_API_URL requires HTTP or HTTPS");
|
|
20
|
+
if (baseUrl.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(baseUrl.hostname)) {
|
|
21
|
+
throw new Error("CAELARIO_API_URL requires HTTPS except on loopback");
|
|
22
|
+
}
|
|
23
|
+
if (baseUrl.pathname !== "/" || baseUrl.search || baseUrl.hash || baseUrl.username || baseUrl.password) {
|
|
24
|
+
throw new Error("CAELARIO_API_URL must contain only an API origin");
|
|
25
|
+
}
|
|
26
|
+
return { apiKey, baseUrl: baseUrl.origin };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
class ApiError extends Error {
|
|
30
|
+
constructor(message, metadata = {}) {
|
|
31
|
+
super(message);
|
|
32
|
+
this.metadata = metadata;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
async function api(method, path, { body, params, idempotencyKey } = {}) {
|
|
37
|
+
const { apiKey, baseUrl } = apiConfiguration();
|
|
38
|
+
const timeout = Number(process.env.CAELARIO_MCP_TIMEOUT_MS || 120_000);
|
|
39
|
+
if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 2_147_483_647) {
|
|
40
|
+
throw new Error("CAELARIO_MCP_TIMEOUT_MS must be a positive integer");
|
|
41
|
+
}
|
|
42
|
+
const url = new URL(path, `${baseUrl}/`);
|
|
43
|
+
for (const [key, value] of Object.entries(params || {})) {
|
|
44
|
+
if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
|
|
45
|
+
}
|
|
46
|
+
const recovery = idempotencyKey ? {
|
|
47
|
+
idempotency_key: idempotencyKey,
|
|
48
|
+
retry_instruction: "Use this idempotency_key with identical arguments to recover the original request; check its job status before starting a new request.",
|
|
49
|
+
} : {};
|
|
50
|
+
let response;
|
|
51
|
+
try {
|
|
52
|
+
response = await fetch(url, {
|
|
53
|
+
method,
|
|
54
|
+
redirect: "manual",
|
|
55
|
+
headers: {
|
|
56
|
+
Accept: "application/json",
|
|
57
|
+
"Content-Type": "application/json",
|
|
58
|
+
"X-API-Key": apiKey,
|
|
59
|
+
"User-Agent": `caelario-mcp/${VERSION}`,
|
|
60
|
+
...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
|
|
61
|
+
},
|
|
62
|
+
body: body === undefined ? undefined : JSON.stringify(body),
|
|
63
|
+
signal: AbortSignal.timeout(timeout),
|
|
64
|
+
});
|
|
65
|
+
} catch {
|
|
66
|
+
throw new ApiError("The Caelario API request could not complete. Its outcome is unknown.", {
|
|
67
|
+
error: "api_transport_error", retryable: true, outcome_unknown: true, ...recovery,
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
if (response.status === 204) return null;
|
|
71
|
+
let payload;
|
|
72
|
+
try {
|
|
73
|
+
payload = await response.json();
|
|
74
|
+
} catch {
|
|
75
|
+
throw new ApiError("The Caelario API returned an invalid response. Check the request before retrying.", {
|
|
76
|
+
error: "invalid_api_response", status_code: response.status,
|
|
77
|
+
retryable: true, outcome_unknown: Boolean(idempotencyKey), ...recovery,
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
if (!response.ok) {
|
|
81
|
+
const detail = payload?.detail;
|
|
82
|
+
const code = typeof detail === "object" ? detail?.error : undefined;
|
|
83
|
+
const message = typeof detail === "object" ? detail?.message : typeof detail === "string" ? detail : undefined;
|
|
84
|
+
const safeMessage = typeof message === "string" ? message.replaceAll(apiKey, "[redacted]") : undefined;
|
|
85
|
+
const jobId = typeof detail?.job_id === "string" && /^[A-Za-z0-9_-]{1,128}$/.test(detail.job_id) ? detail.job_id : undefined;
|
|
86
|
+
throw new ApiError(`Caelario API request failed (${response.status})${safeMessage ? `: ${safeMessage}` : ""}`, {
|
|
87
|
+
error: typeof code === "string" && /^[a-z0-9_]{1,64}$/.test(code) ? code : "api_request_failed",
|
|
88
|
+
status_code: response.status, retryable: Boolean(detail?.retryable),
|
|
89
|
+
...([401, 403].includes(response.status) ? { setup_url: SETUP_URL } : {}),
|
|
90
|
+
outcome_unknown: false, ...(jobId ? { job_id: jobId } : {}), ...recovery,
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
return payload;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function response(value) {
|
|
97
|
+
return {
|
|
98
|
+
content: [{ type: "text", text: JSON.stringify(value) }],
|
|
99
|
+
structuredContent: { result: value },
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function withoutResult(job) {
|
|
104
|
+
if (!job || typeof job !== "object") return job;
|
|
105
|
+
const { result: _result, ...summary } = job;
|
|
106
|
+
return summary;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function capabilityFor(catalog, platformName, operationName) {
|
|
110
|
+
const definition = catalog.find((item) => item.platform === platformName.toLowerCase());
|
|
111
|
+
const capability = definition?.operations?.find((item) => item.operation === operationName);
|
|
112
|
+
if (!definition || !capability) throw new Error(`Unsupported operation: ${platformName}/${operationName}`);
|
|
113
|
+
return { definition, capability };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function billing(capability) {
|
|
117
|
+
if (capability.base_credits && !capability.credits_per_result) {
|
|
118
|
+
return `${capability.base_credits} credits for a non-empty collection; valid empty results cost 0.`;
|
|
119
|
+
}
|
|
120
|
+
if (capability.results_per_credit > 1) {
|
|
121
|
+
return `${capability.credits_per_result} credits per ${capability.results_per_credit} delivered results, rounded up.`;
|
|
122
|
+
}
|
|
123
|
+
return `${capability.credits_per_result} credit${capability.credits_per_result === 1 ? "" : "s"} per delivered result.`;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function pagedResult(job, offset, limit, textOffset, textLimit) {
|
|
127
|
+
const page = (value) => Array.isArray(value) ? value.slice(offset, offset + limit) : value;
|
|
128
|
+
let result = job.result;
|
|
129
|
+
const pagination = {};
|
|
130
|
+
if (Array.isArray(result)) {
|
|
131
|
+
pagination.result = pageInfo(result.length, offset, limit);
|
|
132
|
+
result = page(result);
|
|
133
|
+
} else if (result && typeof result === "object") {
|
|
134
|
+
result = { ...result };
|
|
135
|
+
for (const [key, value] of Object.entries(result)) {
|
|
136
|
+
if (Array.isArray(value)) {
|
|
137
|
+
pagination[key] = pageInfo(value.length, offset, limit);
|
|
138
|
+
result[key] = page(value);
|
|
139
|
+
} else if (typeof value === "string" && (textOffset || value.length > textLimit)) {
|
|
140
|
+
pagination[key] = pageInfo(value.length, textOffset, textLimit);
|
|
141
|
+
result[key] = value.slice(textOffset, textOffset + textLimit);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
return { job_id: job.id, status: job.status, error: job.error ?? null, request_cursor: job.request_cursor ?? null, ready: job.status === "completed" && job.result != null, result_count: job.result_count, billed_credits: job.billed_credits, source_exhausted: Boolean(job.source_exhausted), next_cursor: job.next_cursor ?? null, result, pagination };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function pageInfo(total, offset, limit) {
|
|
149
|
+
const returned = Math.max(0, Math.min(limit, total - offset));
|
|
150
|
+
return { offset, limit, returned, total, next_offset: offset + returned < total ? offset + returned : null };
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function requestBody(input) {
|
|
154
|
+
return { platform: input.platform, operation: input.operation, target: input.target, limit: input.limit, include_posts: input.include_posts, cursor: input.cursor ?? null };
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
const extractionSchema = z.object({
|
|
158
|
+
platform,
|
|
159
|
+
operation,
|
|
160
|
+
target: z.string().min(1).max(2_000),
|
|
161
|
+
limit: z.number().int().min(1).max(25_000).default(12),
|
|
162
|
+
include_posts: z.number().int().min(0).max(200).default(0),
|
|
163
|
+
cursor: z.string().max(8_000).optional(),
|
|
164
|
+
idempotency_key: z.string().min(1).max(128).optional(),
|
|
165
|
+
});
|
|
166
|
+
|
|
167
|
+
export function createServer() {
|
|
168
|
+
const server = new McpServer(
|
|
169
|
+
{ name: "Caelario", version: VERSION },
|
|
170
|
+
{ instructions: "For first-time setup or a missing connection key, direct the user to https://app.caelario.com/connect to create an account and follow the browser setup. Never ask them to paste the key into chat. Use discover_platforms and get_operation_guide before unfamiliar or expensive work. Prefer extract_now for one bounded target. Use durable jobs or batches for larger work, then wait and page the result. Only a Caelario workspace API key is needed; never ask users for social-network credentials." },
|
|
171
|
+
);
|
|
172
|
+
const tool = (name, description, inputSchema, handler) => server.registerTool(name, { description, inputSchema }, async (input) => {
|
|
173
|
+
try {
|
|
174
|
+
return response(await handler(input));
|
|
175
|
+
} catch (error) {
|
|
176
|
+
const failure = { message: error.message, ...(error instanceof ApiError ? error.metadata : { error: "mcp_request_failed" }) };
|
|
177
|
+
return { isError: true, content: [{ type: "text", text: JSON.stringify(failure) }] };
|
|
178
|
+
}
|
|
179
|
+
});
|
|
180
|
+
|
|
181
|
+
tool("discover_platforms", "List every Caelario platform, operation, limit, and price.", z.object({}), () => api("GET", "/v1/platforms"));
|
|
182
|
+
tool("get_operation_guide", "Explain and validate one operation before spending credits.", z.object({ platform, operation }), async (input) => {
|
|
183
|
+
const catalog = await api("GET", "/v1/platforms");
|
|
184
|
+
const { capability } = capabilityFor(catalog, input.platform, input.operation);
|
|
185
|
+
return { platform: input.platform.toLowerCase(), operation: input.operation, capability, billing: billing(capability) };
|
|
186
|
+
});
|
|
187
|
+
tool("get_account", "Return workspace identity and extraction limits.", z.object({}), () => api("GET", "/v1/account"));
|
|
188
|
+
tool("get_credit_usage", "Return available, reserved, promotional, purchased, and spent credits.", z.object({}), () => api("GET", "/v1/usage/current"));
|
|
189
|
+
tool("estimate_credits", "Estimate the maximum reservation for one or many targets before starting work.", z.object({ platform, operation, limit: z.number().int().min(1).max(25_000).default(12), include_posts: z.number().int().min(0).max(200).default(0), target_count: z.number().int().min(1).max(100).default(1) }), async (input) => {
|
|
190
|
+
const catalog = await api("GET", "/v1/platforms");
|
|
191
|
+
const { definition, capability } = capabilityFor(catalog, input.platform, input.operation);
|
|
192
|
+
if (capability.available === false) throw new ApiError(capability.unavailable_reason || "This operation is temporarily unavailable.", { error: "operation_unavailable", retryable: false });
|
|
193
|
+
const single = new Set(["profile", "post", "video", "transcript", "adlibrary_ad", "adlibrary_ad_transcript", "profile_analytics", "playlist"]);
|
|
194
|
+
const fixedCollection = input.platform.toLowerCase() === "instagram" && new Set(["highlights", "highlight_items", "stories"]).has(input.operation);
|
|
195
|
+
const normalizedLimit = single.has(input.operation) ? 1 : fixedCollection ? capability.max_results : input.limit;
|
|
196
|
+
if (normalizedLimit > capability.max_results) throw new Error(`limit exceeds the platform maximum of ${capability.max_results}`);
|
|
197
|
+
if (input.include_posts && input.operation !== "profile") throw new Error("include_posts is supported only for profile requests");
|
|
198
|
+
const posts = input.include_posts ? definition.operations.find((item) => item.operation === "posts") : null;
|
|
199
|
+
if (input.include_posts > (posts?.max_results || 0)) throw new Error(`include_posts exceeds the platform maximum of ${posts?.max_results || 0}`);
|
|
200
|
+
// Profile bundles use the backend's included_credit_rate. Standalone post
|
|
201
|
+
// list grouping does not apply to posts embedded in a profile request.
|
|
202
|
+
const included = input.include_posts * (posts?.credits_per_result || 0);
|
|
203
|
+
const perTarget = capability.base_credits + Math.ceil(normalizedLimit * capability.credits_per_result / Math.max(1, capability.results_per_credit)) + Math.ceil(included);
|
|
204
|
+
return { ...input, normalized_limit: normalizedLimit, maximum_reserved_credits_per_target: perTarget, maximum_reserved_credits_total: perTarget * input.target_count, settlement: "Actual billing uses delivered results and releases unused reservation." };
|
|
205
|
+
});
|
|
206
|
+
tool("extract_now", "Run one bounded target synchronously and return a model-safe result page.", extractionSchema.extend({ result_offset: z.number().int().min(0).default(0), result_limit: z.number().int().min(1).max(100).default(50), text_offset: z.number().int().min(0).default(0), text_limit: z.number().int().min(1).max(50_000).default(20_000) }), async (input) => {
|
|
207
|
+
const idempotencyKey = input.idempotency_key || randomUUID();
|
|
208
|
+
const job = await api("POST", "/v1/extract", { body: requestBody(input), idempotencyKey });
|
|
209
|
+
return { idempotency_key: idempotencyKey, ...pagedResult(job, input.result_offset, input.result_limit, input.text_offset, input.text_limit) };
|
|
210
|
+
});
|
|
211
|
+
tool("create_extraction", "Create one durable extraction job for work that may continue in the background.", extractionSchema, async (input) => {
|
|
212
|
+
const idempotencyKey = input.idempotency_key || randomUUID();
|
|
213
|
+
return { idempotency_key: idempotencyKey, job: withoutResult(await api("POST", "/v1/jobs", { body: requestBody(input), idempotencyKey })) };
|
|
214
|
+
});
|
|
215
|
+
tool("list_extractions", "List recent durable extraction jobs without embedding their large results.", z.object({ limit: z.number().int().min(1).max(100).default(25) }), (input) => api("GET", "/v1/jobs", { params: input }));
|
|
216
|
+
tool("get_extraction", "Get one job's progress, billing, and error metadata.", z.object({ job_id: id }), async ({ job_id }) => withoutResult(await api("GET", `/v1/jobs/${job_id}`)));
|
|
217
|
+
tool("get_extraction_result", "Page through a completed job's structured result without flooding model context.", z.object({ job_id: id, offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(100).default(50), text_offset: z.number().int().min(0).default(0), text_limit: z.number().int().min(1).max(50_000).default(20_000) }), async (input) => pagedResult(await api("GET", `/v1/jobs/${input.job_id}`), input.offset, input.limit, input.text_offset, input.text_limit));
|
|
218
|
+
tool("wait_for_extraction", "Wait briefly for a durable job to become terminal without returning its large result.", z.object({ job_id: id, timeout_seconds: z.number().min(1).max(120).default(60), poll_interval_seconds: z.number().min(.5).max(10).default(2) }), async (input) => {
|
|
219
|
+
const deadline = Date.now() + input.timeout_seconds * 1_000;
|
|
220
|
+
while (true) {
|
|
221
|
+
const job = await api("GET", `/v1/jobs/${input.job_id}`);
|
|
222
|
+
if (TERMINAL.has(job.status)) return { timed_out: false, job: withoutResult(job) };
|
|
223
|
+
if (Date.now() >= deadline) return { timed_out: true, job: withoutResult(job) };
|
|
224
|
+
await new Promise((resolve) => setTimeout(resolve, input.poll_interval_seconds * 1_000));
|
|
225
|
+
}
|
|
226
|
+
});
|
|
227
|
+
tool("cancel_extraction", "Cancel a queued job or request cancellation of a running job.", z.object({ job_id: id }), ({ job_id }) => api("POST", `/v1/jobs/${job_id}/cancel`));
|
|
228
|
+
tool("create_batch", "Run one operation for up to 100 targets as an expandable durable batch.", z.object({ platform, operation, targets: z.array(z.string().min(1).max(2_000)).min(1).max(100), limit: z.number().int().min(1).max(25_000).default(12), include_posts: z.number().int().min(0).max(200).default(0), idempotency_key: z.string().min(1).max(128).optional() }), async ({ idempotency_key, ...input }) => {
|
|
229
|
+
const idempotencyKey = idempotency_key || randomUUID();
|
|
230
|
+
return { idempotency_key: idempotencyKey, batch: await api("POST", "/v1/batches", { body: input, idempotencyKey }) };
|
|
231
|
+
});
|
|
232
|
+
tool("list_batches", "List recent batches and optionally their child jobs.", z.object({ limit: z.number().int().min(1).max(100).default(25), include_jobs: z.boolean().default(false) }), (input) => api("GET", "/v1/batches", { params: input }));
|
|
233
|
+
tool("get_batch", "Get aggregate status and child jobs for one batch.", z.object({ batch_id: id }), ({ batch_id }) => api("GET", `/v1/batches/${batch_id}`));
|
|
234
|
+
tool("cancel_batch", "Cancel queued batch children and request cancellation of running children.", z.object({ batch_id: id }), ({ batch_id }) => api("POST", `/v1/batches/${batch_id}/cancel`));
|
|
235
|
+
tool("list_schedules", "List active and paused extraction schedules.", z.object({ limit: z.number().int().min(1).max(100).default(50) }), (input) => api("GET", "/v1/schedules", { params: input }));
|
|
236
|
+
tool("get_schedule", "Get one schedule and its recent run history.", z.object({ schedule_id: id }), ({ schedule_id }) => api("GET", `/v1/schedules/${schedule_id}`));
|
|
237
|
+
const scheduleSchema = z.object({ name: z.string().min(1).max(120), platform, operation, targets: z.array(z.string().min(1).max(2_000)).min(1).max(100), frequency: z.enum(["once", "daily", "weekly", "monthly"]), timezone: z.string().min(1).max(100), starts_at: z.iso.datetime({ offset: true }), limit: z.number().int().min(1).max(25_000).default(12), include_posts: z.number().int().min(0).max(200).default(0) });
|
|
238
|
+
tool("create_schedule", "Create a timezone-aware once, daily, weekly, or monthly extraction schedule.", scheduleSchema, (input) => api("POST", "/v1/schedules", { body: { ...input, overlap_policy: "skip" } }));
|
|
239
|
+
tool("update_schedule", "Replace a schedule definition while preserving its run history.", scheduleSchema.extend({ schedule_id: id }), ({ schedule_id, ...input }) => api("PUT", `/v1/schedules/${schedule_id}`, { body: { ...input, overlap_policy: "skip" } }));
|
|
240
|
+
tool("manage_schedule", "Pause, resume, run now, or delete an extraction schedule.", z.object({ schedule_id: id, action: z.enum(["pause", "resume", "run", "delete"]) }), ({ schedule_id, action }) => action === "delete" ? api("DELETE", `/v1/schedules/${schedule_id}`) : api("POST", `/v1/schedules/${schedule_id}/${action}`));
|
|
241
|
+
return server;
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
export async function runServer() {
|
|
245
|
+
await serveStdio(createServer);
|
|
246
|
+
}
|