Acemcp

🚀 Acemcp

コードライブラリのインデックス作成とセマンティック検索を行う MCP サーバーです。このサーバーは、コードの検索や管理を効率的に行うために設計されています。

MseeP.ai Security Assessment Badge English

🚀 クイックスタート

Acemcp を使用するには、まずインストールが必要です。以下にインストール方法を示します。

📦 インストール

ツールとしてのインストール（推奨）

# システムにインストール
uv tool install acemcp

# または一時的に実行（インストール不要）
uvx acemcp

開発用インストール

# リポジトリをクローン
git clone https://github.com/qy527145/acemcp.git
cd acemcp

# 依存関係をインストール
uv sync

# 実行
uv run acemcp

🔧 設定

設定ファイルは初回実行時に ~/.acemcp/settings.toml に自動的に作成され、デフォルト値が含まれています。

~/.acemcp/settings.toml を編集して設定を行います。

BATCH_SIZE = 10
MAX_LINES_PER_BLOB = 800
BASE_URL = "https://your-api-endpoint.com"
TOKEN = "your-bearer-token-here"
TEXT_EXTENSIONS = [".py", ".js", ".ts", ...]
EXCLUDE_PATTERNS = [".venv", "node_modules", ".git", "__pycache__", "*.pyc", ...]

設定オプション：

• BATCH_SIZE: 1 バッチでアップロードするファイル数（デフォルト: 10）
• MAX_LINES_PER_BLOB: 大きなファイルを分割する前の最大行数（デフォルト: 800）
• BASE_URL: API エンドポイントの URL
• TOKEN: 認証トークン
• TEXT_EXTENSIONS: インデックスを作成するファイルの拡張子のリスト
• EXCLUDE_PATTERNS: 除外するパターンのリスト（*.pyc のようなワイルドカードをサポート）

以下の方法でも設定できます。

• コマンドライン引数（最優先）：--base-url、--token
• Web 管理画面（ユーザー設定ファイルを更新）
• 環境変数（ACEMCP_ 接頭辞を使用）

MCP 設定

以下の内容を MCP クライアントの設定に追加します（例: Claude Desktop）。

基本設定

{
  "mcpServers": {
    "acemcp": {
      "command": "uvx",
      "args": [
        "acemcp"
      ]
    }
  }
}

使用可能なコマンドライン引数：

• --base-url: BASE_URL 設定を上書き
• --token: TOKEN 設定を上書き
• --web-port: 指定したポートで Web 管理画面を有効にする（例: 8080）

Web 管理画面を有効にする設定

Web 管理画面を有効にするには、--web-port 引数を追加します。

{
  "mcpServers": {
    "acemcp": {
      "command": "uvx",
      "args": [
        "acemcp",
        "--web-port",
        "8888"
      ]
    }
  }
}

その後、管理画面にアクセスします：http://localhost:8888

Web 管理機能：

• 設定管理：サーバーの設定（BASE_URL、TOKEN、BATCH_SIZE、MAX_LINES_PER_BLOB、TEXT_EXTENSIONS）を表示および編集
• リアルタイムログ：WebSocket 接続を通じてサーバーのログをリアルタイムで監視。スマートな再接続機能付き
  • 指数関数的なバックオフ再接続策略（1秒 → 1.5秒 → 2.25秒 ... 最大 30秒）
  • 最大 10 回の再接続試行で無限ループを防止
  • ネットワーク障害時に自動的に再接続
  • ログのノイズを減らす（WebSocket 接続の記録は DEBUG レベル）
• ツールデバッガー：Web 画面から直接 MCP ツールをテストおよびデバッグ
  • search_context ツールをテストし、プロジェクトパスとクエリを入力
  • 整形された結果とエラーメッセージを表示

💻 使用例

基本的な使用法

search_context ツール

このツールは、クエリに基づいて関連するコードのコンテキストを検索します。検索前に自動的にインクリメンタルインデックスを実行し、結果が常に最新のものになるようにします。コードライブラリ内でセマンティック検索を行い、関連するコードの位置を示す整形されたテキスト断片を返します。

主な機能：

• 自動インクリメンタルインデックス：各検索の前に、ツールは自動的に新しいファイルまたは変更されたファイルのみをインデックスし、変更されていないファイルはスキップして効率を向上させます。
• 手動インデックス不要：プロジェクトを手動でインデックスする必要はありません。検索するだけで、ツールが自動的にインデックスを処理します。
• 常に最新：検索結果はコードライブラリの現在の状態を反映します。
• 複数のエンコーディングサポート：複数のファイルエンコーディング（UTF-8、GBK、GB2312、Latin-1）を自動的に検出して処理します。
• .gitignore 統合：プロジェクトをインデックスする際に、.gitignore パターンを自動的に遵守します。

パラメータ：

• project_root_path（文字列）：プロジェクトのルートディレクトリの絶対パス
  • 重要：Windows でも正斜線（/）をパス区切り文字として使用します。
  • Windows の例：C:/Users/username/projects/myproject
  • Linux/Mac の例：/home/username/projects/myproject
• query（文字列）：関連するコードのコンテキストを検索するための自然言語のクエリ
  • 検索したい内容に関連する記述的なキーワードを使用します。
  • ツールはセマンティックマッチングを行い、単なるキーワード検索ではありません。
  • ファイルパスと行番号付きのコード断片を返します。

返される内容：

• クエリに一致するファイル内の整形されたテキスト断片
• 各断片のファイルパスと行番号
• 関連するコード部分の周囲のコンテキスト
• 関連性でソートされた複数の結果

クエリの例：

1. 設定コードを検索する：

   {
     "project_root_path": "C:/Users/username/projects/myproject",
     "query": "ログ設定 設定 初期化 logger"
   }
   

   返される内容：ログ設定、logger の初期化、設定に関連するコード

2. 認証ロジックを検索する：

   {
     "project_root_path": "C:/Users/username/projects/myproject",
     "query": "ユーザー認証 ログイン パスワード検証"
   }
   

   返される内容：認証ハンドラー、ログイン関数、パスワード検証コード

3. データベースコードを検索する：

   {
     "project_root_path": "C:/Users/username/projects/myproject",
     "query": "データベース接続プール 初期化"
   }
   

   返される内容：データベース接続設定、接続プールの設定、初期化コード

4. エラー処理を検索する：

   {
     "project_root_path": "C:/Users/username/projects/myproject",
     "query": "エラー処理 例外 try catch"
   }
   

   返される内容：エラー処理パターン、例外ハンドラー、try-catch ブロック

5. API エンドポイントを検索する：

   {
     "project_root_path": "C:/Users/username/projects/myproject",
     "query": "API エンドポイント ルート HTTP ハンドラー"
   }
   

   返される内容：API ルート定義、HTTP ハンドラー、エンドポイントの実装

より良い結果を得るためのヒント：

• 複数の関連するキーワードを使用します（例: "ログ設定設定" は "ログ" よりも良い）
• 検索したい特定の技術用語を含めます
• 正確な変数名ではなく、機能を記述します
• 最初のクエリで必要な内容が返されない場合は、異なる表現を試してみます

インデックスの機能：

• インクリメンタルインデックス：新しいファイルまたは変更されたファイルのみをアップロードし、変更されていないファイルはスキップ
• ハッシュベースの重複排除：パス + 内容の SHA-256 ハッシュでファイルを識別
• 自動リトライ：ネットワーク要求は最大 3 回自動的にリトライされ、指数関数的なバックオフ（1秒、2秒、4秒）が適用されます
• バッチの柔軟性：バッチアップロードがリトライ後に失敗した場合、ツールは次のバッチを処理し続けます
• ファイル分割：大きなファイルは自動的に複数のブロックに分割されます（デフォルト: 1 ブロックあたり 800 行）
• 除外パターン：仮想環境、node_modules、.git、ビルド生成物などを自動的にスキップ
• 複数のエンコーディングサポート：ファイルのエンコーディング（UTF-8、GBK、GB2312、Latin-1）を自動的に検出し、失敗した場合は UTF-8 エラー処理にフォールバック
• .gitignore 統合：プロジェクトのルートディレクトリから .gitignore パターンを自動的に読み込み、設定された除外パターンと組み合わせて使用

検索の機能：

• 自動リトライ：検索要求は最大 3 回自動的にリトライされ、指数関数的なバックオフ（2秒、4秒、8秒）が適用されます
• グレースフルデグレード：すべてのリトライ後に検索が失敗した場合、明確なエラーメッセージを返します
• タイムアウト処理：長時間実行される検索には 60 秒のタイムアウトが適用されます
• 空の結果の処理：関連するコードが見つからない場合、有用なメッセージを返します

デフォルトの除外パターン：

.venv, venv, .env, env, node_modules, .git, .svn, .hg, __pycache__,
.pytest_cache, .mypy_cache, .tox, .eggs, *.egg-info, dist, build,
.idea, .vscode, .DS_Store, *.pyc, *.pyo, *.pyd, .Python,
pip-log.txt, pip-delete-this-directory.txt, .coverage, htmlcov,
.gradle, target, bin, obj

パターンはワイルドカード（*、?）をサポートし、ディレクトリ/ファイル名またはパスに一致します。

注意： プロジェクトのルートディレクトリに .gitignore ファイルが存在する場合、そのパターンは自動的に読み込まれ、設定された除外パターンと組み合わせて使用されます。.gitignore パターンは Git の標準的な wildmatch 構文に従います。

🔧 技術詳細

複数エンコードのファイルサポート

Acemcp は、異なる文字エンコードのファイルを自動的に検出して処理し、国際化されたプロジェクトに適しています。

• 自動検出：複数のエンコードを順番に試みます：UTF-8 → GBK → GB2312 → Latin-1
• フォールバック処理：すべてのエンコードが失敗した場合、UTF-8 エラー処理を使用してクラッシュを防止
• ログ記録：各ファイルで成功したエンコードを記録します（DEBUG レベル）
• 設定不要：デフォルトで大多数の一般的なエンコードをサポート

これは以下のような場合に特に有用です。

• 混合エンコードのファイルを含むプロジェクト（例: UTF-8 のソースコード + GBK のドキュメント）
• 非 UTF-8 エンコードを使用するレガシーコードライブラリ
• 異なる言語のファイルを持つ国際チーム

.gitignore 統合

Acemcp は、プロジェクトの .gitignore ファイルを自動的に遵守します。

• 自動読み込み：存在する場合、プロジェクトのルートディレクトリから .gitignore を読み込みます。
• 標準構文：Git の標準的な wildmatch パターンをサポート
• 組み合わせフィルタリング：設定された EXCLUDE_PATTERNS と一緒に動作
• ディレクトリ処理：末尾にスラッシュが付いたディレクトリパターンを正しく処理
• 設定不要：プロジェクトのルートディレクトリに .gitignore を配置するだけです

.gitignore パターンの例：

# 依存関係
node_modules/
vendor/

# ビルド出力
dist/
build/
*.pyc

# IDE ファイル
.vscode/
.idea/

# 環境ファイル
.env
.env.local

これらのパターンは、インデックス作成中に自動的に遵守され、デフォルトの除外パターンと組み合わせて使用されます。

データストレージ

• 設定：~/.acemcp/settings.toml
• インデックスされたプロジェクト：~/.acemcp/data/projects.json（固定位置）
• ログファイル：~/.acemcp/log/acemcp.log（自動ローテーション）
• プロジェクトは絶対パスで識別されます（正斜線で正規化）

ログ記録

アプリケーションは自動的に ~/.acemcp/log/acemcp.log にログを記録し、以下の特性を持っています。

• コンソール出力：INFO レベル以上（カラー出力）
• ファイル出力：DEBUG レベル以上（詳細な形式で、モジュール、関数、行番号を含む）
• 自動ローテーション：ログファイルが 5MB に達すると自動的にローテーション
• 保持ポリシー：最大 10 個のログファイルを保持
• 圧縮：ローテーションされたログファイルは自動的に .zip 形式で圧縮
• スレッドセーフ：ログ記録は並行操作に対してスレッドセーフ

ログ形式：

2025-11-06 13:51:25 | INFO     | acemcp.server:main:103 - Starting acemcp MCP server...

ログファイルは初回実行時に自動的に作成され、手動での設定は不要です。

Web 管理画面

Web 管理画面は以下を提供します。

• リアルタイムサーバー状態の監視
• WebSocket を介したリアルタイムログストリーム
• 設定管理：サーバーの設定を表示および編集
• Token 検証：API Key が有効かどうかをワンクリックで検出
• プロジェクト統計：インデックスされたプロジェクトの数
• ツールデバッガー：Web 画面から直接 MCP ツールをテストおよびデバッグ

Web 画面を有効にするには、サーバーを起動するときに --web-port 引数を使用します。

機能：

• 自動スクロール付きのリアルタイムログ表示
• サーバーの状態と指標
• 設定の概要と編集
• Tailwind CSS を使用したレスポンシブなデザイン
• ビルドステップ不要（CDN リソースを使用）
• 指数関数的なバックオフを持つスマートな WebSocket 再接続

最近の更新

バージョン 0.2.1

改善点：

• 🔧 search_context ツールのプロンプト説明を最適化
• 🔧 ツールパラメータの説明テキストを調整

バージョン 0.2.0

エラー修正：

• 🐛 プロジェクトに .env ファイルが存在する場合に、エンコードエラーにより acemcp が起動できない問題を修正

依存関係の更新：

• ⬆️ サードパーティの依存パッケージのバージョンをアップグレード

バージョン 0.1.9

新機能：

• Web ポートが使用中かどうかを自動で判断し、使用中の場合は Web パネルを再利用

改善点：

• Antigravity 互換性エラーを修正

バージョン 0.1.8

新機能：

• ✨ Token 検証機能：Web 管理画面に API Key 検出ボタンを追加
  • 設定部分に "Key を検出" ボタンを追加し、トークンが有効かどうかを即座に検証
  • 表示モードと編集モードでトークンを検証できる
  • 明確な検証結果のフィードバック（成功/失敗メッセージ）を提供
  • ユーザーが API 設定の問題を迅速に診断できるようにする

技術的詳細：

• 新しい /api/validate-token API エンドポイントを追加
• API にテスト要求を送信してトークンの有効性を検証
• 完全なエラー処理：401 未認証、403 アクセス禁止、タイムアウト、接続エラーなど
• 英語と日本語の両方のインターフェースをサポート

バージョン 0.1.7

改善点：

• 🔧 インターフェース要求の最適化：https://github.com/qy527145/acemcp/pull/6
• 🔧 プロキシ環境への対応：httpx[socks] 拡張依存関係を追加し、プロキシ環境でのエラーを解決

バージョン 0.1.5

新機能：

• ✨ ログシステムの最適化：FastAPI/Uvicorn のログを loguru にリダイレクトし、MCP stdio プロトコルの汚染を防止
• ✨ ツールデバッグインターフェース：Web 管理画面にツールリストとデバッグ機能を追加

改善点：

• 🔧 WebSocket の最適化：指数関数的なバックオフを持つスマートな再接続（1秒 → 最大 30秒）
• 🔧 ログノイズの削減：WebSocket 接続を現在は DEBUG レベルで記録し、INFO ではなくなりました
• 🔧 接続の安定性：最大 10 回の再接続試行で無限ループを防止
• 🔧 より良いエラー処理：どのエンコードでもデコードできないファイルに対してグレースフルなフォールバック

エラー修正：

• 🐛 頻繁な WebSocket 接続/切断のサイクルを修正
• 🐛 非 UTF-8 エンコードのファイルを読み取る際のエンコードエラーを修正
• 🐛 ディレクトリマッチを含む .gitignore パターンの処理を改善

バージョン 0.1.4

新機能：

• ✨ 複数エンコードのファイルサポート：複数のファイルエンコーディング（UTF-8、GBK、GB2312、Latin-1）を自動的に検出して処理
• ✨ .gitignore 統合：プロジェクトのルートディレクトリから .gitignore パターンを自動的に読み込み、遵守
• ✨ 改善されたツール応答形式：リストベースの形式から辞書ベースの形式に変更し、クライアントの互換性を向上

改善点：

• 🔧 WebSocket の最適化：指数関数的なバックオフを持つスマートな再接続（1秒 → 最大 30秒）
• 🔧 ログノイズの削減：WebSocket 接続を現在は DEBUG レベルで記録し、INFO ではなくなりました
• 🔧 接続の安定性：最大 10 回の再接続試行で無限ループを防止
• 🔧 より良いエラー処理：どのエンコードでもデコードできないファイルに対してグレースフルなフォールバック

エラー修正：

• 🐛 頻繁な WebSocket 接続/切断のサイクルを修正
• 🐛 非 UTF-8 エンコードのファイルを読み取る際のエンコードエラーを修正
• 🐛 ディレクトリマッチを含む .gitignore パターンの処理を改善