@alfe.ai/github-mcp 0.3.18 → 0.3.20

package/README.md

@@ -2,6 +2,18 @@
 
 GitHub MCP proxy server — bridges the official @modelcontextprotocol/server-github with Alfe OAuth credentials (Pattern A multi-account)
 
+The proxy starts one pinned child process per connected GitHub account.
+Every provider tool requires the lowercase `login` returned by
+`github_list_accounts`, so the caller chooses the exact OAuth identity
+instead of relying on an implicit default. `github_check_connection`
+verifies both token validity and token-to-login identity.
+
+The child receives only its GitHub token and a small runtime/TLS/proxy
+environment allowlist. Tool catalogs, arguments, results, health probes,
+errors, startup, calls, and shutdown are validated and bounded at the
+proxy boundary. With no connected accounts the server remains available
+in discovery-only mode.
+
 Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: build, deploy, and run agents with persistent memory, identity, integrations, and channels. See the [documentation](https://docs.alfe.ai) to get started.
 
 ## Install
@@ -10,6 +22,10 @@ Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: buil
 npm install @alfe.ai/github-mcp
 ```
 
+The production integration invokes this package through `npx`; direct
+installation is primarily useful for package development. Agent API
+configuration must already be present in `~/.alfe/config.toml`.
+
 ## Links
 
 - 🌐 Website: <https://alfe.ai>

package/dist/server.js

@@ -1,308 +1,647 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { resolveConfig } from "@alfe.ai/config";
 import { AgentApiClient } from "@alfe.ai/agent-api-client";
 import { assertPatternA } from "@alfe.ai/mcp-bundler";
+import { createHash } from "node:crypto";
+const MAX_FORWARDED_ARGUMENT_BYTES = 2 * 1024 * 1024;
+const MAX_TOOL_RESULT_BYTES = 5 * 1024 * 1024;
+const MAX_SCHEMA_BYTES = 512 * 1024;
+const MAX_CHECK_RESPONSE_BYTES = 64 * 1024;
+const MAX_JSON_DEPTH = 12;
+const MAX_JSON_NODES = 3e4;
+const MAX_JSON_ARRAY_ITEMS = 2e3;
+const MAX_ARGUMENT_STRING_CHARS = 15e5;
+const MAX_TOKEN_CHARS = 16384;
+const MAX_ERROR_CHARS = 2048;
+const GITHUB_CHECK_TIMEOUT_MS = 15e3;
+const LOGIN_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/u;
+const TOOL_NAME_PATTERN = /^[A-Za-z0-9_.:-]{1,128}$/u;
+const UNSAFE_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const RESERVED_TOOLS = new Set(["github_list_accounts", "github_check_connection"]);
+const CHILD_ENV_ALLOWLIST = [
+	"PATH",
+	"HOME",
+	"TMPDIR",
+	"TMP",
+	"TEMP",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"TZ",
+	"SSL_CERT_FILE",
+	"SSL_CERT_DIR",
+	"NODE_EXTRA_CA_CERTS",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"NO_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"no_proxy",
+	"NPM_CONFIG_CACHE",
+	"XDG_CACHE_HOME"
+];
+const READ_ONLY_TOOLS = new Set([
+	"search_repositories",
+	"get_file_contents",
+	"list_commits",
+	"list_issues",
+	"search_code",
+	"search_issues",
+	"search_users",
+	"get_issue",
+	"get_pull_request",
+	"list_pull_requests",
+	"get_pull_request_files",
+	"get_pull_request_status",
+	"get_pull_request_comments",
+	"get_pull_request_reviews"
+]);
+const DESTRUCTIVE_TOOLS = new Set(["merge_pull_request"]);
+function buildChildEnvironment(accessToken, source = process.env) {
+	const token = validateAccessToken(accessToken);
+	const environment = Object.create(null);
+	for (const name of CHILD_ENV_ALLOWLIST) {
+		const value = source[name];
+		if (value !== void 0 && !containsControlCharacter(value)) environment[name] = value;
+	}
+	return {
+		...environment,
+		GITHUB_PERSONAL_ACCESS_TOKEN: token
+	};
+}
+function normalizeGitHubAccount(value) {
+	if (!isRecord(value)) throw new Error("GitHub account must be an object");
+	return {
+		connectionId: validateText("connectionId", value.connectionId, 128),
+		displayName: value.displayName === null ? null : validateText("display name", value.displayName, 256),
+		connectedAt: validateConnectedAt(value.connectedAt),
+		accessToken: validateAccessToken(value.accessToken),
+		login: normalizeGitHubLogin(value.login)
+	};
+}
+function assertAccountCount(value) {
+	if (!Array.isArray(value)) throw new Error("GitHub accounts response must be an array");
+	if (value.length > 50) throw new Error(`GitHub accounts response exceeds ${String(50)} accounts`);
+}
+function injectLoginSelector(tool) {
+	const name = validateToolName(tool.name);
+	if (RESERVED_TOOLS.has(name)) throw new Error(`Child tool collides with reserved proxy tool: ${name}`);
+	const original = cloneJsonRecord("tool input schema", tool.inputSchema, MAX_SCHEMA_BYTES, 1e5);
+	const propertiesValue = Reflect.get(original, "properties");
+	const originalProperties = propertiesValue === void 0 ? Object.create(null) : cloneJsonRecord("tool schema properties", propertiesValue, MAX_SCHEMA_BYTES, 1e5);
+	const originalRequired = validateRequired(Reflect.get(original, "required"));
+	const result = {
+		name,
+		inputSchema: {
+			...original,
+			type: "object",
+			properties: {
+				...originalProperties,
+				login: {
+					type: "string",
+					pattern: LOGIN_PATTERN.source,
+					maxLength: 39,
+					description: "Lowercase GitHub username from github_list_accounts. This required selector chooses the exact connected OAuth identity; owner/repo still choose the repository target."
+				}
+			},
+			required: [...new Set(["login", ...originalRequired])]
+		}
+	};
+	if (tool.title !== void 0) result.title = validateText("tool title", tool.title, 256);
+	if (tool.description !== void 0) result.description = validateText("tool description", tool.description, 2e4);
+	if (tool.outputSchema !== void 0) result.outputSchema = cloneJsonRecord("tool output schema", tool.outputSchema, MAX_SCHEMA_BYTES, 1e5);
+	if (tool.annotations !== void 0) result.annotations = validateAnnotations(tool.annotations);
+	else result.annotations = {
+		readOnlyHint: READ_ONLY_TOOLS.has(name),
+		destructiveHint: DESTRUCTIVE_TOOLS.has(name),
+		openWorldHint: true
+	};
+	if (tool.execution !== void 0) result.execution = validateExecution(tool.execution);
+	return result;
+}
+function validateToolCatalog(tools) {
+	if (!Array.isArray(tools)) throw new Error("Child tool catalog must be an array");
+	if (tools.length > 100) throw new Error(`Child tool catalog exceeds ${String(100)} tools`);
+	const names = /* @__PURE__ */ new Set();
+	return tools.map((tool) => {
+		if (!isRecord(tool)) throw new Error("Child tool descriptor must be an object");
+		const proxied = injectLoginSelector(tool);
+		if (names.has(proxied.name)) throw new Error(`Child tool catalog contains duplicate name: ${proxied.name}`);
+		names.add(proxied.name);
+		return proxied;
+	});
+}
+function prepareForwardedArguments(value) {
+	const cloned = cloneJsonRecord("tool arguments", value, MAX_FORWARDED_ARGUMENT_BYTES, MAX_ARGUMENT_STRING_CHARS);
+	const loginValue = cloned.login;
+	if (typeof loginValue !== "string") throw new Error("login must be a string");
+	const login = normalizeGitHubLogin(loginValue);
+	const { login: _selector, ...forwarded } = cloned;
+	return {
+		login,
+		forwarded
+	};
+}
+function assertBoundedToolArguments(value) {
+	return cloneJsonRecord("tool arguments", value, MAX_FORWARDED_ARGUMENT_BYTES, MAX_ARGUMENT_STRING_CHARS);
+}
+function assertBoundedToolResult(value) {
+	assertJsonBudget("child tool result", value, MAX_TOOL_RESULT_BYTES, MAX_TOOL_RESULT_BYTES);
+	return value;
+}
+function extractToolErrorText(value) {
+	if (!isRecord(value) || !Array.isArray(value.content)) return "";
+	return value.content.slice(0, 100).map((content) => isRecord(content) && typeof content.text === "string" ? content.text.slice(0, MAX_ERROR_CHARS) : "").join("\n").slice(0, MAX_ERROR_CHARS);
+}
+async function checkGitHubConnection(accessToken, fetchFn = fetch) {
+	const response = await fetchFn("https://api.github.com/user", {
+		headers: {
+			Authorization: `Bearer ${validateAccessToken(accessToken)}`,
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28",
+			"User-Agent": "alfe-github-mcp"
+		},
+		redirect: "error",
+		signal: AbortSignal.timeout(GITHUB_CHECK_TIMEOUT_MS)
+	});
+	if (!response.ok) {
+		await response.body?.cancel().catch(() => void 0);
+		return {
+			ok: false,
+			status: response.status
+		};
+	}
+	const text = await readResponseText(response, MAX_CHECK_RESPONSE_BYTES);
+	const parsed = JSON.parse(text);
+	if (!isRecord(parsed)) throw new Error("GitHub /user response must be an object");
+	const id = parsed.id;
+	if (typeof id !== "number" || !Number.isSafeInteger(id) || id < 1) throw new Error("GitHub /user response contains an invalid id");
+	const name = parsed.name;
+	return {
+		ok: true,
+		status: response.status,
+		user: {
+			login: normalizeGitHubLogin(parsed.login),
+			id,
+			name: name === null || name === void 0 ? null : validateText("GitHub user name", name, 256)
+		}
+	};
+}
+function normalizeGitHubLogin(value) {
+	if (typeof value !== "string" || !LOGIN_PATTERN.test(value)) throw new Error("login must be a valid GitHub username of at most 39 characters");
+	return value.toLowerCase();
+}
+function safeErrorMessage(error, secrets = []) {
+	let message = error instanceof Error ? error.message : String(error);
+	for (const secret of secrets) if (secret.length > 0) message = message.split(secret).join("[REDACTED]");
+	return message.replace(/Bearer\s+[^\s,;]+/giu, "Bearer [REDACTED]").replace(/(?:gh[opusr]_[A-Za-z0-9_]{16,}|github_pat_[A-Za-z0-9_]{16,})/gu, "[REDACTED_GITHUB_TOKEN]").replace(/alfe_(?:dev|test|demo|live)_[a-f0-9]{16,}/giu, "[REDACTED_ALFE_KEY]").slice(0, MAX_ERROR_CHARS);
+}
+function connectionLogId(value) {
+	return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+async function withDeadline(promise, timeoutMs, label) {
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`${label} timed out`));
+			}, timeoutMs);
+			timer.unref();
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+function validateAccessToken(value) {
+	if (typeof value !== "string" || value.length < 1 || value.length > MAX_TOKEN_CHARS || containsControlCharacter(value)) throw new Error("GitHub access token is invalid");
+	return value;
+}
+function validateConnectedAt(value) {
+	const validated = validateText("connectedAt", value, 64);
+	const parsed = new Date(validated);
+	if (Number.isNaN(parsed.valueOf()) || parsed.toISOString() !== validated) throw new Error("connectedAt must be a canonical ISO date-time");
+	return validated;
+}
+function validateToolName(value) {
+	if (typeof value !== "string" || !TOOL_NAME_PATTERN.test(value)) throw new Error("Child tool name is invalid");
+	return value;
+}
+function validateText(label, value, maxChars) {
+	if (typeof value !== "string" || value.length < 1 || value.length > maxChars || containsControlCharacter(value)) throw new Error(`${label} must contain 1 to ${String(maxChars)} non-control characters`);
+	return value;
+}
+function validateRequired(value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.length > 100) throw new Error("tool schema required must be an array");
+	const result = [];
+	for (const entry of value) {
+		if (typeof entry !== "string" || entry.length < 1 || entry.length > 128) throw new Error("tool schema required contains an invalid property name");
+		if (!result.includes(entry)) result.push(entry);
+	}
+	return result;
+}
+function validateAnnotations(value) {
+	if (!isRecord(value)) throw new Error("tool annotations must be an object");
+	const result = {};
+	const title = value.title;
+	if (title !== void 0) result.title = validateText("tool annotation title", title, 256);
+	for (const key of [
+		"readOnlyHint",
+		"destructiveHint",
+		"idempotentHint",
+		"openWorldHint"
+	]) {
+		const hint = value[key];
+		if (hint !== void 0) {
+			if (typeof hint !== "boolean") throw new Error(`tool annotation ${key} must be boolean`);
+			result[key] = hint;
+		}
+	}
+	return result;
+}
+function validateExecution(value) {
+	if (!isRecord(value)) throw new Error("tool execution metadata must be an object");
+	const taskSupport = Reflect.get(value, "taskSupport");
+	if (taskSupport !== void 0 && taskSupport !== "optional" && taskSupport !== "required" && taskSupport !== "forbidden") throw new Error("tool execution taskSupport is invalid");
+	return taskSupport === void 0 ? {} : { taskSupport };
+}
+async function readResponseText(response, maxBytes) {
+	const declared = response.headers.get("content-length");
+	if (declared !== null && (!/^\d+$/u.test(declared) || Number(declared) > maxBytes)) {
+		await response.body?.cancel().catch(() => void 0);
+		throw new Error("GitHub /user response exceeds the byte limit");
+	}
+	if (response.body === null) return "";
+	const reader = response.body.getReader();
+	const decoder = new TextDecoder();
+	let bytes = 0;
+	let text = "";
+	try {
+		for (;;) {
+			const readResult = await reader.read();
+			if (readResult.done) break;
+			const chunk = readResult.value;
+			if (chunk === void 0) throw new Error("GitHub /user response stream returned no bytes");
+			bytes += chunk.byteLength;
+			if (bytes > maxBytes) {
+				await reader.cancel("response too large").catch(() => void 0);
+				throw new Error("GitHub /user response exceeds the byte limit");
+			}
+			text += decoder.decode(chunk, { stream: true });
+		}
+		text += decoder.decode();
+		return text;
+	} finally {
+		reader.releaseLock();
+	}
+}
+function cloneJsonRecord(label, value, maxBytes, maxStringChars) {
+	if (!isRecord(value)) throw new Error(`${label} must be an object`);
+	const cloned = cloneRecord(label, value, 0, { nodes: 0 }, maxStringChars);
+	if (Buffer.byteLength(JSON.stringify(cloned), "utf8") > maxBytes) throw new Error(`${label} exceeds the ${String(maxBytes)} byte limit`);
+	return cloned;
+}
+function assertJsonBudget(label, value, maxBytes, maxStringChars) {
+	cloneJson(label, value, 0, { nodes: 0 }, maxStringChars);
+	let encoded;
+	try {
+		encoded = JSON.stringify(value);
+	} catch {
+		throw new Error(`${label} must be JSON serializable`);
+	}
+	if (Buffer.byteLength(encoded, "utf8") > maxBytes) throw new Error(`${label} exceeds the ${String(maxBytes)} byte limit`);
+}
+function cloneJson(label, value, depth, budget, maxStringChars) {
+	budget.nodes += 1;
+	if (budget.nodes > MAX_JSON_NODES) throw new Error(`${label} contains too many values`);
+	if (depth > MAX_JSON_DEPTH) throw new Error(`${label} exceeds the JSON depth limit`);
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite number`);
+		return value;
+	}
+	if (typeof value === "string") {
+		if (value.length > maxStringChars) throw new Error(`${label} contains an oversized string`);
+		return value;
+	}
+	if (Array.isArray(value)) {
+		if (value.length > MAX_JSON_ARRAY_ITEMS) throw new Error(`${label} contains an oversized array`);
+		return value.map((entry) => cloneJson(label, entry, depth + 1, budget, maxStringChars));
+	}
+	if (!isRecord(value)) throw new Error(`${label} contains a non-JSON value`);
+	return cloneRecord(label, value, depth, budget, maxStringChars);
+}
+function cloneRecord(label, value, depth, budget, maxStringChars) {
+	const result = Object.create(null);
+	for (const [key, nested] of Object.entries(value)) {
+		if (key.length < 1 || key.length > 256 || UNSAFE_KEYS.has(key)) throw new Error(`${label} contains an unsafe property name`);
+		result[key] = cloneJson(label, nested, depth + 1, budget, maxStringChars);
+	}
+	return result;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function containsControlCharacter(value) {
+	return Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint < 32 || codePoint === 127;
+	});
+}
+//#endregion
 //#region src/server.ts
 /**
 * GitHub MCP Proxy Server (Pattern A multi-account)
 *
-* A thin proxy that fans out to one official
-* `@modelcontextprotocol/server-github` child process per connected
-* GitHub account. Every credential-touching tool requires the LLM to
-* pass a `login` selector arg (the GitHub username); the proxy strips
-* that arg, dispatches to the right child, and returns the result.
-*
-* Pattern A locked in PR 7-deferred slice 2 of channels-and-credential-
-* driven-integrations. See `packages/mcp-bundler/DEVELOPING.md` for the
-* contract; `services/connect/DEVELOPING.md` for the provider table.
-*
-* Architecture:
-*   OpenClaw ←(stdio)→ this proxy ←(stdio fan-out)→ N × server-github
-*
-* Token model:
-*   GitHub OAuth App tokens have no expiry (`tokenLifecycle: "no_expiry"`
-*   in services/connect's GitHub provider). There is intentionally no
-*   token-refresh path — a revoked token surfaces as a 401 on the next
-*   call and the LLM can prompt the user to reconnect.
-*
-* Known caveat — child dependency:
-*   `@modelcontextprotocol/server-github` is marked deprecated upstream
-*   ("Package no longer supported"). It still works at npm install
-*   time and is the same dependency the existing GitHub integration
-*   manifest invoked directly. Migrating to a native @octokit/rest
-*   tool surface is tracked as a v2 follow-up.
-*
-* Uses the low-level Server class (not McpServer) because child tools
-* return JSON Schema objects — McpServer.registerTool requires Zod.
+* OpenClaw communicates with this process over stdio. The proxy owns one
+* pinned `@modelcontextprotocol/server-github` child per connected GitHub
+* identity and injects a required, lowercase `login` selector into every
+* credential-touching tool.
 */
+const packageMetadata = createRequire(import.meta.url)("../package.json");
+const CHILD_PACKAGE = "@modelcontextprotocol/server-github";
+const childVersion = packageMetadata.dependencies?.[CHILD_PACKAGE];
+if (childVersion === void 0 || !/^\d{4}\.\d+\.\d+$/u.test(childVersion)) throw new Error(`${CHILD_PACKAGE} must have one exact calendar-version dependency`);
+const CHILD_SPECIFIER = `${CHILD_PACKAGE}@${childVersion}`;
+const CHILD_START_TIMEOUT_MS = 3e4;
+const CHILD_CATALOG_TIMEOUT_MS = 15e3;
+const CHILD_CALL_TIMEOUT_MS = 6e4;
+const CHILD_CLOSE_TIMEOUT_MS = 5e3;
 const accounts = /* @__PURE__ */ new Map();
-/**
-* Full snapshot of every GitHub connection returned by getGithubAccounts(),
-* including ones we couldn't spawn a child for (e.g. missing access token
-* or spawn failure). `github_list_accounts` returns this so the LLM can
-* surface partial-failure connections instead of silently dropping them.
-*/
+const claimedLogins = /* @__PURE__ */ new Map();
 const allAccountsSnapshot = [];
-/** Cached, selector-injected tool list returned to OpenClaw. */
+const catalogToolNames = /* @__PURE__ */ new Set();
 let cachedTools = [];
-function log(msg) {
-	process.stderr.write(`[github-mcp-proxy] ${msg}\n`);
+let proxyServer = null;
+let shutdownPromise = null;
+function log(message) {
+	process.stderr.write(`[github-mcp-proxy] ${message}\n`);
+}
+function errorResult(error, context = {}, secrets = []) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				...context,
+				error: safeErrorMessage(error, secrets)
+			})
+		}],
+		isError: true
+	};
 }
 function resolveAccount(login) {
-	if (!login) throw new Error("Missing required login argument. Call github_list_accounts to see the connected GitHub accounts and pass the login you want to target.");
-	const acct = accounts.get(login);
-	if (!acct) {
-		const known = allAccountsSnapshot.find((s) => s.login === login);
-		if (known && !known.connected) throw new Error(`login ${login} is connected on this agent but the proxy could not initialise a child server for it (reason: ${known.reason ?? "unknown"}). Ask the user to reconnect this GitHub account from the dashboard.`);
-		throw new Error(`Unknown login: ${login}. Call github_list_accounts to see the connected GitHub accounts on this agent.`);
-	}
-	return acct;
+	const account = accounts.get(login);
+	if (account !== void 0) return account;
+	const known = allAccountsSnapshot.find((summary) => summary.login === login);
+	if (known !== void 0) throw new Error(`login ${login} is connected on this agent but its credential process is unavailable (${known.reason ?? "unknown"}). Ask the user to reconnect this GitHub account from the dashboard.`);
+	throw new Error(`Unknown login: ${login}. Call github_list_accounts to see the connected GitHub accounts on this agent.`);
+}
+async function closeClient(client) {
+	await withDeadline(client.close(), CHILD_CLOSE_TIMEOUT_MS, "GitHub child close").catch(() => void 0);
 }
-/**
-* Pin the child server-github version to match `package.json` so a future
-* upstream republish (or removal — the package is deprecated) can't
-* silently rotate the child without our knowledge. `package.json` and
-* this string must stay in sync; the openclaw-github CI runs
-* `pnpm run pin:check` (TODO post-v0.1.0) to catch drift.
-*/
-const CHILD_SERVER_GITHUB_VERSION = "2025.4.8";
 async function spawnChild(accessToken) {
 	const transport = new StdioClientTransport({
 		command: "npx",
-		args: ["-y", `@modelcontextprotocol/server-github@${CHILD_SERVER_GITHUB_VERSION}`],
-		env: {
-			...process.env,
-			GITHUB_PERSONAL_ACCESS_TOKEN: accessToken
-		}
+		args: ["-y", CHILD_SPECIFIER],
+		env: buildChildEnvironment(accessToken)
 	});
 	const client = new Client({
 		name: "github-mcp-proxy",
-		version: "0.1.0"
+		version: packageMetadata.version
 	});
-	await client.connect(transport);
-	return client;
+	try {
+		await withDeadline(client.connect(transport), CHILD_START_TIMEOUT_MS, "GitHub child startup");
+		return client;
+	} catch (error) {
+		await closeClient(client);
+		throw error;
+	}
 }
-async function killAllChildren() {
-	for (const acct of accounts.values()) try {
-		await acct.client.close();
-	} catch {}
+async function closeAllChildren() {
+	const current = [...accounts.values()];
 	accounts.clear();
+	await Promise.all(current.map(async ({ client }) => closeClient(client)));
 }
-/**
-* Take a tool descriptor from the child GitHub MCP server and inject a
-* required `login` string property into its inputSchema. The proxy
-* strips this arg before forwarding the call.
-*/
-function injectLoginSelector(tool) {
-	const original = tool.inputSchema ?? {};
-	const originalProperties = original.properties ?? {};
-	const originalRequired = Array.isArray(original.required) ? original.required : [];
-	const injectedProperties = {
-		...originalProperties,
-		login: {
-			type: "string",
-			description: "GitHub username (login) — use the value from github_list_accounts to pick which connected account this call should target. Tool-level `owner` arguments still target a specific repo owner; `login` selects which OAuth identity makes the API call."
-		}
-	};
-	const injectedRequired = originalRequired.includes("login") ? originalRequired : ["login", ...originalRequired];
-	return {
-		name: tool.name,
-		description: tool.description,
-		inputSchema: {
-			...original,
-			type: original.type ?? "object",
-			properties: injectedProperties,
-			required: injectedRequired
+async function discoverChildCatalog() {
+	for (const account of accounts.values()) try {
+		const tools = validateToolCatalog((await withDeadline(account.client.listTools(), CHILD_CATALOG_TIMEOUT_MS, "GitHub child tool discovery")).tools);
+		for (const tool of tools) catalogToolNames.add(tool.name);
+		return tools;
+	} catch (error) {
+		log(`Tool discovery failed for connection ${connectionLogId(account.connectionId)}: ${safeErrorMessage(error, [account.accessToken])}`);
+	}
+	return [];
+}
+function appendLocalTools(tools) {
+	return [
+		...tools,
+		{
+			name: "github_list_accounts",
+			description: "List every connected GitHub account and its local proxy readiness. Use the lowercase login value as the selector on every other GitHub tool.",
+			inputSchema: {
+				type: "object",
+				properties: {},
+				additionalProperties: false
+			},
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: false
+			}
+		},
+		{
+			name: "github_check_connection",
+			description: "Verify that one selected GitHub OAuth token is valid and still belongs to the expected login. Revoked or identity-mismatched tokens must be reconnected.",
+			inputSchema: {
+				type: "object",
+				properties: { login: {
+					type: "string",
+					maxLength: 39,
+					description: "Lowercase GitHub username from github_list_accounts."
+				} },
+				required: ["login"],
+				additionalProperties: false
+			},
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true
+			}
 		}
-	};
+	];
 }
-async function main() {
-	const config = resolveConfig();
-	const { accounts: connected } = await new AgentApiClient({
-		apiKey: config.apiKey,
-		apiUrl: config.apiUrl
-	}).getGithubAccounts();
-	if (connected.length === 0) log("No GitHub accounts connected — proxy will start with github_list_accounts and github_check_connection only");
-	for (const acct of connected) {
-		if (!acct.accessToken) {
-			log(`Skipping account ${acct.login} — no access token`);
+async function loadAccounts(apiClient) {
+	const response = await apiClient.getGithubAccounts();
+	assertAccountCount(response.accounts);
+	if (response.accounts.length === 0) log("No GitHub accounts connected; starting in discovery-only mode");
+	for (const rawAccount of response.accounts) {
+		let account;
+		try {
+			account = normalizeGitHubAccount(rawAccount);
+		} catch (error) {
+			log(`Rejected invalid GitHub connection ${typeof rawAccount.connectionId === "string" ? connectionLogId(rawAccount.connectionId) : "invalid"}: ${safeErrorMessage(error)}`);
 			allAccountsSnapshot.push({
-				login: acct.login,
-				displayName: acct.displayName,
-				connectedAt: acct.connectedAt,
+				login: null,
+				displayName: null,
+				connectedAt: null,
 				connected: false,
-				reason: "missing_access_token"
+				reason: "invalid_account"
 			});
 			continue;
 		}
-		if (accounts.has(acct.login)) {
-			log(`Duplicate login ${acct.login} returned by getGithubAccounts() — keeping the first cached child`);
+		if (claimedLogins.has(account.login)) {
+			log(`Rejected duplicate GitHub login from connection ${connectionLogId(account.connectionId)}`);
+			allAccountsSnapshot.push({
+				login: account.login,
+				displayName: account.displayName,
+				connectedAt: account.connectedAt,
+				connected: false,
+				reason: "duplicate_login"
+			});
 			continue;
 		}
+		claimedLogins.set(account.login, account.connectionId);
 		try {
-			const client = await spawnChild(acct.accessToken);
-			accounts.set(acct.login, {
-				login: acct.login,
-				displayName: acct.displayName,
-				accessToken: acct.accessToken,
+			const client = await spawnChild(account.accessToken);
+			accounts.set(account.login, {
+				...account,
 				client
 			});
 			allAccountsSnapshot.push({
-				login: acct.login,
-				displayName: acct.displayName,
-				connectedAt: acct.connectedAt,
+				login: account.login,
+				displayName: account.displayName,
+				connectedAt: account.connectedAt,
 				connected: true
 			});
-			log(`Spawned child server for account ${acct.login} (${acct.displayName ?? "unnamed"})`);
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			log(`Failed to spawn child for account ${acct.login}: ${message}`);
+			log(`Spawned child for connection ${connectionLogId(account.connectionId)}`);
+		} catch (error) {
+			log(`Child startup failed for connection ${connectionLogId(account.connectionId)}: ${safeErrorMessage(error, [account.accessToken])}`);
 			allAccountsSnapshot.push({
-				login: acct.login,
-				displayName: acct.displayName,
-				connectedAt: acct.connectedAt,
+				login: account.login,
+				displayName: account.displayName,
+				connectedAt: account.connectedAt,
 				connected: false,
-				reason: `spawn_failed: ${message}`
+				reason: "spawn_failed"
 			});
 		}
 	}
-	const firstAccount = accounts.values().next().value;
-	if (firstAccount) {
-		const { tools } = await firstAccount.client.listTools();
-		cachedTools = tools.map(injectLoginSelector);
-		log(`Child MCP server provides ${String(cachedTools.length)} tools (selector injected)`);
-	} else {
-		cachedTools = [];
-		log("No child server available — only github_list_accounts and github_check_connection will be exposed");
+}
+async function handleToolCall(request) {
+	const { name } = request.params;
+	const args = request.params.arguments ?? {};
+	if (name === "github_list_accounts") {
+		const bounded = assertBoundedToolArguments(args);
+		if (Object.keys(bounded).length !== 0) return errorResult("github_list_accounts takes no arguments");
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({ accounts: allAccountsSnapshot }, null, 2)
+		}] };
+	}
+	if (name === "github_check_connection") try {
+		const { login, forwarded } = prepareForwardedArguments(args);
+		if (Object.keys(forwarded).length !== 0) throw new Error("github_check_connection accepts only login");
+		const result = await checkGitHubConnection(resolveAccount(login).accessToken);
+		if (!result.ok) return errorResult("Token may have been revoked. Ask the user to reconnect this GitHub account from the dashboard.", {
+			login,
+			connected: false,
+			status: result.status
+		});
+		if (result.user?.login !== login) return errorResult("The credential belongs to a different GitHub login. Reconnect this account before using it.", {
+			login,
+			connected: false,
+			reason: "identity_mismatch"
+		});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				login,
+				connected: true,
+				user: result.user
+			})
+		}] };
+	} catch (error) {
+		return errorResult(error);
 	}
-	cachedTools.push({
-		name: "github_list_accounts",
-		description: "List the GitHub accounts the agent has connected. Returns one entry per OAuth connection — use the returned login values as the `login` selector arg on every other GitHub tool.",
-		inputSchema: {
-			type: "object",
-			properties: {}
-		}
-	});
-	cachedTools.push({
-		name: "github_check_connection",
-		description: "Verify the GitHub OAuth connection for a specific connected account is still valid. Use this if GitHub API calls are failing with authentication errors. GitHub OAuth App tokens don't expire, so a failure here means the token was revoked.",
-		inputSchema: {
-			type: "object",
-			properties: { login: {
-				type: "string",
-				description: "GitHub username (login) — use the value from github_list_accounts."
-			} },
-			required: ["login"]
-		}
-	});
-	assertPatternA(cachedTools.map((t) => ({
-		name: t.name,
-		parameters: t.inputSchema
+	if (!catalogToolNames.has(name)) return errorResult(`Unknown GitHub tool: ${name}`);
+	let account;
+	let forwarded;
+	try {
+		const prepared = prepareForwardedArguments(args);
+		account = resolveAccount(prepared.login);
+		forwarded = prepared.forwarded;
+	} catch (error) {
+		return errorResult(error);
+	}
+	try {
+		const result = await withDeadline(account.client.callTool({
+			name,
+			arguments: forwarded
+		}), CHILD_CALL_TIMEOUT_MS, `GitHub ${name}`);
+		assertBoundedToolResult(result);
+		if (result.isError === true) return errorResult(extractToolErrorText(result) || "GitHub child tool returned an error", {
+			login: account.login,
+			tool: name
+		}, [account.accessToken]);
+		return result;
+	} catch (error) {
+		return errorResult(error, {
+			login: account.login,
+			tool: name
+		}, [account.accessToken]);
+	}
+}
+async function shutdown() {
+	if (shutdownPromise !== null) return shutdownPromise;
+	shutdownPromise = (async () => {
+		const server = proxyServer;
+		proxyServer = null;
+		await Promise.all([closeAllChildren(), server === null ? Promise.resolve() : withDeadline(server.close(), CHILD_CLOSE_TIMEOUT_MS, "GitHub proxy close").catch(() => void 0)]);
+	})();
+	return shutdownPromise;
+}
+async function main() {
+	const config = resolveConfig();
+	await loadAccounts(new AgentApiClient({
+		apiKey: config.apiKey,
+		apiUrl: config.apiUrl
+	}));
+	cachedTools = appendLocalTools(await discoverChildCatalog());
+	assertPatternA(cachedTools.map((tool) => ({
+		name: tool.name,
+		parameters: tool.inputSchema
 	})), {
 		selector: "login",
 		exempt: ["github_list_accounts"]
 	});
 	const proxy = new Server({
 		name: "github-mcp-proxy",
-		version: "0.1.0"
+		version: packageMetadata.version
 	}, { capabilities: { tools: {} } });
+	proxyServer = proxy;
 	proxy.setRequestHandler(ListToolsRequestSchema, () => ({ tools: cachedTools }));
-	proxy.setRequestHandler(CallToolRequestSchema, async (request) => {
-		const { name, arguments: args } = request.params;
-		const argMap = args ?? {};
-		if (name === "github_list_accounts") return { content: [{
-			type: "text",
-			text: JSON.stringify({ accounts: allAccountsSnapshot }, null, 2)
-		}] };
-		if (name === "github_check_connection") try {
-			const acct = resolveAccount(typeof argMap.login === "string" ? argMap.login : void 0);
-			const response = await fetch("https://api.github.com/user", { headers: {
-				Authorization: `Bearer ${acct.accessToken}`,
-				Accept: "application/vnd.github+json",
-				"X-GitHub-Api-Version": "2022-11-28",
-				"User-Agent": "alfe-openclaw-github"
-			} });
-			if (!response.ok) return {
-				content: [{
-					type: "text",
-					text: JSON.stringify({
-						login: acct.login,
-						connected: false,
-						status: response.status,
-						error: "Token may have been revoked. Ask the user to reconnect this GitHub account from the dashboard."
-					})
-				}],
-				isError: true
-			};
-			const user = await response.json();
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({
-					login: acct.login,
-					connected: true,
-					user
-				})
-			}] };
-		} catch (err) {
-			return {
-				content: [{
-					type: "text",
-					text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
-				}],
-				isError: true
-			};
-		}
-		let acct;
-		try {
-			acct = resolveAccount(typeof argMap.login === "string" ? argMap.login : void 0);
-		} catch (err) {
-			return {
-				content: [{
-					type: "text",
-					text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
-				}],
-				isError: true
-			};
-		}
-		const { login: _ignored, ...forwarded } = argMap;
-		try {
-			return await acct.client.callTool({
-				name,
-				arguments: forwarded
-			});
-		} catch (err) {
-			return {
-				content: [{
-					type: "text",
-					text: JSON.stringify({
-						login: acct.login,
-						tool: name,
-						error: err instanceof Error ? err.message : String(err)
-					})
-				}],
-				isError: true
-			};
-		}
-	});
-	const transport = new StdioServerTransport();
-	await proxy.connect(transport);
-	log(`Proxy running with ${String(accounts.size)} connected account(s) and Pattern A selector enforcement`);
+	proxy.setRequestHandler(CallToolRequestSchema, handleToolCall);
+	await proxy.connect(new StdioServerTransport());
+	log(`Proxy running with ${String(accounts.size)} live account(s) and ${String(catalogToolNames.size)} child tool(s)`);
 }
-for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => {
-	killAllChildren().then(() => {
-		process.exit(0);
-	});
+for (const signal of ["SIGTERM", "SIGINT"]) process.once(signal, () => {
+	shutdown().finally(() => process.exit(0));
 });
-main().catch((err) => {
-	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
-	killAllChildren().finally(() => {
-		process.exit(1);
-	});
+main().catch(async (error) => {
+	log(`Fatal: ${safeErrorMessage(error)}`);
+	await shutdown();
+	process.exit(1);
 });
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/github-mcp",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "GitHub MCP proxy server — bridges the official @modelcontextprotocol/server-github with Alfe OAuth credentials (Pattern A multi-account)",
   "type": "module",
   "main": "./dist/server.js",
@@ -19,9 +19,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": ">=1.24.0",
     "@modelcontextprotocol/server-github": "2025.4.8",
-    "@alfe.ai/config": "0.4.0",
-    "@alfe.ai/agent-api-client": "0.14.0",
-    "@alfe.ai/mcp-bundler": "0.4.0"
+    "@alfe.ai/config": "0.4.1",
+    "@alfe.ai/agent-api-client": "0.16.0",
+    "@alfe.ai/mcp-bundler": "0.4.1"
   },
   "license": "UNLICENSED",
   "homepage": "https://alfe.ai",
@@ -37,6 +37,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "lint": "eslint ."
   }