Atlas Web Compiler & Scraper

@atlascompiler/mcp

适用于 Atlas 的官方 Model Context Protocol (MCP) 服务。

将 AI 编码助手、Agent 和大模型（Cursor、Claude Desktop、Windsurf、ChatGPT、MCP Inspector）直接连接到 Atlas 的零大模型 Web 编译管线。提供确定性、整洁的 Markdown 提取、站点拓扑发现、批量编译和有界爬取，不会产生大模型幻觉或上下文膨胀。

---

功能

• 零大模型确定性编译：内容完全通过 Atlas Web 编译引擎解析和结构化——没有幻觉摘要、注入噪声或数据缺失。
• 上下文窗口保护：自动生成目录（TOC）、拆分章节、预算令牌，并显示明确的截断提示，以保护大模型的上下文限制。
• 现代协议标准：实现 2026-07-28 协议时代的标准，支持原生提示词缓存提示（cacheHints: { ttlMs, cacheScope }），并通过 io.modelcontextprotocol/tasks 异步跟踪任务。
• 双传输方式：
  • Stdio CLI 桥接：通过 npx @atlascompiler/mcp 在本地运行，或直接配置到桌面 IDE 中。
  • Edge Streamable HTTP：原生 Cloudflare Worker 端点，挂载于 POST /mcp，供远程客户端和 Web Agent 使用。
• 企业级安全性：
  • 拒绝 CLI 凭据标志（--api-key、-k），并以退出代码 1 结束，以避免密钥暴露在 ps aux 输出和进程检查中。
  • 对所有 atlas:// 资源实施严格的租户隔离（WHERE workspace_id = ?1 AND id = ?2）。
  • 阻止恶意 Origin，防止基于浏览器的跨源诱导攻击。
  • 所有出站网络请求均交由 atlas-egress 处理，以提供零信任 SSRF 防护。

---

快速开始

获取 API 密钥

登录 Atlas Dashboard 生成免费的 API 密钥（atlas_...）。

交互式设置向导（推荐）

运行一键交互式设置向导，验证 API 密钥并自动配置桌面编辑器（Claude Desktop、Cursor、VS Code、Windsurf）：

# Interactive mode (prompts for scope: Global, Project, or Both):
npx -y @atlascompiler/mcp init

# Or preselect scope directly via CLI flags:
npx -y @atlascompiler/mcp init --global    # User-level (Claude, ~/.cursor, Windsurf)
npx -y @atlascompiler/mcp init --project   # Repo-level (.cursor/mcp.json, .vscode/mcp.json)
npx -y @atlascompiler/mcp init --both      # Both user-level and project-level
npx -y @atlascompiler/mcp init --skip-editors # Save credentials only

向导将：

• 提示输入 Atlas API 密钥（atlas_...）。
• 将其安全存储在 ~/.atlas/credentials.json 中（POSIX 0600 权限）。
• 检测已安装的编辑器，并以非破坏性方式合并 Atlas MCP 服务定义，而不会将敏感令牌硬编码到编辑器配置文件中。
• 区分标准客户端（mcpServers）和 VS Code 工作区格式（servers）。
• 可选安装规范的 Atlas Agent Skill，以便在本地或全局发现 Agent。

直接运行 Stdio 服务

通过 init 完成配置后，即可在无需任何标志或环境变量的情况下运行 MCP 服务：

npx -y @atlascompiler/mcp

无头环境和 CI/CD 环境

在自动化管线、容器化环境或临时工作进程中，通过 ATLAS_API_KEY 环境变量提供凭据：

# macOS / Linux
export ATLAS_API_KEY="atlas_your_api_key_here"

# Windows PowerShell
$env:ATLAS_API_KEY = "atlas_your_api_key_here"

npx -y @atlascompiler/mcp

安全提示： 严禁通过 CLI 标志（--api-key 或 -k）传递 API 密钥，CLI 会阻止此操作，以避免密钥泄露在进程表中。请始终使用 init 或 ATLAS_API_KEY 环境变量。

---

CLI 命令

命令	描述
npx @atlascompiler/mcp	启动 stdio MCP 服务，供 Claude、Cursor 和其他 MCP 客户端使用。
npx @atlascompiler/mcp init	交互式凭据设置向导、编辑器配置和 Agent Skill 安装。
npx @atlascompiler/mcp init --global	设置凭据并配置用户级编辑器（Claude、~/.cursor、Windsurf）。
npx @atlascompiler/mcp init --project	设置凭据并配置仓库级编辑器（.cursor、.vscode）。
npx @atlascompiler/mcp skill	将规范的 Atlas Agent Skill 安装到项目中（.agents/skills/atlas/SKILL.md）。
npx @atlascompiler/mcp skill --global	将规范的 Atlas Agent Skill 全局安装（~/.agents/skills/atlas/SKILL.md）。
npx @atlascompiler/mcp whoami	检查当前使用的凭据及其来源（env 或 ~/.atlas/credentials.json）。
npx @atlascompiler/mcp logout	清除 ~/.atlas/credentials.json 中保存的凭据。
npx @atlascompiler/mcp --help	显示命令行用法。

---

Agent Skill 安装

Atlas 为 AI 编码 Agent（Claude Code、Cursor、Antigravity、Windsurf）发布了官方 Agent Skill，提供用于网页编译、抓取、映射、爬取和批量提取的渐进式披露操作手册。

选项 1：通过 @atlascompiler/mcp CLI（最快）

# In your current project:
npx -y @atlascompiler/mcp skill

# Or globally for all projects:
npx -y @atlascompiler/mcp skill --global

选项 2：通过 Skills Ecosystem CLI（npx skills）

# Via domain discovery (RFC 8615):
npx skills add atlas-compiler.com

# Or via GitHub repository:
npx skills add redcliffe0003/Atlas

选项 3：直接下载 / Curl

curl -fsSL https://atlas-compiler.com/skill.md -o .agents/skills/atlas/SKILL.md

---

客户端配置

你可以通过两种方式配置编辑器：

1. 交互式设置向导（推荐）：运行 npx -y @atlascompiler/mcp init，将凭据安全地保存到 ~/.atlas/credentials.json（POSIX 0600）。编辑器配置文件保持干净，不会有令牌被提交到 git。
2. 直接手动配置：将下方的服务配置块与 ATLAS_API_KEY 一起添加到编辑器的 MCP 配置文件中。

Cursor IDE

将服务添加到 Cursor MCP 设置中（全局配置使用 ~/.cursor/mcp.json，或在仓库中使用 .cursor/mcp.json）：

{
  "mcpServers": {
    "atlas": {
      "command": "npx",
      "args": ["-y", "@atlascompiler/mcp"],
      "env": {
        "ATLAS_API_KEY": "atlas_your_api_key_here"
      }
    }
  }
}

（如果你已运行 atlas-mcp init，可以省略 "env" 块。）

VS Code

将服务添加到项目的 .vscode/mcp.json 中：

{
  "servers": {
    "atlas": {
      "command": "npx",
      "args": ["-y", "@atlascompiler/mcp"],
      "env": {
        "ATLAS_API_KEY": "atlas_your_api_key_here"
      }
    }
  }
}

注意： VS Code 要求根键为 "servers"，而 Cursor、Claude Desktop 和 Windsurf 使用 "mcpServers"。atlas-mcp init 向导会自动为每个编辑器目标应用正确的格式。

Claude Desktop

将服务添加到 Claude Desktop 配置中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "atlas": {
      "command": "npx",
      "args": ["-y", "@atlascompiler/mcp"],
      "env": {
        "ATLAS_API_KEY": "atlas_your_api_key_here"
      }
    }
  }
}

Windsurf / Codeium

将服务添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "atlas": {
      "command": "npx",
      "args": ["-y", "@atlascompiler/mcp"],
      "env": {
        "ATLAS_API_KEY": "atlas_your_api_key_here"
      }
    }
  }
}

远程 / 托管的 Streamable HTTP（POST /mcp）

适用于远程 Agent 或官方 MCP Inspector：

• 服务 URL：https://api.atlas-compiler.com/mcp
• 传输方式：Streamable HTTP
• HTTP 标头：
  • Authorization: Bearer atlas_YOUR_API_KEY_HERE
  • Content-Type: application/json
  • Accept: application/json
• OAuth 发现：支持通过 GET /.well-known/oauth-protected-resource 进行 RFC 8414 受保护资源发现。

---

可用的 MCP 工具

Atlas 为 AI 编码助手和 Agent 工作流提供 5 个专用工具：

#	工具	描述	最适用于
1	atlas_compile	通过 12 轮深度 AST 编译，生成高密度 Markdown	复杂文档、API 参考、表格和代码块
2	atlas_scrape	快速提取单页内容和链接	文章、博客文章、新闻和原始文本
3	atlas_map	域名拓扑爬取工具和站点地图浏览器	在不下载页面正文的情况下发现可访问的 URL
4	atlas_batch_compile	并发并行编译（最多 20 个 URL）	多页面比较和批量数据摄取
5	atlas_crawl	通过路径 glob 过滤进行有界递归网站爬取	针对特定版块的网站爬取（例如 /docs/**）

---

atlas_compile

将任意网页编译为结构化、高密度的 Markdown 文档，针对大模型推理进行了优化。

{
  url: string;                          // Required: Absolute HTTP/HTTPS URL
  format?: 'markdown' | 'semantic' | 'markdown+links'; // 'semantic' includes AST graph; 'markdown+links' appends links
  max_output_chars?: number;            // Maximum characters to return in the tool response (default: 30000)
  force_fresh?: boolean;                // Bypass edge cache and force fresh compile from origin (default: false)
}

Agent 调用示例：

“编译 Stripe payment intents 文档 https://docs.stripe.com/api/payment_intents，并向我展示 API 参数。”

---

atlas_scrape

无需深度编译时，用于快速、轻量地提取单页内容。

{
  url: string;                          // Required: Absolute HTTP/HTTPS URL
  formats?: Array<'markdown' | 'links' | 'text'>; // Formats to extract (default: ['markdown'])
  max_output_chars?: number;            // Capping threshold (default: 30000)
  timeout_ms?: number;                  // Maximum fetch timeout in milliseconds (default: 15000)
}

Agent 调用示例：

“从 https://atlas-compiler.com 抓取正文和链接。”

---

atlas_map

在不下载页面正文的情况下，发现目标域名的站点拓扑、站点地图和可访问的 URL。

{
  url: string;                          // Required: Root URL or domain (e.g. 'https://docs.github.com')
  limit?: number;                       // Maximum URLs to return (1-500, default: 100)
  include_subdomains?: boolean;         // Follow subdomains (default: false)
  sitemap?: 'include' | 'skip' | 'only'; // Sitemap inspection strategy (default: 'include')
}

Agent 调用示例：

“映射 https://docs.github.com 上的文档页面，以便了解有哪些指南可用。”

---

atlas_batch_compile

并行编译多个页面（最多 20 个 URL），并汇总每份文档的成功或失败情况。

{
  urls: string[];                       // Required: Array of 1 to 20 URLs
  format?: 'markdown' | 'semantic' | 'markdown+links'; // Content format (default: 'markdown')
  max_output_chars_per_page?: number;   // Character cap per document (default: 15000)
}

Agent 调用示例：

“同时编译以下 3 个发行说明页面：['https://site.com/v1', 'https://site.com/v2', 'https://site.com/v3']。”

---

atlas_crawl

从种子 URL 开始爬取网站，并通过链接发现、深度限制和路径过滤控制爬取范围。

{
  url: string;                          // Required: Seed URL to begin crawling
  max_pages?: number;                   // Maximum pages to process (1-50, default: 10)
  max_depth?: number;                   // Maximum link hops (1-5, default: 2)
  include_paths?: string[];             // Path glob patterns to restrict compilation (e.g. ['/docs/**', '/reference/**'])
  exclude_paths?: string[];             // Path glob patterns to skip (e.g. ['/changelog/**', '/**/pricing'])
}

Agent 调用示例：

“从 https://example.com/docs/welcome 开始，爬取 /docs/ 中最多 10 个页面。”

---

可用的 MCP 资源（atlas://）

该服务提供确定性的资源 URI，允许 AI Agent 按需检索完整文档内容，而不会污染工具调用日志：

资源 URI 模板	描述
atlas://compilations/{id}	与编译 {id} 对应的完整编译版 Markdown 文档。
atlas://compilations/{id}/sections/{section_id}	编译 {id} 中的特定标题章节或片段。
atlas://crawls/{id}	完整的爬取清单、发现的 URL、HTTP 状态码和工件指针。

所有资源读取都会强制执行工作区租户隔离（WHERE workspace_id = ?1 AND id = ?2）。跨租户访问会以 ATLAS_RESOURCE_NOT_FOUND 失败关闭，以杜绝数据泄漏。

---

程序化使用

你也可以在自己的 Node.js 或 TypeScript 应用程序中嵌入并自定义 @atlascompiler/mcp：

import { createAtlasMcpServer } from '@atlascompiler/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/server';

const server = createAtlasMcpServer({
  context: {
    // Option A: Explicit manual API key
    apiKey: 'atlas_your_api_key_here',

    // Option B: Automatically loaded from process.env.ATLAS_API_KEY
    // apiKey: process.env.ATLAS_API_KEY,

    baseUrl: 'https://api.atlas-compiler.com',
  },
});

const transport = new StdioServerTransport();
await server.connect(transport);

提供自定义执行器（测试 / 存根）

const server = createAtlasMcpServer({
  scrapeExecutor: async (args) => ({
    url: args.url,
    markdown: '# Mock Content',
    status: 200,
  }),
});

---

环境变量

变量	必填	默认值	描述
ATLAS_API_KEY	是	—	你的 Atlas 工作区 API 密钥（atlas_...）。
ATLAS_BASE_URL	否	https://api.atlas-compiler.com	Atlas API 或可自托管后端的基础 URL。

---

开发与测试

# Install dependencies
pnpm install

# Run unit and conformance tests (Vitest)
pnpm test

# Check types
pnpm typecheck

# Check code formatting & linting (Biome)
pnpm lint

# Build ESM & TypeScript declaration bundle
pnpm build

---

许可证

MIT © Atlas Compiler