Deepin MCP

Deepin MCP

MCP (Machine Conversation Protocol) サーバーに接続して、OpenAI 言語モデルを使用してそれらと対話するためのクライアントです。

概要

この MCP クライアントにより、以下のことができます:

1. MCP サーバー (Python または JavaScript) に接続する
2. サーバーから利用可能なツールをリストアップして使用する
3. 自然言語クエリを使用してサーバーと対話する
4. OpenAI の言語モデルで応答を処理する
5. 複雑なタスクを自動的に計画して実行する

セットアップ

前提条件

• Python 3.12 以上
• OpenAI API キー
• 接続する MCP サーバー

UV のインストール (推奨)

UV は高速で信頼性の高い Python パッケージインストーラーおよびリゾルバーです。このプロジェクトでの使用が推奨されます:

1. UV をインストールします:

   # Unix (macOS, Linux)
   curl -LsSf https://astral.sh/uv/install.sh | bash
   
   # Windows (PowerShell)
   irm https://astral.sh/uv/install.ps1 | iex
   

2. インストールを確認します:

   uv --version
   

その他のインストールオプションについては、UV の公式ドキュメントをご覧ください。

インストール

1. このリポジトリをクローンします

2. 仮想環境を作成します:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 依存関係をインストールします:

   pip install -e .
   

   または UV を使用します (推奨):

   uv venv
   uv pip install -e .
   

4. API キーと設定を含む .env ファイルを作成します:

   # OpenAI API Configuration
   OPENAI_API_KEY=your_openai_api_key
   BASE_URL=https://api.openai.com/v1  # Optional: Use your own OpenAI API proxy
   MODEL=gpt-3.5-turbo  # Optional: Specify the model to use
   

5. 必要な依存関係をインストールします:

   UV を使用します (推奨):

   # Install core dependencies
   uv pip install -e .
   
   # Or install individual packages
   uv add openai  # OpenAI API client
   uv add python-dotenv  # For loading environment variables
   uv add mcp  # Machine Conversation Protocol library
   

   標準的な pip を使用します:

   pip install openai python-dotenv mcp
   

   各サーバータイプには追加の依存関係が必要な場合があります:

   # For JavaScript servers
   uv add node-fetch  # If connecting to JavaScript MCP servers
   
   # For additional functionality
   uv add asyncio  # For asynchronous operations
   uv add pathlib  # For file path handling
   

使用方法

UV を使用したクイックスタート

UV で素早く始めましょう:

# Clone the repository
git clone https://github.com/yourusername/deepin-mcp-python.git
cd deepin-mcp-python

# Install UV
curl -sSf https://astral.sh/uv/install.sh | bash

# Create a virtual environment and install dependencies
uv venv
uv pip install -e .

# Create .env file (replace with your actual API key)
echo "OPENAI_API_KEY=your_openai_api_key" > .env
echo "MODEL=gpt-3.5-turbo" >> .env

# Run the client with bash server
uv run python client.py servers/bash_server.py

# Or run the task planning system
uv run python main.py

基本的な使用方法

MCP サーバースクリプトへのパスを指定してクライアントを実行します:

python client.py path/to/your/server_script.py

または UV を使用します:

uv run python client.py path/to/your/server_script.py

JavaScript サーバーの場合:

python client.py path/to/your/server_script.js

または UV を使用します:

uv run python client.py path/to/your/server_script.js

タスク計画システム

プロジェクトには、以下のことができる強力なタスク計画システムが含まれています:

1. 複雑なユーザーリクエストを順序付きタスクに分割する
2. MCP サーバーを使用してタスクを自動的に実行する
3. 詳細な実行サマリーを提供する

タスク計画システムを使用するには:

python main.py

または UV を使用します (推奨):

uv run python main.py

カスタムサーバーパスを指定することもできます:

python main.py --server path/to/your/server_script.py

またはバージョン情報を確認します:

python main.py --version

メインエントリーポイント

プロジェクトは、アプリケーションの一元化されたエントリーポイントとして機能するメインエントリーポイント (main.py) を提供します:

python main.py

または UV を使用します (推奨):

uv run python main.py

メインエントリーポイントは以下の機能があります:

• タスク計画システムを初期化する
• バージョン情報とシステムの説明を提供する
• 例外を適切に処理する
• アプリケーションをより使いやすくする
• --server オプションでカスタムサーバーパスを指定できる

使用例:

$ python main.py

====== Deepin MCP 任务规划系统 ======
版本: 1.0.0
描述: 这是一个基于MCP协议的任务规划执行系统
======================================

欢迎使用任务规划执行系统
这个系统会将您的请求拆解为多个任务，并依次执行

已成功连接到服务器: /home/user/deepin-mcp-python/servers/bash_server.py

请输入您的请求 (输入'quit'退出): 

対話例:

请输入您的请求 (输入'quit'退出): Create a new directory called 'projects' and copy all .txt files from 'documents' to it

正在分析您的请求...
已将您的请求拆解为 3 个任务:
1. Create a new directory called 'projects'
2. List all .txt files in the 'documents' directory
3. Copy all .txt files from 'documents' to 'projects'

是否执行这些任务? (y/n): y

[Task execution progress will be shown here]

执行总结:
[Detailed summary of the executed tasks will be shown here]

タスク計画システムは以下の場合に特に便利です:

• 複雑なファイル操作
• 多段階システム構成
• ワークフロー自動実行
• バッチ処理タスク

インタラクティブモード

接続すると、インタラクティブプロンプトにクエリを入力できます。クライアントは以下を実行します:

1. クエリを言語モデルに送信します
2. モデルが要求したツール呼び出しを処理します
3. 最終的な応答を返します

インタラクティブモードを終了するには quit と入力します。

利用可能なサーバー

Weather Server

weather_server.py は、指定された都市の天気情報をクエリするための MCP ツールを提供します。

python client.py weather_server.py

または UV を使用します:

uv run python client.py weather_server.py

クエリ例: "查询北京的天气"

依存関係:

uv add requests  # For HTTP requests to weather APIs

File Server

file_server.py は、ファイルを開く、コピーする、移動する、名前を変更する、削除する、作成するなどのファイル操作用の MCP ツールを提供します。

python client.py file_server.py

または UV を使用します:

uv run python client.py file_server.py

クエリ例: "创建一个名为test.txt的文件"

依存関係:

uv add pathlib  # For file path handling

Bash Server

bash_server.py は、Linux bash コマンドを実行するための MCP ツールを提供します。

python client.py bash_server.py

または UV を使用します:

uv run python client.py bash_server.py

クエリ例: "列出当前目录下的所有文件"

依存関係:

uv add shlex  # For shell command parsing

開発

このクライアントを拡張または変更するには:

1. MCPClient クラスがメインの機能を処理します
2. process_query メソッドが LLM を使用してクエリを処理します
3. TaskPlanner クラスが複雑なリクエストをタスクに分割します
4. メインエントリーポイント (main.py) がユーザーフレンドリーなインターフェースを提供します
5. エラーハンドリングが堅牢性のために全体に実装されています

トラブルシューティング

問題が発生した場合:

1. .env の API キーを確認してください
2. サーバースクリプトのパスが正しいことを確認してください
3. サーバーが MCP プロトコルを正しく実装していることを確認してください
4. コンソール出力でエラーメッセージを確認してください
5. 必要な依存関係がインストールされていることを確認してください

ライセンス

このプロジェクトは MIT ライセンスの下で利用可能です。

実行可能バイナリのビルド

Python インストールなしで配布できるスタンドアロンバイナリ実行可能ファイルをビルドできます:

ビルドスクリプトを使用する

プロジェクトにはプロセスを簡単にするビルドスクリプトが含まれています:

# Make the build script executable
chmod +x build.sh

# Run the build script
./build.sh

実行可能ファイルは dist ディレクトリに deepin-mcp として作成されます。

手動ビルドプロセス

手動でビルドする場合:

1. UV を使用して PyInstaller をインストールします:

   uv pip install pyinstaller
   

2. 実行可能ファイルをビルドします:

   pyinstaller --clean deepin-mcp.spec
   

3. 実行可能ファイルは dist/deepin-mcp で利用可能になります

実行可能ファイルの実行

ビルド後、実行可能ファイルを直接実行できます:

# Run with default settings
./dist/deepin-mcp

# Check version
./dist/deepin-mcp --version

# Specify a custom server
./dist/deepin-mcp --server path/to/your/server_script.py

実行可能ファイルにはすべての必要な依存関係が含まれており、Python がインストールされていないシステムに配布できます。

サーバーディスカバリーと選択

アプリケーションは利用可能なサーバースクリプトを自動的に検出してロードします:

1. アプリケーション起動時に、以下の場所でサーバースクリプトを検索します:

   • 現在の作業ディレクトリ
   • servers サブディレクトリ
   • アプリケーションの実行可能ファイルディレクトリ
   • 実行可能ファイルディレクトリ内の servers サブディレクトリ

2. 利用可能なサーバーは以下でリストできます:

   ./deepin-mcp --list-servers
   

3. 起動時に特定のサーバーを選択できます:

   ./deepin-mcp --server bash
   # or by path
   ./deepin-mcp --server /path/to/custom_server.py
   

4. プロンプトで switch と入力することで、実行時にサーバーを切り替えられます。

サーバーデプロイメント

アプリケーションがバイナリ実行可能ファイルとしてパッケージ化される場合:

1. サーバースクリプトは実行可能ファイルの隣にある servers ディレクトリに自動的にデプロイされます
2. アプリケーションはこれらのサーバーを自動的に検出してロードします
3. 各サーバーにはラッパースクリプト (例: bash_server.wrapper.py) が付属し、適切な依存関係ロードを確保します
4. 必要な依存関係すべて (mcp モジュールを含む) を持つ専用 Python 環境が server_env ディレクトリに作成されます
5. カスタムサーバーは servers ディレクトリに "server" を含むファイル名で配置することで追加できます (例: custom_server.py)
6. run_server.sh ヘルパースクリプトを使用して任意のサーバーを直接実行できます

サーバーの直接実行

提供されているヘルパースクリプトを使用してサーバーを直接実行できます:

# Run a server by name
./dist/deepin-mcp/run_server.sh bash

# Run a server by file name
./dist/deepin-mcp/run_server.sh bash_server.py

# Run a server by full path
./dist/deepin-mcp/run_server.sh /path/to/your/custom_server.py

これは以下の場合に特に有用です:

• サーバー機能を独立してテストする
• 別のターミナルでサーバーを実行する
• アプリケーションでカスタムサーバースクリプトを使用する

サーバー環境構造

パッケージ化されたアプリケーションには、サーバー用の完全な環境が含まれています:

dist/deepin-mcp/
├── deepin-mcp          # Main executable
├── run_server.sh       # Server helper script
├── server_env/         # Python environment for servers
│   ├── mcp/            # MCP module and dependencies
│   ├── openai/         # OpenAI module
│   └── ...             # Other dependencies
└── servers/
    ├── bash_server.py          # Original server script
    ├── bash_server.wrapper.py  # Wrapper that configures path
    ├── file_server.py          # Original server script
    ├── file_server.wrapper.py  # Wrapper that configures path
    └── ...

カスタムサーバーの追加

パッケージ化されたアプリケーションにカスタムサーバーを追加するには:

1. MCP プロトコルに従ってサーバースクリプトを作成します
2. パッケージ化されたアプリケーションの servers ディレクトリに配置します
3. 付属のラッパーと同じパターンに従うラッパースクリプトを作成するか、dist/deepin-mcp ディレクトリ内で以下のコマンドを実行します:

cat > servers/myserver_server.wrapper.py << EOF
#!/usr/bin/env python
# Wrapper script for myserver_server.py
import os
import sys

# Add the server_env to the Python path
server_env_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'server_env'))
sys.path.insert(0, server_env_path)

# Import the actual server code
server_file = os.path.abspath(os.path.join(os.path.dirname(__file__), 'myserver_server.py'))
with open(server_file, 'r') as f:
    server_code = f.read()

# Execute the server code with the modified path
exec(server_code)
EOF
chmod +x servers/myserver_server.wrapper.py

4. ヘルパースクリプトでカスタムサーバーを実行するか、メインアプリケーションから直接使用します