mono-pilot 0.2.9 → 0.2.10

package/README.md

@@ -48,6 +48,8 @@ If you pass `--tools`, MonoPilot removes built-in `edit`, `write`, `read`, `grep
 - `src/extensions/mono-pilot.ts` – extension entrypoint (tool wiring)
 - `src/extensions/system-prompt.ts` – provider-agnostic prompt stack
 - `src/extensions/user-message.ts` – user message envelope assembly
+- `src/mcp/` – config loading, JSON-RPC transport, server resolution
+- `src/rules/` – rule file discovery (shared by envelope and session hints)
 - `tools/` – tool implementations and descriptions (see `tools/README.md`)
 
 ## Cursor-styled tools
@@ -85,17 +87,20 @@ The full Cursor-styled tool list exposed by the extension:
 
 ## User rules
 
-MonoPilot can inject workspace user rules into the runtime envelope on each input (handled by `src/extensions/user-message.ts`).
+MonoPilot injects user rules into the runtime envelope on each turn (handled by `src/extensions/user-message.ts`).
 
-- Rules live in `.pi/rules/*.rule.txt` under the workspace root
-- Each file becomes one `<user_rule>` block wrapped by a `<rules>` envelope
-- Files are read in filename order; empty files are ignored
-- If no rules are present, the `<rules>` section is omitted
+Rules are loaded from two locations:
+
+- `~/.pi/rules/*.rule.txt` – user-level rules (applies to all projects)
+- `.pi/rules/*.rule.txt` – project-level rules (workspace root)
+
+When the same filename exists in both, the project rule wins. Each file becomes one `<user_rule>` block inside a `<rules>` envelope, sorted by filename. Empty files are ignored; the envelope is omitted if no rules are found.
 
 ## MCP
 
 - The user message envelope issues a lightweight MCP server `initialize` request to collect server instructions.
 - MCP tools then progressively load and surface resources, schemas, and execution only when needed.
+- MCP configs are loaded from `.pi/mcp.json` (project) and `~/.pi/mcp.json` (user); project entries take precedence on name conflicts.
 
 ## Local development
 

package/dist/src/extensions/session-hints.js

@@ -1,49 +1,42 @@
 import { existsSync, readFileSync } from "node:fs";
-import { readdir } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Text } from "@mariozechner/pi-tui";
 import { hasMessageEntries } from "./mode-runtime.js";
+import { isServerEnabled, loadMcpConfig } from "../mcp/config.js";
+import { toNonEmptyString } from "../mcp/config.js";
+import { discoverRules } from "../rules/discovery.js";
 const SESSION_HINTS_MESSAGE_TYPE = "SessionHints";
-const RULES_RELATIVE_DIR = join(".pi", "rules");
 const MONO_PILOT_NAME = "mono-pilot";
 const MAX_VERSION_SEARCH_DEPTH = 6;
 let cachedVersion = null;
-/** List *.rule.txt full paths from a directory (empty array if dir missing). */
-async function listRuleFiles(dirPath) {
-    if (!existsSync(dirPath))
-        return [];
+async function discoverMcpServers(cwd) {
+    let config;
     try {
-        const entries = await readdir(dirPath, { withFileTypes: true, encoding: "utf8" });
-        return entries
-            .filter((e) => e.isFile() && e.name.endsWith(".rule.txt"))
-            .map((e) => resolve(dirPath, e.name))
-            .sort((a, b) => a.localeCompare(b));
+        config = await loadMcpConfig(cwd);
     }
     catch {
-        return [];
+        return { userMcpServers: [], projectMcpServers: [] };
     }
-}
-/** Discover rules files grouped by scope, deduped by rule name. */
-async function discoverRules(cwd) {
-    const workspaceRulesDir = resolve(cwd, RULES_RELATIVE_DIR);
-    const userRulesDir = resolve(homedir(), RULES_RELATIVE_DIR);
-    const [workspaceRules, userRules] = await Promise.all([
-        listRuleFiles(workspaceRulesDir),
-        listRuleFiles(userRulesDir),
-    ]);
-    const seenNames = new Set();
-    const dedupeByName = (rules) => rules.filter((filePath) => {
-        const name = basename(filePath, ".rule.txt");
-        if (seenNames.has(name))
-            return false;
-        seenNames.add(name);
-        return true;
-    });
-    const uniqueWorkspaceRules = dedupeByName(workspaceRules);
-    const uniqueUserRules = dedupeByName(userRules);
-    return { userRules: uniqueUserRules, projectRules: uniqueWorkspaceRules };
+    if (!config)
+        return { userMcpServers: [], projectMcpServers: [] };
+    const groups = { user: [], project: [] };
+    for (const [serverName, serverConfig] of Object.entries(config.servers)) {
+        if (!isServerEnabled(serverConfig))
+            continue;
+        const source = config.sourceByServer[serverName];
+        if (!source)
+            continue;
+        groups[source.scope].push({ name: serverName, url: toNonEmptyString(serverConfig.url) });
+    }
+    for (const servers of Object.values(groups)) {
+        servers.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    return {
+        userMcpServers: groups.user,
+        projectMcpServers: groups.project,
+    };
 }
 function shortenHome(filePath) {
     const home = homedir();
@@ -94,8 +87,14 @@ export default function sessionHintsExtension(pi) {
         lines.push(theme.fg("dim", "option+m") + theme.fg("muted", " to cycle Plan/Ask/Agent mode"));
         const userRules = details?.userRules ?? [];
         const projectRules = details?.projectRules ?? [];
-        if (userRules.length > 0 || projectRules.length > 0) {
+        const userMcpServers = details?.userMcpServers ?? [];
+        const projectMcpServers = details?.projectMcpServers ?? [];
+        const hasRules = userRules.length > 0 || projectRules.length > 0;
+        const hasMcp = userMcpServers.length > 0 || projectMcpServers.length > 0;
+        if (hasRules || hasMcp) {
             lines.push("");
+        }
+        if (hasRules) {
             lines.push(theme.fg("mdHeading", "[Rules]"));
             if (userRules.length > 0) {
                 lines.push(`  ${theme.fg("accent", "user")}`);
@@ -110,6 +109,26 @@ export default function sessionHintsExtension(pi) {
                 }
             }
         }
+        if (hasRules && hasMcp) {
+            lines.push("");
+        }
+        if (hasMcp) {
+            lines.push(theme.fg("mdHeading", "[MCP Servers]"));
+            if (userMcpServers.length > 0) {
+                lines.push(`  ${theme.fg("accent", "user")}`);
+                for (const server of userMcpServers) {
+                    const urlPart = server.url ? `  ${theme.fg("muted", server.url)}` : "";
+                    lines.push(`    ${theme.fg("dim", server.name)}${urlPart}`);
+                }
+            }
+            if (projectMcpServers.length > 0) {
+                lines.push(`  ${theme.fg("accent", "project")}`);
+                for (const server of projectMcpServers) {
+                    const urlPart = server.url ? `  ${theme.fg("muted", server.url)}` : "";
+                    lines.push(`    ${theme.fg("dim", server.name)}${urlPart}`);
+                }
+            }
+        }
         return new Text(lines.join("\n"), 0, 0);
     });
     pi.on("session_start", async (_event, ctx) => {
@@ -118,7 +137,14 @@ export default function sessionHintsExtension(pi) {
         const entries = ctx.sessionManager.getEntries();
         if (hasMessageEntries(entries))
             return;
-        const details = await discoverRules(ctx.cwd);
+        const [rulesDetails, mcpDetails] = await Promise.all([
+            discoverRules(ctx.cwd),
+            discoverMcpServers(ctx.cwd),
+        ]);
+        const details = {
+            ...rulesDetails,
+            ...mcpDetails,
+        };
         pi.sendMessage({
             customType: SESSION_HINTS_MESSAGE_TYPE,
             content: "",

package/dist/src/extensions/user-message.js

@@ -1,14 +1,13 @@
-import { existsSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { buildRuntimeEnvelope, createModeStateData, modeRuntimeStore, MODE_STATE_ENTRY_TYPE, ASK_MODE_SWITCH_REMINDER, PLAN_MODE_STILL_ACTIVE_REMINDER, } from "./mode-runtime.js";
-import { createRpcRequestId, extractStringHeaders, isRecord, isServerEnabled, parseMcpConfig, postJsonRpcRequest, resolveMcpConfigPath, toNonEmptyString, MCP_PROTOCOL_VERSION, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, } from "../utils/mcp-client.js";
+import { createRpcRequestId, postJsonRpcRequest, MCP_PROTOCOL_VERSION, MCP_CLIENT_NAME, MCP_CLIENT_VERSION, } from "../mcp/protocol.js";
+import { extractStringHeaders, isRecord, isServerEnabled, loadMcpConfig, toNonEmptyString, } from "../mcp/config.js";
+import { discoverRules } from "../rules/discovery.js";
 const PLAN_MODE_REMINDER_PATH = fileURLToPath(new URL("../../tools/plan-mode-reminder.md", import.meta.url));
 const ASK_MODE_REMINDER_PATH = fileURLToPath(new URL("../../tools/ask-mode-reminder.md", import.meta.url));
-const RULES_RELATIVE_DIR = join(".pi", "rules");
 const MCP_INSTRUCTIONS_DESCRIPTION = "Instructions provided by MCP servers to help use them properly";
 const USER_QUERY_RENDER_PATCH_FLAG = "__monoPilotUserQueryRenderPatched__";
 function extractUserQueryForTuiDisplay(text) {
@@ -85,17 +84,16 @@ async function fetchServerInstructions(serverUrl, serverHeaders, serverName) {
     }
 }
 async function buildMcpInstructionsEnvelope(workspaceCwd) {
-    const configPath = resolveMcpConfigPath(workspaceCwd);
-    if (!configPath)
-        return undefined;
-    let servers;
+    let config;
     try {
-        servers = await parseMcpConfig(configPath);
+        config = await loadMcpConfig(workspaceCwd);
     }
     catch {
         return undefined;
     }
-    const serverEntries = Object.entries(servers)
+    if (!config)
+        return undefined;
+    const serverEntries = Object.entries(config.servers)
         .filter(([, config]) => isServerEnabled(config))
         .map(([name, config]) => {
         const serverName = normalizeServerLabel(name);
@@ -138,49 +136,26 @@ async function buildMcpInstructionsEnvelope(workspaceCwd) {
     return lines.join("\n");
 }
 async function buildRulesEnvelope(workspaceCwd) {
-    const rulesDirPath = resolve(workspaceCwd, RULES_RELATIVE_DIR);
-    const userRulesDirPath = resolve(homedir(), RULES_RELATIVE_DIR);
-    const loadRulesFromDir = async (dirPath) => {
-        if (!existsSync(dirPath))
-            return new Map();
-        let directoryEntries;
+    const { userRules, projectRules } = await discoverRules(workspaceCwd);
+    const allRulePaths = [...userRules, ...projectRules];
+    if (allRulePaths.length === 0)
+        return undefined;
+    const ruleEntries = [];
+    for (const filePath of allRulePaths) {
         try {
-            directoryEntries = await readdir(dirPath, { withFileTypes: true, encoding: "utf8" });
+            const content = await readFile(filePath, "utf-8");
+            const normalized = content.trim();
+            if (normalized.length > 0) {
+                ruleEntries.push({ filename: basename(filePath), content: normalized });
+            }
         }
         catch {
-            return new Map();
+            // Ignore unreadable rule files.
         }
-        const ruleFileNames = directoryEntries
-            .filter((entry) => entry.isFile() && entry.name.endsWith(".rule.txt"))
-            .map((entry) => entry.name)
-            .sort((a, b) => a.localeCompare(b));
-        const rules = new Map();
-        for (const ruleFileName of ruleFileNames) {
-            const ruleFilePath = resolve(dirPath, ruleFileName);
-            try {
-                const content = await readFile(ruleFilePath, "utf-8");
-                const normalized = content.trim();
-                if (normalized.length > 0) {
-                    rules.set(ruleFileName, normalized);
-                }
-            }
-            catch {
-                // Ignore unreadable rule files.
-            }
-        }
-        return rules;
-    };
-    const userRules = await loadRulesFromDir(userRulesDirPath);
-    const workspaceRules = await loadRulesFromDir(rulesDirPath);
-    const mergedRules = new Map(userRules);
-    for (const [fileName, content] of workspaceRules) {
-        mergedRules.set(fileName, content);
     }
-    if (mergedRules.size === 0)
+    if (ruleEntries.length === 0)
         return undefined;
-    const rules = Array.from(mergedRules.entries())
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([, content]) => content);
+    const rules = ruleEntries.sort((a, b) => a.filename.localeCompare(b.filename)).map((e) => e.content);
     const lines = ["<rules>"];
     for (const rule of rules) {
         lines.push("<user_rule>");

package/dist/src/mcp/config.js

@@ -0,0 +1,112 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export const MCP_CONFIG_RELATIVE_PATH = join(".pi", "mcp.json");
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function toNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed;
+}
+export function toBoolean(value) {
+    if (typeof value === "boolean")
+        return value;
+    return undefined;
+}
+export function formatErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+export function getMcpConfigCandidates(workspaceCwd) {
+    return [resolve(workspaceCwd, MCP_CONFIG_RELATIVE_PATH), resolve(homedir(), MCP_CONFIG_RELATIVE_PATH)];
+}
+export function resolveMcpConfigSources(workspaceCwd) {
+    const projectPath = resolve(workspaceCwd, MCP_CONFIG_RELATIVE_PATH);
+    const userPath = resolve(homedir(), MCP_CONFIG_RELATIVE_PATH);
+    const sources = [];
+    if (existsSync(projectPath))
+        sources.push({ scope: "project", path: projectPath });
+    if (existsSync(userPath))
+        sources.push({ scope: "user", path: userPath });
+    return sources;
+}
+export async function loadMcpConfig(workspaceCwd) {
+    const sources = resolveMcpConfigSources(workspaceCwd);
+    if (sources.length === 0)
+        return undefined;
+    const servers = {};
+    const sourceByServer = {};
+    for (const source of sources) {
+        const parsed = await parseMcpConfig(source.path);
+        for (const [serverName, serverConfig] of Object.entries(parsed)) {
+            if (sourceByServer[serverName])
+                continue;
+            servers[serverName] = serverConfig;
+            sourceByServer[serverName] = source;
+        }
+    }
+    return { servers, sources, sourceByServer };
+}
+async function parseMcpConfig(configPath) {
+    const rawText = await readFile(configPath, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in MCP config: ${formatErrorMessage(error)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new Error("MCP config root must be a JSON object.");
+    }
+    const serversValue = parsed.mcpServers;
+    if (!isRecord(serversValue))
+        return {};
+    const result = {};
+    for (const [serverName, serverConfig] of Object.entries(serversValue)) {
+        if (!isRecord(serverConfig))
+            continue;
+        result[serverName] = serverConfig;
+    }
+    return result;
+}
+export function isServerEnabled(config) {
+    const disabled = toBoolean(config.disabled);
+    if (disabled === true)
+        return false;
+    const enabled = toBoolean(config.enabled);
+    if (enabled === false)
+        return false;
+    return true;
+}
+export function inferTransport(config) {
+    if (toNonEmptyString(config.url))
+        return "remote";
+    if (toNonEmptyString(config.command))
+        return "stdio";
+    return "unknown";
+}
+export function extractStringHeaders(rawHeaders) {
+    if (!isRecord(rawHeaders))
+        return {};
+    const headers = {};
+    for (const [key, value] of Object.entries(rawHeaders)) {
+        const headerName = key.trim();
+        if (!headerName)
+            continue;
+        if (typeof value === "string")
+            headers[headerName] = value;
+    }
+    return headers;
+}
+export function getHeaderKeys(headers) {
+    const keys = Object.keys(headers).sort((a, b) => a.localeCompare(b));
+    return keys.length > 0 ? keys : undefined;
+}

package/dist/src/mcp/protocol.js

@@ -0,0 +1,164 @@
+import { isRecord, toNonEmptyString } from "./config.js";
+export const MCP_PROTOCOL_VERSION = "2025-03-26";
+export const MCP_CLIENT_NAME = "mono-pilot";
+export const MCP_CLIENT_VERSION = "0.1.0";
+export const MCP_REQUEST_TIMEOUT_MS = 20_000;
+export function parseSseJsonPayload(rawBody) {
+    const lines = rawBody.split(/\r?\n/);
+    const events = [];
+    let currentDataLines = [];
+    for (const line of lines) {
+        if (line.length === 0) {
+            if (currentDataLines.length > 0) {
+                events.push(currentDataLines.join("\n"));
+                currentDataLines = [];
+            }
+            continue;
+        }
+        if (line.startsWith("data:")) {
+            currentDataLines.push(line.slice(5).trimStart());
+        }
+    }
+    if (currentDataLines.length > 0) {
+        events.push(currentDataLines.join("\n"));
+    }
+    let parsed;
+    for (const eventData of events) {
+        if (!eventData || eventData === "[DONE]")
+            continue;
+        try {
+            const candidate = JSON.parse(eventData);
+            if (isRecord(candidate))
+                parsed = candidate;
+        }
+        catch {
+            // Ignore malformed SSE chunks.
+        }
+    }
+    return parsed;
+}
+export function parseJsonRpcBody(rawBody, contentType) {
+    const trimmed = rawBody.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (contentType?.includes("text/event-stream")) {
+        const sseParsed = parseSseJsonPayload(rawBody);
+        if (sseParsed)
+            return sseParsed;
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (isRecord(parsed))
+            return parsed;
+    }
+    catch {
+        const sseParsed = parseSseJsonPayload(rawBody);
+        if (sseParsed)
+            return sseParsed;
+    }
+    return undefined;
+}
+export function formatJsonRpcError(error, fallback) {
+    if (!error)
+        return fallback;
+    const codePart = typeof error.code === "number" ? ` (code ${error.code})` : "";
+    const messagePart = toNonEmptyString(error.message) ?? fallback;
+    return `${messagePart}${codePart}`;
+}
+export function createRpcRequestId(prefix) {
+    return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export async function postJsonRpcRequest(options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), options.timeoutMs ?? MCP_REQUEST_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    options.parentSignal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        const requestHeaders = {
+            "content-type": "application/json",
+            accept: "application/json, text/event-stream",
+            ...options.headers,
+        };
+        if (options.sessionId) {
+            requestHeaders["mcp-session-id"] = options.sessionId;
+        }
+        const response = await fetch(options.url, {
+            method: "POST",
+            headers: requestHeaders,
+            body: JSON.stringify(options.body),
+            signal: controller.signal,
+        });
+        const rawBody = await response.text();
+        const contentType = toNonEmptyString(response.headers.get("content-type") ?? undefined);
+        const parsedBody = parseJsonRpcBody(rawBody, contentType);
+        const responseSessionId = toNonEmptyString(response.headers.get("mcp-session-id") ?? undefined) ??
+            toNonEmptyString(response.headers.get("Mcp-Session-Id") ?? undefined);
+        if (!response.ok) {
+            const fallback = `Remote MCP request failed with status ${response.status}.`;
+            const errorText = formatJsonRpcError(parsedBody?.error, fallback) || toNonEmptyString(rawBody) || fallback;
+            throw new Error(errorText);
+        }
+        if (options.expectResponseBody && !parsedBody) {
+            throw new Error("Remote MCP response did not contain a JSON-RPC body.");
+        }
+        return {
+            parsedBody,
+            rawBody,
+            sessionId: responseSessionId,
+            status: response.status,
+            contentType,
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+        options.parentSignal?.removeEventListener("abort", onAbort);
+    }
+}
+export async function initializeMcpSession(options) {
+    const initializeResponse = await postJsonRpcRequest({
+        url: options.serverUrl,
+        headers: options.serverHeaders,
+        body: {
+            jsonrpc: "2.0",
+            id: createRpcRequestId(`${options.toolCallId}:initialize`),
+            method: "initialize",
+            params: {
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: {
+                    name: MCP_CLIENT_NAME,
+                    version: MCP_CLIENT_VERSION,
+                },
+            },
+        },
+        parentSignal: options.signal,
+        expectResponseBody: true,
+    });
+    const initializeBody = initializeResponse.parsedBody;
+    if (initializeBody?.error) {
+        throw new Error(formatJsonRpcError(initializeBody.error, "MCP initialize failed."));
+    }
+    if (!initializeBody || initializeBody.result === undefined) {
+        throw new Error("MCP initialize did not return a result.");
+    }
+    let sessionId = initializeResponse.sessionId;
+    try {
+        const initializedNotification = await postJsonRpcRequest({
+            url: options.serverUrl,
+            headers: options.serverHeaders,
+            body: {
+                jsonrpc: "2.0",
+                method: "notifications/initialized",
+                params: {},
+            },
+            parentSignal: options.signal,
+            sessionId,
+            expectResponseBody: false,
+        });
+        sessionId = initializedNotification.sessionId ?? sessionId;
+    }
+    catch {
+        // Best effort compatibility.
+    }
+    return sessionId;
+}

package/dist/src/mcp/servers.js

@@ -0,0 +1,90 @@
+import { extractStringHeaders, formatErrorMessage, getMcpConfigCandidates, inferTransport, isServerEnabled, loadMcpConfig, resolveMcpConfigSources, toNonEmptyString, } from "./config.js";
+/** Thrown when no MCP config files are found or config fails to parse. */
+export class McpConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpConfigError";
+    }
+}
+/** Thrown when a specific server can't be used (not found, disabled, wrong transport, etc.). */
+export class McpServerError extends Error {
+    transport;
+    configPaths;
+    constructor(message, transport, configPaths) {
+        super(message);
+        this.transport = transport;
+        this.configPaths = configPaths;
+        this.name = "McpServerError";
+    }
+}
+async function loadRequiredMcpConfig(cwd) {
+    const sources = resolveMcpConfigSources(cwd);
+    if (sources.length === 0) {
+        const candidates = getMcpConfigCandidates(cwd);
+        throw new McpConfigError(`MCP config not found. Checked:\n- ${candidates.join("\n- ")}`);
+    }
+    let config;
+    try {
+        config = await loadMcpConfig(cwd);
+    }
+    catch (error) {
+        throw new McpConfigError(formatErrorMessage(error));
+    }
+    if (!config) {
+        const candidates = getMcpConfigCandidates(cwd);
+        throw new McpConfigError(`MCP config not found. Checked:\n- ${candidates.join("\n- ")}`);
+    }
+    return config;
+}
+/**
+ * For list-style tools (ListMcpTools, ListMcpResources).
+ * Returns all enabled remote servers matching the optional name filter.
+ * Throws McpConfigError on config load failure.
+ */
+export async function resolveTargetServers(cwd, serverFilter) {
+    const config = await loadRequiredMcpConfig(cwd);
+    const configPaths = config.sources.map((source) => source.path);
+    const servers = [];
+    for (const [serverName, serverConfig] of Object.entries(config.servers)) {
+        if (serverFilter && serverName !== serverFilter)
+            continue;
+        if (!isServerEnabled(serverConfig))
+            continue;
+        if (inferTransport(serverConfig) !== "remote")
+            continue;
+        const serverUrl = toNonEmptyString(serverConfig.url);
+        if (!serverUrl)
+            continue;
+        servers.push({ name: serverName, url: serverUrl, headers: extractStringHeaders(serverConfig.headers) });
+    }
+    return { servers, sources: config.sources, configPaths };
+}
+/**
+ * For single-server tools (CallMcpTool, FetchMcpResource).
+ * Returns the resolved remote server or throws McpConfigError / McpServerError.
+ */
+export async function resolveTargetServer(cwd, serverName) {
+    const config = await loadRequiredMcpConfig(cwd);
+    const configPaths = config.sources.map((source) => source.path);
+    const serverConfig = config.servers[serverName];
+    if (!serverConfig) {
+        throw new McpServerError(`MCP server '${serverName}' not found in configured MCP sources.`, undefined, configPaths);
+    }
+    if (!isServerEnabled(serverConfig)) {
+        throw new McpServerError(`MCP server '${serverName}' is disabled in config.`, inferTransport(serverConfig), configPaths);
+    }
+    const transport = inferTransport(serverConfig);
+    if (transport === "stdio") {
+        const command = toNonEmptyString(serverConfig.command);
+        const message = `MCP stdio transport is not supported yet.` + (command ? ` Configured command: ${command}` : "");
+        throw new McpServerError(message, transport, configPaths);
+    }
+    const serverUrl = toNonEmptyString(serverConfig.url);
+    if (!serverUrl) {
+        throw new McpServerError(`MCP server '${serverName}' is missing a remote URL.`, transport, configPaths);
+    }
+    return {
+        server: { name: serverName, url: serverUrl, headers: extractStringHeaders(serverConfig.headers) },
+        configPaths,
+    };
+}