@fitchmultz/pi-mcp-adapter 5.0.0

package/dist/resource-tools.d.ts

@@ -0,0 +1 @@
+export declare function resourceNameToToolName(name: string): string;

package/dist/resource-tools.js

@@ -0,0 +1,14 @@
+// resource-tools.ts - MCP resource name utilities
+export function resourceNameToToolName(name) {
+    let result = name
+        .replace(/[^a-zA-Z0-9]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+/, "") // Remove leading underscores
+        .replace(/_+$/, "") // Remove trailing underscores
+        .toLowerCase();
+    // Ensure we have a valid name
+    if (!result || /^\d/.test(result)) {
+        result = "resource" + (result ? "_" + result : "");
+    }
+    return result;
+}

package/dist/runtime-owner.d.ts

@@ -0,0 +1,18 @@
+import type { McpCheckpointEvent } from "./checkpoint.ts";
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+export interface McpRuntimeOwner {
+    readonly signal: AbortSignal;
+    isActive(): boolean;
+    addCleanup(cleanup: () => void | Promise<void>): void;
+    stop(reason?: string): Promise<void>;
+    throwIfInactive(): void;
+    beforeActivity(): void;
+    holdCheckpoint(event: McpCheckpointEvent): () => void;
+    runCallback<T>(kind: "beforeExecute" | "onToolCall", run: () => Promise<T>): Promise<T>;
+    getCheckpointBlocker(): string | undefined;
+}
+export declare function createMcpRuntimeOwner(): McpRuntimeOwner;
+export declare function combineAbortSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined;
+/** Fence session-bound UI calls after the owning extension runtime stops. */
+export declare function createOwnedUi(ui: ExtensionUIContext, owner: McpRuntimeOwner): ExtensionUIContext;
+export declare function isAbortError(error: unknown, signal?: AbortSignal): boolean;

package/dist/runtime-owner.js

@@ -0,0 +1,117 @@
+import { formatTerminalError } from "./utils.js";
+export function createMcpRuntimeOwner() {
+    const controller = new AbortController();
+    const cleanups = [];
+    let stopPromise;
+    let checkpoint;
+    const beforeActivity = () => checkpoint?.invalidate();
+    // These two host hooks can outlive abortable() at their call sites. Count their underlying
+    // promises through settlement, without cancelling, serializing, or replaying callback work.
+    const callbacks = { beforeExecute: 0, onToolCall: 0 };
+    const getCheckpointBlocker = () => {
+        if (callbacks.beforeExecute)
+            return "MCP beforeExecute callback is pending";
+        if (callbacks.onToolCall)
+            return "MCP onToolCall callback is pending";
+        return undefined;
+    };
+    const reportCleanupFailure = (error, late) => {
+        console.error(`MCP: ${late ? "late " : ""}runtime cleanup failed: ${formatTerminalError(error)}`);
+    };
+    return {
+        signal: controller.signal,
+        beforeActivity,
+        getCheckpointBlocker,
+        runCallback: async (kind, run) => {
+            beforeActivity();
+            // Invocation/cancellation policy stays at the call site. In particular, an accepted
+            // tool's outcome callback may still need to persist its result during shutdown.
+            callbacks[kind]++;
+            try {
+                return await run();
+            }
+            finally {
+                callbacks[kind]--;
+            }
+        },
+        holdCheckpoint: event => {
+            if (checkpoint)
+                throw new Error("MCP checkpoint is already held");
+            checkpoint = event;
+            return () => { if (checkpoint === event)
+                checkpoint = undefined; };
+        },
+        isActive: () => !controller.signal.aborted,
+        addCleanup: cleanup => {
+            if (controller.signal.aborted) {
+                void Promise.resolve().then(cleanup).catch(error => reportCleanupFailure(error, true));
+                return;
+            }
+            cleanups.push(cleanup);
+        },
+        stop: (reason = "MCP extension runtime stopped") => {
+            if (stopPromise)
+                return stopPromise;
+            beforeActivity();
+            controller.abort(new Error(reason));
+            const pendingCleanups = cleanups.splice(0).reverse().map(cleanup => Promise.resolve().then(cleanup));
+            stopPromise = Promise.allSettled(pendingCleanups).then(results => {
+                const failures = results.flatMap(result => result.status === "rejected" ? [result.reason] : []);
+                const pendingCallback = getCheckpointBlocker();
+                if (pendingCallback)
+                    failures.push(new Error(pendingCallback));
+                if (failures.length > 0) {
+                    const aggregate = new AggregateError(failures, "MCP runtime cleanup failed");
+                    console.error(`MCP: runtime cleanup failed: ${formatTerminalError(aggregate)}`);
+                    throw aggregate;
+                }
+            });
+            return stopPromise;
+        },
+        throwIfInactive: () => { beforeActivity(); controller.signal.throwIfAborted(); },
+    };
+}
+export function combineAbortSignals(...signals) {
+    const active = signals.filter((signal) => signal !== undefined);
+    if (active.length === 0)
+        return undefined;
+    if (active.length === 1)
+        return active[0];
+    return AbortSignal.any(active);
+}
+/** Fence session-bound UI calls after the owning extension runtime stops. */
+export function createOwnedUi(ui, owner) {
+    const proxies = new WeakMap();
+    const wrap = (value) => {
+        if ((typeof value !== "object" || value === null) && typeof value !== "function") {
+            return value;
+        }
+        const object = value;
+        const existing = proxies.get(object);
+        if (existing)
+            return existing;
+        const proxy = new Proxy(object, {
+            get(target, property, receiver) {
+                if (!owner.isActive())
+                    return undefined;
+                const member = Reflect.get(target, property, receiver);
+                if (typeof member === "function") {
+                    return (...args) => {
+                        if (!owner.isActive())
+                            return undefined;
+                        return Reflect.apply(member, target, args);
+                    };
+                }
+                return owner.isActive() ? wrap(member) : undefined;
+            },
+        });
+        proxies.set(object, proxy);
+        return proxy;
+    };
+    return wrap(ui);
+}
+export function isAbortError(error, signal) {
+    if (signal?.aborted)
+        return true;
+    return error instanceof Error && (error.name === "AbortError" || error.message === "MCP extension runtime stopped");
+}

package/dist/sampling-handler.d.ts

@@ -0,0 +1,15 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionUIContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { Client } from "@modelcontextprotocol/client";
+import { type CreateMessageRequest, type CreateMessageResult } from "@modelcontextprotocol/client";
+export interface SamplingHandlerOptions {
+    serverName: string;
+    autoApprove: boolean;
+    ui?: ExtensionUIContext;
+    modelRegistry: ModelRegistry;
+    getCurrentModel: () => Model<Api> | undefined;
+    getSignal: () => AbortSignal | undefined;
+}
+export type ServerSamplingConfig = Omit<SamplingHandlerOptions, "serverName">;
+export declare function registerSamplingHandler(client: Client, options: SamplingHandlerOptions, own?: (run: () => Promise<CreateMessageResult>) => Promise<CreateMessageResult>): void;
+export declare function handleSamplingRequest(options: SamplingHandlerOptions, request: CreateMessageRequest): Promise<CreateMessageResult>;

package/dist/sampling-handler.js

@@ -0,0 +1,211 @@
+import { truncateAtWord } from "./utils.js";
+import { throwIfAborted } from "./abort.js";
+export function registerSamplingHandler(client, options, own = run => run()) {
+    // Own the handler's real promise, not the SDK caller's cancellable response facade.
+    client.setRequestHandler("sampling/createMessage", request => own(() => handleSamplingRequest(options, request)));
+}
+export async function handleSamplingRequest(options, request) {
+    const params = request.params;
+    const signal = options.getSignal();
+    throwIfAborted(signal);
+    if ("task" in params && params.task) {
+        throw new Error("MCP sampling tasks are not supported");
+    }
+    if (params.includeContext && params.includeContext !== "none") {
+        throw new Error("MCP sampling context inclusion is not supported");
+    }
+    if (params.tools?.length) {
+        throw new Error("MCP sampling tool use is not supported");
+    }
+    if (params.toolChoice) {
+        throw new Error("MCP sampling tool choice is not supported");
+    }
+    if (params.stopSequences?.length) {
+        throw new Error("MCP sampling stop sequences are not supported");
+    }
+    const messages = params.messages.map(convertSamplingMessage);
+    const model = await resolveSamplingModel(options, params.modelPreferences);
+    throwIfAborted(signal);
+    await confirmSampling(options, "Approve MCP sampling request", formatRequestApproval(options.serverName, `${model.provider}/${model.id}`, params.systemPrompt, messages));
+    throwIfAborted(signal);
+    const result = await options.modelRegistry.complete(model, {
+        ...(params.systemPrompt !== undefined ? { systemPrompt: params.systemPrompt } : {}),
+        messages,
+    }, {
+        maxTokens: params.maxTokens,
+        ...(params.temperature !== undefined ? { temperature: params.temperature } : {}),
+        ...(params.metadata !== undefined ? { metadata: params.metadata } : {}),
+        ...(signal ? { signal } : {}),
+    });
+    const converted = convertAssistantResult(result);
+    throwIfAborted(signal);
+    await confirmSampling(options, "Return MCP sampling response", formatResponseApproval(options.serverName, converted));
+    return converted;
+}
+function formatRequestApproval(serverName, modelName, systemPrompt, messages) {
+    const lines = [`${serverName} wants to sample ${messages.length} message${messages.length === 1 ? "" : "s"} with ${modelName}.`];
+    if (systemPrompt) {
+        lines.push(`System: ${truncateAtWord(systemPrompt, 400)}`);
+    }
+    for (const [index, message] of messages.entries()) {
+        lines.push(`${index + 1}. ${message.role}: ${truncateAtWord(messageText(message), 400)}`);
+    }
+    return lines.join("\n\n");
+}
+function formatResponseApproval(serverName, response) {
+    const text = response.content.type === "text" ? response.content.text : `[${response.content.type} content]`;
+    return `${serverName} will receive this response from ${response.model}:\n\n${truncateAtWord(text, 1000)}`;
+}
+function messageText(message) {
+    if (typeof message.content === "string")
+        return message.content;
+    return message.content.map((block) => {
+        if (block.type === "text")
+            return block.text;
+        if (block.type === "image")
+            return `[image: ${block.mimeType}]`;
+        if (block.type === "thinking")
+            return "[thinking]";
+        if (block.type === "toolCall")
+            return `[tool call: ${block.name}]`;
+        return "[content]";
+    }).join("\n");
+}
+async function resolveSamplingModel(options, modelPreferences) {
+    const candidates = [];
+    const availableModels = options.modelRegistry.getAvailable();
+    for (const hint of modelPreferences?.hints ?? []) {
+        const normalizedHint = hint.name?.trim().toLowerCase();
+        if (!normalizedHint)
+            continue;
+        for (const model of availableModels) {
+            const searchableNames = [`${model.provider}/${model.id}`, model.id, model.name];
+            if (searchableNames.some((name) => name.toLowerCase().includes(normalizedHint))) {
+                addSamplingCandidate(candidates, model);
+            }
+        }
+    }
+    const currentModel = options.getCurrentModel();
+    if (currentModel)
+        addSamplingCandidate(candidates, currentModel);
+    for (const model of availableModels) {
+        addSamplingCandidate(candidates, model);
+    }
+    const errors = [];
+    const signal = options.getSignal();
+    for (const model of candidates) {
+        throwIfAborted(signal);
+        const auth = await options.modelRegistry.getApiKeyAndHeaders(model);
+        throwIfAborted(signal);
+        if (auth.ok === false) {
+            errors.push(`${model.provider}/${model.id}: ${auth.error}`);
+            continue;
+        }
+        return model;
+    }
+    if (errors.length > 0) {
+        throw new Error(`No configured auth for MCP sampling model. ${errors.join("; ")}`);
+    }
+    throw new Error("No Pi model is available for MCP sampling");
+}
+function addSamplingCandidate(candidates, model) {
+    if (!candidates.some((candidate) => candidate.provider === model.provider && candidate.id === model.id)) {
+        candidates.push(model);
+    }
+}
+async function confirmSampling(options, title, message) {
+    if (options.autoApprove)
+        return;
+    if (!options.ui) {
+        throw new Error("MCP sampling requires interactive approval. Set settings.samplingAutoApprove to true to allow it without UI.");
+    }
+    const approved = await options.ui.confirm(title, message);
+    if (!approved) {
+        throw new Error("MCP sampling request was declined");
+    }
+}
+function convertSamplingMessage(message) {
+    const blocks = Array.isArray(message.content) ? message.content : [message.content];
+    if (message.role === "user") {
+        return {
+            role: "user",
+            content: blocks.map(convertUserContent),
+            timestamp: Date.now(),
+        };
+    }
+    return {
+        role: "assistant",
+        content: blocks.map(convertAssistantContent),
+        api: "mcp-sampling",
+        provider: "mcp",
+        model: "sampling-request",
+        usage: zeroUsage(),
+        stopReason: "stop",
+        timestamp: Date.now(),
+    };
+}
+function convertUserContent(block) {
+    if (block.type === "text") {
+        return { type: "text", text: block.text };
+    }
+    throw new Error(`MCP sampling ${block.type} content is not supported`);
+}
+function convertAssistantContent(block) {
+    if (block.type === "text") {
+        return { type: "text", text: block.text };
+    }
+    throw new Error(`MCP sampling assistant ${block.type} content is not supported`);
+}
+function convertAssistantResult(message) {
+    if (message.stopReason === "error") {
+        throw new Error(message.errorMessage ?? "MCP sampling model call failed");
+    }
+    if (message.stopReason === "aborted") {
+        throw new Error(message.errorMessage ?? "MCP sampling model call was aborted");
+    }
+    const text = message.content
+        .map((block) => {
+        if (block.type === "text")
+            return block.text;
+        if (block.type === "thinking")
+            return undefined;
+        throw new Error(`MCP sampling result ${block.type} content is not supported`);
+    })
+        .filter((value) => value !== undefined)
+        .join("\n\n")
+        .trim();
+    if (!text) {
+        throw new Error("MCP sampling result did not contain text content");
+    }
+    return {
+        role: "assistant",
+        content: { type: "text", text },
+        model: `${message.provider}/${message.model}`,
+        stopReason: mapStopReason(message.stopReason),
+    };
+}
+function mapStopReason(reason) {
+    if (reason === "stop")
+        return "endTurn";
+    if (reason === "length")
+        return "maxTokens";
+    if (reason === "toolUse")
+        return "toolUse";
+    return reason;
+}
+function zeroUsage() {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            total: 0,
+        },
+    };
+}

package/dist/search-ranking.d.ts

@@ -0,0 +1,20 @@
+import type { McpExtensionState } from "./state.ts";
+import type { ToolMetadata } from "./types.ts";
+export declare const MAX_PAGE_SIZE = 100;
+export declare const MAX_TOOL_NAME_LENGTH = 512;
+export interface RankedToolMatch {
+    server: string;
+    tool: ToolMetadata;
+    score: number;
+}
+export declare function normalizeSearchText(value: string): string;
+export declare function tokenize(value: string): string[];
+export declare function scoreToolMatch(tool: ToolMetadata, server: string, query: string): number | null;
+export declare function rankToolMatches(state: McpExtensionState, query: string, server?: string): RankedToolMatch[];
+export declare function paginate<T>(items: T[], offset: number, limit: number): {
+    items: T[];
+    total: number;
+    hasMore: boolean;
+    nextOffset: number | null;
+};
+export declare function rankSuggestions(state: McpExtensionState, name: string, limit: number, server?: string): string[];

package/dist/search-ranking.js

@@ -0,0 +1,180 @@
+import { getServerPrefix, isServerDisabled, resolveToolPrefix } from "./types.js";
+/**
+ * Shortest field token allowed to stem-match a longer query token.
+ * Real descriptions tokenize possessives into single letters ("project's" -> ["project", "s"]),
+ * which would otherwise make every query starting with that letter a match.
+ */
+const MIN_STEM_LENGTH = 4;
+export const MAX_PAGE_SIZE = 100;
+export const MAX_TOOL_NAME_LENGTH = 512;
+const FIELD_WEIGHTS = {
+    name: 12,
+    originalName: 10,
+    server: 8,
+    description: 5,
+};
+export function normalizeSearchText(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_./:-]+/g, " ")
+        .toLowerCase();
+}
+export function tokenize(value) {
+    return normalizeSearchText(value).split(/[^a-z0-9]+/).filter(Boolean);
+}
+export function scoreToolMatch(tool, server, query) {
+    const normalizedQuery = normalizeSearchText(query).trim();
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0)
+        return null;
+    const fields = {
+        name: normalizeSearchText(tool.name),
+        originalName: normalizeSearchText(tool.originalName),
+        server: normalizeSearchText(server),
+        description: normalizeSearchText(tool.description),
+    };
+    let score = 0;
+    let phraseMatched = false;
+    let wholeFieldExact = false;
+    const matchedTokens = new Set();
+    for (const [field, value] of Object.entries(fields)) {
+        const weight = FIELD_WEIGHTS[field];
+        const fieldTokens = tokenize(value);
+        if (value === normalizedQuery) {
+            score += weight * 14;
+            phraseMatched = true;
+            wholeFieldExact = true;
+        }
+        else if (value.startsWith(normalizedQuery)) {
+            score += weight * 9;
+            phraseMatched = true;
+        }
+        else if (value.includes(normalizedQuery)) {
+            score += weight * 6;
+            phraseMatched = true;
+        }
+        for (const token of queryTokens) {
+            if (fieldTokens.includes(token)) {
+                score += weight * 4;
+                matchedTokens.add(token);
+            }
+            else if (fieldTokens.some(fieldToken => fieldToken.startsWith(token) || (fieldToken.length >= MIN_STEM_LENGTH && token.startsWith(fieldToken)))) {
+                score += weight * 2;
+                matchedTokens.add(token);
+            }
+            else if (value.includes(token)) {
+                score += weight;
+                matchedTokens.add(token);
+            }
+        }
+    }
+    const coverage = matchedTokens.size / queryTokens.length;
+    if (!phraseMatched && (queryTokens.length <= 2 ? coverage !== 1 : coverage < 0.6))
+        return null;
+    score += coverage === 1 ? 25 : Math.round(coverage * 10);
+    const firstQueryToken = queryTokens[0];
+    if (firstQueryToken !== undefined && tokenize(fields.name).includes(firstQueryToken))
+        score += 8;
+    if (wholeFieldExact)
+        score += 20;
+    return score;
+}
+export function rankToolMatches(state, query, server) {
+    const matches = [];
+    for (const [serverName, metadata] of state.toolMetadata.entries()) {
+        if (server && serverName !== server)
+            continue;
+        if (isServerDisabled(state.config.mcpServers[serverName]))
+            continue;
+        for (const tool of metadata) {
+            const score = scoreToolMatch(tool, serverName, query);
+            if (score !== null)
+                matches.push({ server: serverName, tool, score });
+        }
+    }
+    return matches.sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name));
+}
+export function paginate(items, offset, limit) {
+    const safeOffset = Number.isFinite(offset) ? Math.max(0, Math.trunc(offset)) : 0;
+    const safeLimit = Number.isFinite(limit) ? Math.min(MAX_PAGE_SIZE, Math.max(1, Math.trunc(limit))) : 1;
+    const total = items.length;
+    const page = items.slice(safeOffset, safeOffset + safeLimit);
+    const nextOffset = safeOffset + page.length;
+    return {
+        items: page,
+        total,
+        hasMore: nextOffset < total,
+        nextOffset: nextOffset < total ? nextOffset : null,
+    };
+}
+function editDistance(a, b, maxDistance) {
+    if (Math.abs(a.length - b.length) > maxDistance)
+        return maxDistance + 1;
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        let rowMin = i;
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            rowMin = Math.min(rowMin, current[j]);
+        }
+        if (rowMin > maxDistance)
+            return maxDistance + 1;
+        previous = current;
+    }
+    return previous[b.length];
+}
+function rankClosest(tools, query, limit, candidateName) {
+    const normalizedQuery = normalizeSearchText(query).replace(/\s+/g, "_");
+    const maxDistance = Math.max(2, Math.floor(normalizedQuery.length * 0.2));
+    return tools
+        .map(tool => ({
+        tool,
+        distance: editDistance(normalizedQuery, normalizeSearchText(candidateName(tool)).replace(/\s+/g, "_"), maxDistance),
+    }))
+        .filter(({ distance }) => distance <= maxDistance)
+        .sort((a, b) => a.distance - b.distance || a.tool.name.localeCompare(b.tool.name))
+        .slice(0, limit)
+        .map(({ tool }) => tool.name);
+}
+export function rankSuggestions(state, name, limit, server) {
+    if (name.length > MAX_TOOL_NAME_LENGTH)
+        return [];
+    const globalPrefix = state.config.settings?.toolPrefix ?? "server";
+    const inferred = server ? undefined : Object.entries(state.config.mcpServers)
+        .filter(([, definition]) => !isServerDisabled(definition))
+        .map(([candidateServer, definition]) => ({
+        server: candidateServer,
+        prefix: getServerPrefix(candidateServer, resolveToolPrefix(definition, globalPrefix)),
+    }))
+        .filter((candidate) => Boolean(candidate.prefix) && name.startsWith(`${candidate.prefix}_`))
+        .sort((a, b) => b.prefix.length - a.prefix.length)[0];
+    const matchedServer = server ?? inferred?.server;
+    if (!matchedServer) {
+        const tools = [...state.toolMetadata.entries()]
+            .filter(([candidateServer]) => !isServerDisabled(state.config.mcpServers[candidateServer]))
+            .flatMap(([, metadata]) => metadata);
+        const closest = rankClosest(tools, name, limit, tool => tool.name);
+        return closest.length > 0 ? closest : rankToolMatches(state, name).slice(0, limit).map(match => match.tool.name);
+    }
+    const definition = state.config.mcpServers[matchedServer];
+    if (!definition || isServerDisabled(definition))
+        return [];
+    const prefix = inferred?.prefix ?? getServerPrefix(matchedServer, resolveToolPrefix(definition, globalPrefix));
+    const query = prefix && name.startsWith(`${prefix}_`) ? name.slice(prefix.length + 1) : name;
+    const tools = state.toolMetadata.get(matchedServer) ?? [];
+    const closest = rankClosest(tools, query, limit, tool => tool.originalName);
+    if (closest.length > 0)
+        return closest;
+    const queryTokens = tokenize(query);
+    const tokenMatches = rankToolMatches(state, query, matchedServer)
+        .filter(({ tool }) => {
+        const candidateTokens = tokenize(tool.originalName);
+        return queryTokens.every(token => candidateTokens.some(candidate => candidate === token
+            || candidate.startsWith(token)
+            || (candidate.length >= MIN_STEM_LENGTH && token.startsWith(candidate))));
+    })
+        .slice(0, limit)
+        .map(match => match.tool.name);
+    return tokenMatches.length > 0 || !server ? tokenMatches : rankSuggestions(state, name, limit);
+}