agentsbestfriend

AgentsBestFriend（abf）

AI コーディングエージェントに強力な機能を追加しましょう。高速でトークン効率に優れたコードのナビゲーション、検索、分析を行うローカルの MCP サーバーです。

VS Code Copilot、Cursor、Claude Code/Desktop、Codex、Cline、Zed、Gemini CLI、Goose、OpenCode、その他あらゆる MCP 互換エージェントで動作します。

---

なぜ使うのか？

AI コーディングエージェントは、ファイルを何度も読み直したり、手当たり次第に検索したりしてトークンを無駄にしています。ABF は目的に特化したツールを提供し、必要な情報だけを、コンテキストを保った簡潔で構造化された応答として返します。

ツール

ツール	機能
abf_search	コード検索 — 完全一致（ripgrep）、キーワードのランキング順、またはセマンティック検索（埋め込みベース）
abf_search_multi	スコアを重み付けして統合し、1 回の呼び出しで複数の検索クエリ（完全一致／キーワード／セマンティック）を実行
abf_symbols	ファイル内の関数、クラス、エクスポート（TS/JS は AST ベース、Python は正規表現）
abf_chunk	シンボル名、チャンク番号、またはファイル概要を指定して、ファイルをスマートに分割
abf_project_overview	技術スタック、フォルダー構成、主要な依存関係をひと目で確認
abf_dependencies	インポートグラフ — どのファイルが何をインポートしているか
abf_impact	プロジェクト全体からシンボルの使用箇所をすべて検索
abf_impact_typed	分類された参照（definition/call/import/type_ref/jsx）と信頼度レベルを備えた、AST 対応（ts-morph）の影響分析
abf_blast_radius	リスクスコア（低／中／高）を付けて、ファイルの逆インポートグラフを幅優先探索
abf_related_tests	ファイルまたはシンボルをカバーしている可能性が高いテストファイルをヒューリスティックに順位付け
abf_preview_changes	読み取り専用のプレビュー：差分 + シンボル／インポートの増減 + リスクフラグ + 外部使用状況の調査（書き込みなし）
abf_refactor_plan	名前変更／移動／抽出／分割のための、衝突検出を含む読み取り専用の編集計画
abf_apply_edit	書き込みツール — sha256 ハッシュチェック付きのアトミックなファイル書き込み（ABF_ENABLE_WRITES=1 でない限り無効）
abf_diagnostics	1 つのファイル、または追跡対象のすべての TS/JS ファイルの TypeScript 診断（エラー／警告）
abf_definition	TypeScript 言語サービスによる定義ジャンプ — ファイル、行範囲、ソースのプレビュー
abf_hover	識別子の型シグネチャ + JSDoc（IDE 形式のホバー）
abf_call_graph	関数またはメソッドの推移的な呼び出し元／呼び出し先（TS/JS、ts-morph）
abf_git	Git のログ、blame、差分（直近／ステージ済み／未ステージ）
abf_file_summary	LLM 生成のファイル概要を対象とした全文検索（FTS5、OR/AND モード）
abf_conventions	検出された命名、構成、書式の規約
abf_index	インデックスの状態、再構築、差分更新、または要約の再生成を開始
abf_ping	ヘルスチェック — バージョンとプロジェクトルートを返す

インストール

npm install -g agentsbestfriend

前提条件

• Node.js ≥ 20
• ripgrep — brew install ripgrep（macOS）／apt install ripgrep（Linux）
• git
• Ollama（任意）— 要約とセマンティック検索に使用：ollama.com

クイックスタート

abf init

abf init を実行すると、すべての手順が案内されます。

1. プロジェクトをインデックス化します — git ls-files を使ってすべてのファイルを検出し、インデックス化します
2. LLM の要約と埋め込みを生成します（Ollama が起動している場合）— (12/80) のように進捗をリアルタイムで表示します
3. .abf/ を .gitignore に追加します — 書き込み前に確認します
4. エージェント用に ABF を MCP サーバーとしてインストールします — 使用するエージェント（Cursor、VS Code、Claude Code など）と、npx agentsbestfriend start（常に最新）または abf start（ローカルインストール）のどちらを使用するかを選択します

エージェントの手動セットアップ

手動で設定する場合は、ABF を stdio MCP サーバーとして追加します。npx の使用をおすすめします。グローバルインストールは不要で、公開済みの常に最新のバージョンが実行されます。

VS Code / GitHub Copilot（.vscode/mcp.json）：

{
  "servers": {
    "abf": {
      "command": "npx",
      "args": ["agentsbestfriend", "start"]
    }
  }
}

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "abf": {
      "command": "npx",
      "args": ["agentsbestfriend", "start"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "abf": {
      "command": "npx",
      "args": ["agentsbestfriend", "start"]
    }
  }
}

エージェントが作業ディレクトリを自動的に渡さない場合は、env ブロックに ABF_PROJECT_ROOT を設定してください。

CLI コマンド

abf start             Start MCP server in stdio mode (used by agents)
abf init [path]       Index project, set up .gitignore entry, install MCP for agents
abf skill [path]      Install or update the ABF workflow skill for your coding agents
abf index [path]      Re-index a project (incremental by default)
abf status [path]     Show index stats
abf config            Interactive configuration editor
abf doctor            Health checks (Node, ripgrep, git, Ollama)
abf portal            Interactive TUI dashboard

仕組み

ABF は、各プロジェクトのルート内に軽量な SQLite インデックス（.abf/index.db）を保持します。インデックスは一度構築され、その後は差分更新されます。変更されたファイルのみが再処理されます。ファイルウォッチャーが、編集に合わせてインデックスを最新の状態に保ちます。

テーブル	内容
files	パス、ハッシュ、言語、行数、LLM による要約
symbols	関数、クラス、インターフェース、型（AST から抽出）
imports	ファイル間の依存関係
embeddings	セマンティック検索用の Float32 ベクトル（大きなファイルはチャンクに分割）
file_chunks	シンボル境界に沿って分割されたスマートチャンク
files_fts	要約を対象とした FTS5 全文検索インデックス

オプション：LLM による拡充

Ollama をローカルで実行している場合、ABF はファイルの要約と埋め込みを生成します。

ollama pull qwen2.5-coder:1.5b    # file summaries
ollama pull nomic-embed-text       # embeddings / semantic search

abf init と abf portal → Re-index のどちらでも、進行状況がリアルタイムで表示されます。

◆  Generating LLM summaries... (14/80)
◆  Generating embeddings... (28/80)

大きなファイルは埋め込み用に自動でチャンクに分割されるため、コンテキスト長のエラーは発生しません。

Ollama がなくても、すべてのツールは通常どおり動作します。セマンティック検索はキーワードモードにフォールバックします。

設定

グローバル設定は ~/.abf/config.json にあります。abf config または abf portal から対話形式で編集できます。

{
  "llm": {
    "provider": "ollama",
    "ollama": {
      "baseUrl": "http://localhost:11434",
      "summaryModel": "qwen2.5-coder:1.5b",
      "embeddingModel": "nomic-embed-text"
    }
  },
  "indexing": {
    "autoWatch": true,
    "respectGitignore": true,
    "maxFileSizeKb": 512,
    "excludedPatterns": ["*.min.js", "*.min.css", "*.map", "*.lock"]
  },
  "search": {
    "defaultMaxResults": 20
  }
}

アーキテクチャ

AgentsBestFriend/
├── packages/
│   ├── core/     Shared logic — DB, config, search, analysis, indexer, LLM
│   ├── server/   MCP server (11 tools)
│   └── cli/      Commander.js CLI + TUI portal
├── turbo.json
└── package.json

Turborepo と pnpm ワークスペースを使用して構築されています。主なモジュール：

モジュール	目的
@abf/core/db	Drizzle ORM と SQLite（WAL、FTS5）
@abf/core/config	Zod で検証される設定
@abf/core/search	ripgrep、キーワードスコアラー、セマンティック検索（コサイン類似度）
@abf/core/analysis	ts-morph AST、規約検出、プロジェクト概要
@abf/core/indexer	git ls-files による検出、差分処理パイプライン、ファイルウォッチャー
@abf/core/llm	Ollama クライアント、要約およびチャンク分割された埋め込みのパイプライン
@abf/core/git	Git CLI ラッパー

開発

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Watch mode
pnpm dev

# Type-check
pnpm type-check

リンク

• GitHub: github.com/TheRealFloatDev/AgentsBestFriend
• npm: npmjs.com/package/agentsbestfriend
• Issues: github.com/TheRealFloatDev/AgentsBestFriend/issues
• MCP Spec: modelcontextprotocol.io

ライセンス

MIT