Mcpagentre

🚀 MCP_Agent:RE プロジェクトガイド

• MCP_Agent:REは、TAPDプラットフォームから要件と欠陥データを取得し、品質分析レポートを生成するPythonプロジェクトです。AIクライアントにデータサポートを提供することを目的としています。

• 対話效果のプレビュー

• このプロジェクトは、2025年6月10日に punkpeye (Frank Fiegel) によって TAPD Data Fetcher | Glama に収録されました。

• このプロジェクトのGitHubアドレスは https://github.com/OneCuriousLearner/MCPAgentRE です。
• このプロジェクトはGitee上でも同期更新されており、ミラーアドレスは https://gitee.com/ChiTsuHa-Tau5_C/MCPAgentRE です。

🚀 クイックスタート

このセクションでは、MCP_Agent:RE プロジェクトの基本的な使い方を説明します。まずは、プロジェクトの背景と利用可能なツールについて紹介し、その後にプロジェクトの構造、移行手順、AIクライアントへの接続方法、機能拡張方法、関連ドキュメントやURLについて解説します。

✨ 主な機能

利用可能なMCPサーバー

このプロジェクトは、TAPDデータの取得、処理、分析、およびインテリジェント要約機能をサポートする豊富なMCPツールセットを提供しています。

データ取得ツール

• get_tapd_data() - TAPD APIから要件と欠陥データを取得し、ローカルファイルに保存します。数量統計を返します【推奨】
  • 初回のデータ取得または定期的なローカルデータの更新に適しています。
  • 要件と欠陥データの完全な統合を含みます。
• get_tapd_stories() - TAPDプロジェクトの要件データを取得します。ページングをサポートし、JSONデータを直接返しますが、ローカルに保存されません。データ量が少ない場合のみ使用することをお勧めします。
• get_tapd_bugs() - TAPDプロジェクトの欠陥データを取得します。ページングをサポートし、JSONデータを直接返しますが、ローカルに保存されません。データ量が少ない場合のみ使用することをお勧めします。

データ前処理ツール

• preprocess_tapd_description(data_file_path, output_file_path, use_api, process_documents, process_images) - TAPDデータのdescriptionフィールドのHTMLスタイルをクリーニングし、テキスト、リンク、画像コンテンツを抽出し、DeepSeek APIを通じて表現を最適化します（DeepSeek APIキーの設定が必要）。データ長を大幅に圧縮しながら、重要な情報を保持します【開発中...】
• preview_tapd_description_cleaning(data_file_path, item_count) - descriptionフィールドのクリーニング結果をプレビューし、圧縮率と抽出された情報を表示します。元のデータは変更されません。
• docx_summarizer.py - .docxドキュメントからテキスト、画像、およびテーブル情報を抽出し、要約を生成します【開発中...】

ベクトル化と検索ツール

• vectorize_data(data_file_path, chunk_size) - ベクトル化ツールで、カスタムデータソースのベクトル化をサポートします。データをベクトル形式に変換し、後続のセマンティック検索と分析に使用します。
• get_vector_info() - 簡略化されたベクトルデータベースの状態と統計情報を取得します。
• search_data(query, top_k) - セマンティック類似度に基づくインテリジェント検索をサポートし、自然言語クエリを受け付け、クエリに最も関連する結果を返します。

データ生成と分析ツール

• generate_fake_tapd_data(n_story_A, n_story_B, n_bug_A, n_bug_B, output_path) - 模擬TAPDデータを生成し、テストとデモンストレーションに使用します（アドレスを指定しない場合、ローカルデータが上書きされる可能性があります。APIからの正しいデータが必要な場合は、再度データ取得ツールを呼び出してください）。
• generate_tapd_overview(since, until, max_total_tokens, model, endpoint, use_local_data) - LLMを使用して、プロジェクトの概要レポートと要約を簡単に生成し、プロジェクトの概要を把握するために使用します（環境にDeepSeek APIキーを設定する必要があります）。
• analyze_word_frequency(min_frequency, use_extended_fields, data_file_path) - TAPDデータの単語頻度分布を分析し、キーワードのワードクラウド統計を生成し、検索機能に正確なキーワード提案を提供します。

サンプルツール

• example_tool(param1, param2) - MCPツールの登録方法を示すサンプルツールです。

これらのツールは、データ取得からインテリジェント分析までの完全なワークフローをサポートし、AI駆動のテスト管理に強力なサポートを提供します。

利用可能なWorkFlowスクリプト

テストケース評価

• mcp_tools\test_case_rules_customer.py - テストケースの評価ルールと優先度を設定するためのテストケース評価ルール設定スクリプトです。
• mcp_tools\test_case_require_list_knowledge_base.py - TAPDデータから要件情報を抽出して知識ベースを生成するか、要件情報を手動で変更することができるテストケース要件知識ベース生成スクリプトです。
• mcp_tools\test_case_evaluator.py - 設定されたルールに基づいてテストケースの品質を評価し、評価レポートをローカルファイルに生成するテストケースAI評価器スクリプトです。

統一インターフェーススクリプト

• mcp_tools\common_utils.py に位置します。
• MCPツールの登録と呼び出しを簡素化する統一されたツールインターフェースを提供します。
• 含まれるツールは以下の通りです。

MCPToolsConfigクラス

• __init__() - プロジェクトに必要なディレクトリ構造（local_data、models、vector_data）を自動的に作成する設定マネージャーを初期化します。
• _get_project_root() - プロジェクトのルートディレクトリの絶対パスを取得します。
• get_data_file_path(relative_path) - データファイルの絶対パスを取得し、相対パスの自動変換をサポートします。
• get_vector_db_path(name) - ベクトルデータベースファイルのパスを取得します。デフォルトは"data_vector"です。
• get_model_cache_path() - モデルキャッシュディレクトリのパスを取得します。

ModelManagerクラス

• __init__(config) - MCPToolsConfigインスタンスに依存するモデルマネージャーを初期化します。
• get_project_model_path(model_name) - ローカルに指定されたモデルが存在するかどうかを検出し、モデルのパスまたはNoneを返します。
• get_model(model_name) - SentenceTransformerモデルのインスタンスを取得します。ローカルモデルを優先し、自動ダウンロードとキャッシュをサポートします。
• clear_cache() - グローバルモデルキャッシュをクリアし、メモリリソースを解放します。

TextProcessorクラス

• extract_text_from_item(item, item_type) - TAPDデータ項目（要件/欠陥）から重要なテキスト情報を抽出し、さまざまなタイプのフィールド抽出戦略をサポートします。

FileManagerクラス

• __init__(config) - MCPToolsConfigインスタンスに依存するファイルマネージャーを初期化します。
• load_tapd_data(file_path) - TAPD JSONデータファイルをロードし、絶対パスと相対パスをサポートします。
• load_json_data(file_path) - JSONデータファイルをロードし、エラー処理をサポートします。ファイルが存在しない場合は空の辞書を返します。
• save_json_data(data, file_path) - データをJSON形式で保存し、ディレクトリ構造を自動的に作成します。

APIManagerクラス 【2025年7月22日更新】

• __init__() - DeepSeekとSiliconFlowの両方のAPI設定をサポートするAPIマネージャーを初期化します。
• get_headers(endpoint) - エンドポイントに基づいて自動的に対応するAPIキーを選択し、APIリクエストヘッダーをスマートに構築します。
• call_llm(prompt, session, model, endpoint, max_tokens) - 複数のAPIに対応するLLM呼び出しインターフェースです。
  • DeepSeek API（デフォルト）をサポートします：deepseek-chat、deepseek-reasoner モデル。
  • SiliconFlow APIをサポートします：moonshotai/Kimi-K2-Instruct などのモデル。
  • APIタイプを自動的に検出し、さまざまなリクエスト形式とエラー処理に適応します。

グローバルインスタンス管理関数

• get_config() - グローバルMCPToolsConfigインスタンスを取得します（シングルトンパターン）。
• get_model_manager() - グローバルModelManagerインスタンスを取得します（シングルトンパターン）。
• get_file_manager() - グローバルFileManagerインスタンスを取得します（シングルトンパターン）。
• get_api_manager() - グローバルAPIManagerインスタンスを取得します（シングルトンパターン）。

📦 インストール

環境準備

1. Python 3.10のインストール

• Python公式サイト からPython 3.10.xのインストールパッケージをダウンロードします（推奨: 3.10.11、元の環境と一致させる）。
• インストール時にAdd Python to PATHを選択してください（重要！そうしないと、環境変数を手動で設定する必要があります）。
• インストールを検証するには、ターミナルでpython --versionを実行し、Python 3.10.11と表示されることを確認します。

2. uvツールのインストール

• ターミナルでpip install uvを実行します（pipがPythonと一緒にインストールされていることを確認してください）：

  pip install uv
  

• インストールを検証するには、uv --versionを実行し、バージョン情報が表示されることを確認します。

プロジェクトファイルの移行

1. プロジェクトディレクトリのコピー

• 元のプロジェクトディレクトリD:\MiniProject\MCPAgentREを対象のコンピューターに完全にコピーします（推奨: パスに中国語や空白を含まないようにしてください。例: D:\MCPAgentRE）。

依存関係のインストール

1. プロジェクトの依存関係をインストールする

• ターミナルでプロジェクトディレクトリに移動します：cd D:\MCPAgentRE（実際のパスに合わせて調整してください）。

• 依存関係のインストールコマンドを実行します：

  uv sync
  

  • このコマンドは、pyproject.tomlに基づいてすべての依存関係（MCP SDK、aiohttpなどを含む）をインストールします。

設定の調整

1. TAPD APIの設定

• プロジェクトのルートディレクトリにapi.txtファイルを作成し、次のテキストをコピーし、目標TAPDプロジェクトの実際の値に置き換えます：

  API_USER = 'あなたのTAPD APIユーザー名に置き換えてください'
  API_PASSWORD = 'あなたのTAPD APIパスワードに置き換えてください'
  WORKSPACE_ID = 'あなたのTAPDプロジェクトIDに置き換えてください'
  

  • 注意：TAPD APIのユーザー名とパスワードは、TAPDプラットフォームから取得する必要があります。詳細な操作方法は、オープンプラットフォームドキュメント を参照してください。
  • WORKSPACE_ID：TAPDプロジェクトのIDで、TAPDプラットフォームから取得できます。
  • Gitにコミットする際、.gitignoreに従ってapi.txtファイルが無視され、機密情報が漏洩しないようになっています。

2. LLM APIの設定（オプション） システムは現在、2種類のLLM APIプロバイダーをサポートしており、必要に応じて設定を選択できます。

DeepSeek APIの設定

スマート要約機能（generate_tapd_overview）またはdescription最適化機能（preprocess_tapd_description）を使用する場合は、DeepSeek APIキーを設定する必要があります。

• APIキーの取得：DeepSeekオープンプラットフォーム にアクセスし、登録してAPIキーを取得します。

• 環境変数の設定（Windows PowerShell）：

  # 一時的な設定（現在のセッションのみ有効）
  $env:DS_KEY = "あなたのDeepSeek APIキーをここに入力してください"
  
  # 永続的な設定（推奨）
  [Environment]::SetEnvironmentVariable("DS_KEY", "あなたのDeepSeek APIキーをここに入力してください", "User")
  

SiliconFlow APIの設定 【🆕 2025年7月22日追加】

SiliconFlowは、Kimi、通義千問などのさまざまな優れたモデルを提供しています。

• APIキーの取得：SiliconFlowオープンプラットフォーム にアクセスし、登録してAPIキーを取得します。

• 環境変数の設定（Windows PowerShell）：

  # 一時的な設定（現在のセッションのみ有効）
  $env:SF_KEY = "あなたのSiliconFlow APIキーをここに入力してください"
  
  # 永続的な設定（推奨）
  [Environment]::SetEnvironmentVariable("SF_KEY", "あなたのSiliconFlow APIキーをここに入力してください", "User")
  

• 設定の検証：

  echo $env:DS_KEY
  echo $env:SF_KEY
  

• 注意事項：

• 環境変数を設定した後、エディターとMCPクライアントを再起動する必要があります。

• APIキーを設定しない場合、スマート要約ツールはエラーメッセージを返しますが、他の機能には影響しません。

• 詳細な設定説明は、knowledge_documents/DeepSeek API 環境変数設定ガイド.md を参照してください。

テスト実行

1. ターミナルでプロジェクトフォルダに移動する

• ターミナルでcd D:\MCPAgentREを実行します（実際のパスに合わせて調整してください）。

テストモード

1. tapd_data_fetcher.pyが正常にデータを取得できるかどうかを確認する場合は、以下のコマンドを実行します：

uv run tapd_data_fetcher.py

• 期待される出力：

  設定の読み込みに成功しました: ユーザー=********, ワークスペース=********
  ===== 要件データの取得を開始します =====
  要件データの取得が完了しました。合計X件のデータを取得しました。
  ===== 欠陥データの取得を開始します =====
  欠陥データの取得が完了しました。合計Y件のデータを取得しました。
  データはmsg_from_fetcher.jsonファイルに正常に保存されました。
  

2. tapd_mcp_server.py 内のすべてのMCPツールが正常に登録されているかどうかを確認する場合は、以下のコマンドを実行します：

uv run check_mcp_tools.py

出力結果は以下の通りです：

設定の読み込みに成功しました: ユーザー=4ikoesFM, ワークスペース=37857678
✅ MCPサーバーが正常に起動しました！
📊 登録されたツールの数: 14

🛠️ 登録されたツールのリスト:
    1. example_tool -
    MCPツールの登録方法を示すサンプルツール関数

    機能説明:
        ...
    2. get_tapd_data - TAPD APIから要件と欠陥データを取得し、ローカルファイルに保存する

    機能説明:
        ...

3. ベクトル化機能の迅速な検証（推奨）：

uv run test\vector_quick_start.py

• このスクリプトは、データ取得、ベクトル化、および検索機能を自動的に実行し、全体の流れが正常に動作するかどうかを確認します。
• 初回使用時は、モデルをダウンロードするためにVPNに接続する必要があります。
• 期待される出力：ベクトル化の成功と検索のデモ結果が表示されます。

4. コンテキスト最適化ツールと模擬データ生成のテスト：

# テスト用の模擬TAPDデータを生成する
uv run mcp_tools\fake_tapd_gen.py

# コンテキスト最適化ツールを使用してデータの概要を生成する（オフラインモード）
uv run mcp_tools\context_optimizer.py -f local_data\msg_from_fetcher.json --offline --debug

# 詳細な要約を生成する（APIキーの設定が必要）
uv run mcp_tools\context_optimizer.py -f local_data\msg_from_fetcher.json --debug

• 環境変数の設定（オンラインモード）：コンテキスト最適化ツールのオンラインLLM機能を使用するには、以下の環境変数を設定する必要があります：

  set DS_KEY=あなたのDeepSeek APIキー        # DeepSeek APIキー
  set DS_EP=https://api.deepseek.com/v1   # APIエンドポイントURL（オプション、デフォルトはDeepSeek）
  set DS_MODEL=deepseek-chat          # モデル名（オプション、デフォルトはdeepseek-chat）
  

• コンテキスト最適化ツールは、オフラインモード（--offlineパラメーター）とオンラインのスマート要約生成をサポートしています。

• 模擬データ生成ツールは、テストとデモンストレーションに使用され、TAPD形式に準拠した模擬データを生成します。

5. 単語頻度分析ツールのテスト：

uv run mcp_tools\word_frequency_analyzer.py

• このスクリプトは、local_data/msg_from_fetcher.jsonのデータを分析し、キーワードのワードクラウド統計を生成します。

6. ドキュメント要約生成のテスト（開発中）：

uv run mcp_tools\docx_summarizer.py

• このスクリプトは、指定された.docxドキュメントからテキスト、画像、およびテーブル情報を抽出し、要約を生成します。
• 期待される出力：生成された要約JSONファイルと抽出された画像、テーブルファイル。

7. テストケース評価ツール：

# カスタムルールのデモを実行する
uv run test\demo_custom_rules.py

# 要件リストの知識ベースを初期化する
uv run test\init_requirement_kb.py

# テストケース評価ツールを実行する
uv run mcp_tools\test_case_evaluator.py

• テストケース評価ツールは、設定されたルールに基づいてテストケースの品質を評価し、評価レポートを生成します。
• 初回実行時には、デフォルトのルール設定ファイル config/test_case_rules.json と config/require_list_config.json が自動的に生成されます。
• 詳細な説明は、knowledge_documents\AIテストケース評価ツール操作マニュアル.md を参照してください。

8. API互換性テスト 【🆕 2025年7月22日追加】：

uv run test\test_api_compatibility.py

• このスクリプトは、DeepSeekとSiliconFlowの2種類のAPIの接続性と応答をテストします。
• 期待される出力：各APIの呼び出し結果と応答内容が表示されます。
• 複数のAPI設定が正しく機能するかどうかを確認するために使用されます。

通常モード

MCPサーバーの起動

1. tapd_mcp_server.py のmain関数にprint文がないことを確認してください（またはコメントアウトしてください）。これにより、起動時にデバッグ情報が出力されなくなります。
2. MCPサーバーを起動します（この操作はAIクライアントが設定ファイルに基づいて自動的に実行するため、手動で行う必要はありません）：

uv run tapd_mcp_server.py

WorkFlowスクリプトの実行

1. 評価ルールの設定

# ルール設定を表示する
uv run mcp_tools/test_case_rules_customer.py

# ルール設定を変更する
uv run mcp_tools/test_case_rules_customer.py --config

# デフォ，ルール設定にリセットする
uv run mcp_tools/test_case_rules_customer.py --reset

# ヘルプ情報を表示する
uv run mcp_tools/test_case_rules_customer.py --help

2. 要件リストの知識ベースを実行する

uv run mcp_tools/test_case_require_list_knowledge_base.py

3. AI評価ツールを実行する

uv run mcp_tools/test_case_evaluator.py

よくある問題のトラブルシューティング

• 依存関係が不足している場合：ModuleNotFoundError というエラーが表示された場合は、uv add コマンドを実行したかどうかを確認し、または uv add <不足しているモジュール名> を試してみてください。
• API接続が失敗した場合：API_USER / API_PASSWORD / WORKSPACE_ID が正しいことを確認し、TAPDアカウントが対応するプロジェクトの読み取り権限を持っていることを確認してください。
• Pythonバージョンが一致しない場合：対象のコンピューターのPythonバージョンが3.10.xであることを確認してください（python --version を実行して確認できます）。

📚 ドキュメント

プロジェクト構造

MCPAgentRE\
├─config\                     # 設定ファイルのディレクトリ
├─knowledge_documents\        # 知識ドキュメント（Gitコミット時にはディレクトリ内のファイルはデフォルトで無視されます。コミットする場合は、.gitignoreで無視を解除してください）
├─documents_data\             # ドキュメントデータのディレクトリ（一時的なもので、最終的にはlocal_dataに置き換えられます）
│  ├─docx_data\                   # .docxドキュメントを保存するディレクトリ
│  ├─excel_data\                  # Excelテーブルを保存するディレクトリ
│  └─pictures_data\               # 画像を保存するディレクトリ
├─local_data\                 # ローカルデータのディレクトリ。TAPDから取得したデータやデータベースなどを保存します（Gitコミット時には無視されます）
│  ├─msg_from_fetcher.json        # TAPDから取得した要件と欠陥データ
│  ├─fake_tapd.json               # 模擬TAPDデータを生成するための偽データ生成器
│  ├─preprocessed_data.json       # 前処理されたTAPDデータ
│  └─vector_data\                 # ベクトルデータベースファイルのディレクトリ
│     ├─data_vector.index             # ベクトルデータベースのインデックスファイル
│     ├─data_vector.metadata.pkl      # ベクトルデータベースのメタデータファイル
│     └─data_vector.config.json       # ベクトルデータベースの設定ファイル
├─mcp_tools\                  # MCPツールのディレクトリ
│  ├─data_vectorizer.py           # カスタムデータソースのベクトル化をサポートするベクトル化ツール
│  ├─context_optimizer.py         # スマート要約生成をサポートするコンテキスト最適化ツール
│  ├─docx_summarizer.py           # .docxドキュメントの内容を抽出するドキュメント要約生成ツール
│  ├─fake_tapd_gen.py             # テストとデモンストレーションに使用するTAPD偽データ生成ツール
│  ├─word_frequency_analyzer.py   # キーワードのワードクラウド統計を生成する単語頻度分析ツール
│  ├─data_preprocessor.py         # TAPDデータをクリーニングし最適化するデータ前処理ツール
│  ├─common_utils.py              # 統一された共通ツールモジュール
│  └─example_tool.py              # サンプルツール
├─models\                     # モデルのディレクトリ
├─test\                       # テストのディレクトリ
│  ├─test_comprehensive.py        # 包括的なベクトル化機能のテスト
│  ├─test_vectorization.py        # 基本的なベクトル化機能のテスト
│  ├─test_data_vectorizer.py      # 完全版data_vectorizerツールの機能をテストする
│  ├─test_word_frequency.py       # 単語頻度分析ツールのテスト
│  └─vector_quick_start.py        # ベクトル化機能のクイックスタートスクリプト
├─.gitignore                  # Gitコミット時に遵守するフィルタリングルール
├─.python-version             # Pythonバージョンを記録するファイル（3.10）
├─提示词-TAPD平台MCP分析助手.md
├─TAPD平台MCP服务器开发指南.md
├─api.txt                     # APIキー情報を含むファイル。自分で作成する必要があります（Gitコミット時には無視されます）
├─main.py                     # プロジェクトのエントリーファイル。実際の機能はありません。
├─pyproject.toml              # 最新のPython依存関係管理ファイル
├─README.md                   # プロジェクトの説明ドキュメント、つまりこのドキュメント
├─tapd_data_fetcher.py        # TAPD APIから要件と欠陥データを取得するロジックを含むファイル
├─tapd_mcp_server.py          # すべてのMCPツールを提供するためのMCPサーバー起動スクリプト
└─uv.lock                     # UVパッケージマネージャーが使用するロックファイル

プロジェクトをAIクライアントに接続する方法

前提条件

• ローカルコンピューターでプロジェクトの移行と検証が完了していること。
• MCPサーバーがインストールされ、実行されていること。
• ローカルコンピューターにAIクライアント（Claude Desktopを例とする）がインストールされ、実行されていること。

接続手順

1. Claude Desktopを開く

• Claude Desktopクライアントを起動します。

2. MCPサーバーの設定

• ショートカットキーCtrl + ,を使用して設定ページを開きます（または左上のメニューアイコンをクリックし、File - Settingsを選択します）。

• Developerタブを選択します。

• Edit Configボタンをクリックすると、ファイルエクスプローラーが開きます。

• 強調表示されたclaude_desktop_config.jsonファイルを編集し、以下の内容を追加します（他の内容がある場合は、階層関係に注意してください）：

  {
    "mcpServers": {
      "tapd_mcp_server": {
        "command": "uv",
        "args": [
          "--directory",
          "D:\\MiniProject\\MCPAgentRE",
          "run",
          "tapd_mcp_server.py"
        ]
      }
    }
  }
  

  • 注意：
    • commandフィールドは、MCPサーバーを実行するコマンドを指定します（通常はuv）。
    • argsフィールドは、MCPサーバーを実行するためのパラメーターを指定します。プロジェクトディレクトリ（--directory）と実行するスクリプトファイル（run tapd_mcp_server.py）を含みます。
    • --directoryがMCPサーバーが存在するディレクトリを指していることを確認してください。つまり、D:\MiniProject\MCPAgentRE（実際のディレクトリに合わせて変更してください）。

• ファイルを保存して閉じます。

接続テスト

• Claude Desktopの左上の+ボタンをクリックし、New Chatを選択します。

• 新しいチャットウィンドウに以下の内容を入力して基本機能をテストします：

  tapd_mcp_serverプラグインを使用して、TAPDプロジェクトの要件と欠陥データを取得してください。
  

• 送信ボタンをクリックし、MCPサーバーからのデータを待ちます。

• 返されたデータが要件と欠陥の数と内容を含むことを確認します。

注意事項

• MCPサーバーのパスとパラメーターが正しく設定されていることを確認してください。

• MCPサーバーがエラーを返す場合、MCPサーバーのログファイル（通常は%APPDATA%\Claude\logsにあります）を確認して詳細を取得してください。

• AIクライアントがMCPプラグインを認識できない場合、AIクライアントを再インストールまたは更新する必要があるかもしれません。

• 以下のコマンドを実行すると、最近のログをリストし、新しいログを追跡することができます（Windowsでは、最近のログのみが表示されます）：

  type "%APPDATA%\Claude\logs\mcp*.log"
  

MCPサーバーの機能を拡張する

プロジェクトのディレクトリ構造を明確にするために、MCPツール関数をmcp_toolsフォルダに配置することをお勧めします。以下は、新しいツール関数を追加する方法の例です。

新しいツール関数の追加

1. ツール関数ファイルの作成

• mcp_toolsフォルダに新しいPythonファイル（例: new_tool.py）を作成します。

• 非同期関数を記述します。例のテンプレートは以下の通りです：

  async def new_function(param1: str, param2: int) -> dict:
      """
      新しいツール関数の説明
      
      パラメーター:
          param1: パラメーターの説明
          param2: パラメーターの説明
          
      戻り値:
          戻りデータ構造の説明
      """
      # 関数の実装
      return {"result": "処理結果"}
  

2. サーバーにツールを登録する

• tapd_mcp_server.pyに以下を追加します：

  • インポート文：from mcp_tools.new_tool import new_function

  • @mcp.tool()デコレーターを使用して関数を登録します：

    @mcp.tool()
    async def new_tool(param1: str, param2: int) -> dict:
        """
        ツール機能の詳細な説明
        
        パラメーター:
            param1 (str): パラメーターの詳細な説明
            param2 (int): パラメーターの詳細な説明
            
        戻り値:
            dict: 戻りデータ構造の詳細な説明
        """
        return await new_function(param1, param2)
    

3. ドキュメントのベストプラクティス

• AIクライアントに明確なドキュメントを追加します：
  • 関数レベルのドキュメント：パラメーターの型と戻り値の構造を含む詳細な日本語の説明を使用します。
  • パラメーターの説明：各パラメーターのデータ型と予想される用途を明確にします。
  • 戻り値の説明：戻りディクショナリの各フィールドを詳細に説明します。
  • 例：呼び出し例と期待される出力を提供します。

🔧 技術詳細

このセクションでは、MCP_Agent:RE プロジェクトの技術的な詳細について説明します。主に、利用可能なMCPサーバーの各種ツールや、WorkFlowスクリプト、統一インターフェーススクリプトの機能と使い方に焦点を当てています。

利用可能なMCPサーバー

このプロジェクトは、TAPDデータの取得、処理、分析、およびインテリジェント要約機能をサポートする豊富なMCPツールセットを提供しています。各ツールは、特定のタスクを効率的に実行するために設計されています。

データ取得ツール

• get_tapd_data()：TAPD APIから要件と欠陥データを取得し、ローカルファイルに保存します。数量統計を返すため、初回のデータ取得や定期的なローカルデータの更新に適しています。
• get_tapd_stories()：TAPDプロジェクトの要件データを取得します。ページングをサポートし、JSONデータを直接返しますが、ローカルに保存されません。データ量が少ない場合のみ使用することをお勧めします。
• get_tapd_bugs()：TAPDプロジェクトの欠陥データを取得します。ページングをサポートし、JSONデータを直接返しますが、ローカルに保存されません。データ量が少ない場合のみ使用することをお勧めします。

データ前処理ツール

• preprocess_tapd_description()：TAPDデータのdescriptionフィールドのHTMLスタイルをクリーニングし、テキスト、リンク、画像コンテンツを抽出し、DeepSeek APIを通じて表現を最適化します。データ長を大幅に圧縮しながら、重要な情報を保持します。ただし、このツールはまだ開発中です。
• preview_tapd_description_cleaning()：descriptionフィールドのクリーニング結果をプレビューし、圧縮率と抽出された情報を表示します。元のデータは変更されません。
• docx_summarizer.py：.docxドキュメントからテキスト、画像、およびテーブル情報を抽出し、要約を生成します。このツールも開発中です。

ベクトル化と検索ツール

• vectorize_data()：カスタムデータソースのベクトル化をサポートします。データをベクトル形式に変換し、後続のセマンティック検索と分析に使用します。
• get_vector_info()：簡略化されたベクトルデータベースの状態と統計情報を取得します。
• search_data()：セマンティック類似度に基づくインテリジェント検索をサポートし、自然言語クエリを受け付け、クエリに最も関連する結果を返します。

データ生成と分析ツール

• generate_fake_tapd_data()：模擬TAPDデータを生成し、テストとデモンストレーションに使用します。ただし、アドレスを指定しない場合、ローカルデータが上書きされる可能性があります。
• generate_tapd_overview()：LLMを使用して、プロジェクトの概要レポートと要約を簡単に生成し、プロジェクトの概要を把握するために使用します。環境にDeepSeek APIキーを設定する必要があります。
• analyze_word_frequency()：TAPDデータの単語頻度分布を分析し、キーワードのワードクラウド統計を生成し、検索機能に正確なキーワード提案を提供します。

サンプルツール

• example_tool()：MCPツールの登録方法を示すサンプルツールです。

利用可能なWorkFlowスクリプト

テストケース評価

• mcp_tools\test_case_rules_customer.py：テストケースの評価ルールと優先度を設定するためのスクリプトです。
• mcp_tools\test_case_require_list_knowledge_base.py：TAPDデータから要件情報を抽出して知識ベースを生成するか、要件情報を手動で変更することができるスクリプトです。
• mcp_tools\test_case_evaluator.py：設定されたルールに基づいてテストケースの品質を評価し、評価レポートをローカルファイルに生成するスクリプトです。

統一インターフェーススクリプト

mcp_tools\common_utils.py には、MCPツールの登録と呼び出しを簡素化する統一されたツールインターフェースが含まれています。このスクリプトには、いくつかのクラスとグローバルインスタンス管理関数が定義されています。

MCPToolsConfigクラス

• __init__()：プロジェクトに必要なディレクトリ構造（local_data、models、vector_data）を自動的に作成する設定マネージャーを初期化します。
• _get_project_root()：プロジェクトのルートディレクトリの絶対パスを取得します。
• get_data_file_path()：データファイルの絶対パスを取得し、相対パスの自動変換をサポートします。
• get_vector_db_path()：ベクトルデータベースファイルのパスを取得します。デフォルトは"data_vector"です。
• get_model_cache_path()：モデルキャッシュディレクトリのパスを取得します。

ModelManagerクラス

• __init__(config)：MCPToolsConfigインスタンスに依存するモデルマネージャーを初期化します。
• get_project_model_path(model_name)：ローカルに指定されたモデルが存在するかどうかを検出し、モデルのパスまたはNoneを返します。
• get_model(model_name)：SentenceTransformerモデルのインスタンスを取得します。ローカルモデルを優先し、自動ダウンロードとキャッシュをサポートします。
• clear_cache()：グローバルモデルキャッシュをクリアし、メモリリソースを解放します。

TextProcessorクラス

• extract_text_from_item(item, item_type)：TAPDデータ項目（要件/欠陥）から重要なテキスト情報を抽出し、さまざまなタイプのフィールド抽出戦略をサポートします。

FileManagerクラス

• __init__(config)：MCPToolsConfigインスタンスに依存するファイルマネージャーを初期化します。
• load_tapd_data(file_path)：TAPD JSONデータファイルをロードし、絶対パスと相対パスをサポートします。
• load_json_data(file_path)：JSONデータファイルをロードし、エラー処理をサポートします。ファイルが存在しない場合は空の辞書を返します。
• save_json_data(data, file_path)：データをJSON形式で保存し、ディレクトリ構造を自動的に作成します。

APIManagerクラス 【2025年7月22日更新】

• __init__()：DeepSeekとSiliconFlowの両方のAPI設定をサポートするAPIマネージャーを初期化します。
• get_headers(endpoint)：エンドポイントに基づいて自動的に対応するAPIキーを選択し、APIリクエストヘッダーをスマートに構築します。
• call_llm(prompt, session, model, endpoint, max_tokens)：複数のAPIに対応するLLM呼び出しインターフェースです。DeepSeek APIとSiliconFlow APIの両方をサポートし、APIタイプを自動的に検出し、さまざまなリクエスト形式とエラー処理に適応します。

グローバルインスタンス管理関数

• get_config()：グローバルMCPToolsConfigインスタンスを取得します（シングルトンパターン）。
• get_model_manager()：グローバルModelManagerインスタンスを取得します（シングルトンパターン）。
• get_file_manager()：グローバルFileManagerインスタンスを取得します（シングルトンパターン）。
• get_api_manager()：グローバルAPIManagerインスタンスを取得します（シングルトンパターン）。

📄 関連ドキュメントまたはURL

• TAPDヘルプドキュメント
• TAPDオープンプラットフォームドキュメント
• MCP中国語サイト
• Model Context Protocol
• DeepSeek APIドキュメント
• 会話リクエストの作成 - SiliconFlow