Skip to content

Commit d66927e

Browse files
committed
fix: validate MCP plugin variable declarations
1 parent e73df47 commit d66927e

3 files changed

Lines changed: 130 additions & 0 deletions

File tree

‎.github/workflows/validate-plugins.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ jobs:
2525
- name: Install dependencies
2626
run: npm install --no-save ajv ajv-formats
2727

28+
- name: Test plugin validation
29+
run: node --test scripts/validate-plugins.test.mjs
30+
2831
- name: Validate plugin definitions
2932
run: node scripts/validate-plugins.mjs
3033

‎scripts/validate-plugins.mjs‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,54 @@ function fail(message) {
3131
errors++;
3232
}
3333

34+
// Cursor runtime interpolation is not user-configured plugin configuration.
35+
// https://cursor.com/docs/reference/plugins#variables
36+
// https://cursor.com/docs/mcp#config-interpolation
37+
const runtimeVariables = new Set([
38+
"CURSOR_PLUGIN_ROOT", "CLAUDE_PLUGIN_ROOT", "userHome", "workspaceFolder",
39+
"workspaceFolderBasename", "pathSeparator", "/",
40+
]);
41+
42+
function checkMcpVariables(plugin, pluginDir, name) {
43+
const declared = plugin.variables?.properties ?? {};
44+
const configs = plugin.mcpServers === undefined
45+
? (existsSync(resolve(pluginDir, "mcp.json")) ? ["mcp.json"] : [])
46+
: (Array.isArray(plugin.mcpServers) ? plugin.mcpServers : [plugin.mcpServers]);
47+
48+
function visit(value, location) {
49+
if (typeof value === "string") {
50+
for (const [, variable] of value.matchAll(/\$\{([^{}]+)\}/g)) {
51+
// Leave environment references and shell/default expressions alone;
52+
// only plain ${VAR} references are plugin-variable declarations.
53+
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(variable) ||
54+
runtimeVariables.has(variable) || Object.hasOwn(declared, variable)) continue;
55+
fail(`Plugin "${name}": ${location} references undeclared variable "${variable}" (declare it in variables.properties)`);
56+
}
57+
} else if (Array.isArray(value)) {
58+
value.forEach((item, index) => visit(item, `${location}[${index}]`));
59+
} else if (value && typeof value === "object") {
60+
for (const [key, item] of Object.entries(value)) visit(item, `${location}.${key}`);
61+
}
62+
}
63+
64+
for (const [index, config] of configs.entries()) {
65+
if (typeof config !== "string") {
66+
visit(config, `mcpServers[${index}]`);
67+
continue;
68+
}
69+
const path = resolve(pluginDir, config);
70+
let content;
71+
try {
72+
content = loadJSON(path);
73+
} catch (error) {
74+
const reason = error instanceof SyntaxError ? "invalid JSON" : error.code;
75+
fail(`Plugin "${name}": cannot read MCP config "${config}" (${reason})`);
76+
continue;
77+
}
78+
visit(content, config);
79+
}
80+
}
81+
3482
// 1. Validate marketplace.json
3583
const marketplacePath = resolve(root, ".cursor-plugin/marketplace.json");
3684

@@ -84,6 +132,8 @@ for (const entry of marketplace.plugins ?? []) {
84132
}
85133
}
86134

135+
checkMcpVariables(pluginJson, pluginDir, entry.name);
136+
87137
// Check that marketplace name matches plugin name
88138
if (pluginJson.name && pluginJson.name !== entry.name) {
89139
fail(

‎scripts/validate-plugins.test.mjs‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
import { test } from "node:test";
2+
import assert from "node:assert/strict";
3+
import { cpSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
4+
import { tmpdir } from "node:os";
5+
import { dirname, resolve } from "node:path";
6+
import { fileURLToPath } from "node:url";
7+
import { spawnSync } from "node:child_process";
8+
9+
const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
10+
const schema = { type: "object", properties: { TOKEN: { type: "string" } } };
11+
const config = (value) => ({ mcpServers: { example: { url: "https://example.com/mcp", headers: { Authorization: value } } } });
12+
13+
function validate(t, { plugin = {}, entry = {}, files = {} } = {}) {
14+
const dir = mkdtempSync(resolve(tmpdir(), "plugin-validation-"));
15+
t.after(() => rmSync(dir, { recursive: true, force: true }));
16+
mkdirSync(resolve(dir, "scripts"));
17+
cpSync(resolve(root, "scripts/validate-plugins.mjs"), resolve(dir, "scripts/validate-plugins.mjs"));
18+
cpSync(resolve(root, "schemas"), resolve(dir, "schemas"), { recursive: true });
19+
symlinkSync(resolve(root, "node_modules"), resolve(dir, "node_modules"), process.platform === "win32" ? "junction" : "dir");
20+
const contents = {
21+
".cursor-plugin/marketplace.json": { name: "test", owner: { name: "Test" }, plugins: [{ name: "example", source: "example", ...entry }] },
22+
"example/.cursor-plugin/plugin.json": { name: "example", ...plugin },
23+
...Object.fromEntries(Object.entries(files).map(([path, content]) => [`example/${path}`, content])),
24+
};
25+
for (const [path, content] of Object.entries(contents)) {
26+
mkdirSync(dirname(resolve(dir, path)), { recursive: true });
27+
writeFileSync(resolve(dir, path), typeof content === "string" ? content : JSON.stringify(content));
28+
}
29+
return spawnSync(process.execPath, [resolve(dir, "scripts/validate-plugins.mjs")], { encoding: "utf8" });
30+
}
31+
32+
for (const [name, plugin, files] of [
33+
["default discovery", {}, { "mcp.json": config("Bearer ${TYPO}") }],
34+
["explicit path", { mcpServers: "configs/server.json" }, { "configs/server.json": config("${TYPO}") }],
35+
["inline config", { mcpServers: config("${TYPO}") }, {}],
36+
["mixed array", { mcpServers: [config("${TOKEN}"), "other.json"], variables: schema }, { "other.json": config("${TYPO}") }],
37+
["no declared schema", { mcpServers: config("${TOKEN}") }, {}],
38+
["inherited Object property", { mcpServers: config("${toString}"), variables: schema }, {}],
39+
]) {
40+
test(`rejects undeclared variables in ${name}`, (t) => {
41+
const result = validate(t, { plugin, files });
42+
assert.equal(result.status, 1, result.stderr);
43+
assert.match(result.stderr, /references undeclared variable/);
44+
assert.match(result.stderr, /variables.properties/);
45+
});
46+
}
47+
48+
test("declared variables, defaults and runtime interpolation remain valid", (t) => {
49+
const result = validate(t, { plugin: { variables: schema, mcpServers: {
50+
mcpServers: { example: { command: "${CURSOR_PLUGIN_ROOT}/bin/server", cwd: "${CLAUDE_PLUGIN_ROOT}", args: ["${workspaceFolder}", "${workspaceFolderBasename}", "${userHome}", "${pathSeparator}", "${/}"], env: { TOKEN: "${TOKEN}", OTHER: "${env:OTHER}", OPTIONAL: "${CLIENT_SECRET:-}" } } },
51+
} } });
52+
assert.equal(result.status, 0, result.stderr);
53+
});
54+
55+
test("declared variables work in discovered files and mixed arrays", (t) => {
56+
for (const mcpServers of [undefined, [config("${TOKEN}"), "mcp.json"]]) {
57+
const result = validate(t, { plugin: { variables: schema, ...(mcpServers === undefined ? {} : { mcpServers }) }, files: { "mcp.json": config("${TOKEN}") } });
58+
assert.equal(result.status, 0, result.stderr);
59+
}
60+
});
61+
62+
test("explicit MCP configuration replaces default discovery", (t) => {
63+
const result = validate(t, { plugin: { mcpServers: config("literal") }, files: { "mcp.json": config("${TYPO}") } });
64+
assert.equal(result.status, 0, result.stderr);
65+
});
66+
67+
for (const [name, files] of [["missing", {}], ["invalid JSON", { "custom.json": "{broken" }]]) {
68+
test(`reports ${name} MCP files with plugin context`, (t) => {
69+
const result = validate(t, { plugin: { mcpServers: "custom.json" }, files });
70+
assert.equal(result.status, 1, result.stderr);
71+
assert.match(result.stderr, /Plugin "example": cannot read MCP config "custom.json"/);
72+
});
73+
}
74+
75+
test("plugins without MCP configuration remain valid", (t) => {
76+
assert.equal(validate(t).status, 0);
77+
});

0 commit comments

Comments
 (0)