@futuvara/connect 0.1.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.
Files changed (3) hide show
  1. package/README.md +25 -0
  2. package/bin/connect.js +191 -0
  3. package/package.json +26 -0
package/README.md ADDED
@@ -0,0 +1,25 @@
1
+ # @futuvara/connect
2
+
3
+ Connect a coding agent to one Futuvara project: installs the `futuvara-context` skill and adds the
4
+ Futuvara MCP server to the agent. Run it in the root of the project's repository.
5
+
6
+ ```sh
7
+ export FUTUVARA_KEY=<project key from Futuvara > Coding agent access>
8
+ npx @futuvara/connect --project Luxury-Frontiers-Platform --agent claude-code
9
+ ```
10
+
11
+ | `--agent` | Skill | MCP server |
12
+ | --- | --- | --- |
13
+ | `claude-code` | `npx skills add … -a claude-code` | merges `.mcp.json` with `Authorization: Bearer ${FUTUVARA_KEY}` |
14
+ | `cursor` | `-a cursor` | merges `.cursor/mcp.json` with `Authorization: Bearer ${env:FUTUVARA_KEY}` |
15
+ | `codex` | `-a codex` | prints a `config.toml` snippet using `bearer_token_env_var = "FUTUVARA_KEY"` |
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` |
17
+ | other | `-a <agent>` | prints the server URL and header |
18
+
19
+ The key is never written to a file. `--url` points at another Futuvara host (default
20
+ `https://www.futuvara.com`). Needs Node 20 or later. Tests: `npm test`.
21
+
22
+ **Releasing:** bump `version` in `package.json` and merge to `main`. The
23
+ `publish-connect.yml` workflow tests and publishes it through npm trusted
24
+ publishing — no token. The first version was published by hand, because npm
25
+ cannot trust a publisher for a package that does not exist yet.
package/bin/connect.js ADDED
@@ -0,0 +1,191 @@
1
+ #!/usr/bin/env node
2
+ // @futuvara/connect — give a coding agent the Futuvara skill and MCP server for one project.
3
+ // Zero dependencies: Node >= 20 stdlib only. The key is read from FUTUVARA_KEY and never written to a file.
4
+ import { parseArgs as nodeParseArgs } from "node:util";
5
+ import { spawnSync } from "node:child_process";
6
+ import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, realpathSync } from "node:fs";
7
+ import { tmpdir } from "node:os";
8
+ import { join, dirname } from "node:path";
9
+ import { fileURLToPath } from "node:url";
10
+
11
+ export const SKILL_NAME = "futuvara-context";
12
+ export const SERVER_NAME = "futuvara";
13
+ 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
+
17
+ // Agent ids accepted by `npx skills add -a` — https://github.com/vercel-labs/skills
18
+ const SKILLS_AGENT_ID = { copilot: "github-copilot" };
19
+
20
+ export const HELP = `Usage: npx @futuvara/connect --project <Project> --agent <agent> [--url ${DEFAULT_URL}]
21
+
22
+ Installs the "${SKILL_NAME}" skill (fetched from the Futuvara MCP server) and adds the
23
+ Futuvara MCP server to your coding agent. Run it in the root of the project repository.
24
+
25
+ --project Futuvara project folder name, e.g. Luxury-Frontiers-Platform
26
+ --agent claude-code | cursor | codex | copilot | any agent id "npx skills" knows
27
+ --url Futuvara base URL (default ${DEFAULT_URL})
28
+
29
+ Needs env FUTUVARA_KEY: the project key made in Futuvara > Coding agent access.
30
+ The key is never written to a file; the agent's config reads it from the environment.
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`;
36
+
37
+ /** @param {string[]} argv @returns {{project: string, agent: string, url: string, help: boolean}} */
38
+ export function parseArgs(argv) {
39
+ const { values } = nodeParseArgs({
40
+ args: argv,
41
+ options: {
42
+ project: { type: "string" },
43
+ agent: { type: "string" },
44
+ url: { type: "string", default: DEFAULT_URL },
45
+ help: { type: "boolean", short: "h", default: false },
46
+ },
47
+ });
48
+ if (values.help) return { project: "", agent: "", url: DEFAULT_URL, help: true };
49
+ if (!values.project) throw new Error("--project is required");
50
+ if (!values.agent) throw new Error("--agent is required");
51
+ return { project: values.project, agent: values.agent.toLowerCase(), url: values.url.replace(/\/+$/, ""), help: false };
52
+ }
53
+
54
+ /**
55
+ * Add or replace the Futuvara entry in an agent's `{ "mcpServers": {...} }` JSON file, keeping every other server.
56
+ * @param {string | null} existing current file text, or null when there is no file
57
+ * @param {object} entry
58
+ */
59
+ export function mergeMcpServers(existing, entry) {
60
+ const config = existing?.trim() ? JSON.parse(existing) : {};
61
+ config.mcpServers = { ...config.mcpServers, [SERVER_NAME]: entry };
62
+ return JSON.stringify(config, null, 2) + "\n";
63
+ }
64
+
65
+ // https://code.claude.com/docs/en/mcp — .mcp.json expands ${VAR} in url and headers.
66
+ export const claudeEntry = (mcpUrl) => ({
67
+ type: "http",
68
+ url: mcpUrl,
69
+ headers: { Authorization: "Bearer ${FUTUVARA_KEY}" },
70
+ });
71
+
72
+ // https://cursor.com/docs/context/mcp — ${env:NAME} is resolved in url and headers.
73
+ export const cursorEntry = (mcpUrl) => ({
74
+ url: mcpUrl,
75
+ headers: { Authorization: "Bearer ${env:FUTUVARA_KEY}" },
76
+ });
77
+
78
+ /** Parse a JSON-RPC response from either a JSON body or an SSE stream body. */
79
+ export function readRpcResponse(contentType, text, id) {
80
+ if (!contentType?.includes("text/event-stream")) return JSON.parse(text);
81
+ for (const event of text.split(/\r?\n\r?\n/)) {
82
+ const data = event
83
+ .split(/\r?\n/)
84
+ .filter((l) => l.startsWith("data:"))
85
+ .map((l) => l.slice(5).replace(/^ /, ""))
86
+ .join("\n");
87
+ if (!data) continue;
88
+ const msg = JSON.parse(data);
89
+ if (msg.id === id) return msg;
90
+ }
91
+ throw new Error("The MCP server's event stream closed without a response.");
92
+ }
93
+
94
+ /**
95
+ * The skill text is the MCP server's `instructions` (InitializeResult), so there is no download route.
96
+ * Streamable HTTP: POST with Accept listing both application/json and text/event-stream; the reply may be either.
97
+ * https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
98
+ */
99
+ async function fetchInstructions(mcpUrl, key) {
100
+ const res = await fetch(mcpUrl, {
101
+ method: "POST",
102
+ headers: {
103
+ "Content-Type": "application/json",
104
+ Accept: "application/json, text/event-stream",
105
+ Authorization: `Bearer ${key}`,
106
+ },
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
+ });
114
+ if (res.status === 401 || res.status === 403) throw new Error("Futuvara refused the key (revoked, or for another project?).");
115
+ 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(), 1);
117
+ if (msg.error) throw new Error(`Futuvara MCP server error: ${msg.error.message}`);
118
+ const instructions = msg.result?.instructions;
119
+ if (!instructions) throw new Error("The Futuvara MCP server returned no skill instructions.");
120
+ return instructions;
121
+ }
122
+
123
+ /** Agent Skills SKILL.md (https://agentskills.io/specification): our own name/description frontmatter + the server's body. */
124
+ export function skillMarkdown(instructions, project) {
125
+ const body = instructions.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trimStart();
126
+ return `---\nname: ${SKILL_NAME}\ndescription: ${JSON.stringify(SKILL_DESCRIPTION)}\nmetadata:\n futuvara_project: ${JSON.stringify(project)}\n---\n\n${body}`;
127
+ }
128
+
129
+ function run(cmd, args) {
130
+ // Windows needs a shell to run npx.cmd / claude.cmd; quote args there so paths with spaces survive.
131
+ const win = process.platform === "win32";
132
+ const r = spawnSync(cmd, win ? args.map((a) => `"${a}"`) : args, { stdio: "inherit", shell: win });
133
+ if (r.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed (exit ${r.status ?? r.error?.message}).`);
134
+ }
135
+
136
+ function writeJson(path, entry) {
137
+ mkdirSync(dirname(path), { recursive: true });
138
+ writeFileSync(path, mergeMcpServers(existsSync(path) ? readFileSync(path, "utf8") : null, entry));
139
+ console.log(`Added "${SERVER_NAME}" to ${path} (key read from FUTUVARA_KEY at runtime).`);
140
+ }
141
+
142
+ function configureMcp(agent, mcpUrl) {
143
+ switch (agent) {
144
+ case "claude-code":
145
+ return writeJson(join(process.cwd(), ".mcp.json"), claudeEntry(mcpUrl));
146
+ case "cursor":
147
+ return writeJson(join(process.cwd(), ".cursor", "mcp.json"), cursorEntry(mcpUrl));
148
+ case "codex":
149
+ // https://learn.chatgpt.com/docs/extend/mcp?surface=cli — ~/.codex/config.toml or .codex/config.toml
150
+ return console.log(
151
+ `Add to ~/.codex/config.toml (or .codex/config.toml in a trusted project):\n\n[mcp_servers.${SERVER_NAME}]\nurl = "${mcpUrl}"\nbearer_token_env_var = "FUTUVARA_KEY"\n`,
152
+ );
153
+ case "copilot":
154
+ // https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp
155
+ // Same text as the Coding agent panel (coding-agent-panel.tsx), so both give one answer.
156
+ return console.log(
157
+ `In GitHub: repo Settings > Copilot > MCP servers, paste into MCP configuration:\n\n${JSON.stringify(
158
+ { mcpServers: { [SERVER_NAME]: { type: "http", url: mcpUrl, headers: { Authorization: "Bearer $COPILOT_MCP_FUTUVARA_KEY" }, tools: ["*"] } } },
159
+ null,
160
+ 2,
161
+ )}\n\nThen add the key as an Agents secret named COPILOT_MCP_FUTUVARA_KEY.\n`,
162
+ );
163
+ default:
164
+ return console.log(`Add an HTTP MCP server named "${SERVER_NAME}" at ${mcpUrl} with header Authorization: Bearer $FUTUVARA_KEY.`);
165
+ }
166
+ }
167
+
168
+ export async function main(argv = process.argv.slice(2)) {
169
+ const opts = parseArgs(argv);
170
+ if (opts.help) return console.log(HELP);
171
+ const key = process.env.FUTUVARA_KEY;
172
+ 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
+ const mcpUrl = `${opts.url}/api/connect/mcp`;
174
+
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
+ configureMcp(opts.agent, mcpUrl);
183
+ console.log(`Done. Keep FUTUVARA_KEY set in the environment your agent runs in (project ${opts.project}).`);
184
+ }
185
+
186
+ if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
187
+ main().catch((err) => {
188
+ console.error(`futuvara-connect: ${err.message}\n\n${HELP}`);
189
+ process.exit(1);
190
+ });
191
+ }
package/package.json ADDED
@@ -0,0 +1,26 @@
1
+ {
2
+ "name": "@futuvara/connect",
3
+ "version": "0.1.0",
4
+ "description": "Connect a coding agent to a Futuvara project: installs the futuvara-context skill and the Futuvara MCP server settings.",
5
+ "type": "module",
6
+ "bin": {
7
+ "futuvara-connect": "bin/connect.js"
8
+ },
9
+ "files": [
10
+ "bin/connect.js",
11
+ "README.md"
12
+ ],
13
+ "engines": {
14
+ "node": ">=20"
15
+ },
16
+ "scripts": {
17
+ "test": "node --test"
18
+ },
19
+ "license": "MIT",
20
+ "homepage": "https://www.futuvara.com",
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/Futuvara-Agentic/Futuvara.git",
24
+ "directory": "sdk/connect"
25
+ }
26
+ }