caelario-mcp 0.1.8 → 0.1.9
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 +16 -1
- package/bin/caelario-mcp.js +22 -22
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/client.js +25 -3
- package/src/connection.js +19 -0
- package/src/desktop.js +77 -0
- package/src/install.js +21 -21
- package/src/onboarding.js +1 -1
package/README.md
CHANGED
|
@@ -28,12 +28,27 @@ key only into its secure terminal prompt, never into AI chat.
|
|
|
28
28
|
npx -y caelario-mcp@latest install codex
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
## Install for Claude Code
|
|
31
|
+
## Install for Claude Code (terminal or desktop)
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
34
|
npx -y caelario-mcp@latest install claude
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
+
The installer uses the terminal CLI when available. If it is missing, it detects
|
|
38
|
+
Claude desktop and configures its local MCP settings directly, including support
|
|
39
|
+
for local Code tab sessions. You do not need to install a separate CLI.
|
|
40
|
+
|
|
41
|
+
To choose Claude desktop explicitly (also for its regular chat surface), run:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npx -y caelario-mcp@latest install claude-desktop
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Quit Claude completely and reopen it after installation. Approve Caelario when
|
|
48
|
+
Claude asks, then ask it to check your connection and available credits.
|
|
49
|
+
Existing desktop settings and other MCP servers are preserved. If the settings
|
|
50
|
+
file is malformed, the installer stops without overwriting it.
|
|
51
|
+
|
|
37
52
|
The installer finds your assistant before starting setup. On Windows it also
|
|
38
53
|
finds the Codex desktop app when `codex` is absent from your terminal PATH. It
|
|
39
54
|
prompts for a Caelario workspace API key and registers the stdio server at user
|
package/bin/caelario-mcp.js
CHANGED
|
@@ -1,22 +1,22 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
import { installClient, printHelp } from "../src/install.js";
|
|
4
|
-
import { runServer } from "../src/server.js";
|
|
5
|
-
|
|
6
|
-
const [command = "serve", client] = process.argv.slice(2);
|
|
7
|
-
|
|
8
|
-
try {
|
|
9
|
-
if (command === "serve") {
|
|
10
|
-
await runServer();
|
|
11
|
-
} else if (command === "install" &&
|
|
12
|
-
await installClient(client);
|
|
13
|
-
} else if (command === "--help" || command === "-h" || command === "help") {
|
|
14
|
-
printHelp();
|
|
15
|
-
} else {
|
|
16
|
-
printHelp();
|
|
17
|
-
process.exitCode = 2;
|
|
18
|
-
}
|
|
19
|
-
} catch (error) {
|
|
20
|
-
process.stderr.write(`Caelario MCP: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
21
|
-
process.exitCode = 1;
|
|
22
|
-
}
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { installClient, printHelp } from "../src/install.js";
|
|
4
|
+
import { runServer } from "../src/server.js";
|
|
5
|
+
|
|
6
|
+
const [command = "serve", client] = process.argv.slice(2);
|
|
7
|
+
|
|
8
|
+
try {
|
|
9
|
+
if (command === "serve") {
|
|
10
|
+
await runServer();
|
|
11
|
+
} else if (command === "install" && ["codex", "claude", "claude-desktop"].includes(client)) {
|
|
12
|
+
await installClient(client);
|
|
13
|
+
} else if (command === "--help" || command === "-h" || command === "help") {
|
|
14
|
+
printHelp();
|
|
15
|
+
} else {
|
|
16
|
+
printHelp();
|
|
17
|
+
process.exitCode = 2;
|
|
18
|
+
}
|
|
19
|
+
} catch (error) {
|
|
20
|
+
process.stderr.write(`Caelario MCP: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
21
|
+
process.exitCode = 1;
|
|
22
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "caelario-mcp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.9",
|
|
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,12 +9,12 @@
|
|
|
9
9
|
"source": "github",
|
|
10
10
|
"id": "1346708115"
|
|
11
11
|
},
|
|
12
|
-
"version": "0.1.
|
|
12
|
+
"version": "0.1.9",
|
|
13
13
|
"packages": [
|
|
14
14
|
{
|
|
15
15
|
"registryType": "npm",
|
|
16
16
|
"identifier": "caelario-mcp",
|
|
17
|
-
"version": "0.1.
|
|
17
|
+
"version": "0.1.9",
|
|
18
18
|
"transport": {
|
|
19
19
|
"type": "stdio"
|
|
20
20
|
},
|
package/src/client.js
CHANGED
|
@@ -1,20 +1,30 @@
|
|
|
1
1
|
import { spawnSync } from "node:child_process";
|
|
2
2
|
import { existsSync } from "node:fs";
|
|
3
3
|
import { join } from "node:path";
|
|
4
|
+
import { homedir } from "node:os";
|
|
5
|
+
import { findClaudeDesktop } from "./desktop.js";
|
|
4
6
|
|
|
5
7
|
export function resolveClientExecutable(client, {
|
|
6
8
|
platform = process.platform,
|
|
7
9
|
env = process.env,
|
|
8
10
|
spawn = spawnSync,
|
|
9
11
|
exists = existsSync,
|
|
12
|
+
home = homedir(),
|
|
10
13
|
} = {}) {
|
|
11
|
-
if (!["codex", "claude"].includes(client)) throw new Error("client must be codex or claude");
|
|
14
|
+
if (!["codex", "claude", "claude-desktop"].includes(client)) throw new Error("client must be codex, claude or claude-desktop");
|
|
15
|
+
if (client === "claude-desktop") {
|
|
16
|
+
const desktop = findClaudeDesktop({ platform, env, home, exists });
|
|
17
|
+
if (desktop) return desktop;
|
|
18
|
+
throw new Error("Claude desktop was not found. Install and open Claude desktop, then run this command again.");
|
|
19
|
+
}
|
|
12
20
|
const options = { encoding: "utf8", stdio: "pipe", windowsHide: true, timeout: 10_000 };
|
|
13
21
|
const usable = (path) => {
|
|
14
22
|
const shell = platform === "win32" && /\.(cmd|bat)$/i.test(path);
|
|
15
23
|
const command = shell ? `"${path}"` : path;
|
|
16
24
|
const result = spawn(command, ["--version"], { ...options, shell });
|
|
17
|
-
|
|
25
|
+
if (result.error || result.status !== 0) return null;
|
|
26
|
+
if (client === "claude" && !/\bClaude Code\b|^\s*\d+\.\d+\.\d+(?:[-+][\w.-]+)?(?:\s|$)/i.test(result.stdout || "")) return null;
|
|
27
|
+
return { command, shell };
|
|
18
28
|
};
|
|
19
29
|
if (platform !== "win32") {
|
|
20
30
|
const found = usable(client);
|
|
@@ -46,7 +56,19 @@ export function resolveClientExecutable(client, {
|
|
|
46
56
|
}
|
|
47
57
|
}
|
|
48
58
|
}
|
|
59
|
+
if (client === "claude") {
|
|
60
|
+
const candidates = [join(home, ".local", "bin", platform === "win32" ? "claude.exe" : "claude")];
|
|
61
|
+
if (platform === "win32" && env.APPDATA) candidates.push(join(env.APPDATA, "npm", "claude.cmd"));
|
|
62
|
+
for (const path of candidates) {
|
|
63
|
+
if (exists(path)) {
|
|
64
|
+
const found = usable(path);
|
|
65
|
+
if (found) return found;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
const desktop = findClaudeDesktop({ platform, env, home, exists });
|
|
69
|
+
if (desktop) return desktop;
|
|
70
|
+
}
|
|
49
71
|
throw new Error(client === "codex"
|
|
50
72
|
? "Codex was not found. Install the Codex desktop app or Codex CLI, then run this command again."
|
|
51
|
-
: "Claude Code was
|
|
73
|
+
: "Neither Claude Code nor Claude desktop was found. Install either one, then run this command again.");
|
|
52
74
|
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export const KEY_PATTERN = /^[A-Za-z0-9._-]{16,256}$/;
|
|
2
|
+
|
|
3
|
+
export function connectionConfiguration(apiKey, apiUrl = "https://api.caelario.com", platform = process.platform) {
|
|
4
|
+
if (!KEY_PATTERN.test(apiKey)) throw new Error("the Caelario API key format is invalid");
|
|
5
|
+
const origin = new URL(apiUrl);
|
|
6
|
+
if (!["http:", "https:"].includes(origin.protocol)) throw new Error("the Caelario API URL requires HTTP or HTTPS");
|
|
7
|
+
if (/[&|<>^%!()\r\n]/.test(origin.origin)) throw new Error("the Caelario API origin contains unsafe launcher characters");
|
|
8
|
+
if (origin.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname)) {
|
|
9
|
+
throw new Error("the Caelario API URL must use HTTPS");
|
|
10
|
+
}
|
|
11
|
+
if (origin.pathname !== "/" || origin.search || origin.hash || origin.username || origin.password) {
|
|
12
|
+
throw new Error("the Caelario API URL must contain only an origin");
|
|
13
|
+
}
|
|
14
|
+
return {
|
|
15
|
+
command: platform === "win32" ? "cmd" : "npx",
|
|
16
|
+
args: [...(platform === "win32" ? ["/c", "npx"] : []), "-y", "caelario-mcp", "serve"],
|
|
17
|
+
env: { CAELARIO_API_URL: origin.origin, CAELARIO_API_KEY: apiKey },
|
|
18
|
+
};
|
|
19
|
+
}
|
package/src/desktop.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { existsSync, readFileSync, mkdirSync, openSync, closeSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { join, dirname } from "node:path";
|
|
4
|
+
import { randomUUID } from "node:crypto";
|
|
5
|
+
import { connectionConfiguration } from "./connection.js";
|
|
6
|
+
|
|
7
|
+
export function findClaudeDesktop({ platform = process.platform, env = process.env, home = homedir(), exists = existsSync } = {}) {
|
|
8
|
+
if (platform === "win32") {
|
|
9
|
+
const local = env.LOCALAPPDATA || join(home, "AppData", "Local");
|
|
10
|
+
const installed = [join(local, "AnthropicClaude", "claude.exe"), join(local, "Programs", "Claude", "Claude.exe")];
|
|
11
|
+
if (installed.some((path) => exists(path))) {
|
|
12
|
+
return { desktop: true, configPath: join(env.APPDATA || join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json") };
|
|
13
|
+
}
|
|
14
|
+
} else if (platform === "darwin" && ["/Applications/Claude.app", join(home, "Applications", "Claude.app")].some((path) => exists(path))) {
|
|
15
|
+
return { desktop: true, configPath: join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") };
|
|
16
|
+
}
|
|
17
|
+
return null;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
class DesktopConfigurationError extends Error {}
|
|
21
|
+
|
|
22
|
+
function readConfiguration(path) {
|
|
23
|
+
let source;
|
|
24
|
+
try { source = readFileSync(path, "utf8"); }
|
|
25
|
+
catch (error) {
|
|
26
|
+
if (error.code === "ENOENT") return { source: null, config: {} };
|
|
27
|
+
throw new DesktopConfigurationError("Could not read Claude desktop settings. Check file permissions and retry.");
|
|
28
|
+
}
|
|
29
|
+
let config;
|
|
30
|
+
try { config = JSON.parse(source.replace(/^\uFEFF/, "")); }
|
|
31
|
+
catch { throw new DesktopConfigurationError("Claude desktop settings contain invalid JSON. Fix them in Claude settings and retry. No settings were changed."); }
|
|
32
|
+
if (!config || typeof config !== "object" || Array.isArray(config)
|
|
33
|
+
|| (config.mcpServers !== undefined && (!config.mcpServers || typeof config.mcpServers !== "object" || Array.isArray(config.mcpServers)))) {
|
|
34
|
+
throw new DesktopConfigurationError("Claude desktop settings have an invalid structure. Fix them in Claude settings and retry. No settings were changed.");
|
|
35
|
+
}
|
|
36
|
+
return { source, config };
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export function checkClaudeDesktopConfiguration(path) {
|
|
40
|
+
readConfiguration(path);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function configureClaudeDesktop(apiKey, apiUrl, { configPath, platform = process.platform } = {}) {
|
|
44
|
+
const entry = connectionConfiguration(apiKey, apiUrl, platform);
|
|
45
|
+
const lockPath = `${configPath}.caelario-install.lock`;
|
|
46
|
+
const temporaryPath = `${configPath}.caelario-${randomUUID()}.tmp`;
|
|
47
|
+
let lock;
|
|
48
|
+
let temporaryCreated = false;
|
|
49
|
+
try {
|
|
50
|
+
mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
|
|
51
|
+
try { lock = openSync(lockPath, "wx", 0o600); }
|
|
52
|
+
catch (error) {
|
|
53
|
+
if (error.code === "EEXIST") throw new DesktopConfigurationError("Another Caelario installer is updating Claude desktop settings. Let it finish and retry.");
|
|
54
|
+
throw error;
|
|
55
|
+
}
|
|
56
|
+
const { source, config } = readConfiguration(configPath);
|
|
57
|
+
const updated = { ...config, mcpServers: { ...config.mcpServers, caelario: entry } };
|
|
58
|
+
const temporary = openSync(temporaryPath, "wx", 0o600);
|
|
59
|
+
temporaryCreated = true;
|
|
60
|
+
try { writeFileSync(temporary, `${JSON.stringify(updated, null, 2)}\n`); }
|
|
61
|
+
finally { closeSync(temporary); }
|
|
62
|
+
if (readConfiguration(configPath).source !== source) {
|
|
63
|
+
throw new DesktopConfigurationError("Claude desktop settings changed during installation. Run the installer again. No settings were overwritten.");
|
|
64
|
+
}
|
|
65
|
+
renameSync(temporaryPath, configPath);
|
|
66
|
+
temporaryCreated = false;
|
|
67
|
+
} catch (error) {
|
|
68
|
+
if (error instanceof DesktopConfigurationError) throw error;
|
|
69
|
+
throw new Error("Could not update Claude desktop settings. Close Claude, check file permissions and retry.");
|
|
70
|
+
} finally {
|
|
71
|
+
if (temporaryCreated) { try { unlinkSync(temporaryPath); } catch {} }
|
|
72
|
+
if (lock !== undefined) {
|
|
73
|
+
closeSync(lock);
|
|
74
|
+
try { unlinkSync(lockPath); } catch {}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
package/src/install.js
CHANGED
|
@@ -2,32 +2,21 @@ import { spawnSync } from "node:child_process";
|
|
|
2
2
|
import process from "node:process";
|
|
3
3
|
import readline from "node:readline";
|
|
4
4
|
import { resolveClientExecutable } from "./client.js";
|
|
5
|
+
import { connectionConfiguration, KEY_PATTERN } from "./connection.js";
|
|
6
|
+
import { checkClaudeDesktopConfiguration, configureClaudeDesktop } from "./desktop.js";
|
|
5
7
|
import { SETUP_URL, setupInstructions, openSetupPage, verifyWorkspaceKey, ConnectionKeyRejectedError } from "./onboarding.js";
|
|
6
8
|
|
|
7
9
|
const CLIENTS = new Set(["codex", "claude"]);
|
|
8
|
-
const KEY_PATTERN = /^[A-Za-z0-9._-]{16,256}$/;
|
|
9
10
|
|
|
10
11
|
export function registrationCommand(client, apiKey, apiUrl = "https://api.caelario.com", platform = process.platform) {
|
|
11
12
|
if (!CLIENTS.has(client)) throw new Error("client must be codex or claude");
|
|
12
|
-
|
|
13
|
-
const
|
|
14
|
-
if (!["http:", "https:"].includes(origin.protocol)) throw new Error("the Caelario API URL requires HTTP or HTTPS");
|
|
15
|
-
if (/[&|<>^%!()\r\n]/.test(origin.origin)) throw new Error("the Caelario API origin contains unsafe launcher characters");
|
|
16
|
-
if (origin.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(origin.hostname)) {
|
|
17
|
-
throw new Error("the Caelario API URL must use HTTPS");
|
|
18
|
-
}
|
|
19
|
-
if (origin.pathname !== "/" || origin.search || origin.hash || origin.username || origin.password) {
|
|
20
|
-
throw new Error("the Caelario API URL must contain only an origin");
|
|
21
|
-
}
|
|
22
|
-
|
|
23
|
-
const launcher = platform === "win32"
|
|
24
|
-
? ["cmd", "/c", "npx", "-y", "caelario-mcp", "serve"]
|
|
25
|
-
: ["npx", "-y", "caelario-mcp", "serve"];
|
|
13
|
+
const connection = connectionConfiguration(apiKey, apiUrl, platform);
|
|
14
|
+
const launcher = [connection.command, ...connection.args];
|
|
26
15
|
const common = [
|
|
27
16
|
"mcp", "add",
|
|
28
17
|
...(client === "claude" ? ["--scope", "user"] : []),
|
|
29
18
|
"caelario",
|
|
30
|
-
"--env", `CAELARIO_API_URL=${
|
|
19
|
+
"--env", `CAELARIO_API_URL=${connection.env.CAELARIO_API_URL}`,
|
|
31
20
|
"--env", `CAELARIO_API_KEY=${apiKey}`,
|
|
32
21
|
"--",
|
|
33
22
|
...launcher,
|
|
@@ -43,6 +32,7 @@ export async function installClient(
|
|
|
43
32
|
platform = process.platform,
|
|
44
33
|
spawn = spawnSync,
|
|
45
34
|
resolveClient = resolveClientExecutable,
|
|
35
|
+
configureDesktop = configureClaudeDesktop,
|
|
46
36
|
openBrowser = openSetupPage,
|
|
47
37
|
prompt = promptSecret,
|
|
48
38
|
verifyKey = verifyWorkspaceKey,
|
|
@@ -50,9 +40,13 @@ export async function installClient(
|
|
|
50
40
|
interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY),
|
|
51
41
|
} = {},
|
|
52
42
|
) {
|
|
53
|
-
if (!CLIENTS.has(client)) throw new Error("client must be codex or claude");
|
|
54
|
-
write(`Finding ${client === "codex" ? "Codex" : "Claude
|
|
43
|
+
if (!CLIENTS.has(client) && client !== "claude-desktop") throw new Error("client must be codex, claude or claude-desktop");
|
|
44
|
+
write(`Finding ${client === "codex" ? "Codex" : "Claude"}...\n`);
|
|
55
45
|
const executable = resolveClient(client, { platform });
|
|
46
|
+
if (executable.desktop) {
|
|
47
|
+
checkClaudeDesktopConfiguration(executable.configPath);
|
|
48
|
+
write("Found Claude desktop. Connecting without a separate Claude Code CLI.\n");
|
|
49
|
+
}
|
|
56
50
|
let key = apiKey?.trim();
|
|
57
51
|
let setupShown = false;
|
|
58
52
|
let registration;
|
|
@@ -60,7 +54,7 @@ export async function installClient(
|
|
|
60
54
|
while (true) {
|
|
61
55
|
if (!key) {
|
|
62
56
|
if (!setupShown) {
|
|
63
|
-
write(`${setupInstructions(client)}\n\n`);
|
|
57
|
+
write(`${setupInstructions(executable.desktop ? "claude-desktop" : client)}\n\n`);
|
|
64
58
|
if (interactive) {
|
|
65
59
|
write("Opening your browser setup page...\n");
|
|
66
60
|
openBrowser();
|
|
@@ -79,7 +73,7 @@ export async function installClient(
|
|
|
79
73
|
continue;
|
|
80
74
|
}
|
|
81
75
|
// Validate the origin before sending a key, even when setup needs a retry.
|
|
82
|
-
registration = registrationCommand(client, key, apiUrl, platform);
|
|
76
|
+
registration = registrationCommand(client === "claude-desktop" ? "claude" : client, key, apiUrl, platform);
|
|
83
77
|
write("Checking your Caelario connection key...\n");
|
|
84
78
|
try {
|
|
85
79
|
await verifyKey(key, apiUrl);
|
|
@@ -90,6 +84,11 @@ export async function installClient(
|
|
|
90
84
|
key = "";
|
|
91
85
|
}
|
|
92
86
|
}
|
|
87
|
+
if (executable.desktop) {
|
|
88
|
+
configureDesktop(key, apiUrl, { configPath: executable.configPath, platform });
|
|
89
|
+
write("Caelario is configured for Claude desktop, including local Code sessions. Quit Claude completely and reopen it, approve the Caelario connection if asked, then ask it to use Caelario.\n");
|
|
90
|
+
return;
|
|
91
|
+
}
|
|
93
92
|
const completed = spawn(executable.command, registration.args, {
|
|
94
93
|
stdio: "pipe",
|
|
95
94
|
encoding: "utf8",
|
|
@@ -147,7 +146,8 @@ export function printHelp() {
|
|
|
147
146
|
"Caelario MCP",
|
|
148
147
|
"",
|
|
149
148
|
" npx -y caelario-mcp install codex Register for Codex (user-wide)",
|
|
150
|
-
" npx -y caelario-mcp install claude
|
|
149
|
+
" npx -y caelario-mcp install claude Connect Claude Code or detect Claude desktop",
|
|
150
|
+
" npx -y caelario-mcp install claude-desktop Connect Claude desktop explicitly",
|
|
151
151
|
" npx -y caelario-mcp serve Run the stdio server",
|
|
152
152
|
"",
|
|
153
153
|
setupInstructions(),
|
package/src/onboarding.js
CHANGED
|
@@ -4,7 +4,7 @@ export const SETUP_URL = "https://app.caelario.com/connect";
|
|
|
4
4
|
export const SIGNUP_URL = "https://app.caelario.com/sign-up";
|
|
5
5
|
|
|
6
6
|
export function setupInstructions(client = "codex") {
|
|
7
|
-
const label = client === "claude" ? "Claude Code" : "Codex";
|
|
7
|
+
const label = client === "claude-desktop" ? "Claude desktop" : client === "claude" ? "Claude Code" : "Codex";
|
|
8
8
|
return [
|
|
9
9
|
"Caelario connects social media data to your AI assistant.",
|
|
10
10
|
"",
|