@xevy/skills 0.1.24 → 0.1.28
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/.claude-plugin/plugin.json +2 -2
- package/README.md +23 -11
- package/bin/cli.mjs +145 -10
- package/bin/xevy-mcp-bridge.mjs +346 -0
- package/package.json +2 -2
- package/skills/analyze/SKILL.md +53 -15
- package/skills/execute/SKILL.md +59 -19
- package/skills/fix/SKILL.md +47 -15
- package/skills/generate-image/SKILL.md +46 -22
- package/skills/investigate/SKILL.md +1 -1
- package/skills/merge/SKILL.md +45 -13
- package/skills/move-to-qa/SKILL.md +45 -11
- package/skills/plan/SKILL.md +53 -14
- package/skills/xevy-setup/SKILL.md +5 -4
- package/skills/analyze-here/SKILL.md +0 -30
- package/skills/execute-here/SKILL.md +0 -36
- package/skills/fix-here/SKILL.md +0 -23
- package/skills/merge-here/SKILL.md +0 -22
- package/skills/move-to-qa-here/SKILL.md +0 -21
- package/skills/plan-here/SKILL.md +0 -26
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "xevy",
|
|
3
3
|
"displayName": "Xevy",
|
|
4
|
-
"description": "Native /xevy:* SDLC workflow commands driven through the Xevy MCP server.
|
|
5
|
-
"version": "0.1.
|
|
4
|
+
"description": "Native /xevy:* SDLC workflow commands driven through the Xevy MCP server. Work runs locally by default; pass --cloud to use the server Web Agent. The coding agent reviews and corrects the result after every action.",
|
|
5
|
+
"version": "0.1.28",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Xevy"
|
|
8
8
|
},
|
package/README.md
CHANGED
|
@@ -5,7 +5,8 @@ Install **Xevy SDLC agent skills** and the **Xevy MCP server** for Cursor, Claud
|
|
|
5
5
|
This package wraps:
|
|
6
6
|
|
|
7
7
|
- [`npx skills`](https://github.com/vercel-labs/skills) — copies skills into `.cursor/skills/`, `.claude/skills/`, etc.
|
|
8
|
-
- [`npx add-mcp`](https://github.com/neondatabase/add-mcp) — writes
|
|
8
|
+
- [`npx add-mcp`](https://github.com/neondatabase/add-mcp) — writes remote OAuth MCP configs for Cursor, Claude Code, and other clients
|
|
9
|
+
- `codex mcp add` — registers the bundled local API-key bridge for Codex
|
|
9
10
|
|
|
10
11
|
The skill files under [`skills/`](skills/) are the source of truth — edit them there directly.
|
|
11
12
|
|
|
@@ -47,8 +48,9 @@ XEVY_BASE=https://your-xevy-host.example.com npx @xevy/skills -y
|
|
|
47
48
|
|
|
48
49
|
Then:
|
|
49
50
|
|
|
50
|
-
1. **
|
|
51
|
-
- **Codex:**
|
|
51
|
+
1. **Authentication**:
|
|
52
|
+
- **Codex:** the installer configures a local stdio bridge that reads the API key
|
|
53
|
+
stored by `xevy setup`; restart Codex or start a new session. No OAuth login is needed.
|
|
52
54
|
- **Claude Code:** run `/mcp`, select `xevy`, and complete authentication.
|
|
53
55
|
- **Cursor:** Settings → MCP → `xevy` → Connect.
|
|
54
56
|
- **Other clients:** use the client's MCP connect/OAuth action for `xevy`.
|
|
@@ -88,28 +90,38 @@ npx skills add ./node_modules/@xevy/skills -y
|
|
|
88
90
|
|
|
89
91
|
### Install MCP manually
|
|
90
92
|
|
|
93
|
+
For remote OAuth clients:
|
|
94
|
+
|
|
91
95
|
```bash
|
|
92
|
-
npx add-mcp https://xevy.ai/mcp -n xevy -a cursor -a claude-code -
|
|
96
|
+
npx add-mcp https://xevy.ai/mcp -n xevy -a cursor -a claude-code -y
|
|
93
97
|
```
|
|
94
98
|
|
|
99
|
+
For Codex, use `xevy setup --component credentials --component mcp --agent codex`.
|
|
100
|
+
This installs the bundled local bridge at a stable user path and registers it
|
|
101
|
+
with `codex mcp add`.
|
|
102
|
+
|
|
95
103
|
## Included skills
|
|
96
104
|
|
|
97
105
|
| Skill | Purpose |
|
|
98
106
|
|-------|---------|
|
|
99
107
|
| `setup` | Link repo, `.xevy/project.json`, deploy defaults, env sync |
|
|
100
|
-
| `analyze
|
|
101
|
-
| `plan
|
|
102
|
-
| `execute
|
|
103
|
-
| `fix
|
|
104
|
-
| `merge
|
|
105
|
-
| `move-to-qa
|
|
108
|
+
| `analyze [task] [--cloud]` | Task analysis (local by default) |
|
|
109
|
+
| `plan [task] [--cloud]` | Planning + review (local by default) |
|
|
110
|
+
| `execute [task] [--cloud]` | Build, verify, and open a PR (local by default) |
|
|
111
|
+
| `fix [task] [--cloud]` | Rework after review (local by default) |
|
|
112
|
+
| `merge [task] [--cloud]` | Merge locally by default; `--cloud` lands the remote branch |
|
|
113
|
+
| `move-to-qa [task] [--cloud]` | QA handoff (local by default) |
|
|
106
114
|
| `deploy` | Coolify preview/main |
|
|
107
115
|
| `investigate` | Diagnose with ephemeral scripts (.env; no secrets) |
|
|
108
116
|
| `create-xevy-task` | Capture session work into a task |
|
|
109
117
|
|
|
118
|
+
The six SDLC workflow skills run in the current coding-agent session by default. Add the exact `--cloud` flag before or after the task code to delegate that workflow to Xevy's server agent, for example `execute VI22-01 --cloud`.
|
|
119
|
+
|
|
110
120
|
## Security
|
|
111
121
|
|
|
112
|
-
- **MCP** uses
|
|
122
|
+
- **Codex MCP** uses a local bridge and the mode-`600` API key stored by
|
|
123
|
+
`xevy setup`; the key is never placed in MCP arguments, URLs, or output.
|
|
124
|
+
- **Remote MCP clients** use OAuth — no API key in the MCP URL.
|
|
113
125
|
- **REST helpers** (`sync-env`, `link-repo`) read `~/.config/xevy/credentials` or `XEVY_API_KEY`.
|
|
114
126
|
- Env values are never printed; sync-env only reports key names.
|
|
115
127
|
|
package/bin/cli.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
|
-
* @xevy/skills — install Xevy skills
|
|
3
|
+
* @xevy/skills — install Xevy skills and per-agent MCP transports.
|
|
4
4
|
*
|
|
5
5
|
* Usage:
|
|
6
6
|
* npx @xevy/skills # install skills + MCP (default)
|
|
@@ -10,6 +10,8 @@
|
|
|
10
10
|
* npx @xevy/skills mcp # MCP only
|
|
11
11
|
*/
|
|
12
12
|
import { spawnSync } from "node:child_process";
|
|
13
|
+
import fs from "node:fs";
|
|
14
|
+
import os from "node:os";
|
|
13
15
|
import path from "node:path";
|
|
14
16
|
import { fileURLToPath } from "node:url";
|
|
15
17
|
import {
|
|
@@ -27,6 +29,14 @@ const pkgRoot = path.resolve(here, "..");
|
|
|
27
29
|
|
|
28
30
|
const DEFAULT_BASE = "https://xevy.ai";
|
|
29
31
|
const DEFAULT_AGENTS = ["cursor", "claude-code", "codex"];
|
|
32
|
+
const RETIRED_SKILLS = [
|
|
33
|
+
"analyze-here",
|
|
34
|
+
"plan-here",
|
|
35
|
+
"execute-here",
|
|
36
|
+
"fix-here",
|
|
37
|
+
"merge-here",
|
|
38
|
+
"move-to-qa-here",
|
|
39
|
+
];
|
|
30
40
|
|
|
31
41
|
function usage() {
|
|
32
42
|
console.log(`Xevy skills + MCP installer
|
|
@@ -154,6 +164,7 @@ function parseArgv(argv) {
|
|
|
154
164
|
|
|
155
165
|
if (opts.agents.length === 0) opts.agents = [...DEFAULT_AGENTS];
|
|
156
166
|
opts.agents = [...new Set(opts.agents)];
|
|
167
|
+
validateBaseUrl(opts.base);
|
|
157
168
|
return opts;
|
|
158
169
|
}
|
|
159
170
|
|
|
@@ -162,6 +173,19 @@ function die(msg) {
|
|
|
162
173
|
process.exit(1);
|
|
163
174
|
}
|
|
164
175
|
|
|
176
|
+
function validateBaseUrl(base) {
|
|
177
|
+
let parsed;
|
|
178
|
+
try {
|
|
179
|
+
parsed = new URL(base);
|
|
180
|
+
} catch {
|
|
181
|
+
die(`Invalid Xevy base URL: ${base}`);
|
|
182
|
+
}
|
|
183
|
+
const local = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
|
|
184
|
+
if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
|
|
185
|
+
die("The Xevy base URL must use HTTPS (HTTP is allowed only for localhost).");
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
|
|
165
189
|
const isWindows = process.platform === "win32";
|
|
166
190
|
|
|
167
191
|
function quoteArg(a) {
|
|
@@ -171,7 +195,8 @@ function quoteArg(a) {
|
|
|
171
195
|
function run(cmd, args, { label } = {}) {
|
|
172
196
|
const title = label || [cmd, ...args].join(" ");
|
|
173
197
|
console.log(`→ ${title}`);
|
|
174
|
-
const command =
|
|
198
|
+
const command =
|
|
199
|
+
isWindows && (cmd === "npx" || cmd === "codex") ? `${cmd}.cmd` : cmd;
|
|
175
200
|
const finalArgs = isWindows ? args.map(quoteArg) : args;
|
|
176
201
|
const r = spawnSync(command, finalArgs, { stdio: "inherit", shell: isWindows, env: process.env });
|
|
177
202
|
if (r.error) die(r.error.message);
|
|
@@ -179,6 +204,17 @@ function run(cmd, args, { label } = {}) {
|
|
|
179
204
|
return r;
|
|
180
205
|
}
|
|
181
206
|
|
|
207
|
+
function runOptional(cmd, args) {
|
|
208
|
+
const command =
|
|
209
|
+
isWindows && (cmd === "npx" || cmd === "codex") ? `${cmd}.cmd` : cmd;
|
|
210
|
+
const finalArgs = isWindows ? args.map(quoteArg) : args;
|
|
211
|
+
return spawnSync(command, finalArgs, {
|
|
212
|
+
stdio: "ignore",
|
|
213
|
+
shell: isWindows,
|
|
214
|
+
env: process.env,
|
|
215
|
+
});
|
|
216
|
+
}
|
|
217
|
+
|
|
182
218
|
function installSkills(opts, skillsRoot = pkgRoot) {
|
|
183
219
|
const skillArgs = ["--yes", "skills", "add", skillsRoot];
|
|
184
220
|
if (opts.global) skillArgs.push("-g");
|
|
@@ -193,13 +229,105 @@ function installSkills(opts, skillsRoot = pkgRoot) {
|
|
|
193
229
|
run("npx", skillArgs, { label: "npx skills add (Xevy skills)" });
|
|
194
230
|
}
|
|
195
231
|
|
|
232
|
+
function readSkillsLock(opts) {
|
|
233
|
+
const lockPath = opts.global
|
|
234
|
+
? path.join(
|
|
235
|
+
process.env.XDG_STATE_HOME || path.join(os.homedir(), ".agents"),
|
|
236
|
+
...(process.env.XDG_STATE_HOME ? ["skills", ".skill-lock.json"] : [".skill-lock.json"]),
|
|
237
|
+
)
|
|
238
|
+
: path.join(process.cwd(), "skills-lock.json");
|
|
239
|
+
try {
|
|
240
|
+
return JSON.parse(fs.readFileSync(lockPath, "utf-8"));
|
|
241
|
+
} catch {
|
|
242
|
+
return { skills: {} };
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
function isXevySkillSource(source) {
|
|
247
|
+
const normalized = String(source || "").replaceAll("\\", "/").toLowerCase();
|
|
248
|
+
return (
|
|
249
|
+
normalized.includes("@xevy/skills") ||
|
|
250
|
+
normalized.includes("@innotech-ai/skills") ||
|
|
251
|
+
normalized.includes("vytedev/xevy.ai") ||
|
|
252
|
+
normalized.includes("/src/packages/xevy-skills")
|
|
253
|
+
);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function removeRetiredSkills(opts) {
|
|
257
|
+
const lock = readSkillsLock(opts);
|
|
258
|
+
const retired = RETIRED_SKILLS.filter((name) =>
|
|
259
|
+
isXevySkillSource(lock?.skills?.[name]?.source),
|
|
260
|
+
);
|
|
261
|
+
if (retired.length === 0) return;
|
|
262
|
+
|
|
263
|
+
const removeArgs = ["--yes", "skills", "remove", ...retired];
|
|
264
|
+
if (opts.global) removeArgs.push("-g");
|
|
265
|
+
removeArgs.push("-y");
|
|
266
|
+
run("npx", removeArgs, { label: "npx skills remove (retired Xevy aliases)" });
|
|
267
|
+
}
|
|
268
|
+
|
|
196
269
|
function installMcp(opts) {
|
|
197
270
|
const mcpUrl = `${opts.base}/mcp`;
|
|
198
|
-
const
|
|
199
|
-
|
|
200
|
-
if (
|
|
201
|
-
|
|
202
|
-
|
|
271
|
+
const remoteAgents = opts.agents.filter((agent) => agent !== "codex");
|
|
272
|
+
|
|
273
|
+
if (remoteAgents.length > 0) {
|
|
274
|
+
const mcpArgs = ["--yes", "add-mcp", mcpUrl, "-n", "xevy"];
|
|
275
|
+
if (opts.global) mcpArgs.push("-g");
|
|
276
|
+
if (opts.yes) mcpArgs.push("-y");
|
|
277
|
+
for (const agent of remoteAgents) mcpArgs.push("-a", agent);
|
|
278
|
+
run("npx", mcpArgs, { label: `npx add-mcp ${mcpUrl}` });
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
if (opts.agents.includes("codex")) {
|
|
282
|
+
installCodexMcp(opts);
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
function installBridge() {
|
|
287
|
+
const configRoot =
|
|
288
|
+
process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
|
|
289
|
+
const bridgeDir = path.join(configRoot, "xevy", "bin");
|
|
290
|
+
const source = path.join(pkgRoot, "bin", "xevy-mcp-bridge.mjs");
|
|
291
|
+
const destination = path.join(bridgeDir, "xevy-mcp-bridge.mjs");
|
|
292
|
+
const temporary = path.join(
|
|
293
|
+
bridgeDir,
|
|
294
|
+
`.xevy-mcp-bridge.${process.pid}.${Date.now()}.tmp`,
|
|
295
|
+
);
|
|
296
|
+
|
|
297
|
+
fs.mkdirSync(bridgeDir, { recursive: true });
|
|
298
|
+
try {
|
|
299
|
+
fs.copyFileSync(source, temporary);
|
|
300
|
+
fs.chmodSync(temporary, 0o700);
|
|
301
|
+
fs.renameSync(temporary, destination);
|
|
302
|
+
} finally {
|
|
303
|
+
try {
|
|
304
|
+
fs.unlinkSync(temporary);
|
|
305
|
+
} catch {
|
|
306
|
+
// The rename normally removes the temporary path.
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
return destination;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
function installCodexMcp(opts) {
|
|
313
|
+
const bridge = installBridge();
|
|
314
|
+
// `mcp add` rejects duplicate names. Remove an old OAuth URL or bridge
|
|
315
|
+
// definition first, then atomically add the current stable bridge command.
|
|
316
|
+
runOptional("codex", ["mcp", "remove", "xevy"]);
|
|
317
|
+
run(
|
|
318
|
+
"codex",
|
|
319
|
+
[
|
|
320
|
+
"mcp",
|
|
321
|
+
"add",
|
|
322
|
+
"xevy",
|
|
323
|
+
"--",
|
|
324
|
+
process.execPath,
|
|
325
|
+
bridge,
|
|
326
|
+
"--base",
|
|
327
|
+
opts.base,
|
|
328
|
+
],
|
|
329
|
+
{ label: "codex mcp add xevy (local API-key bridge)" },
|
|
330
|
+
);
|
|
203
331
|
}
|
|
204
332
|
|
|
205
333
|
function recordInstallStamp(opts, version) {
|
|
@@ -220,10 +348,14 @@ function missingAgents(installedAgents, requestedAgents) {
|
|
|
220
348
|
}
|
|
221
349
|
|
|
222
350
|
function printOAuthInstructions(opts) {
|
|
223
|
-
console.log(" • Authorize Xevy in each installed MCP client before using its tools:");
|
|
224
351
|
if (opts.agents.includes("codex")) {
|
|
225
|
-
console.log(
|
|
352
|
+
console.log(
|
|
353
|
+
" • Codex uses the local Xevy bridge and your stored API key; restart Codex or start a new session.",
|
|
354
|
+
);
|
|
226
355
|
}
|
|
356
|
+
const oauthAgents = opts.agents.filter((agent) => agent !== "codex");
|
|
357
|
+
if (oauthAgents.length === 0) return;
|
|
358
|
+
console.log(" • Authorize Xevy in each remote MCP client before using its tools:");
|
|
227
359
|
if (opts.agents.includes("claude-code")) {
|
|
228
360
|
console.log(" Claude Code: run `/mcp`, select `xevy`, and complete authentication.");
|
|
229
361
|
}
|
|
@@ -231,7 +363,7 @@ function printOAuthInstructions(opts) {
|
|
|
231
363
|
console.log(" Cursor: open Settings → MCP → `xevy` and choose Connect.");
|
|
232
364
|
}
|
|
233
365
|
const otherAgents = opts.agents.filter(
|
|
234
|
-
(agent) => !DEFAULT_AGENTS.includes(agent),
|
|
366
|
+
(agent) => agent !== "codex" && !DEFAULT_AGENTS.includes(agent),
|
|
235
367
|
);
|
|
236
368
|
if (otherAgents.length > 0) {
|
|
237
369
|
console.log(
|
|
@@ -339,6 +471,7 @@ async function runCheck(opts) {
|
|
|
339
471
|
|
|
340
472
|
async function runUpdate(opts) {
|
|
341
473
|
await maybeReexecLatestCli(opts);
|
|
474
|
+
removeRetiredSkills(opts);
|
|
342
475
|
|
|
343
476
|
const stamp = readInstalledStamp(process.cwd(), { global: opts.global });
|
|
344
477
|
const { latest } = await resolveLatestVersion(opts);
|
|
@@ -410,6 +543,7 @@ async function main() {
|
|
|
410
543
|
}
|
|
411
544
|
|
|
412
545
|
if (opts.command === "skills") {
|
|
546
|
+
removeRetiredSkills(opts);
|
|
413
547
|
installSkills(opts);
|
|
414
548
|
recordInstallStamp(opts, readPackageVersion());
|
|
415
549
|
}
|
|
@@ -419,6 +553,7 @@ async function main() {
|
|
|
419
553
|
}
|
|
420
554
|
|
|
421
555
|
if (opts.command === "install") {
|
|
556
|
+
removeRetiredSkills(opts);
|
|
422
557
|
installSkills(opts);
|
|
423
558
|
installMcp(opts);
|
|
424
559
|
// Record coverage only after both installers succeed. A failed MCP write
|
|
@@ -0,0 +1,346 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Local stdio → Streamable HTTP bridge for Codex.
|
|
4
|
+
*
|
|
5
|
+
* Codex owns only the local stdio transport. The bridge reads the existing
|
|
6
|
+
* Xevy API key from ~/.config/xevy/credentials and authenticates upstream
|
|
7
|
+
* requests itself, avoiding Codex's cross-process OAuth refresh-token cache.
|
|
8
|
+
*
|
|
9
|
+
* stdout is reserved for newline-delimited JSON-RPC messages. Diagnostics go
|
|
10
|
+
* to stderr and never include credentials or upstream response bodies.
|
|
11
|
+
*/
|
|
12
|
+
import fs from "node:fs";
|
|
13
|
+
import os from "node:os";
|
|
14
|
+
import path from "node:path";
|
|
15
|
+
import readline from "node:readline";
|
|
16
|
+
|
|
17
|
+
const DEFAULT_BASE = "https://xevy.ai";
|
|
18
|
+
const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
|
|
19
|
+
const API_KEY_PREFIX = "xevy_pk_";
|
|
20
|
+
const REQUEST_TIMEOUT_MS = 300_000;
|
|
21
|
+
|
|
22
|
+
function fail(message) {
|
|
23
|
+
process.stderr.write(`xevy-mcp: ${message}\n`);
|
|
24
|
+
process.exit(1);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function parseArgs(argv) {
|
|
28
|
+
let base = null;
|
|
29
|
+
for (let index = 0; index < argv.length; index += 1) {
|
|
30
|
+
const arg = argv[index];
|
|
31
|
+
if (arg === "--base") {
|
|
32
|
+
const value = argv[index + 1];
|
|
33
|
+
if (!value) fail("Missing value for --base");
|
|
34
|
+
base = value;
|
|
35
|
+
index += 1;
|
|
36
|
+
continue;
|
|
37
|
+
}
|
|
38
|
+
if (arg === "-h" || arg === "--help") {
|
|
39
|
+
process.stderr.write(
|
|
40
|
+
"Usage: node xevy-mcp-bridge.mjs [--base https://xevy.ai]\n",
|
|
41
|
+
);
|
|
42
|
+
process.exit(0);
|
|
43
|
+
}
|
|
44
|
+
fail(`Unknown option: ${arg}`);
|
|
45
|
+
}
|
|
46
|
+
return { base };
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function credentialsPath() {
|
|
50
|
+
const configRoot =
|
|
51
|
+
process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
|
|
52
|
+
return path.join(configRoot, "xevy", "credentials");
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function readCredentials(baseOverride) {
|
|
56
|
+
const file = credentialsPath();
|
|
57
|
+
let source;
|
|
58
|
+
try {
|
|
59
|
+
source = fs.readFileSync(file, "utf-8");
|
|
60
|
+
} catch {
|
|
61
|
+
fail(
|
|
62
|
+
`Xevy credentials not found at ${file}. Run \`xevy setup --component credentials\`.`,
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
let token = "";
|
|
67
|
+
let storedBase = "";
|
|
68
|
+
for (const line of source.split(/\r?\n/)) {
|
|
69
|
+
const trimmed = line.trim();
|
|
70
|
+
if (trimmed.startsWith("token=")) {
|
|
71
|
+
token = trimmed.slice("token=".length).trim();
|
|
72
|
+
} else if (trimmed.startsWith("baseUrl=")) {
|
|
73
|
+
storedBase = trimmed.slice("baseUrl=".length).trim();
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
if (!token.startsWith(API_KEY_PREFIX)) {
|
|
78
|
+
fail(
|
|
79
|
+
`A Xevy API key is required in ${file}. Run \`xevy setup --component credentials\`.`,
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const base = String(
|
|
84
|
+
baseOverride || storedBase || process.env.XEVY_BASE || DEFAULT_BASE,
|
|
85
|
+
).replace(/\/+$/, "");
|
|
86
|
+
let parsed;
|
|
87
|
+
try {
|
|
88
|
+
parsed = new URL(base);
|
|
89
|
+
} catch {
|
|
90
|
+
fail("The configured Xevy base URL is invalid");
|
|
91
|
+
}
|
|
92
|
+
const local = ["localhost", "127.0.0.1", "::1"].includes(parsed.hostname);
|
|
93
|
+
if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
|
|
94
|
+
fail("The Xevy base URL must use HTTPS (HTTP is allowed only for localhost)");
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
return { base, token };
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function parseJsonRpcMessages(text, contentType) {
|
|
101
|
+
const trimmed = text.trim();
|
|
102
|
+
if (!trimmed) return [];
|
|
103
|
+
|
|
104
|
+
if (contentType.toLowerCase().includes("text/event-stream")) {
|
|
105
|
+
const messages = [];
|
|
106
|
+
for (const line of trimmed.split(/\r?\n/)) {
|
|
107
|
+
if (!line.startsWith("data:")) continue;
|
|
108
|
+
const data = line.slice("data:".length).trim();
|
|
109
|
+
if (!data || data === "[DONE]") continue;
|
|
110
|
+
try {
|
|
111
|
+
const parsed = JSON.parse(data);
|
|
112
|
+
if (Array.isArray(parsed)) messages.push(...parsed);
|
|
113
|
+
else messages.push(parsed);
|
|
114
|
+
} catch {
|
|
115
|
+
// Ignore non-JSON SSE keepalives or event metadata.
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return messages;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
try {
|
|
122
|
+
const parsed = JSON.parse(trimmed);
|
|
123
|
+
return Array.isArray(parsed) ? parsed : [parsed];
|
|
124
|
+
} catch {
|
|
125
|
+
return [];
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function writeMessage(message) {
|
|
130
|
+
process.stdout.write(`${JSON.stringify(message)}\n`);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function requestId(message) {
|
|
134
|
+
if (!message || typeof message !== "object") return undefined;
|
|
135
|
+
return Object.hasOwn(message, "id") ? message.id : undefined;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const opts = parseArgs(process.argv.slice(2));
|
|
139
|
+
const credentials = readCredentials(opts.base);
|
|
140
|
+
const endpoint = new URL("/mcp", `${credentials.base}/`).toString();
|
|
141
|
+
|
|
142
|
+
let sessionId = null;
|
|
143
|
+
let protocolVersion = DEFAULT_PROTOCOL_VERSION;
|
|
144
|
+
let initializeMessage = null;
|
|
145
|
+
let initialized = false;
|
|
146
|
+
let recovering = null;
|
|
147
|
+
|
|
148
|
+
function headers() {
|
|
149
|
+
const result = {
|
|
150
|
+
Authorization: `Bearer ${credentials.token}`,
|
|
151
|
+
Accept: "application/json, text/event-stream",
|
|
152
|
+
"Content-Type": "application/json",
|
|
153
|
+
"MCP-Protocol-Version": protocolVersion,
|
|
154
|
+
};
|
|
155
|
+
if (sessionId) result["Mcp-Session-Id"] = sessionId;
|
|
156
|
+
return result;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function syntheticError(message, status, detail) {
|
|
160
|
+
const id = requestId(message);
|
|
161
|
+
if (id === undefined) return null;
|
|
162
|
+
return {
|
|
163
|
+
jsonrpc: "2.0",
|
|
164
|
+
id,
|
|
165
|
+
error: {
|
|
166
|
+
code: status === 401 ? -32001 : -32000,
|
|
167
|
+
message:
|
|
168
|
+
status === 401
|
|
169
|
+
? "Xevy authentication failed. Run `xevy setup --component credentials`."
|
|
170
|
+
: detail,
|
|
171
|
+
},
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
async function recoverSession() {
|
|
176
|
+
if (recovering) return recovering;
|
|
177
|
+
if (!initializeMessage) {
|
|
178
|
+
throw new Error("upstream MCP session expired before initialization");
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
recovering = (async () => {
|
|
182
|
+
sessionId = null;
|
|
183
|
+
const init = await postUpstream(initializeMessage, {
|
|
184
|
+
forward: false,
|
|
185
|
+
allowRecovery: false,
|
|
186
|
+
});
|
|
187
|
+
if (!init.ok) throw new Error("upstream MCP reinitialization failed");
|
|
188
|
+
|
|
189
|
+
if (initialized) {
|
|
190
|
+
const notification = {
|
|
191
|
+
jsonrpc: "2.0",
|
|
192
|
+
method: "notifications/initialized",
|
|
193
|
+
};
|
|
194
|
+
const ready = await postUpstream(notification, {
|
|
195
|
+
forward: false,
|
|
196
|
+
allowRecovery: false,
|
|
197
|
+
});
|
|
198
|
+
if (!ready.ok) {
|
|
199
|
+
throw new Error("upstream MCP initialization notification failed");
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
})().finally(() => {
|
|
203
|
+
recovering = null;
|
|
204
|
+
});
|
|
205
|
+
|
|
206
|
+
return recovering;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
async function postUpstream(
|
|
210
|
+
message,
|
|
211
|
+
{ forward = true, allowRecovery = true } = {},
|
|
212
|
+
) {
|
|
213
|
+
let response;
|
|
214
|
+
try {
|
|
215
|
+
response = await fetch(endpoint, {
|
|
216
|
+
method: "POST",
|
|
217
|
+
headers: headers(),
|
|
218
|
+
body: JSON.stringify(message),
|
|
219
|
+
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
|
|
220
|
+
});
|
|
221
|
+
} catch {
|
|
222
|
+
const error = syntheticError(
|
|
223
|
+
message,
|
|
224
|
+
0,
|
|
225
|
+
"Could not reach the Xevy MCP server",
|
|
226
|
+
);
|
|
227
|
+
if (forward && error) writeMessage(error);
|
|
228
|
+
return { ok: false, status: 0, messages: [] };
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
const returnedSessionId = response.headers.get("mcp-session-id");
|
|
232
|
+
if (returnedSessionId) sessionId = returnedSessionId;
|
|
233
|
+
|
|
234
|
+
const text = await response.text();
|
|
235
|
+
const messages = parseJsonRpcMessages(
|
|
236
|
+
text,
|
|
237
|
+
response.headers.get("content-type") || "",
|
|
238
|
+
);
|
|
239
|
+
const sessionExpired =
|
|
240
|
+
response.status === 404 ||
|
|
241
|
+
messages.some(
|
|
242
|
+
(entry) =>
|
|
243
|
+
entry &&
|
|
244
|
+
typeof entry === "object" &&
|
|
245
|
+
entry.error &&
|
|
246
|
+
typeof entry.error === "object" &&
|
|
247
|
+
entry.error.code === -32001,
|
|
248
|
+
);
|
|
249
|
+
|
|
250
|
+
if (
|
|
251
|
+
allowRecovery &&
|
|
252
|
+
sessionExpired &&
|
|
253
|
+
initializeMessage &&
|
|
254
|
+
message?.method !== "initialize"
|
|
255
|
+
) {
|
|
256
|
+
try {
|
|
257
|
+
await recoverSession();
|
|
258
|
+
return postUpstream(message, { forward, allowRecovery: false });
|
|
259
|
+
} catch {
|
|
260
|
+
const error = syntheticError(
|
|
261
|
+
message,
|
|
262
|
+
response.status,
|
|
263
|
+
"The Xevy MCP session expired and could not be reinitialized",
|
|
264
|
+
);
|
|
265
|
+
if (forward && error) writeMessage(error);
|
|
266
|
+
return { ok: false, status: response.status, messages };
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
if (!response.ok) {
|
|
271
|
+
const error = syntheticError(
|
|
272
|
+
message,
|
|
273
|
+
response.status,
|
|
274
|
+
`Upstream Xevy MCP request failed (HTTP ${response.status})`,
|
|
275
|
+
);
|
|
276
|
+
if (forward && error) writeMessage(error);
|
|
277
|
+
return { ok: false, status: response.status, messages };
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
if (message?.method === "initialize") {
|
|
281
|
+
initializeMessage = message;
|
|
282
|
+
const negotiated = messages.find(
|
|
283
|
+
(entry) =>
|
|
284
|
+
entry &&
|
|
285
|
+
typeof entry === "object" &&
|
|
286
|
+
entry.result &&
|
|
287
|
+
typeof entry.result.protocolVersion === "string",
|
|
288
|
+
)?.result?.protocolVersion;
|
|
289
|
+
if (negotiated) protocolVersion = negotiated;
|
|
290
|
+
} else if (message?.method === "notifications/initialized") {
|
|
291
|
+
initialized = true;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
if (forward) {
|
|
295
|
+
for (const entry of messages) writeMessage(entry);
|
|
296
|
+
}
|
|
297
|
+
return { ok: true, status: response.status, messages };
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
async function handleLine(line) {
|
|
301
|
+
const trimmed = line.trim();
|
|
302
|
+
if (!trimmed) return;
|
|
303
|
+
|
|
304
|
+
let message;
|
|
305
|
+
try {
|
|
306
|
+
message = JSON.parse(trimmed);
|
|
307
|
+
} catch {
|
|
308
|
+
writeMessage({
|
|
309
|
+
jsonrpc: "2.0",
|
|
310
|
+
id: null,
|
|
311
|
+
error: { code: -32700, message: "Parse error" },
|
|
312
|
+
});
|
|
313
|
+
return;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
await postUpstream(message);
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
async function closeUpstreamSession() {
|
|
320
|
+
if (!sessionId) return;
|
|
321
|
+
try {
|
|
322
|
+
await fetch(endpoint, {
|
|
323
|
+
method: "DELETE",
|
|
324
|
+
headers: headers(),
|
|
325
|
+
signal: AbortSignal.timeout(2_000),
|
|
326
|
+
});
|
|
327
|
+
} catch {
|
|
328
|
+
// Best-effort cleanup only.
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
const input = readline.createInterface({
|
|
333
|
+
input: process.stdin,
|
|
334
|
+
crlfDelay: Infinity,
|
|
335
|
+
});
|
|
336
|
+
|
|
337
|
+
let queue = Promise.resolve();
|
|
338
|
+
for await (const line of input) {
|
|
339
|
+
queue = queue
|
|
340
|
+
.then(() => handleLine(line))
|
|
341
|
+
.catch(() => {
|
|
342
|
+
process.stderr.write("xevy-mcp: failed to proxy an MCP message\n");
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
await queue;
|
|
346
|
+
await closeUpstreamSession();
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xevy/skills",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Install Xevy agent skills and MCP for Cursor, Claude Code, Codex, and other coding agents
|
|
3
|
+
"version": "0.1.28",
|
|
4
|
+
"description": "Install Xevy agent skills and secure per-agent MCP transports for Cursor, Claude Code, Codex, and other coding agents.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"xevy",
|