Atlas Web Compiler & Scraper

@atlascompiler/mcp

Atlas の公式 Model Context Protocol (MCP) サーバーです。

AI コーディングアシスタント、エージェント、LLM（Cursor、Claude Desktop、Windsurf、ChatGPT、MCP Inspector）を、Atlas の LLM を使わないウェブコンパイルパイプラインに直接接続します。LLM による幻覚やコンテキストの肥大化を招くことなく、決定論的でクリーンな Markdown の抽出、サイト構造の検出、一括コンパイル、範囲を限定したクロールを実現します。

---

機能

• LLM を使わない決定論的なコンパイル：Atlas のウェブコンパイラーエンジンのみでコンテンツを解析、構造化します。幻覚による要約、不要なノイズの注入、データの欠落はありません。
• コンテキストウィンドウの保護：目次（TOC）の自動生成、セクション分割、トークン予算の管理、明示的な切り捨てバナーにより、LLM のコンテキスト制限を保護します。
• 最新のプロトコル標準：ネイティブなプロンプトキャッシュヒント（cacheHints: { ttlMs, cacheScope }）を備えた 2026-07-28 プロトコル世代を実装し、io.modelcontextprotocol/tasks による非同期タスク追跡に対応しています。
• 2 種類のトランスポート：
  • Stdio CLI ブリッジ：npx @atlascompiler/mcp でローカル実行するか、デスクトップ IDE に直接設定できます。
  • Edge Streamable HTTP：リモートクライアントやウェブエージェント向けに、Cloudflare Worker エンドポイントを POST /mcp にネイティブにマウントします。
• エンタープライズレベルのセキュリティ：
  • 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 をインストールします。

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	Claude、Cursor、その他の MCP クライアント向けに、stdio 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 は、Web のコンパイル、スクレイピング、マッピング、クロール、バッチ抽出のための段階的な開示形式のプレイブックを提供する、AI コーディングエージェント（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 エコシステム 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

---

クライアントの設定

エディターは、次の 2 つの方法で設定できます。

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）

リモートエージェントまたは公式の 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 コーディングアシスタントやエージェントのワークフロー向けに、用途を絞った5つのツールを提供します。

#	Tool	Description	Best For
1	atlas_compile	AST を12段階で詳細にコンパイルし、高密度の Markdown に変換します	複雑なドキュメント、API リファレンス、表、コードブロック
2	atlas_scrape	単一ページのコンテンツとリンクをすばやく抽出します	記事、ブログ投稿、ニュース、プレーンテキスト
3	atlas_map	ドメインの構造をたどり、サイトマップを探索します	ページ本文をダウンロードせずに到達可能な URL を見つける場合
4	atlas_batch_compile	複数のページを並行してコンパイルします（最大20 URL）	複数ページの比較、一括データ取り込み
5	atlas_crawl	パスの glob フィルタリングによる、範囲を限定した再帰的なウェブサイトクロール	セクションを指定したサイトのクロール（例：/docs/**）

---

atlas_compile

任意のウェブページを、LLM の推論に最適化された構造化済み高密度 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)
}

エージェントの呼び出し例：

"https://docs.stripe.com/api/payment_intents にある Stripe の 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)
}

エージェントの呼び出し例：

"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')
}

エージェントの呼び出し例：

"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)
}

エージェントの呼び出し例：

"次の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'])
}

エージェントの呼び出し例：

"https://example.com/docs/welcome から /docs/ 内を最大10ページまでクロールしてください。"

---

利用可能なMCPリソース（atlas://）

サーバーは、ツール呼び出しログを汚さずに AI エージェントが必要に応じてドキュメント全体を取得できる、決定論的なリソース URI を提供します。

Resource URI Template	Description
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,
  }),
});

---

環境変数

Variable	Required	Default	Description
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