@plurnk/plurnk-mcp 1.23.0 → 1.25.0

package/dist/index.js

@@ -1,5 +1,5 @@
 export { default as Module } from "./Module.js";
 export { default } from "./Module.js";
 export { MCP_CLIENT_VERSION, MCP_CONFORMANCE_VERSION, MCP_PROTOCOL_VERSION, MCP_SPECIFICATION_COMMIT, MCP_TASKS_EXTENSION_ID, MCP_TASKS_SPECIFICATION_COMMIT, } from "./protocol.js";
-export { connectTimeoutMs, expandReferences, requestTimeoutMs, serverDefinition, serverNames, serviceDefinitions, serviceEnabledNames, } from "./config.js";
+export { serviceDefinitions, configuredDefinitions, connectTimeoutMs, expandReferences, requestTimeoutMs, serverSettings, validateConfiguration, } from "./config.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EACH,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,8BAA8B,GACjC,MAAM,eAAe,CAAC;AACvB,OAAO,EACH,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,GACtB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EACH,kBAAkB,EAClB,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,sBAAsB,EACtB,8BAA8B,GACjC,MAAM,eAAe,CAAC;AACvB,OAAO,EACH,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,qBAAqB,GACxB,MAAM,aAAa,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,60 @@
+import type { McpStdioServerDefinition, McpStreamableHttpServerDefinition } from "@plurnk/plurnk-contracts";
+type McpServerEntry = Omit<McpStdioServerDefinition, "name"> | Omit<McpStreamableHttpServerDefinition, "name">;
+interface Argument {
+    readonly type?: unknown;
+    readonly name?: unknown;
+    readonly value?: unknown;
+    readonly default?: unknown;
+    readonly isRequired?: unknown;
+}
+interface KeyValue {
+    readonly name?: unknown;
+    readonly value?: unknown;
+    readonly default?: unknown;
+    readonly isRequired?: unknown;
+    readonly isSecret?: unknown;
+}
+interface Package {
+    readonly registryType?: unknown;
+    readonly identifier?: unknown;
+    readonly version?: unknown;
+    readonly runtimeHint?: unknown;
+    readonly transport?: {
+        readonly type?: unknown;
+    };
+    readonly runtimeArguments?: readonly Argument[];
+    readonly packageArguments?: readonly Argument[];
+    readonly environmentVariables?: readonly KeyValue[];
+}
+interface Remote {
+    readonly type?: unknown;
+    readonly url?: unknown;
+    readonly headers?: readonly KeyValue[];
+}
+export interface RegistryServer {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly packages?: readonly Package[];
+    readonly remotes?: readonly Remote[];
+}
+export interface RegistryEntry {
+    readonly alias: string;
+    readonly summary: string;
+    readonly entry: McpServerEntry;
+    readonly reference: string;
+}
+export declare const aliasOf: (registryName: string) => string | null;
+export declare const registryEntries: (server: RegistryServer) => RegistryEntry[];
+export declare class RegistryError extends Error {
+    readonly status: number | null;
+    constructor(message: string, status: number | null, options?: ErrorOptions);
+}
+export declare const searchRegistry: ({ url, query, limit, timeoutMs }: {
+    readonly url: string;
+    readonly query: string;
+    readonly limit: number;
+    readonly timeoutMs: number;
+}) => Promise<RegistryServer[]>;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/registry.js

@@ -0,0 +1,150 @@
+const text = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
+const templated = (value) => /\{[^}]*\}/u.test(value);
+// The command each registry type runs through, as the registry's own examples launch it; a
+// non-interactive flag keeps a first-run install prompt off the protocol's stdin.
+const RUNNERS = {
+    npm: { command: "npx", flags: ["-y"], reference: (identifier, version) => `${identifier}@${version}` },
+    pypi: { command: "uvx", flags: [], reference: (identifier, version) => `${identifier}@${version}` },
+    nuget: { command: "dnx", flags: [], reference: (identifier, version) => `${identifier}@${version}` },
+    oci: { command: "docker", flags: ["run", "-i", "--rm"], reference: (identifier) => identifier },
+};
+// Positional values in order, named ones as `--name value`; null when one needs a person's input.
+const argv = (args) => {
+    const out = [];
+    for (const arg of args ?? []) {
+        const value = text(arg.value) ?? text(arg.default);
+        if (value !== undefined && templated(value))
+            return null;
+        if (value === undefined) {
+            if (arg.isRequired === true)
+                return null;
+            continue;
+        }
+        if (arg.type === "named") {
+            const name = text(arg.name);
+            if (name === undefined)
+                return null;
+            out.push(name, value);
+        }
+        else {
+            out.push(value);
+        }
+    }
+    return out;
+};
+// The server's registry name's last segment, as plurnk spells a server.
+export const aliasOf = (registryName) => {
+    const alias = (registryName.split("/").at(-1) ?? "")
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9-]+/gu, "-")
+        .replace(/^[^a-z]+/u, "")
+        .replace(/-+$/u, "");
+    return alias.length === 0 ? null : alias;
+};
+const packageEntry = (pkg) => {
+    const registryType = text(pkg.registryType);
+    const identifier = text(pkg.identifier);
+    const version = text(pkg.version);
+    const runner = registryType === undefined ? undefined : RUNNERS[registryType];
+    if (runner === undefined || identifier === undefined || (version === undefined && registryType !== "oci"))
+        return null;
+    if (pkg.transport?.type !== "stdio")
+        return null;
+    const runtime = argv(pkg.runtimeArguments);
+    const packaged = argv(pkg.packageArguments);
+    if (runtime === null || packaged === null)
+        return null;
+    const variables = (pkg.environmentVariables ?? []).flatMap((variable) => text(variable.name) ?? []);
+    const command = text(pkg.runtimeHint) ?? runner.command;
+    const flags = runner.flags.filter((flag) => !runtime.includes(flag));
+    // A container inherits nothing: each declared variable passes through from the launch environment.
+    const passed = registryType === "oci" ? variables.flatMap((name) => ["-e", name]) : [];
+    const args = [...flags, ...passed, ...runtime, runner.reference(identifier, version ?? ""), ...packaged];
+    const needs = (pkg.environmentVariables ?? [])
+        .filter((variable) => variable.isRequired === true && text(variable.default) === undefined)
+        .flatMap((variable) => text(variable.name) ?? []);
+    return { entry: { type: "stdio", command, args }, launch: [command, ...args].join(" "), needs };
+};
+const remoteEntry = (remote) => {
+    const url = text(remote.url);
+    if (remote.type !== "streamable-http" || url === undefined || templated(url))
+        return null;
+    const headers = {};
+    const needs = [];
+    for (const header of remote.headers ?? []) {
+        const name = text(header.name);
+        if (name === undefined)
+            return null;
+        const value = header.isSecret === true ? undefined : text(header.value) ?? text(header.default);
+        if (value !== undefined && templated(value))
+            return null;
+        if (value !== undefined)
+            headers[name] = value;
+        else if (header.isRequired === true)
+            needs.push(`the ${name} header`);
+    }
+    return {
+        entry: { type: "streamable-http", url, ...(Object.keys(headers).length === 0 ? {} : { headers }) },
+        launch: url,
+        needs,
+    };
+};
+export const registryEntries = (server) => {
+    const alias = aliasOf(server.name);
+    if (alias === null)
+        return [];
+    const purpose = server.description?.trim() ?? "";
+    return [...(server.packages ?? []).map(packageEntry), ...(server.remotes ?? []).map(remoteEntry)]
+        .flatMap((found) => found === null ? [] : [{
+            alias,
+            summary: [purpose, found.launch, found.needs.length === 0 ? "" : `Needs ${found.needs.join(", ")}.`]
+                .filter((part) => part.length > 0).join(" — "),
+            entry: found.entry,
+            reference: `${server.name}@${server.version}`,
+        }]);
+};
+export class RegistryError extends Error {
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.name = "RegistryError";
+        this.status = status;
+    }
+}
+const isServer = (value) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const server = value;
+    return typeof server.name === "string" && typeof server.version === "string";
+};
+// One page of the latest version of every server whose name matches the query.
+export const searchRegistry = async ({ url, query, limit, timeoutMs }) => {
+    const endpoint = new URL("v0.1/servers", url.endsWith("/") ? url : `${url}/`);
+    endpoint.searchParams.set("search", query);
+    endpoint.searchParams.set("version", "latest");
+    endpoint.searchParams.set("limit", String(limit));
+    let response;
+    try {
+        response = await fetch(endpoint, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (cause) {
+        throw new RegistryError(`The MCP Registry at ${endpoint.origin} could not be reached.`, null, { cause });
+    }
+    if (!response.ok)
+        throw new RegistryError(`The MCP Registry at ${endpoint.origin} answered ${response.status}.`, response.status);
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throw new RegistryError(`The MCP Registry at ${endpoint.origin} answered with malformed JSON.`, response.status, { cause });
+    }
+    const listed = body?.servers;
+    if (!Array.isArray(listed))
+        throw new RegistryError(`The MCP Registry at ${endpoint.origin} answered without a server list.`, response.status);
+    return listed.flatMap((item) => {
+        const server = item?.server;
+        return isServer(server) ? [server] : [];
+    });
+};
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/docs/mcp.md

@@ -12,59 +12,78 @@ One fenced call runs one tool, and the result is that call's output.
 `worker:///_plurnk/tools/<server>.md` lists a server's invocations and their
 required top-level inputs; each invocation links to the complete raw input
 schema. The turn-0 catalog lists every enabled server's document. `list`
-shows every configured server, including disabled ones and unavailable ones
-with their exact Problem; `enable` turns a configured server on; `discover`
-inspects a server before anything is attached.
+shows every server, including disabled ones and unavailable ones with their
+exact Problem; `enable` turns a server on; `discover` finds servers to add.
 
 ## discover, then add
 
-`discover` takes `{"source": "<URL or command line>"}`: the server is
-connected once, its tool list is read, and one inert candidate comes back
-carrying the exact definition to add. Discovery never persists or enables a
-server definition.
+`discover` takes `{"query": "<name>"}` and searches the MCP Registry; each
+candidate carries the exact definition to add. Discovery never persists or
+enables anything.
 
-```mcp (discover) <!-- inspect before adding -->
-{"source": "npx -y @modelcontextprotocol/server-filesystem /absolute/project/path"}
+```mcp (discover) <!-- search before adding -->
+{"query": "filesystem"}
 ```
 
-`add` persists the definition for this workspace, connects, and enables it
-atomically. It is a host effect, admitted under the loop's policy.
+`add` saves a workspace definition, connects, and enables it atomically. It is a host
+effect, admitted under the loop's policy.
 
 ```mcp (add)
-{"alias": "files", "definition": {"name": "files", "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/project/path"]}}
+{"alias": "files", "definition": {"name": "files", "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/project/path"]}}
 ```
 
-A `stdio` definition carries `command` and optional `args`, `cwd`; an `http`
-definition carries `url` and optional `headers`. `tools` narrows the enabled
-tool set and `read` names the tools that are read-only; every other tool keeps
-the conservative `host` effect. A credential is a symbolic reference such as
-`"${TOKEN}"` to the operator's environment, never a pasted secret.
-
-Local servers start in their workspace's server directory under
-`XDG_STATE_HOME` (normally `~/.local/state/plurnk`), not in the project:
-project inputs and outputs are absolute paths, or `cwd` is set explicitly when
-a server requires it. State survives reconnects and disable/remove; a discovery
-probe uses a temporary directory removed after it closes. This is file
-placement, not a sandbox.
+A complete definition names one transport: `stdio` has `command` and optional
+`args`, `env`, `cwd`; `streamable-http` has `url` and optional `headers`,
+`authorization`. Native definitions run local commands without a shell, in workspace-owned state
+unless `cwd` supplies an absolute directory. Use absolute project paths in
+arguments. This is file placement, not a sandbox or plugin installation.
+A tool marked `readOnlyHint` runs as a read; other tools retain the `host` effect.
 
 ## Environment
 
-Workspace variables, set with the `env` family (`env.md`) before discovering
-or adding a local server, reach every server launch; worker-local overrides do
-not. A running server keeps its launch environment; `disable` then `enable`
-restarts it with the current workspace values, without a daemon restart.
+Shared definitions may come from `~/.agents/mcp.json`,
+`$XDG_CONFIG_HOME/plurnk/mcp.json`, or the project's `.agents/mcp.json`, each
+containing a `mcpServers` map. Nearer files override farther ones; environment
+definitions override files. `list` reports the winning file and entry.
+Live management changes the workspace, never those files. File edits are
+picked up before the next turn; enabledness and tool filters still use
+`PLURNK_MCP_<alias>_ENABLED` and `PLURNK_MCP_<alias>_TOOLS`.
+
+Installed Agent Plugins contribute servers from their root `mcp.json` through
+the same family. Within each scope standalone definitions win; nearer scopes
+win over farther ones. Plugin commands default to the plugin root and receive
+`PLUGIN_ROOT` plus a persistent `PLUGIN_DATA` directory. Their arguments,
+environment values, and cwd expand only those two placeholders; HTTP values
+and all other placeholder-like text remain literal. `list` identifies the
+source. A complete workspace override replaces these plugin semantics too.
+
+A local server inherits the operator's environment, which is where it reads
+its credentials, without plurnk's own settings or model provider keys.
+Workspace variables set with the `env` family (`env.md`) apply on top at
+every server launch; worker-local overrides do not. A running server keeps its
+launch environment; `disable` then `enable` restarts it with the current
+workspace values, without a daemon restart.
+
+```env (add)
+{"scope": "workspace", "alias": "SERVICE_TOKEN", "definition": {"value": "<credential>"}}
+```
+
+Native definitions may reference workspace variables as `${NAME}` in arguments,
+environment values, working directories, HTTP headers, and authorization.
+Structured authorization secrets must be references, not literal credentials.
 
 ## Authorization
 
-An `http` server that needs OAuth comes up `authorization-required` with an
+An HTTP server that needs OAuth comes up `authorization-required` with an
 authorization URL. That step is the user's, from their client; a body carries
 no credentials and the URL is not a resource to READ. Afterwards `enable`
 retries and the tools appear.
 
 ## Lifecycle
 
-`disable` withdraws a server's tools while keeping its definition; `remove`
-deletes a workspace definition. Operator-configured servers
-(`PLURNK_MCP_<server>` in the service environment) are disable-only. The
-family document projects the enabled-tool snapshot: after `enable`, FIND the
-reference again before relying on a tool's signature.
+`disable` withdraws a server's tools while keeping its definition. `remove`
+undoes the workspace definition and restores any inherited definition and
+enabled state; use `disable` to suppress an inherited server. Neither action
+deletes configuration files or saved results. The family document projects
+the enabled-tool snapshot: after
+`enable`, FIND the reference again before relying on a tool's signature.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-mcp",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "Current Model Context Protocol host module for Plurnk.",
   "keywords": [
     "plurnk",
@@ -55,8 +55,10 @@
     "prepublishOnly": "npm audit --audit-level=moderate && npm test"
   },
   "dependencies": {
+    "@plurnk/plurnk-agent-plugins": "1.25.0",
     "@modelcontextprotocol/client": "2.0.0",
-    "@plurnk/plurnk-contracts": "1.23.0"
+    "@plurnk/plurnk-meta": "1.25.0",
+    "@plurnk/plurnk-contracts": "1.25.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/conformance": "0.2.0-alpha.11",
@@ -64,7 +66,7 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@plurnk/plurnk-execs": "^1.23.0",
-    "@plurnk/plurnk-schemes": "^1.23.0"
+    "@plurnk/plurnk-execs": "^1.25.0",
+    "@plurnk/plurnk-schemes": "^1.25.0"
   }
 }