@futuvara/connect 0.3.2 → 0.3.4
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 +3 -0
- package/bin/connect.js +86 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -44,6 +44,9 @@ What it does, in order:
|
|
|
44
44
|
4. **Verify** — every skill the server lists is where it was installed, the end-of-turn check is in
|
|
45
45
|
the settings it was written to (Claude Code), the repository's `futuvara` entry reads the
|
|
46
46
|
project's variable, and that variable is set. A `[FAIL]` exits 1 with the exact fix.
|
|
47
|
+
5. **Jean** — when the Jean desktop app is installed, every run (not only installs) makes sure
|
|
48
|
+
`claude:futuvara` (or `codex:` / `cursor:`) is in Jean's default MCP servers: Jean hands each
|
|
49
|
+
session its own server list and ignores `.mcp.json`. `--check` only reports it.
|
|
47
50
|
|
|
48
51
|
**Staying current.** Each install writes the live version to `<skills dir>/.futuvara-version`.
|
|
49
52
|
A re-run reads the live version with one `list_skills` call: when the marker matches and verify
|
package/bin/connect.js
CHANGED
|
@@ -10,7 +10,7 @@ import { join, dirname } from "node:path";
|
|
|
10
10
|
import { fileURLToPath } from "node:url";
|
|
11
11
|
|
|
12
12
|
export const SERVER_NAME = "futuvara";
|
|
13
|
-
const DEFAULT_URL = "https://
|
|
13
|
+
const DEFAULT_URL = "https://app.futuvara.com";
|
|
14
14
|
|
|
15
15
|
/**
|
|
16
16
|
* The environment variable holding one project's key: FUTUVARA_KEY_ + the project name upper-cased, every
|
|
@@ -49,6 +49,9 @@ Python 3 for the project config, gh (warning only), the key. Any [FAIL] exits 1.
|
|
|
49
49
|
a verify step checks what landed and exits 1 with the fix when something is missing.
|
|
50
50
|
Children never read stdin and are time-limited, so it runs unattended (CI, agents, scripts).
|
|
51
51
|
|
|
52
|
+
No futuvara tools in your session? Send each call directly instead — same tools, same arguments:
|
|
53
|
+
npx -y @futuvara/connect@latest call report_progress '{"pack":"BP-050","task":"…"}' --project <Project>
|
|
54
|
+
|
|
52
55
|
claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY_<PROJECT>}); skills in ~/.claude/skills
|
|
53
56
|
cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY_<PROJECT>}); skills in ~/.agents/skills
|
|
54
57
|
codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY_<PROJECT>"); skills in ~/.agents/skills
|
|
@@ -142,9 +145,24 @@ export async function callTool(mcpUrl, key, name, args = {}, fetchImpl = fetch)
|
|
|
142
145
|
if (!res.ok) throw new Error(`Futuvara MCP server answered ${res.status} ${res.statusText} at ${mcpUrl}`);
|
|
143
146
|
const msg = readRpcResponse(res.headers.get("content-type"), await res.text(), id);
|
|
144
147
|
if (msg.error) throw new Error(`Futuvara MCP server error: ${msg.error.message}`);
|
|
148
|
+
// An image (get_image) has no text to print: save it and answer with where it is, so the agent can open it.
|
|
149
|
+
const images = (msg.result?.content ?? []).filter((c) => c.type === "image" && c.data);
|
|
150
|
+
if (images.length && !msg.result?.isError) {
|
|
151
|
+
const dir = join(tmpdir(), "futuvara-images");
|
|
152
|
+
mkdirSync(dir, { recursive: true });
|
|
153
|
+
return images.map((c, i) => {
|
|
154
|
+
const file = join(dir, `${name}-${Date.now()}-${i}.${(c.mimeType ?? "image/png").split("/")[1].replace("jpeg", "jpg")}`);
|
|
155
|
+
writeFileSync(file, Buffer.from(c.data, "base64"));
|
|
156
|
+
return { image: file, mimeType: c.mimeType };
|
|
157
|
+
});
|
|
158
|
+
}
|
|
145
159
|
const text = msg.result?.content?.[0]?.text ?? "";
|
|
146
160
|
if (msg.result?.isError) throw new Error(`Futuvara ${name}: ${text}`);
|
|
147
|
-
|
|
161
|
+
try {
|
|
162
|
+
return JSON.parse(text);
|
|
163
|
+
} catch {
|
|
164
|
+
return text; // a tool that answers in prose (report_progress, ask_question)
|
|
165
|
+
}
|
|
148
166
|
}
|
|
149
167
|
|
|
150
168
|
/** Every skill, every file: `list_skills` (unless already fetched), then `get_skill` for each. */
|
|
@@ -297,6 +315,39 @@ export function removeUserServer(home = homedir()) {
|
|
|
297
315
|
}
|
|
298
316
|
}
|
|
299
317
|
|
|
318
|
+
// Jean (desktop app that runs agent sessions per worktree) hands each session its own MCP server list and
|
|
319
|
+
// ignores the repository's .mcp.json; sessions it starts from an issue get only its default list.
|
|
320
|
+
const JEAN_BACKEND = { "claude-code": "claude", codex: "codex", cursor: "cursor" };
|
|
321
|
+
export const jeanPrefsPaths = (home = homedir(), env = process.env) => [
|
|
322
|
+
join(env.APPDATA ?? join(home, "AppData", "Roaming"), "com.jean.desktop", "preferences.json"),
|
|
323
|
+
join(home, "Library", "Application Support", "com.jean.desktop", "preferences.json"),
|
|
324
|
+
join(env.XDG_DATA_HOME ?? join(home, ".local", "share"), "com.jean.desktop", "preferences.json"),
|
|
325
|
+
join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "com.jean.desktop", "preferences.json"),
|
|
326
|
+
];
|
|
327
|
+
|
|
328
|
+
/**
|
|
329
|
+
* Put "<backend>:futuvara" in Jean's default MCP servers, so every session Jean starts gets the Futuvara tools.
|
|
330
|
+
* @returns {{status: "ok" | "fail", label: string, fix?: string} | null} null when Jean is not installed
|
|
331
|
+
*/
|
|
332
|
+
export function ensureJeanDefault(agent, { write = true, paths = jeanPrefsPaths() } = {}) {
|
|
333
|
+
const backend = JEAN_BACKEND[agent];
|
|
334
|
+
const path = backend && paths.find((p) => existsSync(p));
|
|
335
|
+
if (!path) return null;
|
|
336
|
+
const id = `${backend}:${SERVER_NAME}`;
|
|
337
|
+
let prefs;
|
|
338
|
+
try {
|
|
339
|
+
prefs = JSON.parse(readFileSync(path, "utf8"));
|
|
340
|
+
} catch {
|
|
341
|
+
return { status: "fail", label: `Jean preferences unreadable (${path})`, fix: `add ${id} to Jean > Settings > MCP servers` };
|
|
342
|
+
}
|
|
343
|
+
const lists = ["default_enabled_mcp_servers", "known_mcp_servers"];
|
|
344
|
+
if (lists.every((k) => prefs[k]?.includes(id))) return { status: "ok", label: `Jean starts every session with ${id}` };
|
|
345
|
+
if (!write) return { status: "fail", label: `Jean's default MCP servers lack ${id} — sessions it starts have no Futuvara tools`, fix: "run without --check" };
|
|
346
|
+
for (const k of lists) prefs[k] = [...new Set([...(prefs[k] ?? []), id])];
|
|
347
|
+
writeFileSync(path, JSON.stringify(prefs, null, 2));
|
|
348
|
+
return { status: "ok", label: `Added ${id} to Jean's default MCP servers (${path}) — restart Jean if it is open` };
|
|
349
|
+
}
|
|
350
|
+
|
|
300
351
|
/** The key: the project's variable, else plain FUTUVARA_KEY (backwards compatible). */
|
|
301
352
|
export function readKey(project, env = process.env) {
|
|
302
353
|
const variable = keyVar(project);
|
|
@@ -397,8 +448,37 @@ export function report(title, checks) {
|
|
|
397
448
|
return checks.every((c) => c.status !== "fail");
|
|
398
449
|
}
|
|
399
450
|
|
|
451
|
+
export const CALL_USAGE = `Usage: npx -y @futuvara/connect@latest call <tool> '<JSON arguments>' --project <Project> [--url ${DEFAULT_URL}]`;
|
|
452
|
+
|
|
453
|
+
/**
|
|
454
|
+
* `call <tool> '<json>' --project P`: one Futuvara tool call straight over HTTP, for a session that was started
|
|
455
|
+
* without the futuvara MCP tools (a desktop app that picks its own server list, an unapproved .mcp.json).
|
|
456
|
+
* Prints the tool's answer; exits 1 with the reason when it was not delivered.
|
|
457
|
+
*/
|
|
458
|
+
export async function callMain(argv, env = process.env, fetchImpl = fetch) {
|
|
459
|
+
const { values, positionals } = nodeParseArgs({
|
|
460
|
+
args: argv,
|
|
461
|
+
allowPositionals: true,
|
|
462
|
+
options: { project: { type: "string" }, url: { type: "string", default: DEFAULT_URL } },
|
|
463
|
+
});
|
|
464
|
+
const [tool, json = "{}"] = positionals;
|
|
465
|
+
if (!tool || !values.project) throw new Error(CALL_USAGE);
|
|
466
|
+
let args;
|
|
467
|
+
try {
|
|
468
|
+
args = JSON.parse(json);
|
|
469
|
+
} catch {
|
|
470
|
+
throw new Error(`The arguments are not JSON: ${json}\n${CALL_USAGE}`);
|
|
471
|
+
}
|
|
472
|
+
const { key, from } = readKey(values.project, env);
|
|
473
|
+
if (!from) throw new Error(`${keyVar(values.project)} is not set, so nothing was sent. ${exportLine(keyVar(values.project))}`);
|
|
474
|
+
const answer = await callTool(`${values.url.replace(/\/+$/, "")}/api/connect/mcp`, key, tool, args, fetchImpl);
|
|
475
|
+
console.log(typeof answer === "string" ? answer : JSON.stringify(answer, null, 2));
|
|
476
|
+
return 0;
|
|
477
|
+
}
|
|
478
|
+
|
|
400
479
|
/** @returns {Promise<number>} the exit code */
|
|
401
480
|
export async function main(argv = process.argv.slice(2)) {
|
|
481
|
+
if (argv[0] === "call") return callMain(argv.slice(1));
|
|
402
482
|
let opts;
|
|
403
483
|
try {
|
|
404
484
|
opts = parseArgs(argv);
|
|
@@ -455,6 +535,10 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
455
535
|
checks = [fresh, ...checks];
|
|
456
536
|
}
|
|
457
537
|
|
|
538
|
+
// Every run, not only installs: a machine current on skills can still have Jean without the server.
|
|
539
|
+
const jean = ensureJeanDefault(opts.agent, { write: !opts.check });
|
|
540
|
+
if (jean) checks = [...checks, jean];
|
|
541
|
+
|
|
458
542
|
if (!report("Verify", checks)) {
|
|
459
543
|
console.log("\nNot complete — fix the [FAIL] lines above, then run this again.");
|
|
460
544
|
return 1;
|
package/package.json
CHANGED