@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.
- package/README.md +25 -0
- package/bin/connect.js +191 -0
- 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
|
+
}
|