@cursor/july 0.1.101 → 0.1.103

package/dist/internal/discovery/connections.js

@@ -0,0 +1,422 @@
+/**
+ * `agent/mcp-connections/*.ts` and `agent/host-connections/*.ts`: MCP servers for the model and the host.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { join } from "node:path";
+import { cursorAccountServersHasMixedWildcard, isInlineStdioConnection, isToolEffect, normalizeConnectionEffects, normalizeConnectionTools, normalizeCursorAccountServers, } from "../../types.js";
+import { packageInlineStdioConnection } from "../package-inline-stdio.js";
+import { displayPath, errorMessage, isBlank, } from "./context.js";
+import { importDefault, moduleEntries } from "./modules.js";
+import { NAME_PATTERN } from "./names.js";
+/** One-line `/v1/info` label for a connection transport. */
+export function connectionTransportLabel(transport) {
+    if ("cursorAccount" in transport) {
+        return transport.servers === undefined
+            ? "cursor-account"
+            : `cursor-account:${transport.servers.join(",")}`;
+    }
+    if ("agent" in transport) {
+        return `agent:${transport.agent}`;
+    }
+    if ("url" in transport) {
+        return transport.oauth === true
+            ? `${transport.url} (oauth)`
+            : transport.url;
+    }
+    return transport.command;
+}
+function hasAuthorizationHeader(headers) {
+    if (headers === undefined) {
+        return false;
+    }
+    return Object.keys(headers).some((key) => key.toLowerCase() === "authorization");
+}
+function parseConnectionEffects(effects) {
+    if (effects === undefined) {
+        return { ok: true, value: undefined };
+    }
+    const raw = typeof effects === "string" ? [effects] : effects;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return { ok: false };
+    }
+    const parsed = [];
+    for (const value of raw) {
+        if (!isToolEffect(value)) {
+            return { ok: false };
+        }
+        parsed.push(value);
+    }
+    return { ok: true, value: normalizeConnectionEffects(parsed) };
+}
+function parseConnectionTools(tools) {
+    if (tools === undefined) {
+        return { ok: true, value: undefined };
+    }
+    if (!Array.isArray(tools) || tools.length === 0) {
+        return { ok: false };
+    }
+    if (tools.some((name) => typeof name !== "string")) {
+        return { ok: false };
+    }
+    const normalized = normalizeConnectionTools(tools);
+    if (normalized.length === 0) {
+        return { ok: false };
+    }
+    return { ok: true, value: normalized };
+}
+function connectionHasSpawnOrRemote(connection) {
+    if ("cursorAccount" in connection && connection.cursorAccount === true) {
+        return true;
+    }
+    if ("agent" in connection && !isBlank(connection.agent)) {
+        return true;
+    }
+    if ("url" in connection && !isBlank(connection.url)) {
+        return true;
+    }
+    return "command" in connection && !isBlank(connection.command);
+}
+function connectionTransport(connection) {
+    if ("cursorAccount" in connection && connection.cursorAccount === true) {
+        const servers = normalizeCursorAccountServers(connection.servers);
+        return Object.assign({ cursorAccount: true }, (servers === undefined ? {} : { servers }));
+    }
+    if ("agent" in connection && !isBlank(connection.agent)) {
+        return { agent: connection.agent };
+    }
+    if ("url" in connection && !isBlank(connection.url)) {
+        return {
+            type: connection.type,
+            url: connection.url,
+            headers: connection.headers,
+            oauth: connection.oauth === true ? true : undefined,
+        };
+    }
+    if ("command" in connection && !isBlank(connection.command)) {
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (connection.type === undefined ? {} : { type: connection.type })), { command: connection.command }), (connection.args === undefined ? {} : { args: connection.args })), (connection.env === undefined ? {} : { env: connection.env })), (connection.cwd === undefined ? {} : { cwd: connection.cwd }));
+    }
+    return undefined;
+}
+export function loadHostConnections(ctx, agentDir, modelConnections) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const hostDir = join(agentDir, "host-connections");
+        const loaded = yield loadConnections(ctx, hostDir, "host");
+        const modelNames = new Set(modelConnections.map((connection) => connection.name));
+        const hostConnections = [];
+        for (const connection of loaded) {
+            if (modelNames.has(connection.name)) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
+                    message: `Host connection "${connection.name}" collides with agent/mcp-connections/${connection.name}. Rename one of them.`,
+                });
+                continue;
+            }
+            if (rejectHostConnectionFeatures(ctx, join(hostDir, `${connection.name}.ts`), connection)) {
+                continue;
+            }
+            hostConnections.push(connection);
+        }
+        return hostConnections;
+    });
+}
+export function compileHostConnection(ctx, path, name, definition) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const connection = yield compileConnection(ctx, path, name, definition, "host");
+        if (connection === undefined ||
+            rejectHostConnectionFeatures(ctx, path, connection)) {
+            return undefined;
+        }
+        return connection;
+    });
+}
+function rejectHostConnectionFeatures(ctx, path, connection) {
+    if (connection.advertiseTools === true) {
+        ctx.diagnostics.push({
+            severity: "error",
+            path: displayPath(ctx, path),
+            message: "Host connections are off the model. `advertiseTools` cannot apply. Drop it.",
+        });
+        return true;
+    }
+    if (connection.auth !== undefined) {
+        ctx.diagnostics.push({
+            severity: "error",
+            path: displayPath(ctx, path),
+            message: "Host connections are off the model. `auth` cannot apply. Use static headers or `oauth: true`.",
+        });
+        return true;
+    }
+    return false;
+}
+export function loadConnections(ctx_1, connectionsDir_1) {
+    return __awaiter(this, arguments, void 0, function* (ctx, connectionsDir, role = "model") {
+        const connections = [];
+        for (const { name, path } of yield moduleEntries(ctx, connectionsDir, "connection")) {
+            const definition = yield importDefault(ctx, path, "connection");
+            if (definition === undefined) {
+                continue;
+            }
+            const connection = yield compileConnection(ctx, path, name, definition, role);
+            if (connection !== undefined) {
+                connections.push(connection);
+            }
+        }
+        return connections;
+    });
+}
+/** Validate one `defineConnection` and resolve its transport. */
+export function compileConnection(ctx, entryPath, name, connection, role) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (Object.hasOwn(connection, "hostOnly")) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `hostOnly` was removed. Files under `agent/mcp-connections/` are always visible to the model. Put privileged servers in `agent/host-connections/` so only host tools can call them.",
+            });
+            return undefined;
+        }
+        if (isInlineStdioConnection(connection) &&
+            connectionHasSpawnOrRemote(connection)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `tools` cannot be combined with `command`, `url`, `agent`, or `cursorAccount`. Author TypeScript tools, or point at an existing server, not both.",
+            });
+            return undefined;
+        }
+        if (connection.auth !== undefined && typeof connection.auth !== "function") {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `auth` must be a function: (session) => { headers }.",
+            });
+            return undefined;
+        }
+        if (connection.auth !== undefined && !("url" in connection)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `auth` (per-session headers) is only supported on http/sse connections (`url`).",
+            });
+            return undefined;
+        }
+        if (connection.advertiseTools !== undefined &&
+            typeof connection.advertiseTools !== "boolean") {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `advertiseTools` must be a boolean.",
+            });
+            return undefined;
+        }
+        const parsedEffects = parseConnectionEffects(connection.effects);
+        if (!parsedEffects.ok) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: 'MCP connection `effects` must be "read", "write", or a non-empty array of those.',
+            });
+            return undefined;
+        }
+        if (parsedEffects.value !== undefined && connection.advertiseTools !== true) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `effects` filters advertised tools; set `advertiseTools: true` or drop `effects`.",
+            });
+            return undefined;
+        }
+        const parsedTools = isInlineStdioConnection(connection)
+            ? { ok: true, value: undefined }
+            : parseConnectionTools(connection.tools);
+        if (!parsedTools.ok) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `tools` allowlist must be a non-empty array of tool names.",
+            });
+            return undefined;
+        }
+        if (isInlineStdioConnection(connection) &&
+            connection.disallowedTools !== undefined) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `disallowedTools` is not supported on inline `tools` connections — author only the tools you want.",
+            });
+            return undefined;
+        }
+        const parsedDisallowed = isInlineStdioConnection(connection)
+            ? { ok: true, value: undefined }
+            : parseConnectionTools(connection.disallowedTools);
+        if (!parsedDisallowed.ok) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `disallowedTools` must be a non-empty array of tool names.",
+            });
+            return undefined;
+        }
+        if ((parsedTools.value !== undefined || parsedDisallowed.value !== undefined) &&
+            role === "model" &&
+            connection.advertiseTools !== true) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `tools` / `disallowedTools` filter advertised tools; set `advertiseTools: true` or drop the name list. Put the connection in `agent/host-connections/` to restrict `host.mcp` only.",
+            });
+            return undefined;
+        }
+        if (connection.advertiseTools === true &&
+            isInlineStdioConnection(connection)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `advertiseTools` is not supported on inline `tools` connections — author those as agent/tools/ server tools instead.",
+            });
+            return undefined;
+        }
+        if (connection.auth !== undefined &&
+            "url" in connection &&
+            connection.oauth === true) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `oauth: true` cannot be combined with `auth` (per-session headers): the host OAuth provider owns the Authorization header. Drop one of them.",
+            });
+            return undefined;
+        }
+        if (isInlineStdioConnection(connection)) {
+            return loadInlineStdioConnection(ctx, name, entryPath, connection);
+        }
+        if ("url" in connection &&
+            connection.oauth === true &&
+            hasAuthorizationHeader(connection.headers)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `oauth: true` cannot set an Authorization header. Drop the header or remove `oauth`.",
+            });
+            return undefined;
+        }
+        if ("cursorAccount" in connection &&
+            connection.cursorAccount === true &&
+            cursorAccountServersHasMixedWildcard(connection.servers)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: 'Cursor account MCP connection `servers` cannot mix `"*"` with connector names. Use `"*"` / `["*"]` (or omit `servers`) for every connected server, or list only concrete connector names.',
+            });
+            return undefined;
+        }
+        const transport = connectionTransport(connection);
+        if (transport === undefined) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connections require a `url` (http/sse), a `command` (stdio), `tools` (TypeScript packaged as stdio), an `agent` (peer agent slug on the same serve host), or `cursorAccount: true` (the Cursor account's MCP connectors).",
+            });
+            return undefined;
+        }
+        if ("cursorAccount" in transport &&
+            transport.servers !== undefined &&
+            (transport.servers.length === 0 ||
+                transport.servers.some((server) => isBlank(server)))) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: 'Cursor account MCP connection `servers` must be a non-empty list of connector names, `"*"` / `["*"]` for every connected server, or omitted for the same all-connectors behavior.',
+            });
+            return undefined;
+        }
+        if ("agent" in transport && !NAME_PATTERN.test(transport.agent)) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: `Peer MCP connection agent "${transport.agent}" must be a mount slug matching ${NAME_PATTERN}.`,
+            });
+            return undefined;
+        }
+        return {
+            name,
+            transport,
+            description: connection.description,
+            auth: connection.auth,
+            advertiseTools: connection.advertiseTools,
+            effects: parsedEffects.value,
+            tools: parsedTools.value,
+            disallowedTools: parsedDisallowed.value,
+        };
+    });
+}
+function loadInlineStdioConnection(ctx, name, entryPath, connection) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const tools = connection.tools;
+        const names = Object.keys(tools);
+        if (names.length === 0) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: "MCP connection `tools` must declare at least one tool.",
+            });
+            return undefined;
+        }
+        for (const toolName of names) {
+            if (!NAME_PATTERN.test(toolName)) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, entryPath),
+                    message: `MCP tool name "${toolName}" must match ${NAME_PATTERN}.`,
+                });
+                return undefined;
+            }
+            const tool = tools[toolName];
+            if (tool === undefined || isBlank(tool.description)) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, entryPath),
+                    message: `MCP tool "${toolName}" requires a non-empty description.`,
+                });
+                return undefined;
+            }
+            if (typeof tool.execute !== "function") {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, entryPath),
+                    message: `MCP tool "${toolName}" requires an execute(input) function.`,
+                });
+                return undefined;
+            }
+        }
+        try {
+            const transport = yield packageInlineStdioConnection({
+                name,
+                entryPath,
+                tools,
+                absWorkingDir: ctx.rootDir,
+            });
+            return {
+                name,
+                transport,
+                description: connection.description,
+            };
+        }
+        catch (error) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, entryPath),
+                message: `Failed to package inline stdio MCP connection: ${errorMessage(error)}`,
+            });
+            return undefined;
+        }
+    });
+}

package/dist/internal/discovery/context.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared discovery state: the loader options, the per-project context every loader receives, and the diagnostic helpers.
+ */
+import type { Diagnostic } from "../../types.js";
+export interface LoadAgentProjectOptions {
+    /** Override the module loader (embedders / tests). */
+    importModule?: (absolutePath: string) => Promise<Record<string, unknown>>;
+}
+type ImportModule = (absolutePath: string) => Promise<Record<string, unknown>>;
+export declare function defaultImportModule(absolutePath: string): Promise<Record<string, unknown>>;
+export interface DiscoveryContext {
+    rootDir: string;
+    diagnostics: Diagnostic[];
+    importModule: ImportModule;
+}
+export declare function displayPath(ctx: DiscoveryContext, absolutePath: string): string;
+export declare function errorMessage(error: unknown): string;
+export declare function isBlank(value: unknown): boolean;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/internal/discovery/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGjD,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAED,KAAK,YAAY,GAAG,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE/E,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKlC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,wBAAgB,WAAW,CACzB,GAAG,EAAE,gBAAgB,EACrB,YAAY,EAAE,MAAM,GACnB,MAAM,CAGR;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/C"}

package/dist/internal/discovery/context.js

@@ -0,0 +1,30 @@
+/**
+ * Shared discovery state: the loader options, the per-project context every loader receives, and the diagnostic helpers.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { toPosix } from "./fs.js";
+export function defaultImportModule(absolutePath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return (yield import(pathToFileURL(absolutePath).href));
+    });
+}
+export function displayPath(ctx, absolutePath) {
+    const rel = relative(ctx.rootDir, absolutePath);
+    return rel.startsWith("..") ? absolutePath : toPosix(rel);
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function isBlank(value) {
+    return typeof value !== "string" || value.trim() === "";
+}

package/dist/internal/discovery/cursor-plugin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A Cursor plugin directory read as an extension tree: skills, commands, agents, and MCP servers under the plugin's own names.
+ */
+import type { DiscoveredConnection, DiscoveredSkill } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+/** One `agents/*.md` file: a subagent the plugin ships. */
+export interface CursorPluginAgent {
+    name: string;
+    description?: string;
+    /** Model id; absent inherits the parent agent's model. */
+    model?: string;
+    prompt: string;
+}
+/** What a plugin contributes, under its own (unprefixed) names. */
+export interface CursorPluginTree {
+    description?: string;
+    /** `skills/` and `commands/`; a command is a user-invoked skill. */
+    skills: DiscoveredSkill[];
+    connections: DiscoveredConnection[];
+    /** Servers the plugin declares that the mount overlays; left uncompiled. */
+    overlaidServers: string[];
+    agents: CursorPluginAgent[];
+}
+export declare function readCursorPlugin(ctx: DiscoveryContext, root: string, mountPath: string, variables: Record<string, string>, overlaid: ReadonlySet<string>): Promise<CursorPluginTree | undefined>;
+//# sourceMappingURL=cursor-plugin.d.ts.map

package/dist/internal/discovery/cursor-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-plugin.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/cursor-plugin.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAEV,oBAAoB,EACpB,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,KAAK,gBAAgB,EAItB,MAAM,cAAc,CAAC;AAItB,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,4EAA4E;IAC5E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAoGD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAC5B,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAqCvC"}