@xiaozhiclaw/mcp-host-config 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import { type McpBindingV1, type McpInstallationRecordV1, type SecretRefV1 } from "@xiaozhiclaw/mcp-contract";
+export declare const MCP_HOST_CONFIG_FORMATS: readonly ["xiaozhi", "vscode", "codex", "claude-desktop"];
+export type McpHostConfigFormat = (typeof MCP_HOST_CONFIG_FORMATS)[number];
+export interface McpHostProjectionV1 {
+    readonly name: string;
+    readonly installation: McpInstallationRecordV1;
+    readonly binding: McpBindingV1;
+}
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type ParsedMcpHostConfigV1 = {
+    readonly format: "xiaozhi";
+    readonly value: JsonObject;
+} | {
+    readonly format: "vscode";
+    readonly value: JsonObject;
+} | {
+    readonly format: "claude-desktop";
+    readonly value: JsonObject;
+} | {
+    readonly format: "codex";
+    readonly source: string;
+    readonly occupiedNames: readonly string[];
+    readonly additions: readonly McpHostProjectionV1[];
+};
+export interface McpHostConfigConflictV1 {
+    readonly code: "MCP_HOST_CONFIG_COLLISION";
+    readonly format: McpHostConfigFormat;
+    readonly name: string;
+    readonly path: string;
+}
+export type McpHostConfigMergePlanV1 = {
+    readonly ok: true;
+    readonly document: ParsedMcpHostConfigV1;
+} | {
+    readonly ok: false;
+    readonly conflicts: readonly McpHostConfigConflictV1[];
+};
+export declare function parseMcpHostConfig(format: McpHostConfigFormat, source: string): ParsedMcpHostConfigV1;
+export declare function renderSecretRefPlaceholder(secretRef: SecretRefV1): string;
+export declare function planMcpHostConfigMerge(document: ParsedMcpHostConfigV1, values: readonly McpHostProjectionV1[]): McpHostConfigMergePlanV1;
+export declare function renderMcpHostConfig(document: ParsedMcpHostConfigV1): string;
+export {};

package/dist/index.js

@@ -0,0 +1,335 @@
+import { parseMcpBindingV1, parseMcpInstallationRecordV1, } from "@xiaozhiclaw/mcp-contract";
+import { parse as parseToml, stringify as stringifyToml } from "@iarna/toml";
+export const MCP_HOST_CONFIG_FORMATS = [
+    "xiaozhi",
+    "vscode",
+    "codex",
+    "claude-desktop",
+];
+function fail(path, message) {
+    throw new TypeError(`${path}: ${message}`);
+}
+function compareUnicodeCodePoints(left, right) {
+    const leftCodePoints = Array.from(left);
+    const rightCodePoints = Array.from(right);
+    const sharedLength = Math.min(leftCodePoints.length, rightCodePoints.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        const difference = leftCodePoints[index].codePointAt(0) - rightCodePoints[index].codePointAt(0);
+        if (difference !== 0)
+            return difference;
+    }
+    return leftCodePoints.length - rightCodePoints.length;
+}
+function assertValidUnicode(value, path) {
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const nextCodeUnit = value.charCodeAt(index + 1);
+            if (index + 1 >= value.length || nextCodeUnit < 0xdc00 || nextCodeUnit > 0xdfff) {
+                fail(path, "contains an unpaired Unicode surrogate");
+            }
+            index += 1;
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            fail(path, "contains an unpaired Unicode surrogate");
+        }
+    }
+}
+function hasOwn(value, key) {
+    return Object.hasOwn(value, key);
+}
+function setOwn(target, key, value) {
+    Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true,
+    });
+}
+function emptyJsonObject() {
+    return Object.create(null);
+}
+function object(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail(path, "expected object");
+    return value;
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function parseJsonRoot(source, path) {
+    let value;
+    try {
+        value = JSON.parse(source.trim() === "" ? "{}" : source);
+    }
+    catch (error) {
+        fail(path, error instanceof Error ? error.message : "invalid JSON");
+    }
+    return object(value, `${path} root`);
+}
+function parseCodexNames(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("codex TOML", "expected object root");
+    const servers = value.mcp_servers;
+    if (servers === undefined)
+        return [];
+    if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+        return fail("codex TOML mcp_servers", "expected table");
+    }
+    return Object.keys(servers).sort(compareUnicodeCodePoints);
+}
+export function parseMcpHostConfig(format, source) {
+    if (typeof source !== "string")
+        fail("source", "expected string");
+    if (format === "codex") {
+        let parsed;
+        try {
+            parsed = parseToml(source);
+        }
+        catch (error) {
+            fail("codex TOML", error instanceof Error ? error.message : "parse failed");
+        }
+        return Object.freeze({
+            format,
+            source,
+            occupiedNames: Object.freeze(parseCodexNames(parsed)),
+            additions: Object.freeze([]),
+        });
+    }
+    const value = parseJsonRoot(source, format);
+    if (format === "xiaozhi") {
+        if (value.installations !== undefined)
+            object(value.installations, "xiaozhi.installations");
+        if (value.bindings !== undefined)
+            object(value.bindings, "xiaozhi.bindings");
+    }
+    else {
+        const key = format === "vscode" ? "servers" : "mcpServers";
+        if (value[key] !== undefined)
+            object(value[key], `${format}.${key}`);
+    }
+    return Object.freeze({ format, value: cloneJson(value) });
+}
+export function renderSecretRefPlaceholder(secretRef) {
+    if (secretRef?.kind !== "secret-ref" || typeof secretRef.id !== "string" || secretRef.id.length === 0) {
+        return fail("secretRef", "expected SecretRefV1");
+    }
+    return `<secret-ref:${secretRef.id}>`;
+}
+function definitionValue(value, binding) {
+    if (value.kind === "literal")
+        return value.value;
+    if (value.valueKind === "text") {
+        const input = binding.inputValues[value.inputKey];
+        if (!input)
+            return fail(`binding.inputValues.${value.inputKey}`, "required by installation template");
+        return input.value;
+    }
+    const secretRef = binding.secretRefs[value.inputKey];
+    if (!secretRef)
+        return fail(`binding.secretRefs.${value.inputKey}`, "required by installation template");
+    return renderSecretRefPlaceholder(secretRef);
+}
+function valueRecord(values, binding) {
+    if (!values)
+        return undefined;
+    return Object.fromEntries(Object.keys(values).sort(compareUnicodeCodePoints).map((key) => [key, definitionValue(values[key], binding)]));
+}
+function externalDefinition(format, definition, binding) {
+    if (definition.transport === "stdio") {
+        const projected = { command: definition.commandPath };
+        if (definition.args)
+            projected.args = definition.args.map((value) => definitionValue(value, binding));
+        if (definition.cwd)
+            projected.cwd = definition.cwd;
+        const environment = valueRecord(definition.environment, binding);
+        if (environment)
+            projected.env = environment;
+        if (format === "vscode")
+            projected.type = "stdio";
+        return projected;
+    }
+    const projected = { url: definition.url };
+    const headers = valueRecord(definition.headers, binding);
+    if (headers)
+        projected[format === "codex" ? "http_headers" : "headers"] = headers;
+    if (format !== "codex")
+        projected.type = "http";
+    return projected;
+}
+function projection(value) {
+    if (!value || typeof value !== "object")
+        fail("projection", "expected object");
+    if (typeof value.name === "string")
+        assertValidUnicode(value.name, "projection.name");
+    if (typeof value.name !== "string" || value.name.length === 0 || value.name.length > 128 || /[\u0000-\u001f\u007f]/.test(value.name)) {
+        fail("projection.name", "expected non-empty display key without control characters");
+    }
+    const installation = parseMcpInstallationRecordV1(value.installation);
+    const binding = parseMcpBindingV1(value.binding);
+    if (binding.installationId !== installation.installationId) {
+        fail("projection.binding.installationId", "must match installation.installationId");
+    }
+    const definitionValues = installation.definition.transport === "stdio"
+        ? [...(installation.definition.args ?? []), ...Object.values(installation.definition.environment ?? {})]
+        : Object.values(installation.definition.headers ?? {});
+    for (const definitionValue of definitionValues) {
+        if (definitionValue.kind !== "binding-input-ref")
+            continue;
+        if (definitionValue.valueKind === "text") {
+            if (!Object.hasOwn(binding.inputValues, definitionValue.inputKey))
+                fail(`projection.binding.inputValues.${definitionValue.inputKey}`, "required by installation template");
+            if (Object.hasOwn(binding.secretRefs, definitionValue.inputKey))
+                fail(`projection.binding.${definitionValue.inputKey}`, "text template input cannot use a SecretRef");
+        }
+        else {
+            if (!Object.hasOwn(binding.secretRefs, definitionValue.inputKey))
+                fail(`projection.binding.secretRefs.${definitionValue.inputKey}`, "SecretRef required by installation template");
+            if (Object.hasOwn(binding.inputValues, definitionValue.inputKey))
+                fail(`projection.binding.inputValues.${definitionValue.inputKey}`, "secret template input must never contain plaintext");
+        }
+    }
+    return Object.freeze({ name: value.name, installation, binding });
+}
+function conflict(format, entry, path) {
+    return Object.freeze({ code: "MCP_HOST_CONFIG_COLLISION", format, name: entry.name, path });
+}
+function stableJsonValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableJsonValue);
+    if (value && typeof value === "object") {
+        const stable = emptyJsonObject();
+        for (const key of Object.keys(value).sort(compareUnicodeCodePoints)) {
+            setOwn(stable, key, stableJsonValue(value[key]));
+        }
+        return stable;
+    }
+    return value;
+}
+function jsonPlan(document, entries) {
+    const value = cloneJson(document.value);
+    const conflicts = [];
+    const seenNames = new Set();
+    if (document.format === "xiaozhi") {
+        const installations = value.installations === undefined ? emptyJsonObject() : object(value.installations, "xiaozhi.installations");
+        const bindings = value.bindings === undefined ? emptyJsonObject() : object(value.bindings, "xiaozhi.bindings");
+        const batchInstallationIds = new Set();
+        const batchBindingIds = new Set();
+        for (const entry of entries) {
+            if (seenNames.has(entry.name))
+                conflicts.push(conflict(document.format, entry, `projections.${entry.name}`));
+            if (hasOwn(installations, entry.installation.installationId)) {
+                conflicts.push(conflict(document.format, entry, `installations.${entry.installation.installationId}`));
+            }
+            else if (hasOwn(bindings, entry.binding.bindingId)) {
+                conflicts.push(conflict(document.format, entry, `bindings.${entry.binding.bindingId}`));
+            }
+            else {
+                if (batchInstallationIds.has(entry.installation.installationId)) {
+                    conflicts.push(conflict(document.format, entry, `installations.${entry.installation.installationId}`));
+                }
+                if (batchBindingIds.has(entry.binding.bindingId)) {
+                    conflicts.push(conflict(document.format, entry, `bindings.${entry.binding.bindingId}`));
+                }
+            }
+            seenNames.add(entry.name);
+            batchInstallationIds.add(entry.installation.installationId);
+            batchBindingIds.add(entry.binding.bindingId);
+        }
+        if (conflicts.length > 0)
+            return { ok: false, conflicts: Object.freeze(conflicts) };
+        for (const entry of entries) {
+            setOwn(installations, entry.installation.installationId, cloneJson(entry.installation));
+            setOwn(bindings, entry.binding.bindingId, cloneJson(entry.binding));
+        }
+        value.installations = installations;
+        value.bindings = bindings;
+    }
+    else {
+        const key = document.format === "vscode" ? "servers" : "mcpServers";
+        const servers = value[key] === undefined ? emptyJsonObject() : object(value[key], `${document.format}.${key}`);
+        for (const entry of entries) {
+            if (seenNames.has(entry.name) || hasOwn(servers, entry.name))
+                conflicts.push(conflict(document.format, entry, `${key}.${entry.name}`));
+            seenNames.add(entry.name);
+        }
+        if (conflicts.length > 0)
+            return { ok: false, conflicts: Object.freeze(conflicts) };
+        for (const entry of entries)
+            setOwn(servers, entry.name, externalDefinition(document.format, entry.installation.definition, entry.binding));
+        value[key] = servers;
+    }
+    return { ok: true, document: Object.freeze({ format: document.format, value }) };
+}
+export function planMcpHostConfigMerge(document, values) {
+    if (!Array.isArray(values))
+        fail("projections", "expected array");
+    const entries = values.map(projection).sort((left, right) => compareUnicodeCodePoints(left.name, right.name));
+    if (document.format !== "codex")
+        return jsonPlan(document, entries);
+    const occupied = new Set([
+        ...document.occupiedNames,
+        ...document.additions.map((entry) => entry.name),
+    ]);
+    const conflicts = [];
+    for (const entry of entries) {
+        if (occupied.has(entry.name))
+            conflicts.push(conflict("codex", entry, `mcp_servers.${entry.name}`));
+        occupied.add(entry.name);
+    }
+    if (conflicts.length > 0)
+        return { ok: false, conflicts: Object.freeze(conflicts) };
+    return {
+        ok: true,
+        document: Object.freeze({
+            format: "codex",
+            source: document.source,
+            occupiedNames: Object.freeze([...document.occupiedNames]),
+            additions: Object.freeze([...document.additions, ...entries].sort((left, right) => compareUnicodeCodePoints(left.name, right.name))),
+        }),
+    };
+}
+function tomlString(value) {
+    assertValidUnicode(value, "TOML string");
+    return stringifyToml.value(value);
+}
+function tomlArray(values) {
+    return `[${values.map(tomlString).join(", ")}]`;
+}
+function tomlInlineTable(values) {
+    return `{ ${Object.keys(values).sort(compareUnicodeCodePoints).map((key) => `${tomlString(key)} = ${tomlString(values[key])}`).join(", ")} }`;
+}
+function renderCodexEntry(entry) {
+    const definition = entry.installation.definition;
+    const lines = [`[mcp_servers.${tomlString(entry.name)}]`];
+    if (definition.transport === "stdio") {
+        lines.push(`command = ${tomlString(definition.commandPath)}`);
+        if (definition.args)
+            lines.push(`args = ${tomlArray(definition.args.map((value) => definitionValue(value, entry.binding)))}`);
+        if (definition.cwd)
+            lines.push(`cwd = ${tomlString(definition.cwd)}`);
+        const environment = valueRecord(definition.environment, entry.binding);
+        if (environment)
+            lines.push(`env = ${tomlInlineTable(environment)}`);
+    }
+    else {
+        lines.push(`url = ${tomlString(definition.url)}`);
+        const headers = valueRecord(definition.headers, entry.binding);
+        if (headers)
+            lines.push(`http_headers = ${tomlInlineTable(headers)}`);
+    }
+    return lines.join("\n");
+}
+export function renderMcpHostConfig(document) {
+    if (document.format !== "codex") {
+        return `${JSON.stringify(stableJsonValue(document.value), null, 2)}\n`;
+    }
+    if (document.additions.length === 0)
+        return document.source;
+    let source = document.source;
+    if (source.length > 0 && !source.endsWith("\n"))
+        source += "\n";
+    if (source.length > 0 && !source.endsWith("\n\n"))
+        source += "\n";
+    return `${source}${document.additions.map(renderCodexEntry).join("\n\n")}\n`;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@xiaozhiclaw/mcp-host-config",
+  "version": "0.1.0",
+  "description": "Pure MCP configuration projections for Xiaozhi and external Hosts",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@iarna/toml": "2.2.5",
+    "@xiaozhiclaw/mcp-contract": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "pack:check": "node scripts/check-pack.mjs"
+  }
+}