MCP Ahrefs

🚀 MCP Ahrefs

AhrefsのMCPサーバーをSAAGAで動作させます。

🚀 クイックスタート

AIアシスタントによるクイックスタート

始め方がわからない場合、AIコーディングアシスタントに以下のように依頼することができます。 「私はMCP Ahrefsプロジェクトを持っています。WORKING_WITH_SAAGA_PROMPT.mdを読み、このMCPサーバーの理解と作業を支援してください。」

簡単な参照用に、.ai-prompts.mdファイルには主要なパターンの要約版が含まれています。 詳細な技術ドキュメントについては、docs/DECORATOR_PATTERNS.mdを参照してください。

✨ 主な機能

このMCPサーバーはSAAGA MCP Server Cookie Cutterテンプレートを使用して生成され、以下の機能を備えています。

• FastMCP統合：双方向トランスポートをサポートする最新のMCPフレームワーク
• SAAGAデコレータ：自動的な例外処理、ロギング、並列化
• プラットフォーム対応設定：クロスプラットフォームの設定管理
• Streamlit管理UI：ウェブベースの設定と監視インターフェイス
• SQLiteロギング：データベースに保存される包括的なロギング

📦 インストール

前提条件

• Python 3.12以上
• UV - 非常に高速なPythonパッケージマネージャー

ソースからのインストール

# UVをインストールする（まだインストールされていない場合）
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linuxの場合
# または、Windowsの手順についてはhttps://github.com/astral-sh/uvを参照
git clone <your-repository-url>
cd mcp_ahrefs
uv venv
uv sync

開発用インストール

git clone <your-repository-url>
cd mcp_ahrefs
uv venv
uv sync --extra dev

💻 使用例

MCP Inspectorを使用したテスト

MCPサーバーのテストを開始する準備ができたら、MCP Inspector Guideには以下の内容が記載されています。

• 仮想環境のトラブルシューティングを含むステップバイステップのセットアップ手順
• 含まれるすべてのツールのテスト例
• 並列ツールのJSONモードの手順
• 一般的な問題と解決策

クイックスタート:

source .venv/bin/activate  # または: uv shellを使用
uv run mcp dev mcp_ahrefs/server/app.py

Claude CLIを使用したテスト

このプロジェクトには、ClaudeでMCPサーバーをテストするための便利なテストスクリプトが含まれています。

# 簡単なプロンプトでテスト
./test_mcp_with_claude.sh "List all available tools"

# 特定のツールをテスト
./test_mcp_with_claude.sh "Run the echo_tool with message 'Hello World'"

# 複数のツールをテスト
./test_mcp_with_claude.sh "Test calculate_fibonacci with n=10 and echo_tool with message 'Done'"

# Windowsの場合
.\test_mcp_with_claude.ps1 "List all available tools"

このスクリプトは自動的に以下のことを行います。

• 生成されたmcp.integration_test.json構成（cookiecutterによって作成される）を使用
• SonnetモデルでClaudeを実行
• 適切なMCP構成フラグを含む
• 読みやすさを向上させるための色付き出力を提供

MCP統合テスト

このプロジェクトには、実際のMCPクライアントとの相互作用でツールが正しく動作することを検証する包括的な統合テストが含まれています。

統合テストの実行

# すべての統合テストを実行
test-mcp-integration

# 詳細な出力で実行
test-mcp-integration --verbose

# 特定のツールをテスト
test-mcp-integration --tool echo_tool

# 利用可能なすべてのツールをリストする
test-mcp-integration --list

# クロスプラットフォームのスクリプトも利用可能
./test_mcp_integration.sh        # Unix/Mac
.\test_mcp_integration.ps1        # Windows

テスト対象

統合テストは以下を検証します。

• ツールの検出：すべてのツールが正しいスキーマで検出可能である（"kwargs"パラメータなし）
• パラメータ変換：MCPからの文字列パラメータが適切な型に変換される
• エラー処理：無効なパラメータや例外が適切なエラー応答を返す
• SAAGA統合：デコレータが完全なMCPプロトコルフローで正しく動作する
• プロトコル準拠：ツールが実際のMCPクライアント接続で動作する

新しいツールのテスト生成

新しいツールを追加した場合、そのための統合テストを生成します。

# テストテンプレートを生成
generate-mcp-tests my_new_tool

# これにより、カスタマイズ可能なテストテンプレートが作成されます
# tests/integration/test_mcp_integration.pyに追加します

統合テストと単体テストの比較

• 単体テスト (test_decorators.py)：SAAGAデコレータを単独でテスト
• 統合テスト (test_mcp_integration.py)：実際のクライアントとの完全なMCPプロトコルフローをテスト

両方のテストスイートを実行して、完全なカバレッジを確保します。

# すべてのテストを実行
pytest

# 単体テストのみを実行
pytest tests/test_decorators.py

# 統合テストのみを実行
test-mcp-integration

MCPサーバーの実行

サーバーは2つのモードで実行できます。

1. STDIOモード（Claude DesktopなどのMCPクライアント用）

# デフォルト設定で実行
uv run python -m mcp_ahrefs.server.app

# カスタムログレベルで実行
uv run python -m mcp_ahrefs.server.app --log-level DEBUG

# サーバーを直接実行
uv run python mcp_ahrefs/server/app.py

uv run mcp_ahrefs-server

2. SSEモード（ウェブベースのクライアント用）

# SSEトランスポートで実行
uv run python -m mcp_ahrefs.server.app --transport sse --port 3001

# カスタムホストとポートで実行
uv run python -m mcp_ahrefs.server.app --transport sse --host 0.0.0.0 --port 8080

コマンドラインオプション

uv run python -m mcp_ahrefs.server.app --help

利用可能なオプション:

• --transport: "stdio"（デフォルト）または "sse"を選択
• --host: SSEトランスポート用のホストを指定（デフォルト: 127.0.0.1）
• --port: SSEトランスポート用のポートを指定（デフォルト: 3001）
• --log-level: ログレベル - DEBUG, INFO, WARNING, ERROR（デフォルト: INFO）

MCPクライアントの設定

Claude Desktopの設定

Claude DesktopのMCP設定 (claude_desktop_config.json) に以下を追加します。

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_ahrefs.server.app"],
      "cwd": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs"
    }
  }
}

高度な設定オプション

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "uv",
      "args": [
        "run", "python", "-m", "mcp_ahrefs.server.app",
        "--log-level", "DEBUG"
      ],
      "cwd": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs",
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs/.venv"
      }
    }
  }
}

システムPythonを使用する場合（代替案）

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs/.venv/bin/python",
      "args": ["-m", "mcp_ahrefs.server.app"]
    }
  }
}

uvツールを使用する場合

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "uv",
      "args": ["--directory=/Users/jakub/Ragnarson/saaga/mcp_ahrefs", "run" ,"mcp_ahrefs-server"]
    }
  }
}

設定ファイルの場所

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

管理UI

Streamlit管理インターフェイスを起動します。

uv run streamlit run mcp_ahrefs/ui/app.py

ダッシュボード

ダッシュボードは以下を提供します。

• リアルタイムのサーバーステータス監視
• プロジェクト情報と設定の概要
• 一般的なアクションへのクイックアクセス
• システムリソースの使用状況

設定エディター

設定エディターは以下の機能を備えています。

• 検証付きのライブ設定編集
• 保留中の変更を示す差分プレビュー
• エクスポート/インポート機能（JSON & YAML形式）
• 確認ダイアログ付きのデフォルト設定へのリセット
• 自動サーバー再起動通知

ログビューアー

ログビューアーには以下が含まれています。

• 履歴分析用の日付範囲フィルタリング
• ステータスフィルタリング（成功/エラー/すべて）
• ツール固有のフィルタリング
• さらなる分析用のエクスポート機能
• リアルタイムのログ更新

AIアシスタントの指示

AIコーディングアシスタント（Claude、Cursor、GitHub Copilotなど）でこのMCP Ahrefs MCPサーバーを使用する場合:

サーバーアーキテクチャの理解

このサーバーはSAAGAデコレータを使用しており、すべてのMCPツールを自動的にラップします。

• 例外処理：すべてのエラーが捕捉され、構造化されたエラー応答として返されます。
• 包括的なロギング：すべてのツール呼び出しがタイミングとパラメーターとともにログに記録されます。
• オプションの並列化：並列実行用にマークされたツールは同時に実行されます。

AIアシスタントの重要ポイント

1. ツール登録パターン：ツールはすでにデコレータが適用された状態で登録されています。手動でデコレータでツールをラップしないでください - これはserver/app.pyで自動的に処理されます。
2. パラメータ型：MCPはすべてのパラメータをクライアントから文字列として渡します。ツールが型変換を処理するようにしてください。

   def my_tool(count: str) -> dict:
       # 文字列を整数に変換
       count_int = int(count)
       return {"result": count_int * 2}
   

3. エラー処理：ツールは自由に例外を発生させることができます - 例外ハンドラーデコレータがそれを捕捉し、適切なエラー応答を返します。
4. 非同期サポート：同期および非同期の両方のツールがサポートされています。デコレータは自動的に両方のパターンを検出して処理します。
5. ロギング：デバッグ用に、プラットフォーム固有のデータディレクトリのログを確認してください。
   • macOS: ~/Library/Application Support/mcp_ahrefs/logs.db
   • Linux: ~/.local/share/mcp_ahrefs/logs.db
   • Windows: %APPDATA%/mcp_ahrefs/logs.db

一般的なタスク

新しいツールの追加:

# mcp_ahrefs/tools/my_new_tool.py
def my_new_tool(param: str) -> dict:
    """このツールが行うことの説明。"""
    # 実装
    return {"result": "processed"}

# mcp_ahrefs/tools/__init__.py
from .my_new_tool import my_new_tool
example_tools.append(my_new_tool)

MCP Inspectorを使用したテスト:

# プロジェクトのルートから
uv run mcp dev mcp_ahrefs/server/app.py

ツールのデバッグ:

1. SQLiteログを確認してエラーメッセージを確認する
2. --log-level DEBUGで実行して詳細な出力を得る
3. MCP Inspectorで直接テストしてパラメーターの処理を確認する

重要な実装メモ

• サーバーは標準のMCP SDK (from mcp.server.fastmcp import FastMCP) を使用しています。
• 関数シグネチャは注意深いデコレータの実装によって保持されます。
• server/app.pyのregister_tools()関数がすべてのデコレータの適用を処理します。
• ツールはJSONシリアライズ可能なPythonオブジェクト（dict、list、str、intなど）を返す必要があります。

📚 ドキュメント

設定

設定ファイルはプラットフォーム固有の場所に保存されます。

• macOS: ~/Library/Application Support/mcp_ahrefs/
• Linux: ~/.local/share/mcp_ahrefs/
• Windows: %APPDATA%/mcp_ahrefs/

設定オプション

• log_level: ログレベル（INFO）
• log_retention_days: ログを保持する日数（30）
• server_port: HTTPサーバーのポート（3001）

開発

プロジェクト構造

mcp_ahrefs/
├── mcp_ahrefs/
│   ├── config.py              # プラットフォーム対応設定
│   ├── server/
│   │   └── app.py             # デコレータ付きのFastMCPサーバー
│   ├── tools/                 # あなたのMCPツール
│   ├── decorators/            # SAAGAデコレータ
│   └── ui/                    # Streamlit管理UI
├── tests/                     # テストスイート
├── docs/                      # ドキュメント
└── pyproject.toml            # プロジェクト設定

新しいツールの追加

1. mcp_ahrefs/tools/に新しいPythonファイルを作成します。
2. ツール関数を定義します。
3. server/app.pyでそれをインポートして登録します。

例:

# mcp_ahrefs/tools/my_tool.py
def my_tool(message: str) -> str:
    """MCPツールの例。"""
    return f"Processed: {message}"

# サーバーは自動的にSAAGAデコレータを適用します

テストの実行

pytest tests/

コード品質

このプロジェクトはいくつかのコード品質ツールを使用しています。

# コードを整形する
black mcp_ahrefs/
isort mcp_ahrefs/

# コードをリントする
flake8 mcp_ahrefs/
mypy mcp_ahrefs/

SAAGAデコレータ

このサーバーは、MCPツールに3つの主要なデコレータを自動的に適用します。

1. 例外ハンドラー：ロギング付きのエラー処理
2. ツールロガー：SQLiteデータベースへの包括的なロギング
3. 並列化：計算集約的なツールのオプションの並列処理

ロギング

ログは以下のスキーマでSQLiteデータベースに保存されます。

• timestamp: ツールが呼び出された時間
• tool_name: MCPツールの名前
• duration_ms: ミリ秒単位の実行時間
• status: 成功/失敗ステータス
• input_args: ツールの入力引数
• output_summary: ツール出力の概要
• error_message: エラー詳細（ある場合）

🔧 技術詳細

このMCPサーバーはSAAGA MCP Server Cookie Cutterテンプレートを使用して生成され、FastMCPフレームワークを利用しています。SAAGAデコレータを使用することで、自動的な例外処理、ロギング、並列化が可能になります。また、Streamlitを使用した管理UIを提供し、SQLiteを使用してログを保存しています。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細についてはLICENSEファイルを参照してください。

サポート

問題や質問については:

• GitHubでIssueを作成してください。
• docs/ディレクトリのドキュメントを確認してください。
• テストスイートを確認して使用例を確認してください。

謝辞

• FastMCP のMCPフレームワーク
• SAAGA のデコレータパターン
• Cookiecutter のテンプレートシステム