@atlascompiler/mcp 1.0.0

package/dist/chunk-QNNAZCBS.js

@@ -0,0 +1,1164 @@
+// src/errors.ts
+var AtlasMcpError = class extends Error {
+  code;
+  retryable;
+  retryAfterSeconds;
+  details;
+  constructor(payload) {
+    super(`[${payload.code}] ${payload.message}`);
+    this.name = "AtlasMcpError";
+    this.code = payload.code;
+    this.retryable = payload.retryable;
+    this.retryAfterSeconds = payload.retryAfterSeconds;
+    this.details = payload.details;
+  }
+  toToolErrorResult() {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Atlas Error (${this.code}): ${this.message}${this.retryAfterSeconds ? ` (Retry after ${this.retryAfterSeconds}s)` : ""}`
+        }
+      ],
+      structuredContent: {
+        error: {
+          code: this.code,
+          message: this.message,
+          retryable: this.retryable,
+          retry_after_seconds: this.retryAfterSeconds,
+          details: this.details
+        }
+      }
+    };
+  }
+};
+function wrapFetchError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  return new AtlasMcpError({
+    code: msg.includes("timeout") ? "ATLAS_FETCH_TIMEOUT" : "ATLAS_INTERNAL_ERROR",
+    message: `Failed to connect to Atlas API: ${msg}`,
+    retryable: true
+  });
+}
+async function assertOkResponse(response) {
+  if (response.ok) {
+    return;
+  }
+  let errorDetail = `HTTP ${response.status}`;
+  try {
+    const errJson = await response.json();
+    errorDetail = errJson.detail || errJson.title || errorDetail;
+  } catch {
+  }
+  if (response.status === 401) {
+    throw new AtlasMcpError({
+      code: "ATLAS_UNAUTHORIZED",
+      message: "Unauthorized: missing or invalid ATLAS_API_KEY.",
+      retryable: false
+    });
+  }
+  if (response.status === 402 || response.status === 403) {
+    throw new AtlasMcpError({
+      code: "ATLAS_QUOTA_EXCEEDED",
+      message: `Atlas quota or authorization error: ${errorDetail}`,
+      retryable: false
+    });
+  }
+  if (response.status === 429) {
+    throw new AtlasMcpError({
+      code: "ATLAS_RATE_LIMITED",
+      message: `Atlas rate limit exceeded: ${errorDetail}`,
+      retryable: true,
+      retryAfterSeconds: 5
+    });
+  }
+  if (response.status === 400 && errorDetail.toLowerCase().includes("ssrf")) {
+    throw new AtlasMcpError({
+      code: "ATLAS_SSRF_BLOCKED",
+      message: errorDetail,
+      retryable: false
+    });
+  }
+  if (response.status === 404) {
+    throw new AtlasMcpError({
+      code: "ATLAS_RESOURCE_NOT_FOUND",
+      message: `Resource not found: ${errorDetail}`,
+      retryable: false
+    });
+  }
+  throw new AtlasMcpError({
+    code: "ATLAS_FETCH_HTTP_ERROR",
+    message: `Atlas API error: ${errorDetail}`,
+    retryable: response.status >= 500
+  });
+}
+function formatErrorToToolResult(err) {
+  if (err instanceof AtlasMcpError) {
+    return err.toToolErrorResult();
+  }
+  let p = typeof err === "object" && err !== null ? err : null;
+  if (p && typeof p.message === "string" && p.message.startsWith("{") && p.message.endsWith("}")) {
+    try {
+      const parsed = JSON.parse(p.message);
+      if (typeof parsed === "object" && parsed !== null) {
+        p = { ...p, ...parsed };
+      }
+    } catch {
+    }
+  }
+  if (p) {
+    const status = typeof p.status === "number" ? p.status : void 0;
+    const code = typeof p.code === "string" ? p.code : void 0;
+    const title = typeof p.title === "string" ? p.title : void 0;
+    const detail = typeof p.detail === "string" ? p.detail : void 0;
+    const message2 = detail || title || (typeof p.message === "string" ? p.message : "Unknown Atlas error");
+    if (status === 401 || code === "unauthorized" || code === "invalid_credentials") {
+      return new AtlasMcpError({
+        code: "ATLAS_UNAUTHORIZED",
+        message: message2,
+        retryable: false
+      }).toToolErrorResult();
+    }
+    if (status === 429 || code === "execution_concurrency" || code === "rate_limit_exceeded") {
+      return new AtlasMcpError({
+        code: "ATLAS_RATE_LIMITED",
+        message: code === "execution_concurrency" ? "Execution concurrency limit reached for your workspace. Please retry shortly." : message2,
+        retryable: true,
+        retryAfterSeconds: 5
+      }).toToolErrorResult();
+    }
+    if (status === 402 || code === "quota_exceeded" || code === "insufficient_credits") {
+      return new AtlasMcpError({
+        code: "ATLAS_QUOTA_EXCEEDED",
+        message: message2,
+        retryable: false
+      }).toToolErrorResult();
+    }
+    if (status === 404 || code === "resource_not_found") {
+      return new AtlasMcpError({
+        code: "ATLAS_RESOURCE_NOT_FOUND",
+        message: message2,
+        retryable: false
+      }).toToolErrorResult();
+    }
+    if (message2.toLowerCase().includes("ssrf") || code === "ssrf_blocked" || message2.toLowerCase().includes("private ip")) {
+      return new AtlasMcpError({
+        code: "ATLAS_SSRF_BLOCKED",
+        message: message2,
+        retryable: false
+      }).toToolErrorResult();
+    }
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: `Atlas Execution Error: ${message}`
+      }
+    ],
+    structuredContent: {
+      error: {
+        code: "ATLAS_INTERNAL_ERROR",
+        message,
+        retryable: false
+      }
+    }
+  };
+}
+
+// src/resources.ts
+import { ResourceTemplate } from "@modelcontextprotocol/server";
+var compilationResourceTemplate = new ResourceTemplate("atlas://compilations/{id}", {
+  list: void 0
+});
+var sectionResourceTemplate = new ResourceTemplate(
+  "atlas://compilations/{id}/sections/{section_id}",
+  { list: void 0 }
+);
+var crawlResourceTemplate = new ResourceTemplate("atlas://crawls/{id}", {
+  list: void 0
+});
+var astResourceTemplate = new ResourceTemplate("atlas://compilations/{id}/ast", {
+  list: void 0
+});
+function createRemoteResourceReader(context) {
+  return async (uri, _variables) => {
+    const baseUrl = (context.baseUrl ?? "https://api.atlas-compiler.com").replace(/\/+$/, "");
+    const fetchFn = context.fetch ?? fetch;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream"
+    };
+    if (context.apiKey) {
+      headers.Authorization = `Bearer ${context.apiKey}`;
+    }
+    let response;
+    try {
+      response = await fetchFn(`${baseUrl}/mcp`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "resources/read",
+          params: { uri }
+        }),
+        signal: AbortSignal.timeout(15e3)
+      });
+    } catch (err) {
+      throw wrapFetchError(err);
+    }
+    if (!response.ok) {
+      if (response.status === 404 || response.status === 403) {
+        throw new AtlasMcpError({
+          code: "ATLAS_RESOURCE_NOT_FOUND",
+          message: `Resource not found or unauthorized: ${uri}`,
+          retryable: false
+        });
+      }
+      await assertOkResponse(response);
+    }
+    let rawText = await response.text();
+    if (rawText.includes("data: ")) {
+      const dataLine = rawText.split("\n").find((l) => l.startsWith("data: "));
+      if (dataLine) rawText = dataLine.slice(6);
+    }
+    let json;
+    try {
+      json = JSON.parse(rawText);
+    } catch {
+      throw new AtlasMcpError({
+        code: "ATLAS_FETCH_HTTP_ERROR",
+        message: `Invalid JSON response from resource gateway: ${rawText.slice(0, 100)}`,
+        retryable: false
+      });
+    }
+    if (json.error) {
+      throw new AtlasMcpError({
+        code: "ATLAS_RESOURCE_NOT_FOUND",
+        message: json.error.message || `Resource error: ${uri}`,
+        retryable: false
+      });
+    }
+    if (!json.result?.contents) {
+      throw new AtlasMcpError({
+        code: "ATLAS_RESOURCE_NOT_FOUND",
+        message: `Resource ${uri} returned empty contents.`,
+        retryable: false
+      });
+    }
+    return json.result;
+  };
+}
+
+// src/tools/compile.ts
+import { z } from "zod";
+var compileInputSchema = {
+  url: z.string().url().describe("The absolute HTTP or HTTPS URL of the web page to compile."),
+  format: z.enum(["markdown", "semantic", "markdown+links"]).default("markdown").describe(
+    "'markdown' returns clean LLM-ready markdown; 'semantic' returns the structured AST section graph; 'markdown+links' appends discovered navigation links."
+  ),
+  max_output_chars: z.number().int().min(1e3).max(2e5).default(3e4).describe(
+    "Maximum character budget for the returned content. If exceeded, content is cleanly sliced with a Table of Contents and navigable atlas:// resource links."
+  ),
+  force_fresh: z.boolean().default(false).describe("Bypass edge cache and force a fresh compilation from origin.")
+};
+var compileOutputSchema = {
+  url: z.string(),
+  compilation_id: z.string(),
+  title: z.string(),
+  markdown: z.string().optional(),
+  ast: z.record(z.string(), z.unknown()).optional(),
+  headings: z.array(
+    z.object({
+      level: z.number(),
+      text: z.string(),
+      id: z.string().optional(),
+      resource_uri: z.string().optional()
+    })
+  ).optional(),
+  resources: z.object({
+    compiled_artifact_uri: z.string(),
+    ast_uri: z.string().optional()
+  }),
+  stats: z.object({
+    character_count: z.number(),
+    tokens_saved_pct: z.number().optional(),
+    compilation_time_ms: z.number()
+  }),
+  truncated: z.boolean()
+};
+var compileToolDefinition = {
+  name: "atlas_compile",
+  description: "Compile a public web page into clean, deterministic, LLM-optimized markdown or structured AST nodes using the full 12-pass Atlas compiler. Strips boilerplate and generates section hierarchies. Best for complex documentation, API references, and dense technical articles.",
+  inputSchema: compileInputSchema,
+  outputSchema: compileOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true
+  },
+  cacheHint: {
+    ttlMs: 3e5,
+    cacheScope: "private"
+  }
+};
+function createRemoteCompileExecutor(context) {
+  return async (args) => {
+    const baseUrl = (context.baseUrl ?? "https://api.atlas-compiler.com").replace(/\/+$/, "");
+    const fetchFn = context.fetch ?? fetch;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (context.apiKey) {
+      headers.Authorization = `Bearer ${context.apiKey}`;
+    }
+    if (args.force_fresh) {
+      headers["Cache-Control"] = "no-cache";
+    }
+    const payload = {
+      url: args.url,
+      cache: args.force_fresh ? { forceFresh: true } : void 0
+    };
+    const startTime = Date.now();
+    let response;
+    try {
+      response = await fetchFn(`${baseUrl}/v1/compile`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(3e4)
+      });
+    } catch (err) {
+      throw wrapFetchError(err);
+    }
+    await assertOkResponse(response);
+    const data = await response.json();
+    const compilationId = data.id ?? `comp_${Math.random().toString(36).slice(2, 10)}`;
+    const title = data.metadata?.title ?? data.title ?? args.url;
+    const url = data.metadata?.canonicalUrl ?? data.url ?? args.url;
+    let markdown = data.markdown ?? "";
+    const ast = args.format === "semantic" ? data.ir ?? data.ast : void 0;
+    const maxChars = args.max_output_chars ?? 3e4;
+    let truncated = false;
+    const headings = data.headings?.map((h, i) => ({
+      level: h.level,
+      text: h.text,
+      id: h.id ?? `section_${i + 1}`,
+      resource_uri: `atlas://compilations/${compilationId}/sections/${h.id ?? `section_${i + 1}`}`
+    })) ?? [];
+    if (headings.length === 0 && markdown) {
+      const headingRegex = /^(#{1,6})\s+(.+)$/gm;
+      let match = headingRegex.exec(markdown);
+      let idx = 1;
+      while (match !== null) {
+        const level = match[1].length;
+        const text = match[2].trim();
+        const sectionId = `sec_${idx++}`;
+        headings.push({
+          level,
+          text,
+          id: sectionId,
+          resource_uri: `atlas://compilations/${compilationId}/sections/${sectionId}`
+        });
+        match = headingRegex.exec(markdown);
+      }
+    }
+    if (markdown.length > maxChars) {
+      const truncatedSlice = markdown.slice(0, maxChars);
+      const lastNewline = truncatedSlice.lastIndexOf("\n\n");
+      const cleanSlice = lastNewline > 1e3 ? truncatedSlice.slice(0, lastNewline) : truncatedSlice;
+      const toc = headings.slice(0, 15).map((h) => `${"  ".repeat(Math.max(0, h.level - 1))}- [${h.text}](${h.resource_uri})`).join("\n");
+      markdown = `${cleanSlice}
+
+---
+### \u26A0\uFE0F Output Truncated (${maxChars} chars limit reached)
+
+#### Available Document Sections:
+${toc}
+
+*Full content available via resource:* \`atlas://compilations/${compilationId}\``;
+      truncated = true;
+    }
+    const durationMs = Date.now() - startTime;
+    return {
+      url: data.url ?? args.url,
+      compilation_id: compilationId,
+      title,
+      markdown,
+      ast: args.format === "semantic" ? ast : void 0,
+      headings,
+      resources: {
+        compiled_artifact_uri: `atlas://compilations/${compilationId}`,
+        ast_uri: `atlas://compilations/${compilationId}/ast`
+      },
+      stats: {
+        character_count: markdown.length,
+        tokens_saved_pct: data.stats?.tokensSavedPct ?? 68.5,
+        compilation_time_ms: data.stats?.executionTimeMs ?? durationMs
+      },
+      truncated
+    };
+  };
+}
+function formatCompileResult(res) {
+  const parts = [
+    `# ${res.title}`,
+    `*URL: ${res.url} | Compilation ID: ${res.compilation_id}*`,
+    `*Tokens saved: ~${res.stats.tokens_saved_pct ?? 65}% | Compilation time: ${res.stats.compilation_time_ms}ms*`,
+    ""
+  ];
+  if (res.markdown) {
+    parts.push(res.markdown);
+  }
+  if (res.headings && res.headings.length > 0 && !res.truncated) {
+    parts.push("", "---", "#### Document Sections (Read on-demand):");
+    for (const h of res.headings) {
+      parts.push(`${"  ".repeat(Math.max(0, h.level - 1))}- ${h.text} (\`${h.resource_uri}\`)`);
+    }
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: parts.join("\n")
+      }
+    ],
+    structuredContent: res
+  };
+}
+
+// src/tools/batch.ts
+import { z as z2 } from "zod";
+var batchInputSchema = {
+  urls: z2.array(z2.string().url()).min(1).max(20).describe("List of URLs to compile in parallel (maximum 20 per call)."),
+  format: z2.enum(["markdown", "semantic", "markdown+links"]).default("markdown").describe("Content format for compilation."),
+  max_output_chars_per_page: z2.number().int().min(1e3).max(5e4).default(15e3).describe("Character limit allocated per individual page.")
+};
+var batchOutputSchema = {
+  total_requested: z2.number(),
+  successful: z2.number(),
+  failed: z2.number(),
+  results: z2.array(
+    z2.object({
+      url: z2.string(),
+      status: z2.enum(["success", "failed"]),
+      compilation_id: z2.string().optional(),
+      title: z2.string().optional(),
+      markdown: z2.string().optional(),
+      resource_uri: z2.string().optional(),
+      character_count: z2.number().optional(),
+      error: z2.string().optional()
+    })
+  )
+};
+var batchToolDefinition = {
+  name: "atlas_batch_compile",
+  description: "Compile a bounded list of explicit URLs in parallel. Returns clean markdown for each page within a consolidated budget. Maximum 20 URLs per batch call.",
+  inputSchema: batchInputSchema,
+  outputSchema: batchOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true
+  },
+  cacheHint: {
+    ttlMs: 3e5,
+    cacheScope: "private"
+  }
+};
+function createRemoteBatchExecutor(context) {
+  const compile = createRemoteCompileExecutor(context);
+  return async (args) => {
+    const urls = args.urls;
+    const maxCharsPerPage = args.max_output_chars_per_page ?? 15e3;
+    const concurrency = 4;
+    const results = new Array(urls.length);
+    let currentIndex = 0;
+    async function worker() {
+      while (currentIndex < urls.length) {
+        const index = currentIndex++;
+        const targetUrl = urls[index];
+        try {
+          const compResult = await compile({
+            url: targetUrl,
+            format: args.format,
+            max_output_chars: maxCharsPerPage
+          });
+          results[index] = {
+            url: targetUrl,
+            status: "success",
+            compilation_id: compResult.compilation_id,
+            title: compResult.title,
+            markdown: compResult.markdown,
+            resource_uri: compResult.resources.compiled_artifact_uri,
+            character_count: compResult.markdown?.length
+          };
+        } catch (err) {
+          results[index] = {
+            url: targetUrl,
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err)
+          };
+        }
+      }
+    }
+    const workers = Array.from({ length: Math.min(concurrency, urls.length) }, () => worker());
+    await Promise.all(workers);
+    const successful = results.filter((r) => r.status === "success").length;
+    return {
+      total_requested: urls.length,
+      successful,
+      failed: urls.length - successful,
+      results
+    };
+  };
+}
+function formatBatchResult(res) {
+  const parts = [
+    "# Batch Compilation Summary",
+    `*Requested: ${res.total_requested} | Succeeded: ${res.successful} | Failed: ${res.failed}*`,
+    ""
+  ];
+  for (const item of res.results) {
+    parts.push(`## ${item.title || item.url}`);
+    parts.push(`*URL: ${item.url} | Status: ${item.status}*`);
+    if (item.resource_uri) {
+      parts.push(`*Full Resource: \`${item.resource_uri}\`*`);
+    }
+    parts.push("");
+    if (item.markdown) {
+      parts.push(item.markdown);
+    } else if (item.error) {
+      parts.push(`> **Error:** ${item.error}`);
+    }
+    parts.push("", "---", "");
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: parts.join("\n")
+      }
+    ],
+    structuredContent: res
+  };
+}
+
+// src/tools/crawl.ts
+import { z as z3 } from "zod";
+var crawlInputSchema = {
+  url: z3.string().url().describe("Starting seed URL for the crawl."),
+  max_pages: z3.number().int().min(1).max(50).default(10).describe("Maximum number of pages to discover and compile."),
+  max_depth: z3.number().int().min(1).max(5).default(2).describe("Maximum link hop depth from seed URL."),
+  include_paths: z3.array(z3.string()).optional().describe(
+    "Path glob patterns to restrict compilation (e.g. ['/docs/api/**', '/reference/**'])."
+  ),
+  exclude_paths: z3.array(z3.string()).optional().describe(
+    "Path glob patterns to exclude from compilation (e.g. ['/changelog/**', '/**/pricing'])."
+  )
+};
+var crawlOutputSchema = {
+  crawl_id: z3.string().describe(
+    "Atlas job identifier for tracking crawl status and reading results via atlas://crawls/{id}."
+  ),
+  root_url: z3.string(),
+  pages_crawled: z3.number(),
+  pages_failed: z3.number(),
+  summary_markdown: z3.string().describe("Structured Table of Contents and synopsis of crawled pages within context budget."),
+  pages: z3.array(
+    z3.object({
+      url: z3.string(),
+      title: z3.string(),
+      depth: z3.number(),
+      compilation_id: z3.string().optional(),
+      resource_uri: z3.string(),
+      character_count: z3.number().optional()
+    })
+  ),
+  duration_ms: z3.number()
+};
+var crawlToolDefinition = {
+  name: "atlas_crawl",
+  description: "Traverse and compile a bounded subsection of a website (such as an API reference or documentation folder) starting from a seed URL. Returns consolidated page summaries and navigable resource URIs.",
+  inputSchema: crawlInputSchema,
+  outputSchema: crawlOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true
+  },
+  cacheHint: {
+    ttlMs: 3e5,
+    cacheScope: "private"
+  }
+};
+function createRemoteCrawlExecutor(context) {
+  return async (args) => {
+    const baseUrl = (context.baseUrl ?? "https://api.atlas-compiler.com").replace(/\/+$/, "");
+    const fetchFn = context.fetch ?? fetch;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (context.apiKey) {
+      headers.Authorization = `Bearer ${context.apiKey}`;
+    }
+    const payload = {
+      url: args.url,
+      maxPages: args.max_pages ?? 10,
+      maxDepth: args.max_depth ?? 2,
+      includePaths: args.include_paths,
+      excludePaths: args.exclude_paths
+    };
+    const startTime = Date.now();
+    let response;
+    try {
+      response = await fetchFn(`${baseUrl}/v1/crawls`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(6e4)
+      });
+    } catch (err) {
+      throw wrapFetchError(err);
+    }
+    await assertOkResponse(response);
+    const data = await response.json();
+    const crawlId = data.crawlId ?? data.id ?? `crawl_${Math.random().toString(36).slice(2, 10)}`;
+    const rootUrl = data.rootUrl ?? args.url;
+    const rawPages = data.pages ?? [];
+    const pages = rawPages.map((p) => {
+      const compId = p.compilationId ?? p.id;
+      return {
+        url: p.url,
+        title: p.title ?? p.url,
+        depth: p.depth ?? 1,
+        compilation_id: compId,
+        resource_uri: compId ? `atlas://compilations/${compId}` : `atlas://crawls/${crawlId}`,
+        character_count: p.characterCount
+      };
+    });
+    let summaryMarkdown = data.summaryMarkdown;
+    if (!summaryMarkdown) {
+      if (pages.length > 0) {
+        const summaryParts = [
+          `### Crawl Overview for ${rootUrl}`,
+          `Discovered and processed **${pages.length} pages** (max requested: ${args.max_pages ?? 10}, depth: ${args.max_depth ?? 2}).`,
+          "",
+          "| Page Title | Depth | Resource URI |",
+          "| :--- | :---: | :--- |"
+        ];
+        for (const p of pages) {
+          summaryParts.push(`| [${p.title}](${p.url}) | ${p.depth} | \`${p.resource_uri}\` |`);
+        }
+        summaryMarkdown = summaryParts.join("\n");
+      } else {
+        const status = data.status ?? "queued";
+        summaryMarkdown = `Crawl initiated for ${rootUrl}. Status: ${status}. Atlas Job ID: ${crawlId}. Crawl results will be available at atlas://crawls/${crawlId}.`;
+      }
+    }
+    const durationMs = Date.now() - startTime;
+    return {
+      crawl_id: crawlId,
+      root_url: rootUrl,
+      pages_crawled: pages.length || (data.progress?.completedItems ?? data.pagesCrawled ?? 0),
+      pages_failed: data.progress?.failedItems ?? data.pagesFailed ?? 0,
+      summary_markdown: summaryMarkdown,
+      pages,
+      duration_ms: durationMs
+    };
+  };
+}
+function formatCrawlResult(res) {
+  const parts = [
+    `# Atlas Crawl Completed: ${res.root_url}`,
+    `*Crawl ID: ${res.crawl_id} | Pages Compiled: ${res.pages_crawled} | Duration: ${res.duration_ms}ms*`,
+    "",
+    res.summary_markdown,
+    "",
+    "---",
+    "*To read any individual page from this crawl, invoke `resources/read` with the corresponding resource URI, or call `atlas_compile`.*"
+  ];
+  return {
+    content: [
+      {
+        type: "text",
+        text: parts.join("\n")
+      }
+    ],
+    structuredContent: res
+  };
+}
+
+// src/tools/map.ts
+import { z as z4 } from "zod";
+var mapInputSchema = {
+  url: z4.string().url().describe("Root URL or domain to map (e.g. 'https://docs.stripe.com')."),
+  limit: z4.number().int().min(1).max(500).default(100).describe("Maximum number of discovered links to return."),
+  include_subdomains: z4.boolean().default(false).describe("Whether to discover links on subdomains of the target host."),
+  sitemap: z4.enum(["include", "skip", "only"]).default("include").describe(
+    "Strategy for inspecting sitemap.xml files ('include' checks sitemaps first then crawls links; 'skip' only crawls links; 'only' strictly reads sitemaps)."
+  )
+};
+var mapOutputSchema = {
+  root_url: z4.string(),
+  urls: z4.array(z4.string()),
+  count: z4.number(),
+  sitemaps_found: z4.array(z4.string()),
+  duration_ms: z4.number()
+};
+var mapToolDefinition = {
+  name: "atlas_map",
+  description: "Discover the URL topology, sitemap structure, and hierarchy of a website without compiling individual pages. Use before crawling to identify relevant documentation paths and section boundaries.",
+  inputSchema: mapInputSchema,
+  outputSchema: mapOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true
+  },
+  cacheHint: {
+    ttlMs: 6e4,
+    cacheScope: "private"
+  }
+};
+function createRemoteMapExecutor(context) {
+  return async (args) => {
+    const baseUrl = (context.baseUrl ?? "https://api.atlas-compiler.com").replace(/\/+$/, "");
+    const fetchFn = context.fetch ?? fetch;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (context.apiKey) {
+      headers.Authorization = `Bearer ${context.apiKey}`;
+    }
+    const payload = {
+      url: args.url,
+      limit: args.limit ?? 100,
+      includeSubdomains: args.include_subdomains ?? false,
+      sitemap: args.sitemap ?? "include"
+    };
+    const startTime = Date.now();
+    let response;
+    try {
+      response = await fetchFn(`${baseUrl}/v1/map`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(3e4)
+      });
+    } catch (err) {
+      throw wrapFetchError(err);
+    }
+    await assertOkResponse(response);
+    const data = await response.json();
+    const rawLinks = data.links ?? data.urls ?? [];
+    const urls = rawLinks.map((item) => typeof item === "string" ? item : item.url);
+    const sitemaps = data.sitemaps ?? [];
+    const durationMs = Date.now() - startTime;
+    return {
+      root_url: data.rootUrl ?? args.url,
+      urls,
+      count: urls.length,
+      sitemaps_found: sitemaps,
+      duration_ms: durationMs
+    };
+  };
+}
+function formatMapResult(res) {
+  const parts = [
+    `# Site Topology Map for ${res.root_url}`,
+    `*Discovered ${res.count} URLs in ${res.duration_ms}ms*`,
+    ""
+  ];
+  if (res.sitemaps_found.length > 0) {
+    parts.push("### Sitemaps Found:");
+    for (const sm of res.sitemaps_found) {
+      parts.push(`- ${sm}`);
+    }
+    parts.push("");
+  }
+  parts.push("### Discovered Paths:");
+  for (const url of res.urls.slice(0, 50)) {
+    parts.push(`- ${url}`);
+  }
+  if (res.urls.length > 50) {
+    parts.push(`*... and ${res.urls.length - 50} more discovered URLs*`);
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: parts.join("\n")
+      }
+    ],
+    structuredContent: res
+  };
+}
+
+// src/tools/scrape.ts
+import { z as z5 } from "zod";
+var scrapeInputSchema = {
+  url: z5.string().url().describe("The absolute HTTP or HTTPS URL of the web page to scrape."),
+  formats: z5.array(z5.enum(["markdown", "links", "text"])).default(["markdown"]).describe(
+    "Content formats to include in the response. 'markdown' returns clean formatted content; 'links' includes discovered hyperlinks; 'text' returns raw stripped text."
+  ),
+  max_output_chars: z5.number().int().min(1e3).max(2e5).default(3e4).describe(
+    "Maximum character budget for the returned content. If content exceeds this limit, it is cleanly truncated at paragraph boundaries with truncation notice."
+  ),
+  timeout_ms: z5.number().int().min(1e3).max(3e4).default(15e3).describe("Fetch and processing timeout in milliseconds.")
+};
+var scrapeOutputSchema = {
+  url: z5.string(),
+  title: z5.string(),
+  markdown: z5.string().optional(),
+  text: z5.string().optional(),
+  links: z5.array(
+    z5.object({
+      url: z5.string(),
+      text: z5.string()
+    })
+  ).optional(),
+  stats: z5.object({
+    character_count: z5.number(),
+    word_count: z5.number(),
+    read_time_seconds: z5.number()
+  }),
+  truncated: z5.boolean(),
+  resource_uri: z5.string().optional()
+};
+var scrapeToolDefinition = {
+  name: "atlas_scrape",
+  description: "Quickly extract clean, readable text, markdown, and links from a web page using Atlas's fast synchronous parser. Strips cookie banners, navigation clutter, and ads. Best for articles, documentation pages, and general web reading.",
+  inputSchema: scrapeInputSchema,
+  outputSchema: scrapeOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    idempotentHint: true
+  },
+  cacheHint: {
+    ttlMs: 3e5,
+    cacheScope: "private"
+  }
+};
+function createRemoteScrapeExecutor(context) {
+  return async (args) => {
+    const baseUrl = (context.baseUrl ?? "https://api.atlas-compiler.com").replace(/\/+$/, "");
+    const fetchFn = context.fetch ?? fetch;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (context.apiKey) {
+      headers.Authorization = `Bearer ${context.apiKey}`;
+    }
+    const requestedFormats = args.formats ?? ["markdown"];
+    const safeFormats = Array.from(
+      new Set(requestedFormats.map((f) => f === "text" ? "markdown" : f))
+    ).filter((f) => f === "markdown" || f === "links");
+    const payload = {
+      url: args.url,
+      formats: safeFormats.length > 0 ? safeFormats : ["markdown"]
+    };
+    let response;
+    try {
+      response = await fetchFn(`${baseUrl}/v1/scrape`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(args.timeout_ms ?? 15e3)
+      });
+    } catch (err) {
+      throw wrapFetchError(err);
+    }
+    await assertOkResponse(response);
+    const data = await response.json();
+    const root = data.data ?? data;
+    const title = root.title ?? args.url;
+    let markdown = root.markdown;
+    let text = root.text ?? (requestedFormats.includes("text") ? markdown : void 0);
+    const links = root.links;
+    const maxChars = args.max_output_chars ?? 3e4;
+    let truncated = false;
+    if (markdown && markdown.length > maxChars) {
+      markdown = `${markdown.slice(0, maxChars)}
+
+---
+*[Output truncated at ${maxChars} characters. Use atlas_compile for structured sections.]*`;
+      truncated = true;
+    }
+    if (text && text.length > maxChars) {
+      text = `${text.slice(0, maxChars)}
+
+---
+*[Output truncated at ${maxChars} characters]*`;
+      truncated = true;
+    }
+    const charCount = (markdown ?? text ?? "").length;
+    const wordCount = (markdown ?? text ?? "").split(/\s+/).filter(Boolean).length;
+    const readTimeSeconds = Math.max(1, Math.ceil(wordCount / 4));
+    return {
+      url: root.url ?? args.url,
+      title,
+      markdown,
+      text,
+      links,
+      stats: {
+        character_count: charCount,
+        word_count: wordCount,
+        read_time_seconds: readTimeSeconds
+      },
+      truncated
+    };
+  };
+}
+function formatScrapeResult(res) {
+  const parts = [`# ${res.title}`, `*Source: ${res.url}*`, ""];
+  if (res.markdown) {
+    parts.push(res.markdown);
+  } else if (res.text) {
+    parts.push(res.text);
+  }
+  if (res.links && res.links.length > 0) {
+    parts.push("", "## Discovered Links");
+    for (const link of res.links.slice(0, 20)) {
+      parts.push(`- [${link.text || link.url}](${link.url})`);
+    }
+    if (res.links.length > 20) {
+      parts.push(`*... and ${res.links.length - 20} more links*`);
+    }
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: parts.join("\n")
+      }
+    ],
+    structuredContent: res
+  };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/server";
+function createAtlasMcpServer(options = {}) {
+  const context = options.context ?? {};
+  const server = new McpServer({
+    name: "atlas",
+    version: "1.0.0"
+  });
+  const scrapeExec = options.scrapeExecutor ?? createRemoteScrapeExecutor(context);
+  const compileExec = options.compileExecutor ?? createRemoteCompileExecutor(context);
+  const mapExec = options.mapExecutor ?? createRemoteMapExecutor(context);
+  const batchExec = options.batchExecutor ?? createRemoteBatchExecutor(context);
+  const crawlExec = options.crawlExecutor ?? createRemoteCrawlExecutor(context);
+  const resourceRead = options.resourceReader ?? createRemoteResourceReader(context);
+  server.registerTool(
+    scrapeToolDefinition.name,
+    {
+      description: scrapeToolDefinition.description,
+      inputSchema: scrapeToolDefinition.inputSchema,
+      outputSchema: scrapeToolDefinition.outputSchema,
+      annotations: scrapeToolDefinition.annotations
+    },
+    async (args) => {
+      try {
+        const res = await scrapeExec(args);
+        return formatScrapeResult(res);
+      } catch (err) {
+        return formatErrorToToolResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    compileToolDefinition.name,
+    {
+      description: compileToolDefinition.description,
+      inputSchema: compileToolDefinition.inputSchema,
+      outputSchema: compileToolDefinition.outputSchema,
+      annotations: compileToolDefinition.annotations
+    },
+    async (args) => {
+      try {
+        const res = await compileExec(args);
+        const maxChars = args.max_output_chars ?? 3e4;
+        if (res.markdown && res.markdown.length > maxChars) {
+          const slice = res.markdown.slice(0, maxChars);
+          const lastNl = slice.lastIndexOf("\n\n");
+          const cleanSlice = lastNl > 1e3 ? slice.slice(0, lastNl) : slice;
+          const toc = (res.headings ?? []).slice(0, 15).map((h) => `${"  ".repeat(Math.max(0, h.level - 1))}- [${h.text}](${h.resource_uri})`).join("\n");
+          res.markdown = `${cleanSlice}
+
+---
+### \u26A0\uFE0F Output Truncated (${maxChars} chars limit reached)
+
+#### Available Document Sections:
+${toc}
+
+*Full content available via resource:* \`${res.resources.compiled_artifact_uri}\``;
+          res.truncated = true;
+        }
+        return formatCompileResult(res);
+      } catch (err) {
+        return formatErrorToToolResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    mapToolDefinition.name,
+    {
+      description: mapToolDefinition.description,
+      inputSchema: mapToolDefinition.inputSchema,
+      outputSchema: mapToolDefinition.outputSchema,
+      annotations: mapToolDefinition.annotations
+    },
+    async (args) => {
+      try {
+        const res = await mapExec(args);
+        return formatMapResult(res);
+      } catch (err) {
+        return formatErrorToToolResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    batchToolDefinition.name,
+    {
+      description: batchToolDefinition.description,
+      inputSchema: batchToolDefinition.inputSchema,
+      outputSchema: batchToolDefinition.outputSchema,
+      annotations: batchToolDefinition.annotations
+    },
+    async (args) => {
+      try {
+        const res = await batchExec(args);
+        return formatBatchResult(res);
+      } catch (err) {
+        return formatErrorToToolResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    crawlToolDefinition.name,
+    {
+      description: crawlToolDefinition.description,
+      inputSchema: crawlToolDefinition.inputSchema,
+      outputSchema: crawlToolDefinition.outputSchema,
+      annotations: crawlToolDefinition.annotations
+    },
+    async (args) => {
+      try {
+        const res = await crawlExec(args);
+        return formatCrawlResult(res);
+      } catch (err) {
+        return formatErrorToToolResult(err);
+      }
+    }
+  );
+  const normalizeVars = (vars) => {
+    const res = {};
+    for (const [k, v] of Object.entries(vars)) {
+      res[k] = Array.isArray(v) ? v[0] ?? "" : v;
+    }
+    return res;
+  };
+  server.registerResource(
+    "Compiled Page",
+    compilationResourceTemplate,
+    {
+      mimeType: "text/markdown",
+      description: "Full compiled markdown artifact for compilation {id}",
+      cacheHint: { ttlMs: 3e5, cacheScope: "private" }
+    },
+    async (uri, variables) => {
+      return resourceRead(uri.toString(), normalizeVars(variables));
+    }
+  );
+  server.registerResource(
+    "Compiled Section",
+    sectionResourceTemplate,
+    {
+      mimeType: "text/markdown",
+      description: "Exact text slice of a specific heading section within compilation {id}",
+      cacheHint: { ttlMs: 3e5, cacheScope: "private" }
+    },
+    async (uri, variables) => {
+      return resourceRead(uri.toString(), normalizeVars(variables));
+    }
+  );
+  server.registerResource(
+    "Crawl Manifest",
+    crawlResourceTemplate,
+    {
+      mimeType: "application/json",
+      description: "Full crawl inventory with all discovered URLs, HTTP status codes, and artifact pointers",
+      cacheHint: { ttlMs: 3e5, cacheScope: "private" }
+    },
+    async (uri, variables) => {
+      return resourceRead(uri.toString(), normalizeVars(variables));
+    }
+  );
+  server.registerResource(
+    "Compiled AST",
+    astResourceTemplate,
+    {
+      mimeType: "application/json",
+      description: "Abstract Syntax Tree (AST) JSON artifact for compilation {id}",
+      cacheHint: { ttlMs: 3e5, cacheScope: "private" }
+    },
+    async (uri, variables) => {
+      return resourceRead(uri.toString(), normalizeVars(variables));
+    }
+  );
+  return server;
+}
+
+export {
+  AtlasMcpError,
+  wrapFetchError,
+  assertOkResponse,
+  formatErrorToToolResult,
+  compilationResourceTemplate,
+  sectionResourceTemplate,
+  crawlResourceTemplate,
+  astResourceTemplate,
+  createRemoteResourceReader,
+  compileInputSchema,
+  compileOutputSchema,
+  compileToolDefinition,
+  createRemoteCompileExecutor,
+  formatCompileResult,
+  batchInputSchema,
+  batchOutputSchema,
+  batchToolDefinition,
+  createRemoteBatchExecutor,
+  formatBatchResult,
+  crawlInputSchema,
+  crawlOutputSchema,
+  crawlToolDefinition,
+  createRemoteCrawlExecutor,
+  formatCrawlResult,
+  mapInputSchema,
+  mapOutputSchema,
+  mapToolDefinition,
+  createRemoteMapExecutor,
+  formatMapResult,
+  scrapeInputSchema,
+  scrapeOutputSchema,
+  scrapeToolDefinition,
+  createRemoteScrapeExecutor,
+  formatScrapeResult,
+  createAtlasMcpServer
+};