augments-mcp-server

Model Context Protocol（MCP）を介して Claude Code に次世代のフレームワークドキュメントを提供します。厳選されたパッケージだけでなく、あらゆる npm パッケージについて、コンテキストに応じた形式で 型＋解説＋サンプルを返します。

mcp-name: dev.augments/mcp

v7 の新機能

バージョン 7.0 はこれまでで最大のアップグレードです。ドキュメント優先の検索、4 つの新しいツール、BM25 インデックス、そして本番環境レベルの信頼性を備えています。

v6	v7
3 つのツール	8 つのツール（＋診断）
型のみの検索	ドキュメント優先の BM25 検索
8 個の概念同義語	25 個の概念同義語クラスター
汎用的なバージョン差分	実際の変更履歴に基づく破壊的変更
移行ガイドなし	バージョンをまたいだ移行ガイド
エラー診断なし	厳選されたエラーパターン＋GitHub Issues
パッケージ比較なし	パッケージの並列比較
依存関係スキャンなし	依存関係スキャナー（古い依存関係／非推奨／セキュリティ）
FIFO キャッシュ	ヒット／ミス統計付き LRU キャッシュ
固定された再試行間隔	指数バックオフ＋サーキットブレーカー

クイックスタート

Claude Code

# Add the MCP server (runs locally via npx)
claude mcp add -s user augments -- npx -y @augmnt-sh/augments-mcp-server

# Verify configuration
claude mcp list

Cursor

MCP 設定に追加します：

{
  "mcpServers": {
    "augments": {
      "command": "npx",
      "args": ["-y", "@augmnt-sh/augments-mcp-server"]
    }
  }
}

環境変数

サンプルやドキュメントを取得する際の GitHub API レート制限を緩和するには、GITHUB_TOKEN を設定します。

{
  "mcpServers": {
    "augments": {
      "command": "npx",
      "args": ["-y", "@augmnt-sh/augments-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

使い方

# Get API context with prose + examples (recommended first tool)
@augments get_api_context query="useEffect cleanup" framework="react"

# Natural language queries work great
@augments get_api_context query="how to use zustand middleware"

# Search for APIs by concept (synonym-aware)
@augments search_apis query="state management"

# Get version info with real breaking changes
@augments get_version_info framework="react" fromVersion="18" toVersion="19"

# Migration guide between versions
@augments get_migration_guide package="next" fromVersion="14" toVersion="15"

# Diagnose an error
@augments diagnose_error error="Objects are not valid as a React child" package="react"

# Compare packages side-by-side
@augments compare_packages packages=["zod", "yup", "joi"]

# Scan project dependencies
@augments scan_project_deps

ツール

ツール	説明
get_api_context	主要ツール。 あらゆる npm パッケージの API シグネチャ、解説ドキュメント、コードサンプルを返します。意図を検出して自然言語のクエリに対応します。ドキュメント優先の BM25 検索を新たに搭載しました。
search_apis	キーワードまたは概念を使って、フレームワーク全体から API を検索します。25 個の同義語クラスターにより、「state」で useState、createStore、atom などが検索結果に含まれます。
get_version_info	npm のバージョン情報を取得し、バージョンを比較して、実際の変更履歴に基づいて破壊的変更を検出します。
get_migration_guide	新機能。 破壊的変更、新機能、非推奨項目、型の差分、公式の移行ドキュメントを含む、バージョンをまたいだ移行ガイドを提供します。
diagnose_error	新機能。 厳選されたパターン、GitHub Issues の検索、トラブルシューティングドキュメントを使ってエラーを診断します。
compare_packages	新機能。 2～5 個の npm パッケージを比較します。ダウンロード数、バンドルサイズ、GitHub スター数、依存関係、エクスポートされた API を比較できます。
scan_project_deps	新機能。 package.json をスキャンし、古い依存関係、非推奨の依存関係、安全でない依存関係を検出します。
diagnostics	サーバーの状態を確認します。バージョン、稼働時間、メモリ、キャッシュ統計、Node.js のバージョンを表示します。

アーキテクチャ

flowchart TD
    A["Query: 'how to use useEffect cleanup'"] --> B

    B["Intent Detection → howto<br/>Query Parser → react / useEffect"]

    B --> C["Type Fetcher<br/>CDN racing · npm metadata · @types"]
    B --> D["Doc Fetcher<br/>GitHub API · BM25 search · 25 synonym clusters"]
    B --> E["Example Extractor<br/>GitHub docs · README fallback · Auto-discovery"]

    C --> F["Type Parser<br/>Signatures · Parameters · Related types"]
    D --> G["Doc Search Engine<br/>BM25 indexing · Heading-based chunks · API boost"]

    F --> H["Intent-Driven Formatter (howto)<br/>→ Examples first, prose, brief signature<br/>→ ~500-2000 tokens, 10KB max"]
    G --> H
    E --> H

ソース構成

src/
├── cli.ts                   # stdio entry point
├── server.ts                # MCP server (8 tools + diagnostics)
├── core/                    # Core modules
│   ├── query-parser.ts      # Parse natural language → framework + concept
│   ├── type-fetcher.ts      # Fetch .d.ts + README from npm/unpkg/jsdelivr
│   ├── type-parser.ts       # Parse TypeScript, extract signatures, synonym search
│   ├── example-extractor.ts # Fetch examples from GitHub docs + auto-discovery
│   ├── version-registry.ts  # npm registry integration + changelog-backed diffs
│   ├── doc-fetcher.ts       # GitHub documentation fetcher
│   ├── doc-search.ts        # BM25 inverted index search engine
│   ├── changelog-fetcher.ts # CHANGELOG.md + GitHub Releases parser
│   ├── type-differ.ts       # .d.ts diff between versions
│   └── error-patterns.ts    # Curated error pattern database
├── tools/v4/                # MCP tools
│   ├── get-api-context.ts   # Primary tool (types + docs + examples)
│   ├── search-apis.ts       # Cross-framework API search
│   ├── get-version-info.ts  # Version comparison
│   ├── get-migration-guide.ts # Cross-version migration guides
│   ├── diagnose-error.ts    # Error diagnosis
│   ├── compare-packages.ts  # Package comparison
│   └── scan-project-deps.ts # Dependency scanner
└── utils/
    ├── logger.ts            # stderr logger
    └── lru-cache.ts         # Generic LRU cache with stats

主な機能

ドキュメント優先の検索（v7 の新機能）

「prisma findMany with pagination」や「zustand create store with middleware」のようなクエリで、実際のドキュメント内容が返されるようになりました。BM25 検索エンジンは、GitHub から取得したドキュメントを見出し単位のチャンクに分けてインデックス化し、API 名の重み付けと同義語の拡張にも対応しています。

概念の同義語

25 個の同義語クラスターが、state、form、fetch、animation、routing、auth、cache、effect、middleware、pagination、validation、testing、streaming、error handling、database、layout、modal、table、upload、realtime、deployment、i18n、SSR、component、context の各パターンをカバーします。双方向の検索により、「usestate」を検索すると「state」クラスターに展開されます。

意図に応じたフォーマット

意図	トリガー	形式
howto	"how to"、"example of"、"guide"	サンプル → 解説 → 簡潔なシグネチャ
reference	"signature"、"types"、"parameters"	完全なシグネチャ → 関連する型 → 1 つのサンプル
migration	"migrate"、"upgrade"、"breaking"	解説 → シグネチャ → サンプル
balanced	デフォルト	シグネチャ → 解説 → サンプル

本番環境での信頼性（v7の新機能）

• npm レジストリへの再試行にジッター付き指数バックオフを採用し、429 Retry-After に対応
• CDN サーキットブレーカー — 繰り返し失敗する CDN エンドポイントをスキップします（5分間に3回失敗）
• GitHub レート制限 — 残りのクォータを追跡し、上限に達した場合はフェッチをスキップします
• キャッシュを使用するすべてのモジュールで、ヒット数とミス数の統計情報を備えたLRU キャッシュ

対応範囲

あらゆる npm パッケージ

すべての npm パッケージをそのまま利用できます。選定や設定は不要です。Augments は4つのレイヤーを通じてドキュメントを自動的に解決します。

1. ドキュメント検索 — GitHub リポジトリから実際のドキュメントを取得し、BM25 でインデックス化します
2. TypeScript 型 — バンドル済みの型（package.json の "types"）または DefinitelyTyped（@types/*）
3. 自動検出されたドキュメント — npm の repository フィールドを解析して GitHub リポジトリを特定し、docs/ ディレクトリを調べます
4. README のフォールバック — README.md から概念に関連するコードブロックと説明文を抽出します

つまり Augments は、選定された一部のパッケージだけでなく、npm エコシステム全体（約250万パッケージ）で動作します。

人気のフレームワーク向けの強化された結果

より充実した例を提供するため、22のフレームワークに厳選されたドキュメントソースがあります：React、Next.js、Vue、Prisma、Zod、Supabase、TanStack Query、tRPC、React Hook Form、Framer Motion、Express、Zustand、Jotai、Drizzle、SWR、Vitest、Playwright、Fastify、Hono、Solid、Svelte、Angular、Redux

バレルエクスポートの処理

次の対象では、サブモジュールの特別な解決を行います：React Hook Form、TanStack Query、Zustand、Jotai、tRPC、Drizzle ORM、Next.js

ローカル開発

# Clone and install
git clone https://github.com/augmentscode/augments-mcp-server.git
cd augments-mcp-server
npm install

# Build with tsup
npm run build

# Run locally
npm start

# Watch mode
npm run dev

# Run tests
npm test

# Run e2e tests (real network calls)
npm run test:e2e

# Type check
npm run type-check

Augments と Context7 の比較

項目	Context7	Augments v7
ソース	解析済みの説明文ドキュメント	型 + BM25 でインデックス化されたドキュメント + README
正確性	ドキュメントに誤りがある場合があります	型の正確性を必須とし、ドキュメントで補足します
コンテキストサイズ	約5～10KBのチャンク	約500～2000トークン（意図を考慮）
対応範囲	手動での申請	あらゆる npm パッケージ（自動検出）
形式	画一的	意図を考慮（使い方とリファレンス）
検索	キーワード一致	BM25 + 25の概念同義語クラスター
最新性	クロールスケジュール	npm + GitHub からオンデマンドで取得
移行	なし	バージョン間の移行ガイド
エラー対応	なし	厳選されたパターン + GitHub Issues
依存関係スキャン	なし	古い依存関係／非推奨／セキュリティのチェック

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. 変更を加えます
4. テストを実行します：npm test
5. プルリクエストを送信します

ライセンス

MIT ライセンス — 詳細は LICENSE を参照してください。

サポート

• GitHub Issues
• GitHub Discussions

---

Claude Code エコシステム向けに構築 | バージョン 7.0.0