@bedolla/enriweb 0.1.0

package/dist/shared/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/shared/validation.ts"],"names":[],"mappings":"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"}

package/dist/tools/WebFetchTool.d.ts

@@ -0,0 +1,232 @@
+/**
+ * WEB FETCH TOOL
+ *
+ * Implements the `web_fetch` MCP tool by delegating to EnriProxy.
+ *
+ * @module tools/WebFetchTool
+ */
+import type { EnriProxyClient } from "../client/EnriProxyClient.js";
+/**
+ * Tool parameters for `web_fetch`.
+ */
+export interface WebFetchToolParams {
+    /**
+     * URL to fetch.
+     */
+    readonly url?: string;
+    /**
+     * Cursor identifier returned by a previous call.
+     */
+    readonly cursor?: string;
+    /**
+     * Optional prompt for extraction.
+     */
+    readonly prompt?: string;
+    /**
+     * Maximum content length in characters.
+     */
+    readonly maxChars?: number;
+    /**
+     * Offset in characters for cursor pagination.
+     */
+    readonly offsetChars?: number;
+    /**
+     * Limit in characters for cursor pagination.
+     */
+    readonly limitChars?: number;
+}
+/**
+ * Tool result for `web_fetch`.
+ */
+export interface WebFetchToolResult extends Record<string, unknown> {
+    /**
+     * Fetched content.
+     */
+    readonly content: string;
+    /**
+     * HTTP status code.
+     */
+    readonly status: number;
+    /**
+     * Content type of the response.
+     */
+    readonly content_type: string;
+    /**
+     * Whether content was truncated.
+     */
+    readonly truncated: boolean;
+    /**
+     * URL that was fetched.
+     */
+    readonly url: string;
+    /**
+     * Cursor identifier for pagination (when available).
+     */
+    readonly cursor?: string;
+    /**
+     * Offset in characters (cursor reads).
+     */
+    readonly offset_chars?: number;
+    /**
+     * Limit in characters (cursor reads).
+     */
+    readonly limit_chars?: number;
+    /**
+     * Total captured characters (cursor reads).
+     */
+    readonly total_chars?: number;
+    /**
+     * Whether more content exists beyond this slice.
+     */
+    readonly has_more?: boolean;
+    /**
+     * Whether content was reduced into an excerpt pack.
+     */
+    readonly reduced?: boolean;
+    /**
+     * Whether the upstream fetch was truncated.
+     */
+    readonly fetched_truncated?: boolean;
+}
+/**
+ * Dependencies for {@link WebFetchTool}.
+ */
+export interface WebFetchToolDeps {
+    /**
+     * Creates an EnriProxy client with a base URL, API key, and timeout.
+     *
+     * @param serverUrl - EnriProxy URL
+     * @param apiKey - EnriProxy API key
+     * @param timeoutMs - Timeout in ms
+     * @returns Client instance
+     */
+    readonly createClient: (serverUrl: string, apiKey: string, timeoutMs: number) => EnriProxyClient;
+    /**
+     * Default EnriProxy server URL.
+     */
+    readonly defaultServerUrl: string;
+    /**
+     * Default EnriProxy API key.
+     */
+    readonly defaultApiKey: string;
+    /**
+     * Default timeout in milliseconds.
+     */
+    readonly defaultTimeoutMs: number;
+    /**
+     * Default maximum content length in characters returned by the tool when
+     * `max_chars` is not provided.
+     */
+    readonly defaultMaxChars: number;
+}
+/**
+ * MCP tool that fetches URL content via EnriProxy.
+ */
+export declare class WebFetchTool {
+    /**
+     * Readme file candidates commonly used in GitHub repositories.
+     */
+    private static readonly README_FILENAMES;
+    /**
+     * Default branches to try when resolving GitHub raw README URLs.
+     */
+    private static readonly README_BRANCHES;
+    /**
+     * Tool dependencies.
+     */
+    private readonly deps;
+    /**
+     * Creates a new {@link WebFetchTool}.
+     *
+     * @param deps - Tool dependencies
+     */
+    constructor(deps: WebFetchToolDeps);
+    /**
+     * Gets the configured default max chars for web fetch results.
+     *
+     * @returns Default max chars
+     */
+    getDefaultMaxChars(): number;
+    /**
+     * Validates raw MCP tool arguments.
+     *
+     * @param raw - Raw tool arguments
+     * @returns Validated parameters
+     */
+    parseParams(raw: unknown): WebFetchToolParams;
+    /**
+     * Executes the web fetch tool.
+     *
+     * @param params - Validated parameters
+     * @returns Tool result
+     */
+    execute(params: WebFetchToolParams): Promise<WebFetchToolResult>;
+    /**
+     * Attempts to provide a higher-quality fetch for npm package pages.
+     *
+     * @param params - Tool parameters
+     * @param client - EnriProxy client
+     * @param maxChars - Maximum content length to return
+     * @returns Tool result if the URL is an npm package page, otherwise null
+     */
+    private tryExecuteNpmPackageFetch;
+    /**
+     * Attempts to parse an npm package name from an npmjs.com package page URL.
+     *
+     * @param url - Parsed URL
+     * @returns npm package name (e.g. "chalk" or "@scope/name") or null
+     */
+    private tryParseNpmPackageName;
+    /**
+     * Tries to parse a JSON object from a string.
+     *
+     * @param input - JSON string
+     * @returns Parsed object or null
+     */
+    private tryParseJsonObject;
+    /**
+     * Extracts a string from an unknown value if possible.
+     *
+     * @param value - Unknown input
+     * @returns Trimmed string or null
+     */
+    private tryGetString;
+    /**
+     * Extracts a repository URL from npm metadata.
+     *
+     * @param repository - Repository field value
+     * @returns Normalized URL string or null
+     */
+    private tryGetRepositoryUrl;
+    /**
+     * Normalizes common git repository URL schemes into an https URL.
+     *
+     * @param rawUrl - Raw repository URL from metadata
+     * @returns Normalized URL string or null
+     */
+    private normalizeRepositoryUrl;
+    /**
+     * Normalizes a GitHub repository URL to the canonical https form.
+     *
+     * @param repositoryUrl - Repository URL
+     * @returns Canonical GitHub repo URL (https://github.com/{owner}/{repo}) or null
+     */
+    private tryNormalizeGitHubRepoUrl;
+    /**
+     * Attempts to fetch a GitHub repository README via raw.githubusercontent.com.
+     *
+     * @param client - EnriProxy client
+     * @param githubRepoUrl - Canonical GitHub repo URL
+     * @param maxChars - Maximum content length
+     * @returns README content if found, otherwise null
+     */
+    private tryFetchGitHubReadme;
+    /**
+     * Formats results for MCP text output.
+     *
+     * @param result - Tool result
+     * @returns Formatted text
+     */
+    formatOutput(result: WebFetchToolResult): string;
+}
+//# sourceMappingURL=WebFetchTool.d.ts.map

package/dist/tools/WebFetchTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebFetchTool.d.ts","sourceRoot":"","sources":["../../src/tools/WebFetchTool.ts"],"names":[],"mappings":"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"}

package/dist/tools/WebFetchTool.js

@@ -0,0 +1,429 @@
+import { assertHttpUrl, assertNonEmptyString, assertObject, optionalInt, optionalString } from "../shared/validation.js";
+/**
+ * Default number of characters to include in the human-readable MCP output.
+ *
+ * @remarks
+ * The full fetched payload is still available in `structuredContent.content`,
+ * but MCP clients may enforce tool-result token limits. Keeping the human
+ * output short avoids duplication and reduces the chance of overflows.
+ */
+const DEFAULT_TEXT_PREVIEW_CHARS = 2000;
+/**
+ * MCP tool that fetches URL content via EnriProxy.
+ */
+export class WebFetchTool {
+    /**
+     * Readme file candidates commonly used in GitHub repositories.
+     */
+    static README_FILENAMES = [
+        "README.md",
+        "readme.md"
+    ];
+    /**
+     * Default branches to try when resolving GitHub raw README URLs.
+     */
+    static README_BRANCHES = ["main", "master"];
+    /**
+     * Tool dependencies.
+     */
+    deps;
+    /**
+     * Creates a new {@link WebFetchTool}.
+     *
+     * @param deps - Tool dependencies
+     */
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Gets the configured default max chars for web fetch results.
+     *
+     * @returns Default max chars
+     */
+    getDefaultMaxChars() {
+        return this.deps.defaultMaxChars;
+    }
+    /**
+     * Validates raw MCP tool arguments.
+     *
+     * @param raw - Raw tool arguments
+     * @returns Validated parameters
+     */
+    parseParams(raw) {
+        const obj = assertObject(raw, "arguments");
+        const cursorRaw = optionalString(obj["cursor"]);
+        const cursor = cursorRaw?.trim() ? cursorRaw.trim() : undefined;
+        const urlRaw = optionalString(obj["url"]);
+        const url = urlRaw?.trim() ? assertHttpUrl(urlRaw.trim(), "url") : undefined;
+        if (!cursor && !url) {
+            throw new Error("web_fetch requires either 'url' or 'cursor'.");
+        }
+        const prompt = optionalString(obj["prompt"]);
+        const maxChars = optionalInt(obj["max_chars"]);
+        const offsetCharsRaw = optionalInt(obj["offset_chars"]) ?? optionalInt(obj["offset"]);
+        const limitCharsRaw = optionalInt(obj["limit_chars"]) ?? optionalInt(obj["limit"]);
+        if (maxChars !== undefined && maxChars < 1) {
+            throw new Error("max_chars must be positive.");
+        }
+        const offsetChars = cursor ? offsetCharsRaw : undefined;
+        let limitChars = cursor ? limitCharsRaw : undefined;
+        if (offsetChars !== undefined && offsetChars < 0) {
+            throw new Error("offset must be non-negative.");
+        }
+        if (limitChars !== undefined) {
+            if (limitChars < 0) {
+                throw new Error("limit must be positive.");
+            }
+            if (limitChars === 0) {
+                limitChars = undefined;
+            }
+        }
+        return {
+            url,
+            cursor,
+            prompt,
+            maxChars,
+            offsetChars,
+            limitChars
+        };
+    }
+    /**
+     * Executes the web fetch tool.
+     *
+     * @param params - Validated parameters
+     * @returns Tool result
+     */
+    async execute(params) {
+        const serverUrl = assertHttpUrl(this.deps.defaultServerUrl, "ENRIPROXY_URL");
+        const apiKey = assertNonEmptyString(this.deps.defaultApiKey, "ENRIPROXY_API_KEY");
+        const client = this.deps.createClient(serverUrl, apiKey, this.deps.defaultTimeoutMs);
+        const effectiveMaxChars = typeof params.maxChars === "number" ? params.maxChars : this.deps.defaultMaxChars;
+        if (typeof params.cursor === "string" && params.cursor.trim()) {
+            const response = await client.webFetch({
+                cursor: params.cursor.trim(),
+                offsetChars: params.offsetChars,
+                limitChars: params.limitChars,
+                maxChars: effectiveMaxChars
+            });
+            const resolvedUrl = response.url ?? params.url ?? "(cursor)";
+            return {
+                content: response.content,
+                status: response.status,
+                content_type: response.content_type,
+                truncated: response.truncated,
+                url: resolvedUrl,
+                cursor: response.cursor,
+                offset_chars: response.offset_chars,
+                limit_chars: response.limit_chars,
+                total_chars: response.total_chars,
+                has_more: response.has_more,
+                reduced: response.reduced,
+                fetched_truncated: response.fetched_truncated
+            };
+        }
+        if (!params.url) {
+            throw new Error("web_fetch requires a URL when cursor is not provided.");
+        }
+        const url = params.url;
+        const urlParams = {
+            ...params,
+            url
+        };
+        const npmResult = await this.tryExecuteNpmPackageFetch(urlParams, client, effectiveMaxChars);
+        if (npmResult) {
+            return npmResult;
+        }
+        const response = await client.webFetch({
+            url,
+            prompt: params.prompt,
+            maxChars: effectiveMaxChars
+        });
+        return {
+            content: response.content,
+            status: response.status,
+            content_type: response.content_type,
+            truncated: response.truncated,
+            url: response.url ?? url,
+            cursor: response.cursor,
+            total_chars: response.total_chars,
+            has_more: response.has_more,
+            reduced: response.reduced,
+            fetched_truncated: response.fetched_truncated
+        };
+    }
+    /**
+     * Attempts to provide a higher-quality fetch for npm package pages.
+     *
+     * @param params - Tool parameters
+     * @param client - EnriProxy client
+     * @param maxChars - Maximum content length to return
+     * @returns Tool result if the URL is an npm package page, otherwise null
+     */
+    async tryExecuteNpmPackageFetch(params, client, maxChars) {
+        const requestedUrl = new URL(params.url);
+        const packageName = this.tryParseNpmPackageName(requestedUrl);
+        if (!packageName) {
+            return null;
+        }
+        const metadataUrl = `https://registry.npmjs.org/${packageName}/latest`;
+        const metadataResponse = await client.webFetch({
+            url: metadataUrl,
+            maxChars: Math.min(maxChars, 20000)
+        });
+        if (metadataResponse.status < 200 || metadataResponse.status >= 300) {
+            return null;
+        }
+        const metadata = this.tryParseJsonObject(metadataResponse.content);
+        if (!metadata) {
+            return null;
+        }
+        const name = this.tryGetString(metadata["name"]) ?? packageName;
+        const version = this.tryGetString(metadata["version"]);
+        const description = this.tryGetString(metadata["description"]);
+        const license = this.tryGetString(metadata["license"]);
+        const repositoryUrl = this.tryGetRepositoryUrl(metadata["repository"]);
+        const homepageUrl = this.tryGetString(metadata["homepage"]);
+        let gitHubRepoUrl = null;
+        if (repositoryUrl) {
+            gitHubRepoUrl = this.tryNormalizeGitHubRepoUrl(repositoryUrl);
+        }
+        let readmeText = null;
+        let readmeTruncated = false;
+        if (gitHubRepoUrl) {
+            const readmeResult = await this.tryFetchGitHubReadme(client, gitHubRepoUrl, maxChars);
+            if (readmeResult) {
+                readmeText = readmeResult.content;
+                readmeTruncated = readmeResult.truncated;
+            }
+        }
+        const lines = [];
+        lines.push(`# ${name}`);
+        lines.push("");
+        lines.push(`Requested URL: ${params.url}`);
+        lines.push("");
+        if (description) {
+            lines.push(`Description: ${description}`);
+        }
+        if (version) {
+            lines.push(`Latest version: ${version}`);
+        }
+        if (license) {
+            lines.push(`License: ${license}`);
+        }
+        if (homepageUrl) {
+            lines.push(`Homepage: ${homepageUrl}`);
+        }
+        if (gitHubRepoUrl) {
+            lines.push(`Repository: ${gitHubRepoUrl}`);
+        }
+        else if (repositoryUrl) {
+            lines.push(`Repository: ${repositoryUrl}`);
+        }
+        if (readmeText) {
+            lines.push("");
+            lines.push("## README");
+            lines.push("");
+            lines.push(readmeText);
+        }
+        const combined = lines.join("\n").trim() + "\n";
+        const shouldTrim = combined.length > maxChars;
+        const content = shouldTrim ? combined.slice(0, maxChars) : combined;
+        return {
+            content,
+            status: 200,
+            content_type: "text/markdown",
+            truncated: shouldTrim || readmeTruncated || metadataResponse.truncated,
+            url: params.url
+        };
+    }
+    /**
+     * Attempts to parse an npm package name from an npmjs.com package page URL.
+     *
+     * @param url - Parsed URL
+     * @returns npm package name (e.g. "chalk" or "@scope/name") or null
+     */
+    tryParseNpmPackageName(url) {
+        const hostname = url.hostname.toLowerCase();
+        if (hostname !== "www.npmjs.com" && hostname !== "npmjs.com") {
+            return null;
+        }
+        const segments = url.pathname.split("/").filter(Boolean);
+        if (segments.length < 2) {
+            return null;
+        }
+        if (segments[0] !== "package") {
+            return null;
+        }
+        const first = segments[1];
+        if (!first) {
+            return null;
+        }
+        if (first.startsWith("@")) {
+            const second = segments[2];
+            if (!second) {
+                return null;
+            }
+            return `${first}/${second}`;
+        }
+        return first;
+    }
+    /**
+     * Tries to parse a JSON object from a string.
+     *
+     * @param input - JSON string
+     * @returns Parsed object or null
+     */
+    tryParseJsonObject(input) {
+        try {
+            const parsed = JSON.parse(input);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Extracts a string from an unknown value if possible.
+     *
+     * @param value - Unknown input
+     * @returns Trimmed string or null
+     */
+    tryGetString(value) {
+        if (typeof value !== "string") {
+            return null;
+        }
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    /**
+     * Extracts a repository URL from npm metadata.
+     *
+     * @param repository - Repository field value
+     * @returns Normalized URL string or null
+     */
+    tryGetRepositoryUrl(repository) {
+        if (typeof repository === "string") {
+            return this.normalizeRepositoryUrl(repository);
+        }
+        if (typeof repository === "object" && repository !== null && !Array.isArray(repository)) {
+            const record = repository;
+            const rawUrl = this.tryGetString(record["url"]);
+            if (!rawUrl) {
+                return null;
+            }
+            return this.normalizeRepositoryUrl(rawUrl);
+        }
+        return null;
+    }
+    /**
+     * Normalizes common git repository URL schemes into an https URL.
+     *
+     * @param rawUrl - Raw repository URL from metadata
+     * @returns Normalized URL string or null
+     */
+    normalizeRepositoryUrl(rawUrl) {
+        let urlText = rawUrl.trim();
+        if (urlText.startsWith("git+")) {
+            urlText = urlText.slice("git+".length);
+        }
+        if (urlText.startsWith("git://")) {
+            urlText = `https://${urlText.slice("git://".length)}`;
+        }
+        if (urlText.endsWith(".git")) {
+            urlText = urlText.slice(0, -".git".length);
+        }
+        try {
+            const parsed = new URL(urlText);
+            if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                return null;
+            }
+            return parsed.toString();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Normalizes a GitHub repository URL to the canonical https form.
+     *
+     * @param repositoryUrl - Repository URL
+     * @returns Canonical GitHub repo URL (https://github.com/{owner}/{repo}) or null
+     */
+    tryNormalizeGitHubRepoUrl(repositoryUrl) {
+        try {
+            const parsed = new URL(repositoryUrl);
+            if (parsed.hostname.toLowerCase() !== "github.com") {
+                return null;
+            }
+            const segments = parsed.pathname.split("/").filter(Boolean);
+            if (segments.length < 2) {
+                return null;
+            }
+            const owner = segments[0];
+            const repo = segments[1];
+            if (!owner || !repo) {
+                return null;
+            }
+            return `https://github.com/${owner}/${repo}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Attempts to fetch a GitHub repository README via raw.githubusercontent.com.
+     *
+     * @param client - EnriProxy client
+     * @param githubRepoUrl - Canonical GitHub repo URL
+     * @param maxChars - Maximum content length
+     * @returns README content if found, otherwise null
+     */
+    async tryFetchGitHubReadme(client, githubRepoUrl, maxChars) {
+        const parsed = new URL(githubRepoUrl);
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        if (segments.length < 2) {
+            return null;
+        }
+        const owner = segments[0];
+        const repo = segments[1];
+        if (!owner || !repo) {
+            return null;
+        }
+        for (const branch of WebFetchTool.README_BRANCHES) {
+            for (const filename of WebFetchTool.README_FILENAMES) {
+                const url = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${filename}`;
+                const response = await client.webFetch({
+                    url,
+                    maxChars
+                });
+                if (response.status >= 200 && response.status < 300 && response.content.trim().length > 0) {
+                    return {
+                        content: response.content,
+                        truncated: response.truncated
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Formats results for MCP text output.
+     *
+     * @param result - Tool result
+     * @returns Formatted text
+     */
+    formatOutput(result) {
+        const truncatedNote = result.truncated ? " [TRUNCATED]" : "";
+        const previewChars = Math.min(DEFAULT_TEXT_PREVIEW_CHARS, result.content.length);
+        const preview = result.content.slice(0, previewChars);
+        const header = `Fetched ${result.url} (${result.content_type}, ${result.content.length} chars)${truncatedNote}.`;
+        const previewNote = previewChars < result.content.length
+            ? `\n\nPreview (first ${previewChars} chars):\n\n`
+            : "\n\nContent:\n\n";
+        return header + previewNote + preview;
+    }
+}
+//# sourceMappingURL=WebFetchTool.js.map