@aexol/spectral 0.2.5 → 0.2.7

package/dist/mcp/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/mcp/sampling-handler.js

@@ -0,0 +1,206 @@
+import { complete } from "@mariozechner/pi-ai";
+import { truncateAtWord } from "./utils.js";
+import { CreateMessageRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+export function registerSamplingHandler(client, options) {
+    client.setRequestHandler(CreateMessageRequestSchema, (request) => {
+        return handleSamplingRequest(options, request);
+    });
+}
+export async function handleSamplingRequest(options, request) {
+    const params = request.params;
+    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, apiKey, headers } = await resolveSamplingModel(options, params.modelPreferences);
+    await confirmSampling(options, "Approve MCP sampling request", formatRequestApproval(options.serverName, `${model.provider}/${model.id}`, params.systemPrompt, messages));
+    const result = await complete(model, {
+        systemPrompt: params.systemPrompt,
+        messages,
+    }, {
+        apiKey,
+        headers,
+        maxTokens: params.maxTokens,
+        temperature: params.temperature,
+        metadata: params.metadata,
+        signal: options.getSignal(),
+    });
+    const converted = convertAssistantResult(result);
+    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 = [];
+    for (const model of candidates) {
+        const auth = await options.modelRegistry.getApiKeyAndHeaders(model);
+        if (auth.ok) {
+            return { model, apiKey: auth.apiKey, headers: auth.headers };
+        }
+        errors.push(`${model.provider}/${model.id}: ${auth.error}`);
+    }
+    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/mcp/server-manager.js

@@ -0,0 +1,301 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { serverStreamResultPatchNotificationSchema } from "./types.js";
+import { resolveNpxBinary } from "./npx-resolver.js";
+import { logger } from "./logger.js";
+import { McpOAuthProvider } from "./mcp-oauth-provider.js";
+import { supportsOAuth } from "./mcp-auth-flow.js";
+import { registerSamplingHandler } from "./sampling-handler.js";
+import { interpolateEnvRecord, resolveBearerToken, resolveConfigPath } from "./utils.js";
+export class McpServerManager {
+    connections = new Map();
+    connectPromises = new Map();
+    uiStreamListeners = new Map();
+    samplingConfig;
+    setSamplingConfig(config) {
+        this.samplingConfig = config;
+    }
+    async connect(name, definition) {
+        // Dedupe concurrent connection attempts
+        if (this.connectPromises.has(name)) {
+            return this.connectPromises.get(name);
+        }
+        // Reuse existing connection if healthy
+        const existing = this.connections.get(name);
+        if (existing?.status === "connected") {
+            existing.lastUsedAt = Date.now();
+            return existing;
+        }
+        const promise = this.createConnection(name, definition);
+        this.connectPromises.set(name, promise);
+        try {
+            const connection = await promise;
+            this.connections.set(name, connection);
+            return connection;
+        }
+        finally {
+            this.connectPromises.delete(name);
+        }
+    }
+    async createConnection(name, definition) {
+        const client = this.createClient(name);
+        let transport;
+        if (definition.command) {
+            let command = definition.command;
+            let args = definition.args ?? [];
+            if (command === "npx" || command === "npm") {
+                const resolved = await resolveNpxBinary(command, args);
+                if (resolved) {
+                    command = resolved.isJs ? "node" : resolved.binPath;
+                    args = resolved.isJs ? [resolved.binPath, ...resolved.extraArgs] : resolved.extraArgs;
+                    logger.debug(`${name} resolved to ${resolved.binPath} (skipping npm parent)`);
+                }
+            }
+            transport = new StdioClientTransport({
+                command,
+                args,
+                env: resolveEnv(definition.env),
+                cwd: resolveConfigPath(definition.cwd),
+                stderr: definition.debug ? "inherit" : "ignore",
+            });
+        }
+        else if (definition.url) {
+            // HTTP transport with fallback
+            transport = await this.createHttpTransport(definition, name);
+        }
+        else {
+            throw new Error(`Server ${name} has no command or url`);
+        }
+        try {
+            await client.connect(transport);
+            this.attachAdapterNotificationHandlers(name, client);
+            // Discover tools and resources
+            const [tools, resources] = await Promise.all([
+                this.fetchAllTools(client),
+                this.fetchAllResources(client),
+            ]);
+            return {
+                client,
+                transport,
+                definition,
+                tools,
+                resources,
+                lastUsedAt: Date.now(),
+                inFlight: 0,
+                status: "connected",
+            };
+        }
+        catch (error) {
+            // Check for UnauthorizedError - server requires OAuth
+            if (error instanceof UnauthorizedError && supportsOAuth(definition)) {
+                // Clean up both client and transport before reporting needs-auth.
+                await client.close().catch(() => { });
+                await transport.close().catch(() => { });
+                return {
+                    client,
+                    transport,
+                    definition,
+                    tools: [],
+                    resources: [],
+                    lastUsedAt: Date.now(),
+                    inFlight: 0,
+                    status: "needs-auth",
+                };
+            }
+            // Clean up both client and transport on any error
+            await client.close().catch(() => { });
+            await transport.close().catch(() => { });
+            throw error;
+        }
+    }
+    createClient(serverName) {
+        const client = new Client({ name: `pi-mcp-${serverName}`, version: "1.0.0" }, this.samplingConfig ? { capabilities: { sampling: {} } } : undefined);
+        if (this.samplingConfig) {
+            registerSamplingHandler(client, { ...this.samplingConfig, serverName });
+        }
+        return client;
+    }
+    async createHttpTransport(definition, serverName) {
+        const url = new URL(definition.url);
+        // Build headers first (including any bearer token)
+        const headers = resolveHeaders(definition.headers) ?? {};
+        // For bearer auth, add the token to headers BEFORE creating requestInit
+        if (definition.auth === "bearer") {
+            const token = resolveBearerToken(definition);
+            if (token) {
+                headers["Authorization"] = `Bearer ${token}`;
+            }
+        }
+        // Create request init with headers (Authorization now included for bearer auth)
+        const requestInit = Object.keys(headers).length > 0 ? { headers } : undefined;
+        // For OAuth servers, create an auth provider
+        let authProvider;
+        if (supportsOAuth(definition)) {
+            // Extract OAuth config (handles both object and false cases)
+            const oauthConfig = definition.oauth === false ? {} : {
+                grantType: definition.oauth?.grantType,
+                clientId: definition.oauth?.clientId,
+                clientSecret: definition.oauth?.clientSecret,
+                scope: definition.oauth?.scope,
+            };
+            authProvider = new McpOAuthProvider(serverName, definition.url, oauthConfig, {
+                onRedirect: async (_authUrl) => {
+                    // URL is captured by startAuth, no need to log
+                },
+            });
+        }
+        // Try StreamableHTTP first (modern MCP servers)
+        const streamableTransport = new StreamableHTTPClientTransport(url, {
+            requestInit,
+            authProvider,
+        });
+        try {
+            // Create a test client to verify the transport works
+            const testClient = new Client({ name: "pi-mcp-probe", version: "2.1.2" });
+            await testClient.connect(streamableTransport);
+            await testClient.close().catch(() => { });
+            // Close probe transport before creating fresh one
+            await streamableTransport.close().catch(() => { });
+            // StreamableHTTP works - create fresh transport for actual use
+            return new StreamableHTTPClientTransport(url, { requestInit, authProvider });
+        }
+        catch (error) {
+            // StreamableHTTP failed, close and try SSE fallback
+            await streamableTransport.close().catch(() => { });
+            // If this was an UnauthorizedError, don't try SSE - the server needs auth
+            if (error instanceof UnauthorizedError) {
+                throw error;
+            }
+            // SSE is the legacy transport
+            return new SSEClientTransport(url, { requestInit, authProvider });
+        }
+    }
+    async fetchAllTools(client) {
+        const allTools = [];
+        let cursor;
+        do {
+            const result = await client.listTools(cursor ? { cursor } : undefined);
+            allTools.push(...(result.tools ?? []));
+            cursor = result.nextCursor;
+        } while (cursor);
+        return allTools;
+    }
+    async fetchAllResources(client) {
+        try {
+            const allResources = [];
+            let cursor;
+            do {
+                const result = await client.listResources(cursor ? { cursor } : undefined);
+                allResources.push(...(result.resources ?? []));
+                cursor = result.nextCursor;
+            } while (cursor);
+            return allResources;
+        }
+        catch {
+            // Server may not support resources
+            return [];
+        }
+    }
+    attachAdapterNotificationHandlers(serverName, client) {
+        client.setNotificationHandler(serverStreamResultPatchNotificationSchema, (notification) => {
+            const listener = this.uiStreamListeners.get(notification.params.streamToken);
+            if (!listener)
+                return;
+            listener(serverName, notification.params);
+        });
+    }
+    registerUiStreamListener(streamToken, listener) {
+        this.uiStreamListeners.set(streamToken, listener);
+    }
+    removeUiStreamListener(streamToken) {
+        this.uiStreamListeners.delete(streamToken);
+    }
+    async readResource(name, uri) {
+        const connection = this.connections.get(name);
+        if (!connection || connection.status !== "connected") {
+            throw new Error(`Server "${name}" is not connected`);
+        }
+        try {
+            this.touch(name);
+            this.incrementInFlight(name);
+            return await connection.client.readResource({ uri });
+        }
+        finally {
+            this.decrementInFlight(name);
+            this.touch(name);
+        }
+    }
+    async close(name) {
+        const connection = this.connections.get(name);
+        if (!connection)
+            return;
+        // Delete from map BEFORE async cleanup to prevent a race where a
+        // concurrent connect() creates a new connection that our deferred
+        // delete() would then remove, orphaning the new server process.
+        connection.status = "closed";
+        this.connections.delete(name);
+        await connection.client.close().catch(() => { });
+        await connection.transport.close().catch(() => { });
+    }
+    async closeAll() {
+        const names = [...this.connections.keys()];
+        await Promise.all(names.map(name => this.close(name)));
+    }
+    getConnection(name) {
+        return this.connections.get(name);
+    }
+    getAllConnections() {
+        return new Map(this.connections);
+    }
+    touch(name) {
+        const connection = this.connections.get(name);
+        if (connection) {
+            connection.lastUsedAt = Date.now();
+        }
+    }
+    incrementInFlight(name) {
+        const connection = this.connections.get(name);
+        if (connection) {
+            connection.inFlight = (connection.inFlight ?? 0) + 1;
+        }
+    }
+    decrementInFlight(name) {
+        const connection = this.connections.get(name);
+        if (connection && connection.inFlight) {
+            connection.inFlight--;
+        }
+    }
+    isIdle(name, timeoutMs) {
+        const connection = this.connections.get(name);
+        if (!connection || connection.status !== "connected")
+            return false;
+        if (connection.inFlight > 0)
+            return false;
+        return (Date.now() - connection.lastUsedAt) > timeoutMs;
+    }
+}
+/**
+ * Resolve environment variables with interpolation.
+ */
+function resolveEnv(env) {
+    // Copy process.env, filtering out undefined values
+    const resolved = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            resolved[key] = value;
+        }
+    }
+    if (!env)
+        return resolved;
+    const overrides = interpolateEnvRecord(env);
+    return overrides ? { ...resolved, ...overrides } : resolved;
+}
+/**
+ * Resolve headers with environment variable interpolation.
+ */
+function resolveHeaders(headers) {
+    return interpolateEnvRecord(headers);
+}

package/dist/mcp/state.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/tool-metadata.js

@@ -0,0 +1,128 @@
+import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { formatToolName, isToolExcluded } from "./types.js";
+import { resourceNameToToolName } from "./resource-tools.js";
+import { extractToolUiStreamMode } from "./utils.js";
+export function buildToolMetadata(tools, resources, definition, serverName, prefix) {
+    const metadata = [];
+    const failedTools = [];
+    for (const tool of tools) {
+        if (!tool?.name) {
+            failedTools.push("(unnamed)");
+            continue;
+        }
+        if (isToolExcluded(tool.name, serverName, prefix, definition.excludeTools)) {
+            continue;
+        }
+        let uiResourceUri;
+        try {
+            uiResourceUri = getToolUiResourceUri({ _meta: tool._meta });
+        }
+        catch {
+            failedTools.push(tool.name);
+        }
+        metadata.push({
+            name: formatToolName(tool.name, serverName, prefix),
+            originalName: tool.name,
+            description: tool.description ?? "",
+            inputSchema: tool.inputSchema,
+            uiResourceUri,
+            uiStreamMode: extractToolUiStreamMode(tool._meta),
+        });
+    }
+    if (definition.exposeResources !== false) {
+        for (const resource of resources) {
+            const baseName = `get_${resourceNameToToolName(resource.name)}`;
+            if (isToolExcluded(baseName, serverName, prefix, definition.excludeTools)) {
+                continue;
+            }
+            metadata.push({
+                name: formatToolName(baseName, serverName, prefix),
+                originalName: baseName,
+                description: resource.description ?? `Read resource: ${resource.uri}`,
+                resourceUri: resource.uri,
+            });
+        }
+    }
+    return { metadata, failedTools };
+}
+export function getToolNames(state, serverName) {
+    return state.toolMetadata.get(serverName)?.map(m => m.name) ?? [];
+}
+export function totalToolCount(state) {
+    let count = 0;
+    for (const metadata of state.toolMetadata.values()) {
+        count += metadata.length;
+    }
+    return count;
+}
+export function findToolByName(metadata, toolName) {
+    if (!metadata)
+        return undefined;
+    const exact = metadata.find(m => m.name === toolName);
+    if (exact)
+        return exact;
+    const normalized = toolName.replace(/-/g, "_");
+    return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
+}
+export function formatSchema(schema, indent = "  ") {
+    if (!schema || typeof schema !== "object") {
+        return `${indent}(no schema)`;
+    }
+    const s = schema;
+    if (s.type === "object" && s.properties && typeof s.properties === "object") {
+        const props = s.properties;
+        const required = Array.isArray(s.required) ? s.required : [];
+        if (Object.keys(props).length === 0) {
+            return `${indent}(no parameters)`;
+        }
+        const lines = [];
+        for (const [name, propSchema] of Object.entries(props)) {
+            const isRequired = required.includes(name);
+            const propLine = formatProperty(name, propSchema, isRequired, indent);
+            lines.push(propLine);
+        }
+        return lines.join("\n");
+    }
+    if (s.type) {
+        return `${indent}(${s.type})`;
+    }
+    return `${indent}(complex schema)`;
+}
+function formatProperty(name, schema, required, indent) {
+    if (!schema || typeof schema !== "object") {
+        return `${indent}${name}${required ? " *required*" : ""}`;
+    }
+    const s = schema;
+    const parts = [];
+    let typeStr = "";
+    if (s.type) {
+        if (Array.isArray(s.type)) {
+            typeStr = s.type.join(" | ");
+        }
+        else {
+            typeStr = String(s.type);
+        }
+    }
+    else if (s.enum) {
+        typeStr = "enum";
+    }
+    else if (s.anyOf || s.oneOf) {
+        typeStr = "union";
+    }
+    if (Array.isArray(s.enum)) {
+        const enumVals = s.enum.map(v => JSON.stringify(v)).join(", ");
+        typeStr = `enum: ${enumVals}`;
+    }
+    parts.push(`${indent}${name}`);
+    if (typeStr)
+        parts.push(`(${typeStr})`);
+    if (required)
+        parts.push("*required*");
+    if (s.description && typeof s.description === "string") {
+        parts.push(`- ${s.description}`);
+    }
+    if (s.default !== undefined) {
+        parts.push(`[default: ${JSON.stringify(s.default)}]`);
+    }
+    return parts.join(" ");
+}

package/dist/mcp/tool-registrar.js

@@ -0,0 +1,43 @@
+// tool-registrar.ts - MCP content transformation
+// NOTE: Tools are NOT registered with Pi - only the unified `mcp` proxy tool is registered.
+// This keeps the LLM context small (1 tool instead of 100s).
+/**
+ * Transform MCP content types to Pi content blocks.
+ */
+export function transformMcpContent(content) {
+    return content.map(c => {
+        if (c.type === "text") {
+            return { type: "text", text: c.text ?? "" };
+        }
+        if (c.type === "image") {
+            return {
+                type: "image",
+                data: c.data ?? "",
+                mimeType: c.mimeType ?? "image/png",
+            };
+        }
+        if (c.type === "resource") {
+            const resourceUri = c.resource?.uri ?? "(no URI)";
+            const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
+            return {
+                type: "text",
+                text: `[Resource: ${resourceUri}]\n${resourceContent}`,
+            };
+        }
+        if (c.type === "resource_link") {
+            const linkName = c.name ?? c.uri ?? "unknown";
+            const linkUri = c.uri ?? "(no URI)";
+            return {
+                type: "text",
+                text: `[Resource Link: ${linkName}]\nURI: ${linkUri}`,
+            };
+        }
+        if (c.type === "audio") {
+            return {
+                type: "text",
+                text: `[Audio content: ${c.mimeType ?? "audio/*"}]`,
+            };
+        }
+        return { type: "text", text: JSON.stringify(c) };
+    });
+}