@alfe.ai/mcp-server 0.2.5 → 0.2.6

package/README.md

@@ -10,6 +10,36 @@ Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: buil
 npm install @alfe.ai/mcp-server
 ```
 
+## Profiles
+
+The executable defaults to the OpenClaw-safe integrations-only surface:
+
+```bash
+alfe-mcp-server
+```
+
+Claude Code has no Alfe plugins, so its explicit profile adds memory, voice,
+and messaging tools:
+
+```bash
+alfe-mcp-server --profile claude-code
+```
+
+The default profile must remain integrations-only. OpenClaw already receives
+the other capabilities from its native Alfe plugins, and exposing them here as
+well would duplicate its tool surface.
+
+The server reads credentials through `@alfe.ai/config`. Library callers may
+inject a pre-bound `AgentApiClient`, its API URL, and an identity into
+`createServer` for tests or alternate hosts. The main client and URL must be
+provided together. A distinct `voiceApiUrl` also requires a `voiceClient`; the
+package never reads the local API key and attaches it to an arbitrary injected
+destination.
+
+`main()` attaches a transport and returns the connected server without changing
+process state. The packaged executable owns fatal logging, exit codes, and
+SIGINT/SIGTERM shutdown.
+
 ## Links
 
 - 🌐 Website: <https://alfe.ai>

package/dist/bin.cjs

@@ -1,5 +1,51 @@
 #!/usr/bin/env node
 const require_index = require("./index.cjs");
+//#region src/cli.ts
+const MAX_ERROR_CHARS = 4096;
+/**
+* Own the executable-only process policy around the reusable MCP server.
+* Startup failures set a non-zero exit code after writing a redacted diagnostic;
+* SIGINT/SIGTERM close the transport before terminating the child process.
+*/
+async function runCli(argv, dependencies = {}, runtime = process) {
+	const start = dependencies.start ?? require_index.main;
+	let server;
+	try {
+		server = await start({ profile: require_index.parseProfileArg(argv) });
+	} catch (error) {
+		runtime.stderr.write(`[alfe-mcp-server] failed to start: ${safeErrorMessage(error)}\n`);
+		runtime.exitCode = 1;
+		return;
+	}
+	let shutdownPromise;
+	const shutdown = () => {
+		if (shutdownPromise) return;
+		runtime.off("SIGINT", shutdown);
+		runtime.off("SIGTERM", shutdown);
+		shutdownPromise = server.close().catch((error) => {
+			runtime.stderr.write(`[alfe-mcp-server] failed to close cleanly: ${safeErrorMessage(error)}\n`);
+		}).then(() => {
+			runtime.exit(0);
+		});
+	};
+	runtime.once("SIGINT", shutdown);
+	runtime.once("SIGTERM", shutdown);
+}
+function safeErrorMessage(error) {
+	const redacted = (error instanceof Error ? error.message : String(error)).slice(0, MAX_ERROR_CHARS).replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/giu, "$1 [REDACTED]").replace(/\b(api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password)\s*[=:]\s*[^\s,;]+/giu, "$1=[REDACTED]").replace(/\balfe_[A-Za-z0-9_-]{8,}/gu, "[REDACTED]").replace(/:\/\/[^:/@\s]+:[^@\s]+@/gu, "://[REDACTED]@");
+	let flattened = "";
+	let previousWasControl = false;
+	for (const character of redacted) {
+		const codePoint = character.codePointAt(0) ?? 0;
+		const isControl = codePoint < 32 || codePoint === 127;
+		if (isControl) {
+			if (!previousWasControl) flattened += " ";
+		} else flattened += character;
+		previousWasControl = isControl;
+	}
+	return flattened;
+}
+//#endregion
 //#region src/bin.ts
-require_index.main({ profile: require_index.parseProfileArg(process.argv.slice(2)) });
+runCli(process.argv.slice(2));
 //#endregion

package/dist/bin.js

@@ -1,7 +1,53 @@
 #!/usr/bin/env node
 import { main, parseProfileArg } from "./index.js";
+//#region src/cli.ts
+const MAX_ERROR_CHARS = 4096;
+/**
+* Own the executable-only process policy around the reusable MCP server.
+* Startup failures set a non-zero exit code after writing a redacted diagnostic;
+* SIGINT/SIGTERM close the transport before terminating the child process.
+*/
+async function runCli(argv, dependencies = {}, runtime = process) {
+	const start = dependencies.start ?? main;
+	let server;
+	try {
+		server = await start({ profile: parseProfileArg(argv) });
+	} catch (error) {
+		runtime.stderr.write(`[alfe-mcp-server] failed to start: ${safeErrorMessage(error)}\n`);
+		runtime.exitCode = 1;
+		return;
+	}
+	let shutdownPromise;
+	const shutdown = () => {
+		if (shutdownPromise) return;
+		runtime.off("SIGINT", shutdown);
+		runtime.off("SIGTERM", shutdown);
+		shutdownPromise = server.close().catch((error) => {
+			runtime.stderr.write(`[alfe-mcp-server] failed to close cleanly: ${safeErrorMessage(error)}\n`);
+		}).then(() => {
+			runtime.exit(0);
+		});
+	};
+	runtime.once("SIGINT", shutdown);
+	runtime.once("SIGTERM", shutdown);
+}
+function safeErrorMessage(error) {
+	const redacted = (error instanceof Error ? error.message : String(error)).slice(0, MAX_ERROR_CHARS).replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/giu, "$1 [REDACTED]").replace(/\b(api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password)\s*[=:]\s*[^\s,;]+/giu, "$1=[REDACTED]").replace(/\balfe_[A-Za-z0-9_-]{8,}/gu, "[REDACTED]").replace(/:\/\/[^:/@\s]+:[^@\s]+@/gu, "://[REDACTED]@");
+	let flattened = "";
+	let previousWasControl = false;
+	for (const character of redacted) {
+		const codePoint = character.codePointAt(0) ?? 0;
+		const isControl = codePoint < 32 || codePoint === 127;
+		if (isControl) {
+			if (!previousWasControl) flattened += " ";
+		} else flattened += character;
+		previousWasControl = isControl;
+	}
+	return flattened;
+}
+//#endregion
 //#region src/bin.ts
-main({ profile: parseProfileArg(process.argv.slice(2)) });
+runCli(process.argv.slice(2));
 //#endregion
 export {};
 

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","names":[],"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { main, parseProfileArg } from './index.js';\n\n// The OpenClaw daemon bundler launches this bin with no args → `default`\n// profile (integrations only, unchanged). The Alfe CLI launches it as\n// `node <bin> --profile claude-code` for a Claude Code session → memory +\n// voice + messaging tools on top.\nvoid main({ profile: parseProfileArg(process.argv.slice(2)) });\n"],"mappings":";;;AAOK,KAAK,EAAE,SAAS,gBAAgB,QAAQ,KAAK,MAAM,EAAE,CAAC,EAAE,CAAC"}
+{"version":3,"file":"bin.js","names":[],"sources":["../src/cli.ts","../src/bin.ts"],"sourcesContent":["import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { main, parseProfileArg } from './index.js';\n\nconst MAX_ERROR_CHARS = 4096;\n\ninterface CliRuntime {\n  stderr: { write(message: string): unknown };\n  once(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;\n  off(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;\n  exit(code?: number): unknown;\n  exitCode?: string | number | null;\n}\n\ninterface CliDependencies {\n  start?: typeof main;\n}\n\n/**\n * Own the executable-only process policy around the reusable MCP server.\n * Startup failures set a non-zero exit code after writing a redacted diagnostic;\n * SIGINT/SIGTERM close the transport before terminating the child process.\n */\nexport async function runCli(\n  argv: string[],\n  dependencies: CliDependencies = {},\n  runtime: CliRuntime = process,\n): Promise<void> {\n  const start = dependencies.start ?? main;\n  let server: McpServer;\n  try {\n    server = await start({ profile: parseProfileArg(argv) });\n  } catch (error: unknown) {\n    runtime.stderr.write(`[alfe-mcp-server] failed to start: ${safeErrorMessage(error)}\\n`);\n    runtime.exitCode = 1;\n    return;\n  }\n\n  let shutdownPromise: Promise<void> | undefined;\n  const shutdown = (): void => {\n    if (shutdownPromise) return;\n    runtime.off('SIGINT', shutdown);\n    runtime.off('SIGTERM', shutdown);\n    shutdownPromise = server.close()\n      .catch((error: unknown) => {\n        runtime.stderr.write(`[alfe-mcp-server] failed to close cleanly: ${safeErrorMessage(error)}\\n`);\n      })\n      .then(() => {\n        runtime.exit(0);\n      });\n  };\n  runtime.once('SIGINT', shutdown);\n  runtime.once('SIGTERM', shutdown);\n}\n\nexport function safeErrorMessage(error: unknown): string {\n  const redacted = (error instanceof Error ? error.message : String(error))\n    .slice(0, MAX_ERROR_CHARS)\n    .replace(/\\b(Bearer|Basic)\\s+[A-Za-z0-9._~+/=-]+/giu, '$1 [REDACTED]')\n    .replace(\n      /\\b(api[_-]?key|access[_-]?token|refresh[_-]?token|secret|password)\\s*[=:]\\s*[^\\s,;]+/giu,\n      '$1=[REDACTED]',\n    )\n    .replace(/\\balfe_[A-Za-z0-9_-]{8,}/gu, '[REDACTED]')\n    .replace(/:\\/\\/[^:/@\\s]+:[^@\\s]+@/gu, '://[REDACTED]@');\n  let flattened = '';\n  let previousWasControl = false;\n  for (const character of redacted) {\n    const codePoint = character.codePointAt(0) ?? 0;\n    const isControl = codePoint < 32 || codePoint === 127;\n    if (isControl) {\n      if (!previousWasControl) flattened += ' ';\n    } else {\n      flattened += character;\n    }\n    previousWasControl = isControl;\n  }\n  return flattened;\n}\n","#!/usr/bin/env node\nimport { runCli } from './cli.js';\n\n// The OpenClaw daemon bundler launches this bin with no args → `default`\n// profile (integrations only, unchanged). The Alfe CLI launches it as\n// `node <bin> --profile claude-code` for a Claude Code session → memory +\n// voice + messaging tools on top.\nvoid runCli(process.argv.slice(2));\n"],"mappings":";;;AAGA,MAAM,kBAAkB;;;;;;AAmBxB,eAAsB,OACpB,MACA,eAAgC,EAAE,EAClC,UAAsB,SACP;CACf,MAAM,QAAQ,aAAa,SAAS;CACpC,IAAI;AACJ,KAAI;AACF,WAAS,MAAM,MAAM,EAAE,SAAS,gBAAgB,KAAK,EAAE,CAAC;UACjD,OAAgB;AACvB,UAAQ,OAAO,MAAM,sCAAsC,iBAAiB,MAAM,CAAC,IAAI;AACvF,UAAQ,WAAW;AACnB;;CAGF,IAAI;CACJ,MAAM,iBAAuB;AAC3B,MAAI,gBAAiB;AACrB,UAAQ,IAAI,UAAU,SAAS;AAC/B,UAAQ,IAAI,WAAW,SAAS;AAChC,oBAAkB,OAAO,OAAO,CAC7B,OAAO,UAAmB;AACzB,WAAQ,OAAO,MAAM,8CAA8C,iBAAiB,MAAM,CAAC,IAAI;IAC/F,CACD,WAAW;AACV,WAAQ,KAAK,EAAE;IACf;;AAEN,SAAQ,KAAK,UAAU,SAAS;AAChC,SAAQ,KAAK,WAAW,SAAS;;AAGnC,SAAgB,iBAAiB,OAAwB;CACvD,MAAM,YAAY,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,EACrE,MAAM,GAAG,gBAAgB,CACzB,QAAQ,6CAA6C,gBAAgB,CACrE,QACC,2FACA,gBACD,CACA,QAAQ,8BAA8B,aAAa,CACnD,QAAQ,6BAA6B,iBAAiB;CACzD,IAAI,YAAY;CAChB,IAAI,qBAAqB;AACzB,MAAK,MAAM,aAAa,UAAU;EAChC,MAAM,YAAY,UAAU,YAAY,EAAE,IAAI;EAC9C,MAAM,YAAY,YAAY,MAAM,cAAc;AAClD,MAAI;OACE,CAAC,mBAAoB,cAAa;QAEtC,cAAa;AAEf,uBAAqB;;AAEvB,QAAO;;;;ACrEJ,OAAO,QAAQ,KAAK,MAAM,EAAE,CAAC"}

package/dist/index.cjs

@@ -8,6 +8,8 @@ let _alfe_ai_config = require("@alfe.ai/config");
 let _alfe_ai_mcp_tools = require("@alfe.ai/mcp-tools");
 //#region src/index.ts
 const pkg = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json");
+const MAX_IDENTITY_CHARS = 256;
+const MAX_SERVICE_URL_CHARS = 8192;
 /**
 * Wire shape the bundler advertises this server as — must match the
 * key the CLI registers (`alfe-platform`) so namespacing is consistent
@@ -39,30 +41,44 @@ const SERVER_BIN_PATH = (0, node_url.fileURLToPath)(new URL("./bin.js", require(
 * Pure construction — does not connect a transport. Callers (the bin
 * entry, or tests) attach `StdioServerTransport` or any other transport.
 *
-* `resolveConfig()` is only called when neither `client` nor `apiUrl`
-* is provided — tests can fully construct the server without touching
-* `~/.alfe/config.toml`.
+* `resolveConfig()` is only called when the main `client`/`apiUrl` pair is
+* omitted. Tests and alternate hosts can inject a complete pair without
+* touching `~/.alfe/config.toml`.
 */
 async function createServer(opts = {}) {
-	const profile = opts.profile ?? "default";
-	let client = opts.client;
-	let apiUrl = opts.apiUrl;
+	const profile = validateProfile(opts.profile ?? "default");
+	if (opts.client !== void 0 !== (opts.apiUrl !== void 0)) throw new Error("client and apiUrl must be provided together.");
+	let client;
+	let apiUrl;
 	let voiceClient = opts.voiceClient;
 	let voiceApiUrl = opts.voiceApiUrl;
-	if (!client || !apiUrl || profile === "claude-code" && !voiceClient && !voiceApiUrl) {
-		const cfg = (0, _alfe_ai_config.resolveConfig)();
-		client = client ?? new _alfe_ai_agent_api_client.AgentApiClient({
+	let config;
+	const getConfig = () => {
+		config ??= (0, _alfe_ai_config.resolveConfig)();
+		return config;
+	};
+	if (opts.client !== void 0 && opts.apiUrl !== void 0) {
+		client = opts.client;
+		apiUrl = validateServiceUrl("apiUrl", opts.apiUrl);
+	} else {
+		const cfg = getConfig();
+		apiUrl = validateServiceUrl("apiUrl", cfg.apiUrl);
+		client = new _alfe_ai_agent_api_client.AgentApiClient({
 			apiKey: cfg.apiKey,
-			apiUrl: cfg.apiUrl
+			apiUrl
 		});
-		apiUrl = apiUrl ?? cfg.apiUrl;
-		voiceApiUrl = voiceApiUrl ?? cfg.voiceServiceUrl;
-		voiceClient = voiceClient ?? new _alfe_ai_agent_api_client.AgentApiClient({
-			apiKey: cfg.apiKey,
-			apiUrl: cfg.voiceServiceUrl
+	}
+	if (profile === "claude-code") {
+		const explicitVoiceUrl = voiceApiUrl !== void 0;
+		voiceApiUrl = validateServiceUrl("voiceApiUrl", voiceApiUrl ?? config?.voiceServiceUrl ?? apiUrl);
+		if (!voiceClient) if (voiceApiUrl === apiUrl) voiceClient = client;
+		else if (!explicitVoiceUrl) voiceClient = new _alfe_ai_agent_api_client.AgentApiClient({
+			apiKey: getConfig().apiKey,
+			apiUrl: voiceApiUrl
 		});
+		else throw new Error("voiceClient is required when voiceApiUrl differs from apiUrl.");
 	}
-	const identity = opts.identity ?? await client.whoami();
+	const identity = validateIdentity(opts.identity ?? await client.whoami());
 	const ctx = {
 		client,
 		apiUrl,
@@ -100,23 +116,57 @@ function parseProfileArg(argv) {
 	return "default";
 }
 /**
-* Entry point — boot the server on stdio. Used by `bin.ts`. Any
-* startup failure is fatal: log and exit non-zero so the bundler's
-* connection attempt surfaces a clear error rather than a hung
-* handshake.
+* Boot the server and attach its transport. Used by `bin.ts`; tests can inject
+* an in-memory transport. Process policy (logging, exit code, signals) remains
+* in the executable boundary rather than this reusable library function.
 */
 async function main(opts = {}) {
+	const { transport = new _modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport(), ...serverOptions } = opts;
+	const server = await createServer(serverOptions);
 	try {
-		const server = await createServer({ profile: opts.profile });
-		const transport = new _modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport();
 		await server.connect(transport);
+		return server;
 	} catch (err) {
-		process.stderr.write(`[alfe-mcp-server] failed to start: ${errMsg(err)}\n`);
-		process.exit(1);
+		await server.close().catch(() => void 0);
+		throw err;
+	}
+}
+function validateProfile(value) {
+	if (value !== "default" && value !== "claude-code") throw new Error("profile must be \"default\" or \"claude-code\".");
+	return value;
+}
+function validateIdentity(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Agent identity must be an object.");
+	const record = value;
+	return {
+		agentId: validateIdentityPart("agentId", record.agentId),
+		tenantId: validateIdentityPart("tenantId", record.tenantId)
+	};
+}
+function validateIdentityPart(label, value) {
+	if (typeof value !== "string" || value.length < 1 || value.length > MAX_IDENTITY_CHARS || hasControlCharacters(value)) throw new Error(`${label} must contain 1 to ${String(MAX_IDENTITY_CHARS)} non-control characters.`);
+	return value;
+}
+function hasControlCharacters(value) {
+	return Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint < 32 || codePoint === 127;
+	});
+}
+function validateServiceUrl(label, value) {
+	if (typeof value !== "string" || value.length < 1 || value.length > MAX_SERVICE_URL_CHARS) throw new Error(`${label} must be a bounded absolute HTTP(S) URL.`);
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		throw new Error(`${label} must be a bounded absolute HTTP(S) URL.`);
 	}
+	if (!["http:", "https:"].includes(parsed.protocol) || parsed.username !== "" || parsed.password !== "" || parsed.search !== "" || parsed.hash !== "" || parsed.protocol === "http:" && !isLoopbackHostname(parsed.hostname)) throw new Error(`${label} must use HTTPS (or loopback HTTP) without credentials, query, or fragment.`);
+	return parsed.href.replace(/\/$/u, "");
 }
-function errMsg(err) {
-	return err instanceof Error ? err.message : String(err);
+function isLoopbackHostname(hostname) {
+	const normalized = hostname.replace(/^\[|\]$/gu, "").toLowerCase();
+	return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
 }
 //#endregion
 exports.SERVER_BIN_PATH = SERVER_BIN_PATH;