Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@miyaura(Miyaura)

Season of AI - MCP : pythonでMCPを使ったPython学習支援アプリを作ってみよう

Last updated at Posted at 2025-12-14
Page 1 of 50

Model Context Protocol (MCP)

Python ワークショップ : MCPを使ったPython学習支援アプリを作ってみよう

AIアシスタントと連携するPythonを使ったMCPサーバ構築の基礎を初心者向けにステップを分けて進めます。

  • Pythonで簡単なMCPサーバーを作ってみ
  • MCPを通じてAIとやり取りする方法を体験
  • 「Pythonの学習を支援するアプリ」を実際に動かしてみる

本日のアジェンダ

  1. Part 0: リポジトリの準備

    • GitHubからコードを取得
    • プロジェクト構造の確認

  2. Part 1: 前提とセットアップ

    • 環境構築
    • 簡単なMCPサーバを作ってみよう

  3. Part 2: Study Buddyアプリの構築

    • プロンプトの実装
    • ツールとサンプリング
    • リソース管理
    • 統合アプリケーション

Part 0: リポジトリの準備

まず、今回のワークショップで使用するコードをGitHubから取得します。

git clone https://github.com/TakahiroMiyaura/lets-learn-mcp-python.git -b handle-ja-JP

インストールしていない人は
https://github.com/TakahiroMiyaura/lets-learn-mcp-pythonから直接ダウンロードでも可能

プロジェクトディレクトリに移動

cd lets-learn-mcp-python

プロジェクト構造

lets-learn-mcp-python/
├── .vscode/
│   └── mcp.json          # MCP設定ファイル
├── prompts_server.py     # プロンプトのサンプル
├── tools_server.py       # ツールのサンプル
├── resources_server.py   # リソースのサンプル
├── server_part_2.py      # 統合版サーバー
├── exercises/            # 演習データ
├── progress/             # 進捗データ
└── pyproject.toml        # プロジェクト設定

必要なツール

  • Git（リポジトリのクローン用）
  • Visual Studio Code
  • Python 3.12 or 3.13
  • UV パッケージマネージャー

Part 1: 前提とセットアップ

ワークショップの準備

Windows Only

初回にターミナル（Powershell）の実行ポリシーを変更します。これを実施していない場合サードパティ製のコマンドが実行できずこの後の作業を進めることができません。実行ポリシーについてはで以下のコマンドを実行して確認してください。CurrentUserの実行ポリシーが「RemoteSigned」になっていれば問題ありません。

PS D:\> Get-ExecutionPolicy -List

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser    RemoteSigned
 LocalMachine       Undefined

もし、「Undefined」の場合は以下のコマンドを実行した後リストを表示して変更されていることを確認してください。

PS D:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

Visual Studio Code

インストール

https://code.visualstudio.com/

ワークショップ内では

  • Github CopilotでワークショップでつくるMCPを動かす

Python のインストール

WindowsにPythonをインストールする際は可能であればMicrosoft Storeからではなく、Python公式のダウンロードサイトからインストーラを入手してセットアップしてください。（Microsoft Storeからのインストールはパスの設定が特殊なためうまく動作させられないことがあります）
https://www.python.org/

Pythonのバージョンは3.12 or 3.13
このワークショップではuvを使用します。現時点（2025/12/10）ではuvはpython 3.14には対応していません。

インストール確認

# バージョン確認
python --version
# または
python3 --version

# pip確認
pip --version
# または
pip3 --version

UV とは？

高速なPythonパッケージマネージャー

UVは、Rustで書かれた超高速なPythonパッケージ・プロジェクトマネージャーです。

主な特徴

  • 超高速: pip/pip-toolsの10-100倍の速度
  • ロックファイル: 再現可能な環境
  • 統一ツール: インストール、依存関係解決、環境管理を一元化
  • グローバルキャッシュ: パッケージの再利用で時間短縮

UV のインストール

インストールコマンド

pip install uv

インストール確認

uv --version

UVのパス確認（重要）

# macOS/Linux
which uv

# Windows(コマンドプロンプト)
where uv

# Windows(Powershell)
gcm uv | fl

このパスはMCP設定で使用します！

仮想環境の作成

python3以降は、パッケージのインストール等を開発環境毎に切替える仮想環境の仕組みが提供されています。

クローンしたプロジェクトで作業

# プロジェクトディレクトリにいることを確認
cd lets-learn-mcp-python

# 仮想環境を作成
python -m venv .venv

# macOS/Linux で有効化
source .venv/bin/activate

# Windows で有効化
.venv\Scripts\activate

環境が有効化されると

プロンプトに (.venv) が表示されます

ヒント

VS Codeでプロジェクトフォルダを開くと、自動的に仮想環境を検出します

パッケージのインストール

UVでの依存関係インストール

別のターミナルを開いて実施。

# プロジェクトディレクトリで実行
uv sync

uvの利点

  • pyproject.toml から自動的に依存関係を読み込み
  • 正確な依存関係解決

VS Codeでプロジェクトを開く

プロジェクトを開く

# コマンドラインから開く
code .

または VS Code からFile > Open Folder > lets-learn-mcp-python を選択

Model Context Protocol (MCP) とは？

定義

AIアシスタントが外部ツール、データソース、サービスに安全にアクセス・連携できるようにするオープン標準

できること

  • リアルタイムデータにアクセス: データベース、API、ライブデータ
  • アクションを実行: ファイル作成、メール送信、システム操作
  • 機能を拡張: カスタム機能で専用ワークフロー実現

MCPアーキテクチャ

MCPの主要コンポーネント

3つの核となる機能

  1. Prompts (プロンプト)

    • 再利用可能なテンプレート
    • 変数を受け取れる動的プロンプト

  2. Tools (ツール)

    • AIが実行できるアクション
    • LLMサンプリング（＝ツール内で生成AIを呼ぶ）と組み合わせ可能

  3. Resources (リソース)

    • 構造化データの提供
    • URIベースのアクセス

MCPユースケース

実践的な活用例

  • データ分析: AIをデータベースや解析システムに接続
  • 自動化: 開発ワークフローをAIで管理
  • ドキュメンテーション: ライブコードからドキュメント生成
  • テスト: AI解析からテストを作成・実行
  • デプロイ: AIによるデプロイ手順の自動化
  • ウェブスクレイピング: インテリジェントなデータ収集
  • API統合: 外部サービスとのブリッジ

簡単なプロンプトを作ってみよう

現在開いているプロジェクトに[simple_prompts_server.py]ファイルを作成し以下の実装をおこなってください。

from mcp.server.fastmcp import FastMCP

# Create the MCP server
mcp = FastMCP("Simple Prompts Server")

@mcp.prompt()
def hello_world(language: str = "python") -> str:
    """プログラミング言語名を受け取り、その言語でHello worldを出力するコードを生成します。"""

    prompt = f"Hello worldを出力する{language}コードを書いてください。"

    return prompt

if __name__ == "__main__":
    mcp.run()

.vscode/mcp.jsonを変更します。

{
  "mcpServers": {
    "learnpython-mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        ".",
        "run",
        "simple_prompts_server.py"
      ]
    }
  }
}

重要

command uvが動作するパスを設定します。ターミナルで'uv -V'を入力しuvコマンドが使える場合は"command":"uv"でも動作します。

実際に動かしてみましょう

Github Copilotウィンドウを表示し、チャットモードを「Agentモード」に変更します。次に先ほど作成したMCPサーバの設定を反映するためにToolの再読み込みを実施します。（反映されない場合はVS Codeを再起動を行ってください。）

チャット欄に以下のコマンドを入力し実行してみてください。

/mcp.learnpython-mcp.hello_world language=[好みのプログラミング言語]

チャット欄に置換されたプロンプトが表示されます。そのまま送信するとCopilotがコードを実装してくれます。

image.png

GUIで実施する場合 GUIで実施する場合は以下の手順に従ってください。

image.png

再読み込みを実施すると、以下のような確認ダイアログが表示される場合があります。信頼するを押して次に進めてください。

image.png

チャットウィンドウで「/」を押して、mcp.learnpython-mcp.hello_worldを選択します。

image.png

上部に入力欄があるので好きなプログラミング言語を入力してください。

image.png

チャット欄に置換されたプロンプトが表示されます。そのまま送信するとCopilotがコードを実装してくれます。

image.png

Part 2: Study Buddy アプリの構築

セクション2.1: Study Buddy アプリとは？

🎓 対話型Python学習アシスタント

初心者〜上級者の開発者がPythonの概念を習得するのを支援する
対話型チュートリアルアプリケーション

主な機能

  • レベル別の演習生成
  • 学習進捗トラッキング
  • ヒントと解答例の提供
  • 学習ストリークの管理

MCP サーバー設定

.vscode/mcp.json の設定

{
  "mcpServers": {
    "learnpython-mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        ".",
        "run",
        "server_part_2.py"
      ]
    }
  }
}

セクション2.2: プロンプトについて学ぶ

プロンプトとは？

再利用可能なテンプレート

プロンプトはAIアシスタントが利用できる事前定義されたメッセージテンプレート

特徴

  • 情報を構造化して保存
  • 動的に変数を受け取れる
  • ユーザーが明示的に呼び出す

プロンプトの実装例

prompts_server.py

prompts_server.py(抜粋)
@mcp.prompt()
def python_topics(level: str = "beginner") -> str:
    """List Python topics based on user experience level."""

    level = level.lower()

    learning_levels = {
        "beginner": "for someone new to programming",
        "intermediate": "for someone with some intermediate programming experience",
        "advanced": "for someone with extensive programming experience",
    }

    prompt = f"generate 5 Python topics {learning_levels[level]}, numbered from most fundamental to most complex. After listing the topics, ask if they'd like to try exercises for any topic (recommend starting with #1)."

    # Return a more direct prompt that's easier for the LLM to follow
    return prompt

プロンプトの使い方

VS Code Copilot Chatで

  1. サーバーを起動: mcp.json を prompts_server.py に設定
  2. Copilot Chatを開く: / をタイプ
  3. プロンプトを選択: mcp.learnpython-mcp.python_topics を探す
  4. 変数を渡す: level=beginner を指定
例: /mcp.learnpython-mcp.python_topics level=Beginner

結果

beginnerレベルのトピックリストが生成されます

プロンプトの学びのポイント

重要な概念

  • 情報の保存: プロンプトは再利用可能な知識として機能
  • 動的な生成: 変数により異なる出力を生成
  • 明示的な呼び出し: ユーザーが意図的に使用
  • 構造化された対話: 一貫性のあるAI応答

セクション2.3: ツールとサンプリング

ツールとは？

🔧 AIが実行できるアクション

ツールはAIアシスタントが実際に何かを実行できるようにする機能

プロンプトとの違い

プロンプト ツール
情報を提供 アクションを実行
読み取り専用 副作用あり
テンプレート 関数実行

サンプリングとは？

ツール内でLLMを呼び出す

サンプリング = ツールの実行中にAIモデルに対してテキスト生成を依頼すること

利点

  • AIの創造性を活用
  • 動的なコンテンツ生成
  • コンテキストに応じた出力

ツールの実装例

tools_server.py

tools_server.py(抜粋)
@mcp.tool()
async def list_exercises() -> str:
    """List all created exercises."""
    
    if not exercises_db:
        return "No exercises yet. Use generate_and_create_exercises first!"
    
    result = []
    for level, exercises in exercises_db.items():
        result.append(f"\n{level.upper()} LEVEL:")
        for i, ex in enumerate(exercises):
            result.append(f"\n{i+1}. {ex.title}")
            result.append(f"   {ex.description}")
            result.append(f"   Hint: {ex.hint}")
            result.append(f"   Difficulty: {ex.difficulty}/5")
    
    return "\n".join(result)

ツール実装: サンプリングの使用

tools_server.py(抜粋)
@mcp.tool()
async def generate_and_create_exercises(
    topic: str, 
    level: str = "beginner",
    ctx: Context = None
) -> str:
    """Generate exercises using sampling and create them automatically."""
    
    try:
        # Get the prompt text
        prompt_text = await generate_exercises(topic, level)

        response = await ctx.session.create_message(
            messages=[
                SamplingMessage(
                    role="user",
                    content=TextContent(type="text", text=prompt_text),
                )
            ],
            max_tokens=2000,
        )

        # Extract the text from the response
        response_text = response.content.text if response.content else ""

        # Parse the generated JSON
        exercises_data = json.loads(response_text)

        # Store exercises
        exercises_db[level] = []
        for ex in exercises_data[level]:
            exercises_db[level].append(Exercise(
                title=ex['title'],
                description=ex['description'],
                hint=ex['hint'],
                solution=ex['solution'],
                difficulty=ex['difficulty']
            ))

        return f"Created {len(exercises_db[level])} exercises on '{topic}' for {level} level"

    except json.JSONDecodeError as e:
        return f"JSON Error: {str(e)}\nResponse was: {response_text[:200]}..."
    except Exception as e:
        return f"Error: {str(e)}"

ツールの使い方

VS Code Copilot Chatで

  1. サーバーを起動: mcp.json を tools_server.py に設定
  2. Copilot Chatを開く: / をタイプ
  3. プロンプトを選択: mcp.learnpython-mcp.generate_and_create_exercises を探す
  4. 変数を渡す: topic=Topic: Pythonの基本構文とデータ型 Level: Beginner Number of exercises: 5 を指定
  5. テンプレートプロンプトが入力されるので送信する
  6. 演習問題を生成しJson形式で保存される
例: /mcp.learnpython-mcp.generate_and_create_exercises topic=Topic: Pythonの基本構文とデータ型 Level: Beginner Number of exercises: 5

Topic: Pythonの基本構文とデータ型
Level: Beginner
Number of exercises: 5

プロセス

  1. ツール呼び出し: Copilotがツールを実行
  2. サンプリング: ツール内でLLMが演習を生成
  3. ファイル保存: 生成された演習をJSONファイルとして保存
  4. 結果返却: 保存されたファイル名のリストを返す

ツールの学びのポイント

重要な概念

  • アクション実行: ツールは実際にファイルを作成したり、データを操作
  • LLMサンプリング: ツール内でAIの生成能力を活用
  • 構造化データ: JSON形式で一貫性のある出力
  • ワークフロー統合: 複数のツールを組み合わせて複雑な処理

セクション2.4: リソースについて学ぶ

リソースとは？

構造化データの提供

リソースはAIアシスタントが読み取れるデータソース

特徴

  • URIベース: 一意の識別子でアクセス
  • 構造化: JSONなどの明確な形式
  • パラメータ化: 動的なリソースパス
  • 読み取り専用: データの提供に特化

リソース vs プロンプト vs ツール

種類 目的 方向 例
プロンプト テンプレート AI→ユーザー 学習トピックリスト
ツール アクション ユーザー→システム 演習生成
リソース データ提供 システム→AI 進捗データ

リソースの実装例

resources_server.py

resources_server.py：(抜粋)
@mcp.resource("user://study-progress/{username}")
async def get_study_progress(username: str) -> str:
    """Get study progress for a user."""
    try:
        # Read study progress from JSON file
        with open(study_progress_file, 'r') as file:
            study_progress = json.load(file)
        
        # Check if the username matches (for this simple example)
        if study_progress.get("user_name") == username:
            return json.dumps(study_progress, indent=2)
        else:
            return json.dumps({
                "error": f"No study progress found for user '{username}'"
            })
    except FileNotFoundError:
        return json.dumps({
            "error": "Study progress file not found"
        })
    except json.JSONDecodeError:
        return json.dumps({
            "error": "Invalid study progress file format"
        })

リソース + サンプリング

@mcp.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_users_progress":
        username = arguments["username"]
        
        # 1. リソースから進捗データを取得
        progress_uri = f"user://study-progress/{username}"
        progress_data = await read_resource(progress_uri)
        
        # 2. LLMサンプリングで分析
        result = await mcp.request_sampling(
            types.CreateMessageRequest(
                messages=[
                    types.SamplingMessage(
                        role="user",
                        content=types.TextContent(
                            type="text",
                            text=f"""
以下の学習進捗データを分析してください:

{progress_data}

以下の点について分析してください:
- 現在の学習レベル
- 完了した演習の数
- 学習の継続性（ストリーク）
- 推奨される次のステップ
"""
                        )
                    )
                ],
                max_tokens=1000
            )
        )

リソースの使い方

Copilot Chatで自動参照

リソースは自動的にAIアシスタントのコンテキストに含まれます

例: "Marleneの進捗状況を教えて"

プロセス

  1. リソース検出: Copilotが関連リソースを特定
  2. データ取得: user://study-progress/Marlene を読み取り
  3. コンテキスト追加: 進捗データをAIのコンテキストに追加
  4. 応答生成: データを基に回答を生成

リソースの学びのポイント

重要な概念

  • 構造化データ: AIに明確なデータを提供
  • URIベース: 一貫性のあるアドレス指定
  • パラメータ化: 動的なリソースパス ({username}, {level})
  • ツールとの統合: リソース + ツール + サンプリングの組み合わせ

セクション2.5: Study Buddy 統合アプリ

最後にこれまでの機能をまとめて動作させることでPython学習アプリとして動作させてみます。

VS Code Copilot Chatで

  1. サーバーを起動: mcp.json を server_part_2.py に設定
  2. Copilot Chatを開く: pythonを学習したい をタイプ
  3. /mcp.learnpython-mcp.python_topicsを実行し、テンプレートプロンプトを実行
  4. 提案されたトピックから好きなものを選ぶ
  5. /mcp.learnpython-mcp.generate_exercisesを実行し、指示された文字を入力する（オプション２は空欄）
  6. テンプレートプロンプトを実行（演習問題がJsonで作成される）
  7. 実施者の名前を入力
  8. "Study buddyをターミナルで開始して"とタイプ

期待される体験

サンプルセッション

🐍 Python Study Buddy

ようこそ、CodeLearnerさん！
beginnerレベルのPython学習を始めましょう。

現在のストリーク: 🔥 0日
完了した演習: ✅ 0個

利用可能なBeginner演習
┌────┬─────────────────┬────────────┬──────────────┐
│ No.│ タイトル         │ 難易度     │ ステータス    │
├────┼─────────────────┼────────────┼──────────────┤
│ 1  │ Hello World     │ ⭐         │ 📝 未着手     │
│ 2  │ 変数と代入      │ ⭐⭐       │ 📝 未着手     │
└────┴─────────────────┴────────────┴──────────────┘

演習を選択してください (番号):

デバッグとトラブルシューティング

よくある問題

1. サーバーが起動しない

  • uv のパスを確認
  • mcp.json の構文エラーをチェック
  • Python環境が有効化されているか確認

2. ツールが表示されない

  • サーバーの再起動
  • VS Codeの再読み込み
  • list_tools() の実装を確認

3. サンプリングが失敗する

  • max_tokens を調整
  • プロンプトの内容を確認
  • エラーログを確認

学んだこと - まとめ

プロンプト

  • 再利用可能なテンプレート
  • 動的な変数サポート
  • 明示的な呼び出し

ツール

  • アクションの実行
  • LLMサンプリングの活用
  • ファイル操作などの副作用

リソース

  • 構造化データの提供
  • URIベースのアクセス
  • ツールとの組み合わせ

次のステップ

さらなる学習

  1. Part 3へ進む

    • AI Research Hub の構築
    • より高度なMCPパターン

  2. 独自のMCPサーバーを作成

    • 自分のユースケースに適用
    • カスタムツールとリソースの実装

リソース

📚 公式ドキュメント

🛠️ ツール

💡 サンプルプロジェクト

ありがとうございました！

Happy Coding with MCP! 🐍✨

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?