Llm MCP Tools

🚀 LLM MCP Tools - インテリジェントツールスケジューリングシステム

このシステムは、FastMCP 2.0 をベースに構築されたインテリジェントツールスケジューリングシステムです。知識グラフ、ベクトル検索、リアルタイム進捗表示をサポートし、大規模言語モデルの機能呼び出し能力を通じて、AIが様々なツールを自動的に選択して呼び出すことができ、簡単な計算から複雑な知識グラフ分析までの全プロセスを自動化します。

📖 概要

LLM MCP Tools は、Model Context Protocol (MCP) と FastMCP 2.0 に基づいて構築されたインテリジェントツールスケジューリングシステムです。大規模言語モデルの Function Calling 機能を利用して、AIが様々なツールを自動的に選択し、呼び出すことができ、簡単な計算から複雑な知識グラフ分析までの全プロセスを自動化します。

🎯 適用シーン

• 🏢 企業知識管理：文書のアップロード、ベクトル検索、知識グラフの構築
• 💼 ビジネスデータ分析：従業員情報の照会、部門統計、データ可視化
• 🤖 インテリジェントアシスタント開発：マルチラウンド対話、ツールスケジューリング、リアルタイムフィードバック
• 📚 MCP プロトコル学習：解耦アーキテクチャ、標準化されたインターフェース、ツールの登録

✨ 主な機能

🔧 豊富なツールエコシステム

合計：26 以上のツール関数

🎨 独自の優位性

✅ 解耦アーキテクチャ：MCP Server と Web App が完全に分離されており、独立したデプロイと拡張が可能です。
✅ 自動検出：新しいツールが自動的に登録され、クライアントコードを変更する必要がありません。
✅ 知識グラフ：エンティティ関係を自動的に抽出し、グラフの可視化とパス照会をサポートします。
✅ リアルタイム進捗：文書処理の過程がリアルタイムに表示され、ユーザー体験が良好です。
✅ ベクトル検索：ChromaDB をベースにした効率的な文書検索が可能です。
✅ マルチラウンド対話：コンテキスト理解と会話管理をサポートします。
✅ 標準プロトコル：MCP 標準に準拠しており、拡張と統合が容易です。

🏗️ システムアーキテクチャ

アーキテクチャ図

┌─────────────────────────────────────────────────────────────┐
│                     ユーザーブラウザ                                 │
│                 (http://localhost:8000)                      │
└────────────────────────┬────────────────────────────────────┘
                         │ WebSocket (リアルタイム通信)
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                    Web App (FastAPI)                         │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  WebSocket  │  │  MCP Client  │  │  LLM Client  │       │
│  │   Handler   │→ │  (HTTP呼び出し)  │→ │ (通義千問)   │       │
│  └─────────────┘  └──────────────┘  └──────────────┘       │
│                          ↓                                   │
└──────────────────────────┼───────────────────────────────────┘
                           │ HTTP (MCP Protocol)
                           ↓
┌─────────────────────────────────────────────────────────────┐
│               MCP Server (FastMCP 2.0)                       │
│  ┌───────────────────────────────────────────────────────┐  │
│  │             ツール登録センター (@mcp.tool())                  │  │
│  └───────────────────────────────────────────────────────┘  │
│         ↓              ↓              ↓              ↓       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ データベースツール │  │ 知識ベースツール │  │ 知識グラフ  │  │ 計算ツール  │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└──────┬──────────────┬──────────────┬──────────────┬─────────┘
       │              │              │              │
       ↓              ↓              ↓              ↓
   MySQL      ChromaDB(ベクトル)  NetworkX(グラフ)   外部API

技術スタック

• バックエンドフレームワーク：FastAPI + FastMCP 2.0
• 大規模言語モデル：通義千問 Qwen（Function Calling をサポート）
• データベース：MySQL（構造化データ） + ChromaDB（ベクトルデータベース）
• 知識グラフ：NetworkX（グラフストレージ） + OpenAI API（エンティティ抽出）
• 通信プロトコル：WebSocket（リアルタイム通信） + HTTP（MCPプロトコル）
• フロントエンド：原生 JavaScript + Marked.js（Markdownレンダリング）

🚀 クイックスタート

環境要件

• Python 3.10 以上
• MySQL 5.7 以上（データベースツールを使用する場合に必要）
• 通義千問 API Key

1. プロジェクトをクローンする

git clone https://github.com/houmingya/LLM_MCP_TOOLS.git
cd LLM_MCP_TOOLS

2. 仮想環境を作成する

# conda を使用する場合
conda create -n mcp-demo python=3.10 -y
conda activate mcp-demo

# または venv を使用する場合
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

3. 依存関係をインストールする

pip install -r requirements.txt

4. 環境変数を設定する

重要：プロジェクトは環境変数を使用して機密情報を管理しています。コード内の設定を直接変更しないでください！

環境変数テンプレートをコピーします：

cp .env.example .env

.env ファイルを編集し、設定を入力します：

# ========================
# 大規模言語モデルの設定（必須）
# ========================
# 通義千問 API Key（必須設定）
# 取得先：https://dashscope.console.aliyun.com/apiKey
LLM_API_KEY=your_qwen_api_key_here

# モデル名（オプション：qwen-plus, qwen-turbo, qwen-max）
LLM_MODEL_NAME=qwen-plus

# ========================
# MySQL データベースの設定（オプション）
# ========================
# データベースツールを使用しない場合は設定不要
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_mysql_password_here
DB_DATABASE=test_db

# ========================
# サービスポートの設定
# ========================
WEB_PORT=8000
MCP_PORT=8001

詳細な設定説明は、設定ガイド を参照してください。

5. 設定を検証する

設定テストを実行します：

python test_config.py

"✅ 設定検証成功" と表示されれば、設定が成功しています！

6. サービスを起動する

方法1：一括起動（推奨）

python run.py

これにより、以下のサービスが同時に起動します：

• MCP Server: http://localhost:8001/mcp
• Web App: http://localhost:8000

方法2：個別起動（開発デバッグ用）

# ターミナル1 - MCP Server を起動する
python run_mcp_server.py

# ターミナル2 - Web App を起動する
python run.py --mode webapp

7. アプリケーションにアクセスする

ブラウザで http://localhost:8000 を開きます。

💻 使用例

基本的な対話

👤 こんにちは、あなたは何ができますか？
🤖 私は以下のことができます：
   • 従業員と部門の情報を照会する
   • 文書をアップロードし、検索する
   • 知識グラフを構築し、照会する
   • 数学計算と統計分析を行う
   • 時間情報を取得し、日付計算を行う
   • HTTPリクエストを送信し、天気を照会する

データベース照会

👤 営業部には何人の従業員がいて、平均給与はいくらですか？
🤖 [query_employees_by_department(department_id=2) を呼び出す]
   [get_department_statistics() を呼び出す]
   
   営業部には 15 人の従業員がいて、平均給与は 8,500 元です。

文書のアップロードと検索

👤 この製品説明書をアップロードしてください
🤖 [upload_document(file) を呼び出す]
   📤 文書をアップロード中...
   📝 23 個のテキストブロックに分割されました
   🧠 1/5 番目のテキストブロックを分析中...
   🧠 2/5 番目のテキストブロックを分析中...
   ✅ 知識グラフの構築が完了しました！
   
   文書のアップロードに成功しました！18 個のエンティティと 25 個の関係が抽出されました。

👤 この文書に記載されている主な機能は何ですか？
🤖 [search_documents(query="主な機能") を呼び出す]
   
   文書によると、主な機能は以下の通りです：
   1. データ収集と保存
   2. リアルタイム監視とアラート
   3. データ分析と可視化
   ...

知識グラフ照会

👤 浪潮云洲はどのプロジェクトと関係がありますか？
🤖 [query_entity(entity_name="浪潮云洲") を呼び出す]
   
   知識グラフにおいて、浪潮云洲は以下の関係を持っています：
   • 開発 → 云洲データ管理システム
   • 提供 → データ可視化プラットフォーム
   • 適用 → 金川産業情報プラットフォーム
   ...

👤 浪潮云洲と金川集団の間にはどのような関係がありますか？
🤖 [find_entity_path(source="浪潮云洲", target="金川集団") を呼び出す]
   
   関係パスが見つかりました：
   浪潮云洲 → 開発 → 意思決定支援プラットフォーム → 適用 → 金川集団

計算と分析

👤 (123 + 456) * 2 - 89 を計算してください
🤖 [calculate(expression="(123 + 456) * 2 - 89") を呼び出す]
   
   計算結果：1,069

👤 このデータセット [23, 45, 67, 89, 12, 34, 56, 78] の統計的特徴を分析してください
🤖 [statistics_analysis(data=[23,45,67,89,12,34,56,78]) を呼び出す]
   
   統計分析結果：
   • 平均値：50.5
   • 中央値：50.5
   • 標準偏差：26.4
   • 最小値：12、最大値：89

📁 プロジェクト構造

LLM_MCP_TOOLS/
├── 📄 README.md                     # プロジェクト説明ドキュメント
├── 📄 requirements.txt              # Python依存関係リスト
├── 📄 .env.example                  # 環境変数サンプル
├── 📄 .gitignore                    # Git無視ファイル
│
├── 🚀 run.py                        # 統一的な起動エントリー
├── 🚀 run_decoupled.py             # 解耦モードでの起動（2つのサービスを同時に起動）
├── 🚀 run_mcp_server.py            # MCP Server を単独で起動
│
├── ⚙️ config/                       # 設定モジュール
│   ├── __init__.py
│   └── settings.py                 # 設定センター（データベース、LLM、ポートなど）
│
├── 🔧 mcp_server/                   # MCP Server (port 8001)
│   ├── __init__.py
│   ├── server.py                   # 🎯 ツール登録センター (@mcp.tool())
│   ├── prompts.py                  # プロンプトテンプレート
│   └── tools/                      # ツール実装
│       ├── __init__.py
│       ├── database_tools.py       # データベースツール（6個の関数）
│       ├── knowledge_tools.py      # 知識ベースツール（3個の関数）
│       ├── knowledge_graph_tools.py # 知識グラフツール（7個の関数）
│       ├── calculation_tools.py    # 計算ツール（3個の関数）
│       ├── time_tools.py          # 時間ツール（4個の関数）
│       └── api_tools.py           # APIツール（3個の関数）
│
├── 🌐 web_app/                      # Web App (port 8000)
│   ├── __init__.py
│   ├── main.py                     # 🎯 FastAPIアプリケーション + WebSocket + LLM
│   ├── mcp_client.py              # 🎯 MCP Client（HTTP通信）
│   └── static/                    # フロントエンド静的ファイル
│       ├── index.html             # メインページ
│       ├── knowledge-graph.html   # 知識グラフ可視化
│       ├── css/
│       │   └── style.css         # スタイルファイル
│       └── js/
│           ├── app.js            # アプリケーション初期化
│           ├── websocket.js      # WebSocket接続管理
│           ├── chat.js           # チャット機能
│           ├── message-handler.js # メッセージ処理（進捗表示を含む）
│           ├── file-upload.js    # ファイルアップロード
│           ├── knowledge-graph.js # 知識グラフ可視化
│           └── utils.js          # ユーティリティ関数
│
├── 📚 docs/                         # ドキュメントディレクトリ
│   ├── 知识图谱技术深度解析.md
│   ├── 知识图谱应用说明.md
│   ├── 文本块处理进度功能说明.md
│   └── MCP_API_完整对照表.md
│
├── 📤 uploads/                      # 文書アップロードディレクトリ（.gitignore）
├── 💾 chroma_db/                    # ChromaDBデータディレクトリ（.gitignore）
└── 🧠 knowledge_graph_data/         # 知識グラフデータ（.gitignore）

🔧 開発ガイド

新しいツールを追加する

mcp_server/server.py に以下のコードを追加するだけです：

@mcp.tool()
def my_new_tool(param1: str, param2: int = 10) -> Dict[str, Any]:
    """
    ツールの説明（自動的にツールの説明として使用されます）
    
    Args:
        param1: パラメータ1の説明
        param2: パラメータ2の説明、デフォルト値10
        
    Returns:
        戻り値の説明
    """
    # ロジックを実装する
    result = do_something(param1, param2)
    
    return {
        "success": True,
        "data": result,
        "message": "実行成功"
    }

MCP Server を再起動すると、Web App が自動的に新しいツールを検出します！✨
main.py、ツールリスト、またはフロントエンドコードを変更する必要はありません。

ツール開発のベストプラクティス

1. 明確なドキュメント文字列：ツールの説明として大規模言語モデルに渡されます。
2. 型アノテーション：ツールパラメータのスキーマを自動生成するのに役立ちます。
3. 統一された戻り値形式：success、data、message フィールドを含むことをお勧めします。
4. エラー処理：例外をキャッチし、分かりやすいエラーメッセージを返します。

ローカル開発

# 開発用依存関係をインストールする
pip install -r requirements-dev.txt

# テストを実行する
pytest tests/

# コードを整形する
black .
isort .

# 型チェックを行う
mypy .

📚 ドキュメント

• 知識グラフ技術の詳細解析
• 知識グラフのアプリケーション説明
• テキストブロック処理の進捗機能説明
• MCP APIの完全な対照表

外部リソース

• FastMCP 公式ドキュメント
• MCP プロトコル仕様
• FastAPI ドキュメント
• ChromaDB ドキュメント
• NetworkX ドキュメント

❓ よくある質問

Q: ChromaDB で "Insert of existing embedding ID" エラーが発生します。どうすればいいですか？

A: これは文書の重複アップロードによるものです。新しいバージョンでは upsert を add の代わりに使用することで修正されています。

Q: ポートが使用中の場合はどうすればいいですか？

A: config/settings.py のポート設定を変更します：

class WebConfig:
    PORT = 8000  # 他のポート番号に変更する（例：8080）

class MCPServerConfig:
    PORT = 8001  # 他のポート番号に変更する（例：8081）

Q: 知識グラフの構築が遅いのはなぜですか？

A: これは正常な現象です。エンティティ抽出のために大規模言語モデルのAPIを呼び出す必要があるため、文書が長いほど時間がかかります。新しいバージョンではリアルタイム進捗表示がサポートされています。

Q: データベースツールを使用しないにはどうすればいいですか？

A: データベースツールはオプションです。必要ない場合は、mcp_server/server.py で関連するツールの登録をコメントアウトするだけです。

Q: どの大規模言語モデルをサポートしていますか？

A: 理論的には、OpenAI API 形式に互換性のあるすべての大規模言語モデルをサポートしています。config/settings.py の LLMConfig を変更するだけです：

class LLMConfig:
    API_KEY = "your_api_key"
    API_BASE = "https://api.openai.com/v1"  # または他のエンドポイント
    MODEL_NAME = "gpt-4"  # または他のモデル

🤝 貢献に参加する

私たちはあらゆる形の貢献を歓迎します！新機能の追加、バグ修正、ドキュメントの改善、問題のフィードバックなど、どんなものでも構いません。

貢献方法

1. このリポジトリをフォークする
2. 機能ブランチを作成する (git checkout -b feature/AmazingFeature)
3. 変更をコミットする (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュする (git push origin feature/AmazingFeature)
5. Pull Request を作成する

開発規約

• PEP 8 コード規約に従う
• 必要なコメントとドキュメントを追加する
• 単体テストを作成する
• すべてのテストが通過することを確認する

📄 ライセンス

このプロジェクトは MIT License のオープンソースライセンスの下で公開されています。

🙏 謝辞

• FastMCP - 優れた MCP 実装フレームワーク
• FastAPI - 最新の Python Web フレームワーク
• ChromaDB - 使いやすいベクトルデータベース
• NetworkX - 強力なグラフ分析ライブラリ
• 通義千問 - アリクラウドの大規模言語モデルサービス

📧 連絡先

• GitHub: @houmingya
• Issues: プロジェクトの問題フィードバック