caelario-mcp 0.1.6 → 0.1.8
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 +18 -4
- package/package.json +1 -1
- package/server.json +3 -3
- package/src/client.js +52 -0
- package/src/install.js +60 -10
- package/src/onboarding.js +56 -0
- package/src/server.js +6 -2
package/README.md
CHANGED
|
@@ -10,20 +10,34 @@ The official local server gives Codex and Claude Code typed tools for capability
|
|
|
10
10
|
discovery, immediate and durable extraction, result pagination, and credit
|
|
11
11
|
estimates.
|
|
12
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, or when the key in your terminal environment is rejected. It lets you
|
|
22
|
+
replace a rejected or incomplete key without restarting the command. Paste the
|
|
23
|
+
key only into its secure terminal prompt, never into AI chat.
|
|
24
|
+
|
|
13
25
|
## Install for Codex
|
|
14
26
|
|
|
15
27
|
```bash
|
|
16
|
-
npx -y caelario-mcp install codex
|
|
28
|
+
npx -y caelario-mcp@latest install codex
|
|
17
29
|
```
|
|
18
30
|
|
|
19
31
|
## Install for Claude Code
|
|
20
32
|
|
|
21
33
|
```bash
|
|
22
|
-
npx -y caelario-mcp install claude
|
|
34
|
+
npx -y caelario-mcp@latest install claude
|
|
23
35
|
```
|
|
24
36
|
|
|
25
|
-
The installer
|
|
26
|
-
|
|
37
|
+
The installer finds your assistant before starting setup. On Windows it also
|
|
38
|
+
finds the Codex desktop app when `codex` is absent from your terminal PATH. It
|
|
39
|
+
prompts for a Caelario workspace API key and registers the stdio server at user
|
|
40
|
+
scope. It does not ask for Instagram, TikTok, YouTube, X, or
|
|
27
41
|
Facebook credentials; provider identities are managed by Caelario.
|
|
28
42
|
|
|
29
43
|
After installation, restart the client and ask:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "caelario-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.8",
|
|
4
4
|
"mcpName": "io.github.chunkydonut21/caelario",
|
|
5
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
6
|
"type": "module",
|
package/server.json
CHANGED
|
@@ -9,18 +9,18 @@
|
|
|
9
9
|
"source": "github",
|
|
10
10
|
"id": "1346708115"
|
|
11
11
|
},
|
|
12
|
-
"version": "0.1.
|
|
12
|
+
"version": "0.1.8",
|
|
13
13
|
"packages": [
|
|
14
14
|
{
|
|
15
15
|
"registryType": "npm",
|
|
16
16
|
"identifier": "caelario-mcp",
|
|
17
|
-
"version": "0.1.
|
|
17
|
+
"version": "0.1.8",
|
|
18
18
|
"transport": {
|
|
19
19
|
"type": "stdio"
|
|
20
20
|
},
|
|
21
21
|
"environmentVariables": [
|
|
22
22
|
{
|
|
23
|
-
"description": "
|
|
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
24
|
"isRequired": true,
|
|
25
25
|
"format": "string",
|
|
26
26
|
"isSecret": true,
|
package/src/client.js
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
|
|
5
|
+
export function resolveClientExecutable(client, {
|
|
6
|
+
platform = process.platform,
|
|
7
|
+
env = process.env,
|
|
8
|
+
spawn = spawnSync,
|
|
9
|
+
exists = existsSync,
|
|
10
|
+
} = {}) {
|
|
11
|
+
if (!["codex", "claude"].includes(client)) throw new Error("client must be codex or claude");
|
|
12
|
+
const options = { encoding: "utf8", stdio: "pipe", windowsHide: true, timeout: 10_000 };
|
|
13
|
+
const usable = (path) => {
|
|
14
|
+
const shell = platform === "win32" && /\.(cmd|bat)$/i.test(path);
|
|
15
|
+
const command = shell ? `"${path}"` : path;
|
|
16
|
+
const result = spawn(command, ["--version"], { ...options, shell });
|
|
17
|
+
return !result.error && result.status === 0 ? { command, shell } : null;
|
|
18
|
+
};
|
|
19
|
+
if (platform !== "win32") {
|
|
20
|
+
const found = usable(client);
|
|
21
|
+
if (found) return found;
|
|
22
|
+
} else {
|
|
23
|
+
const located = spawn("where.exe", [client], options);
|
|
24
|
+
if (!located.error && located.status === 0) {
|
|
25
|
+
for (const path of (located.stdout || "").trim().split(/\r?\n/)) {
|
|
26
|
+
if (path && exists(path)) {
|
|
27
|
+
const found = usable(path);
|
|
28
|
+
if (found) return found;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
if (client === "codex") {
|
|
33
|
+
// Desktop installs include a CLI even when a normal terminal cannot find it.
|
|
34
|
+
const powershell = join(env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
|
|
35
|
+
const app = spawn(powershell, ["-NoProfile", "-NonInteractive", "-Command",
|
|
36
|
+
"Get-AppxPackage -Name OpenAI.Codex -ErrorAction SilentlyContinue | ForEach-Object { Join-Path $_.InstallLocation 'app\\resources\\codex.exe' }",
|
|
37
|
+
], options);
|
|
38
|
+
const candidates = !app.error && app.status === 0 ? (app.stdout || "").trim().split(/\r?\n/) : [];
|
|
39
|
+
if (env.LOCALAPPDATA) candidates.push(join(env.LOCALAPPDATA, "Programs", "Codex", "resources", "codex.exe"));
|
|
40
|
+
if (env.ProgramFiles) candidates.push(join(env.ProgramFiles, "Codex", "resources", "codex.exe"));
|
|
41
|
+
for (const path of candidates) {
|
|
42
|
+
if (path && exists(path)) {
|
|
43
|
+
const found = usable(path);
|
|
44
|
+
if (found) return found;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
throw new Error(client === "codex"
|
|
50
|
+
? "Codex was not found. Install the Codex desktop app or Codex CLI, then run this command again."
|
|
51
|
+
: "Claude Code was not found. Install Claude Code, then run this command again.");
|
|
52
|
+
}
|
package/src/install.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { spawnSync } from "node:child_process";
|
|
2
2
|
import process from "node:process";
|
|
3
3
|
import readline from "node:readline";
|
|
4
|
+
import { resolveClientExecutable } from "./client.js";
|
|
5
|
+
import { SETUP_URL, setupInstructions, openSetupPage, verifyWorkspaceKey, ConnectionKeyRejectedError } from "./onboarding.js";
|
|
4
6
|
|
|
5
7
|
const CLIENTS = new Set(["codex", "claude"]);
|
|
6
8
|
const KEY_PATTERN = /^[A-Za-z0-9._-]{16,256}$/;
|
|
@@ -40,29 +42,77 @@ export async function installClient(
|
|
|
40
42
|
apiUrl = process.env.CAELARIO_API_URL || "https://api.caelario.com",
|
|
41
43
|
platform = process.platform,
|
|
42
44
|
spawn = spawnSync,
|
|
45
|
+
resolveClient = resolveClientExecutable,
|
|
46
|
+
openBrowser = openSetupPage,
|
|
47
|
+
prompt = promptSecret,
|
|
48
|
+
verifyKey = verifyWorkspaceKey,
|
|
49
|
+
write = (text) => process.stderr.write(text),
|
|
50
|
+
interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY),
|
|
43
51
|
} = {},
|
|
44
52
|
) {
|
|
45
53
|
if (!CLIENTS.has(client)) throw new Error("client must be codex or claude");
|
|
46
|
-
|
|
47
|
-
const
|
|
48
|
-
|
|
49
|
-
|
|
54
|
+
write(`Finding ${client === "codex" ? "Codex" : "Claude Code"}...\n`);
|
|
55
|
+
const executable = resolveClient(client, { platform });
|
|
56
|
+
let key = apiKey?.trim();
|
|
57
|
+
let setupShown = false;
|
|
58
|
+
let registration;
|
|
59
|
+
if (key) write("Found CAELARIO_API_KEY in your environment.\n");
|
|
60
|
+
while (true) {
|
|
61
|
+
if (!key) {
|
|
62
|
+
if (!setupShown) {
|
|
63
|
+
write(`${setupInstructions(client)}\n\n`);
|
|
64
|
+
if (interactive) {
|
|
65
|
+
write("Opening your browser setup page...\n");
|
|
66
|
+
openBrowser();
|
|
67
|
+
}
|
|
68
|
+
setupShown = true;
|
|
69
|
+
}
|
|
70
|
+
if (!interactive) {
|
|
71
|
+
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.`);
|
|
72
|
+
}
|
|
73
|
+
key = (await prompt("Finish setup in your browser, then paste your connection key here: ")).trim();
|
|
74
|
+
}
|
|
75
|
+
if (!KEY_PATTERN.test(key)) {
|
|
76
|
+
if (!interactive) throw new Error(`The connection key format is invalid. Get your full key at ${SETUP_URL}.`);
|
|
77
|
+
write("That connection key is incomplete or has an invalid format. Paste the full key from browser setup.\n");
|
|
78
|
+
key = "";
|
|
79
|
+
continue;
|
|
80
|
+
}
|
|
81
|
+
// Validate the origin before sending a key, even when setup needs a retry.
|
|
82
|
+
registration = registrationCommand(client, key, apiUrl, platform);
|
|
83
|
+
write("Checking your Caelario connection key...\n");
|
|
84
|
+
try {
|
|
85
|
+
await verifyKey(key, apiUrl);
|
|
86
|
+
break;
|
|
87
|
+
} catch (error) {
|
|
88
|
+
if (!(error instanceof ConnectionKeyRejectedError) || !interactive) throw error;
|
|
89
|
+
write("Caelario did not accept that key. Let's connect with a current key from browser setup.\n");
|
|
90
|
+
key = "";
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
const completed = spawn(executable.command, registration.args, {
|
|
94
|
+
stdio: "pipe",
|
|
95
|
+
encoding: "utf8",
|
|
50
96
|
windowsHide: true,
|
|
51
|
-
|
|
97
|
+
timeout: 30_000,
|
|
98
|
+
shell: executable.shell,
|
|
52
99
|
});
|
|
100
|
+
for (const output of [completed.stdout, completed.stderr]) {
|
|
101
|
+
if (output) write(output.replaceAll(key, "[redacted]"));
|
|
102
|
+
}
|
|
53
103
|
if (completed.error?.code === "ENOENT") {
|
|
54
|
-
throw new Error(`${client === "codex" ? "Codex" : "Claude Code"}
|
|
104
|
+
throw new Error(`${client === "codex" ? "Codex" : "Claude Code"} was not found. Reopen your terminal and run this command again.`);
|
|
55
105
|
}
|
|
56
|
-
if (completed.error) throw
|
|
106
|
+
if (completed.error) throw new Error("The assistant client could not be started. Check its installation and run this command again.");
|
|
57
107
|
if (completed.status !== 0) {
|
|
58
108
|
throw new Error(`${client === "codex" ? "Codex" : "Claude Code"} rejected the MCP registration (exit ${completed.status ?? "unknown"})`);
|
|
59
109
|
}
|
|
60
|
-
|
|
110
|
+
write(`Caelario is connected to ${client === "codex" ? "Codex" : "Claude Code"}. Restart the client, then ask it to use Caelario.\n`);
|
|
61
111
|
}
|
|
62
112
|
|
|
63
113
|
async function promptSecret(prompt) {
|
|
64
114
|
if (!process.stdin.isTTY || !process.stderr.isTTY) {
|
|
65
|
-
throw new Error(
|
|
115
|
+
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.`);
|
|
66
116
|
}
|
|
67
117
|
process.stderr.write(prompt);
|
|
68
118
|
process.stdin.setRawMode?.(true);
|
|
@@ -100,7 +150,7 @@ export function printHelp() {
|
|
|
100
150
|
" npx -y caelario-mcp install claude Register for Claude Code (user-wide)",
|
|
101
151
|
" npx -y caelario-mcp serve Run the stdio server",
|
|
102
152
|
"",
|
|
103
|
-
|
|
153
|
+
setupInstructions(),
|
|
104
154
|
];
|
|
105
155
|
readline.clearLine(process.stderr, 0);
|
|
106
156
|
process.stderr.write(`${output.join("\n")}\n`);
|
|
@@ -0,0 +1,56 @@
|
|
|
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 class ConnectionKeyRejectedError extends Error {
|
|
31
|
+
constructor() {
|
|
32
|
+
super(`Caelario did not accept that key. Open ${SETUP_URL}, copy your full connection key and try again.`);
|
|
33
|
+
this.name = "ConnectionKeyRejectedError";
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export async function verifyWorkspaceKey(apiKey, apiUrl) {
|
|
38
|
+
let response;
|
|
39
|
+
try {
|
|
40
|
+
response = await fetch(new URL("/v1/account", apiUrl), {
|
|
41
|
+
headers: { "X-API-Key": apiKey, Accept: "application/json" },
|
|
42
|
+
redirect: "manual",
|
|
43
|
+
signal: AbortSignal.timeout(20_000),
|
|
44
|
+
});
|
|
45
|
+
} catch {
|
|
46
|
+
throw new Error("Could not reach Caelario to check the key. Check your connection and run the installer again.");
|
|
47
|
+
}
|
|
48
|
+
if (response.status === 401 || response.status === 403) {
|
|
49
|
+
throw new ConnectionKeyRejectedError();
|
|
50
|
+
}
|
|
51
|
+
if (!response.ok) throw new Error("Caelario could not verify the key right now. Please try again shortly.");
|
|
52
|
+
const account = await response.json().catch(() => null);
|
|
53
|
+
if (!account || typeof account.organization_id !== "string") {
|
|
54
|
+
throw new Error("Caelario returned an unexpected response while checking the key. Please try again shortly.");
|
|
55
|
+
}
|
|
56
|
+
}
|
package/src/server.js
CHANGED
|
@@ -4,6 +4,7 @@ import { readFileSync } from "node:fs";
|
|
|
4
4
|
import { McpServer } from "@modelcontextprotocol/server";
|
|
5
5
|
import { serveStdio } from "@modelcontextprotocol/server/stdio";
|
|
6
6
|
import * as z from "zod/v4";
|
|
7
|
+
import { SETUP_URL } from "./onboarding.js";
|
|
7
8
|
|
|
8
9
|
const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
|
|
9
10
|
const TERMINAL = new Set(["completed", "failed", "cancelled"]);
|
|
@@ -13,7 +14,7 @@ const id = z.string().regex(/^[A-Za-z0-9_-]{1,128}$/);
|
|
|
13
14
|
|
|
14
15
|
function apiConfiguration() {
|
|
15
16
|
const apiKey = (process.env.CAELARIO_API_KEY || "").trim();
|
|
16
|
-
if (!apiKey) throw new Error(
|
|
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.`);
|
|
17
18
|
const baseUrl = new URL(process.env.CAELARIO_API_URL || "https://api.caelario.com");
|
|
18
19
|
if (!["https:", "http:"].includes(baseUrl.protocol)) throw new Error("CAELARIO_API_URL requires HTTP or HTTPS");
|
|
19
20
|
if (baseUrl.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(baseUrl.hostname)) {
|
|
@@ -55,6 +56,7 @@ async function api(method, path, { body, params, idempotencyKey } = {}) {
|
|
|
55
56
|
Accept: "application/json",
|
|
56
57
|
"Content-Type": "application/json",
|
|
57
58
|
"X-API-Key": apiKey,
|
|
59
|
+
"User-Agent": `caelario-mcp/${VERSION}`,
|
|
58
60
|
...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
|
|
59
61
|
},
|
|
60
62
|
body: body === undefined ? undefined : JSON.stringify(body),
|
|
@@ -84,6 +86,7 @@ async function api(method, path, { body, params, idempotencyKey } = {}) {
|
|
|
84
86
|
throw new ApiError(`Caelario API request failed (${response.status})${safeMessage ? `: ${safeMessage}` : ""}`, {
|
|
85
87
|
error: typeof code === "string" && /^[a-z0-9_]{1,64}$/.test(code) ? code : "api_request_failed",
|
|
86
88
|
status_code: response.status, retryable: Boolean(detail?.retryable),
|
|
89
|
+
...([401, 403].includes(response.status) ? { setup_url: SETUP_URL } : {}),
|
|
87
90
|
outcome_unknown: false, ...(jobId ? { job_id: jobId } : {}), ...recovery,
|
|
88
91
|
});
|
|
89
92
|
}
|
|
@@ -164,7 +167,7 @@ const extractionSchema = z.object({
|
|
|
164
167
|
export function createServer() {
|
|
165
168
|
const server = new McpServer(
|
|
166
169
|
{ name: "Caelario", version: VERSION },
|
|
167
|
-
{ instructions: "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." },
|
|
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." },
|
|
168
171
|
);
|
|
169
172
|
const tool = (name, description, inputSchema, handler) => server.registerTool(name, { description, inputSchema }, async (input) => {
|
|
170
173
|
try {
|
|
@@ -186,6 +189,7 @@ export function createServer() {
|
|
|
186
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) => {
|
|
187
190
|
const catalog = await api("GET", "/v1/platforms");
|
|
188
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 });
|
|
189
193
|
const single = new Set(["profile", "post", "video", "transcript", "adlibrary_ad", "adlibrary_ad_transcript", "profile_analytics", "playlist"]);
|
|
190
194
|
const fixedCollection = input.platform.toLowerCase() === "instagram" && new Set(["highlights", "highlight_items", "stories"]).has(input.operation);
|
|
191
195
|
const normalizedLimit = single.has(input.operation) ? 1 : fixedCollection ? capability.max_results : input.limit;
|