@futuvara/connect 0.1.0 → 0.2.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 +29 -9
- package/bin/connect.js +99 -43
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,23 +1,43 @@
|
|
|
1
1
|
# @futuvara/connect
|
|
2
2
|
|
|
3
|
-
Connect a coding agent to one Futuvara project:
|
|
4
|
-
|
|
3
|
+
Connect a coding agent to one Futuvara project in one step: adds the Futuvara MCP server to the
|
|
4
|
+
agent, installs every Futuvara skill (fetched from that server), and configures the project. Run it
|
|
5
|
+
in the root of the project's repository.
|
|
5
6
|
|
|
6
7
|
```sh
|
|
7
8
|
export FUTUVARA_KEY=<project key from Futuvara > Coding agent access>
|
|
8
9
|
npx @futuvara/connect --project Luxury-Frontiers-Platform --agent claude-code
|
|
9
10
|
```
|
|
10
11
|
|
|
11
|
-
|
|
12
|
+
What it does, in order:
|
|
13
|
+
|
|
14
|
+
1. **MCP server** — per agent, below. The key is never written to a file.
|
|
15
|
+
2. **Skills** — `list_skills`, then `get_skill` for each, over the MCP server (the set lives in
|
|
16
|
+
`sdk/futu-skills/` in the Futuvara repo, published to the knowledge base on each deploy). They are
|
|
17
|
+
written in plugin layout to a fixed temp folder and installed with
|
|
18
|
+
`npx skills add <folder> -s '*' -a <agent> -y --copy`; the shared `lib/` the scripts source goes
|
|
19
|
+
beside them (`.claude/lib` or `.agents/lib`).
|
|
20
|
+
3. **Project config** — `bash <skills>/futu-setup/futu-setup.sh apply`: the `docs/` skeleton, the
|
|
21
|
+
`AGENTS.md` rules block, `.futu/` (ESLint `futu` rules and scanners), `eslint.config.mjs` wiring and
|
|
22
|
+
`.github/workflows/futu.yml`. It writes no plugin marketplace into `.claude/settings.json`. Needs
|
|
23
|
+
bash (Git Bash on Windows) and python3; skipped with a message when bash is missing, or with
|
|
24
|
+
`--no-config`.
|
|
25
|
+
|
|
26
|
+
Re-running changes nothing that is already current; a newer skill set is picked up by re-running.
|
|
27
|
+
|
|
28
|
+
| `--agent` | Skills land in | MCP server |
|
|
12
29
|
| --- | --- | --- |
|
|
13
|
-
| `claude-code` |
|
|
14
|
-
| `cursor` |
|
|
15
|
-
| `codex` |
|
|
16
|
-
| `copilot` | `-a github-copilot` | prints the repo-settings JSON with `Authorization: Bearer $COPILOT_MCP_FUTUVARA_KEY`; add the key as the Agents secret `COPILOT_MCP_FUTUVARA_KEY` |
|
|
30
|
+
| `claude-code` | `.claude/skills` | merges `.mcp.json` with `Authorization: Bearer ${FUTUVARA_KEY}` |
|
|
31
|
+
| `cursor` | `.agents/skills` | merges `.cursor/mcp.json` with `Authorization: Bearer ${env:FUTUVARA_KEY}` |
|
|
32
|
+
| `codex` | `.agents/skills` | prints a `config.toml` snippet using `bearer_token_env_var = "FUTUVARA_KEY"` |
|
|
33
|
+
| `copilot` | `.agents/skills` (`-a github-copilot`) | prints the repo-settings JSON with `Authorization: Bearer $COPILOT_MCP_FUTUVARA_KEY`; add the key as the Agents secret `COPILOT_MCP_FUTUVARA_KEY` |
|
|
17
34
|
| other | `-a <agent>` | prints the server URL and header |
|
|
18
35
|
|
|
19
|
-
|
|
20
|
-
|
|
36
|
+
`--url` points at another Futuvara host (default `https://www.futuvara.com`). Needs Node 20 or
|
|
37
|
+
later. Tests: `npm test`.
|
|
38
|
+
|
|
39
|
+
The old `futuvara-context` skill (0.1.x) is retired in favour of `futu-mcp-context`,
|
|
40
|
+
`futu-mcp-progress` and `futu-mcp-signoff`; remove an old copy with `npx skills remove futuvara-context`.
|
|
21
41
|
|
|
22
42
|
**Releasing:** bump `version` in `package.json` and merge to `main`. The
|
|
23
43
|
`publish-connect.yml` workflow tests and publishes it through npm trusted
|
package/bin/connect.js
CHANGED
|
@@ -1,40 +1,42 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// @futuvara/connect — give a coding agent the Futuvara
|
|
2
|
+
// @futuvara/connect — give a coding agent the Futuvara skills, MCP server and project config for one project.
|
|
3
3
|
// Zero dependencies: Node >= 20 stdlib only. The key is read from FUTUVARA_KEY and never written to a file.
|
|
4
4
|
import { parseArgs as nodeParseArgs } from "node:util";
|
|
5
5
|
import { spawnSync } from "node:child_process";
|
|
6
|
-
import {
|
|
6
|
+
import { mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync, rmSync, chmodSync, readdirSync } from "node:fs";
|
|
7
7
|
import { tmpdir } from "node:os";
|
|
8
8
|
import { join, dirname } from "node:path";
|
|
9
9
|
import { fileURLToPath } from "node:url";
|
|
10
10
|
|
|
11
|
-
export const SKILL_NAME = "futuvara-context";
|
|
12
11
|
export const SERVER_NAME = "futuvara";
|
|
13
12
|
const DEFAULT_URL = "https://www.futuvara.com";
|
|
14
|
-
const SKILL_DESCRIPTION =
|
|
15
|
-
'Work a GitHub issue that says "Futuvara pack: …" using the Futuvara MCP server. Check what the repo already has before coding, pull the build pack, requirements, sources and screens for context, ask instead of guessing, report progress, and close the pack with a build record.';
|
|
16
13
|
|
|
17
14
|
// Agent ids accepted by `npx skills add -a` — https://github.com/vercel-labs/skills
|
|
18
15
|
const SKILLS_AGENT_ID = { copilot: "github-copilot" };
|
|
19
16
|
|
|
20
|
-
export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--url ${DEFAULT_URL}]
|
|
17
|
+
export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--url ${DEFAULT_URL}] [--no-config]
|
|
21
18
|
|
|
22
|
-
|
|
23
|
-
|
|
19
|
+
Adds the Futuvara MCP server to your coding agent, installs every Futuvara skill (fetched from
|
|
20
|
+
that server), then configures the project with futu-setup. Run it in the root of the project repository.
|
|
24
21
|
|
|
25
|
-
--project
|
|
26
|
-
--agent
|
|
27
|
-
--url
|
|
22
|
+
--project Futuvara project folder name, e.g. Luxury-Frontiers-Platform
|
|
23
|
+
--agent claude-code | cursor | codex | copilot | any agent id "npx skills" knows
|
|
24
|
+
--url Futuvara base URL (default ${DEFAULT_URL})
|
|
25
|
+
--no-config install the skills only; skip "futu-setup.sh apply" (ESLint futu rules, .futu/,
|
|
26
|
+
.github/workflows/futu.yml, the AGENTS.md rules block, docs/ skeleton)
|
|
28
27
|
|
|
29
28
|
Needs env FUTUVARA_KEY: the project key made in Futuvara > Coding agent access.
|
|
30
29
|
The key is never written to a file; the agent's config reads it from the environment.
|
|
30
|
+
The project config step needs bash (Git Bash on Windows) and python3; it is skipped without bash.
|
|
31
31
|
|
|
32
|
-
claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY})
|
|
33
|
-
cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY})
|
|
34
|
-
codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY")
|
|
35
|
-
copilot prints the repo-settings JSON and the secret to add
|
|
32
|
+
claude-code merges .mcp.json (Authorization: Bearer \${FUTUVARA_KEY}); skills in .claude/skills
|
|
33
|
+
cursor merges .cursor/mcp.json (Authorization: Bearer \${env:FUTUVARA_KEY}); skills in .agents/skills
|
|
34
|
+
codex prints a config.toml snippet (bearer_token_env_var = "FUTUVARA_KEY"); skills in .agents/skills
|
|
35
|
+
copilot prints the repo-settings JSON and the secret to add; skills in .agents/skills
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
Re-running changes nothing that is already current.`;
|
|
38
|
+
|
|
39
|
+
/** @param {string[]} argv @returns {{project: string, agent: string, url: string, config: boolean, help: boolean}} */
|
|
38
40
|
export function parseArgs(argv) {
|
|
39
41
|
const { values } = nodeParseArgs({
|
|
40
42
|
args: argv,
|
|
@@ -42,13 +44,14 @@ export function parseArgs(argv) {
|
|
|
42
44
|
project: { type: "string" },
|
|
43
45
|
agent: { type: "string" },
|
|
44
46
|
url: { type: "string", default: DEFAULT_URL },
|
|
47
|
+
"no-config": { type: "boolean", default: false },
|
|
45
48
|
help: { type: "boolean", short: "h", default: false },
|
|
46
49
|
},
|
|
47
50
|
});
|
|
48
|
-
if (values.help) return { project: "", agent: "", url: DEFAULT_URL, help: true };
|
|
51
|
+
if (values.help) return { project: "", agent: "", url: DEFAULT_URL, config: true, help: true };
|
|
49
52
|
if (!values.project) throw new Error("--project is required");
|
|
50
53
|
if (!values.agent) throw new Error("--agent is required");
|
|
51
|
-
return { project: values.project, agent: values.agent.toLowerCase(), url: values.url.replace(/\/+$/, ""), help: false };
|
|
54
|
+
return { project: values.project, agent: values.agent.toLowerCase(), url: values.url.replace(/\/+$/, ""), config: !values["no-config"], help: false };
|
|
52
55
|
}
|
|
53
56
|
|
|
54
57
|
/**
|
|
@@ -91,39 +94,73 @@ export function readRpcResponse(contentType, text, id) {
|
|
|
91
94
|
throw new Error("The MCP server's event stream closed without a response.");
|
|
92
95
|
}
|
|
93
96
|
|
|
97
|
+
let rpcId = 0;
|
|
98
|
+
|
|
94
99
|
/**
|
|
95
|
-
*
|
|
96
|
-
*
|
|
100
|
+
* One MCP `tools/call` over Streamable HTTP. The server is stateless, so no `initialize` is needed first.
|
|
101
|
+
* POST with Accept listing both application/json and text/event-stream; the reply may be either.
|
|
97
102
|
* https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
|
|
98
103
|
*/
|
|
99
|
-
async function
|
|
100
|
-
const
|
|
104
|
+
export async function callTool(mcpUrl, key, name, args = {}, fetchImpl = fetch) {
|
|
105
|
+
const id = ++rpcId;
|
|
106
|
+
const res = await fetchImpl(mcpUrl, {
|
|
101
107
|
method: "POST",
|
|
102
108
|
headers: {
|
|
103
109
|
"Content-Type": "application/json",
|
|
104
110
|
Accept: "application/json, text/event-stream",
|
|
105
111
|
Authorization: `Bearer ${key}`,
|
|
106
112
|
},
|
|
107
|
-
body: JSON.stringify({
|
|
108
|
-
jsonrpc: "2.0",
|
|
109
|
-
id: 1,
|
|
110
|
-
method: "initialize",
|
|
111
|
-
params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "@futuvara/connect", version: "0.1.0" } },
|
|
112
|
-
}),
|
|
113
|
+
body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }),
|
|
113
114
|
});
|
|
114
115
|
if (res.status === 401 || res.status === 403) throw new Error("Futuvara refused the key (revoked, or for another project?).");
|
|
115
116
|
if (!res.ok) throw new Error(`Futuvara MCP server answered ${res.status} ${res.statusText} at ${mcpUrl}`);
|
|
116
|
-
const msg = readRpcResponse(res.headers.get("content-type"), await res.text(),
|
|
117
|
+
const msg = readRpcResponse(res.headers.get("content-type"), await res.text(), id);
|
|
117
118
|
if (msg.error) throw new Error(`Futuvara MCP server error: ${msg.error.message}`);
|
|
118
|
-
const
|
|
119
|
-
if (
|
|
120
|
-
return
|
|
119
|
+
const text = msg.result?.content?.[0]?.text ?? "";
|
|
120
|
+
if (msg.result?.isError) throw new Error(`Futuvara ${name}: ${text}`);
|
|
121
|
+
return JSON.parse(text);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** Every skill, every file: `list_skills`, then `get_skill` for each. */
|
|
125
|
+
export async function fetchSkills(mcpUrl, key, fetchImpl = fetch) {
|
|
126
|
+
const list = await callTool(mcpUrl, key, "list_skills", {}, fetchImpl);
|
|
127
|
+
const skills = [];
|
|
128
|
+
for (const s of list) skills.push(await callTool(mcpUrl, key, "get_skill", { name: s.name }, fetchImpl));
|
|
129
|
+
return skills;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** Write a file only when its bytes differ, so a re-run changes nothing. Scripts stay executable. */
|
|
133
|
+
function put(path, data, executable) {
|
|
134
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
135
|
+
if (!existsSync(path) || !readFileSync(path).equals(data)) writeFileSync(path, data);
|
|
136
|
+
if (executable) chmodSync(path, 0o755);
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
const bytes = (f) => Buffer.from(f.content, f.encoding === "base64" ? "base64" : "utf8");
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* The fetched skills in plugin layout (`skills/<name>/…`, `lib/…`, `.claude-plugin/plugin.json`
|
|
143
|
+
* — futu-setup reads the version there). Starts empty, so a skill removed upstream is not reinstalled.
|
|
144
|
+
*/
|
|
145
|
+
export function writePlugin(root, skills) {
|
|
146
|
+
rmSync(root, { recursive: true, force: true });
|
|
147
|
+
for (const s of skills) for (const f of s.files) put(join(root, f.path), bytes(f), f.executable);
|
|
148
|
+
const manifest = { name: "futuvara-skills", version: skills[0]?.version ?? "" };
|
|
149
|
+
put(join(root, ".claude-plugin", "plugin.json"), Buffer.from(JSON.stringify(manifest, null, 2) + "\n"));
|
|
121
150
|
}
|
|
122
151
|
|
|
123
|
-
/**
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
152
|
+
/**
|
|
153
|
+
* Where `npx skills` puts a project's skills: `.claude/skills` for Claude Code, `.agents/skills` (the
|
|
154
|
+
* shared location) for the others. The shared `lib/` goes beside it — scripts source `../../lib/portable.sh`.
|
|
155
|
+
*/
|
|
156
|
+
export const agentBase = (agent) => (agent === "claude-code" ? ".claude" : ".agents");
|
|
157
|
+
|
|
158
|
+
/** Copy the fetched `lib/` next to the installed skills. */
|
|
159
|
+
export function installLib(root, base) {
|
|
160
|
+
const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(dir, e.name)) : [join(dir, e.name)]));
|
|
161
|
+
const lib = join(root, "lib");
|
|
162
|
+
if (!existsSync(lib)) return;
|
|
163
|
+
for (const src of walk(lib)) put(join(base, "lib", src.slice(lib.length + 1)), readFileSync(src), src.endsWith(".sh"));
|
|
127
164
|
}
|
|
128
165
|
|
|
129
166
|
function run(cmd, args) {
|
|
@@ -172,17 +209,36 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
172
209
|
if (!key) throw new Error("FUTUVARA_KEY is not set. Make a project key in Futuvara > Coding agent access, then: export FUTUVARA_KEY=<key>");
|
|
173
210
|
const mcpUrl = `${opts.url}/api/connect/mcp`;
|
|
174
211
|
|
|
175
|
-
const skill = skillMarkdown(await fetchInstructions(mcpUrl, key), opts.project);
|
|
176
|
-
const dir = join(mkdtempSync(join(tmpdir(), "futuvara-")), SKILL_NAME); // dir name must equal the skill name
|
|
177
|
-
mkdirSync(dir);
|
|
178
|
-
writeFileSync(join(dir, "SKILL.md"), skill);
|
|
179
|
-
// https://github.com/vercel-labs/skills — local path, -a <agent>, -y non-interactive, project scope by default.
|
|
180
|
-
run("npx", ["-y", "skills", "add", dir, "-a", SKILLS_AGENT_ID[opts.agent] ?? opts.agent, "-y"]);
|
|
181
|
-
|
|
182
212
|
configureMcp(opts.agent, mcpUrl);
|
|
213
|
+
|
|
214
|
+
const skills = await fetchSkills(mcpUrl, key);
|
|
215
|
+
// A fixed folder, not a fresh temp one: npx skills records it in skills-lock.json, so a re-run leaves the lock unchanged.
|
|
216
|
+
const root = join(tmpdir(), "futuvara-connect", "plugin");
|
|
217
|
+
writePlugin(root, skills);
|
|
218
|
+
// https://github.com/vercel-labs/skills — every skill in the folder (-s '*'), copied, project scope, no prompts.
|
|
219
|
+
run("npx", ["-y", "skills", "add", root, "-s", "*", "-a", SKILLS_AGENT_ID[opts.agent] ?? opts.agent, "-y", "--copy"]);
|
|
220
|
+
const base = agentBase(opts.agent);
|
|
221
|
+
installLib(root, base);
|
|
222
|
+
console.log(`Installed ${skills.length} Futuvara skills (v${skills[0]?.version ?? "?"}) into ${base}/skills.`);
|
|
223
|
+
|
|
224
|
+
if (!opts.config) console.log("Project config skipped (--no-config).");
|
|
225
|
+
else applyConfig(base, root);
|
|
183
226
|
console.log(`Done. Keep FUTUVARA_KEY set in the environment your agent runs in (project ${opts.project}).`);
|
|
184
227
|
}
|
|
185
228
|
|
|
229
|
+
/** `futu-setup.sh apply` from the installed copy: ESLint futu rules, .futu/, the CI job, the AGENTS.md block. Idempotent. */
|
|
230
|
+
function applyConfig(base, root) {
|
|
231
|
+
if (spawnSync("bash", ["--version"], { stdio: "ignore" }).status !== 0) {
|
|
232
|
+
return console.log("Project config skipped: bash not found (on Windows, run from Git Bash). Re-run, or run futu-setup.sh apply later.");
|
|
233
|
+
}
|
|
234
|
+
const r = spawnSync("bash", [`${base}/skills/futu-setup/futu-setup.sh`, "apply"], {
|
|
235
|
+
stdio: "inherit",
|
|
236
|
+
env: { ...process.env, FUTU_PLUGIN_DIR: root, FUTU_SKILLS_FROM_CONNECT: "1" },
|
|
237
|
+
});
|
|
238
|
+
// futu-setup exits 1 for work it leaves to you (stray docs, a TODO line) — reported above, not a failed install.
|
|
239
|
+
if (r.status === 2 || r.status === null) throw new Error(`futu-setup.sh apply failed (exit ${r.status ?? r.error?.message}).`);
|
|
240
|
+
}
|
|
241
|
+
|
|
186
242
|
if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
|
|
187
243
|
main().catch((err) => {
|
|
188
244
|
console.error(`futuvara-connect: ${err.message}\n\n${HELP}`);
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@futuvara/connect",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Connect a coding agent to a Futuvara project:
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Connect a coding agent to a Futuvara project: adds the Futuvara MCP server, installs every Futuvara skill and applies the project config.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"futuvara-connect": "bin/connect.js"
|