AI学生開発者アシスタント — MCP Server

本番品質のModel Context Protocolサーバー。AIアシスタントに、GitHubのIssue、学業の締め切り（LMS）、個人用タスクトラッカーへの統一アクセスを提供し、*「今日は何をすべき？」*といった質問に対して、実際に優先順位付けされた回答を返せるようにします。

Python 3.12+、公式MCP Python SDK (v2)、FastAPIスタイルのサービス分離、SQLite、httpxで構築。モック化された外部APIで完全にテストされており、スイートの実行に実際の認証情報は不要です。

目次

• プロジェクト概要

• 機能 — MCPツール

• アーキテクチャ

• 技術スタック

• インストール

• 設定

• サーバーの実行

• AIクライアントの接続

• 使用例

• API統合

• データベース

• テスト

• セキュリティ

• 制限事項

• 今後の改善

• プロジェクトアーキテクチャ

• デモシナリオ

• 面接でのトークポイント

プロジェクト概要

問題. 学生開発者の作業は、GitHubのコードタスク、大学LMSの課題と試験、ノートに散らばった個人的なToDoという、互いに接続されていない3つの場所に存在します。優先順位は記憶に基づいて決められるため、物事が漏れてしまいます。

解決策. 3つのソースすべてを、小さく明確に記述され、強い型付けされたツールとして公開する1つのMCPサーバー。AIアシスタントはそれらすべてを一度に読み取って推論できます：割り当てられたIssue、今週の締め切り、保留中のタスクを取得し、期限切れ項目を検出し、優先順位付きのサマリーを構築できます。さらに、同じインターフェースでシステムを変更（Issueの作成/クローズ、タスクの作成、締め切りの一括インポート）できます。

ステータス. これは個人用生産性ツールのポートフォリオ品質の実装です。すべてがエンドツーエンドで動作します。LMS統合は、交換可能なインターフェースの背後で意図的にモックされています（制限事項を参照）。

機能 — MCPツール

15個の狭い範囲に特化したツール。それぞれに明確な名前、AIが呼び出しタイミングを判断するための説明、検証済みの入力、予測可能な出力があります：

GitHub（4ツール）

LMS / 学業の締め切り（3ツール）

タスクトラッカー（8ツール）

すべてのツールは同じJSON形式を返すため、エージェントは結果を確実に解析できます：

{ "ok": true,  "data": { "...": "..." }, "error": null }
{ "ok": false, "data": null, "error": { "code": "not_found", "message": "..." } }

アーキテクチャ

flowchart TB
    subgraph Host["AI Client (e.g. Claude Desktop)"]
        Agent["Assistant / Agent"]
    end
    subgraph MCP["MCP Protocol (stdio)"]
        S["MCPServer (mcp SDK v2)"]
    end
    subgraph App["app/"]
        Tools["tools/ · 15 thin tool functions"]
        Services["services/ · GitHub · LMS · Task"]
        Repo["TaskRepository"]
        DB[("SQLite")]
        Mock["MockLMSService"]
    end
    Ext["GitHub REST API v3"]
    Agent -->|tools/list · tools/call · server/discover| S
    S --> Tools
    Tools --> Services --> Repo --> DB
    Services --> Ext
    Services --> Mock

このコードベースの黄金律： MCPレイヤーは単なるアダプターです。各ツール関数は、型シグネチャを介して入力を検証し、サービスを呼び出し、結果をレンダリングします。ビジネスロジックはツール関数には存在しません。

技術スタック

インストール

要件：Python 3.12+とgit。（MCP SDK自体は≥3.10を必要としますが、このプロジェクトは3.12を対象としています。）

Windows（PowerShell）

cd "C:\Users\ASUS\mcp project"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Activate.ps1が実行ポリシーによってブロックされている場合：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

macOS / Linux

cd mcp-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

設定

プレースホルダーファイルをコピーして、値を記入してください：

cp .env.example .env     # Windows:  copy .env.example .env

GitHubトークンの作成 → GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token → 必要なリポジトリのみを選択 → Issues: Read and Writeのみを許可。

⚠️ .envはgit無視されています。絶対にコミットしないでください。.env.exampleにはプレースホルダーしか含まれていません。

サーバーの実行

1. データベースを初期化し、デモデータを投入する

python -m scripts.seed_demo

これによりdata/tasks.dbが作成され、いくつかの現実的なデモタスク（1つは意図的に期限切れ）が挿入されます。

2. MCPサーバーを実行する

python -m app.server

サーバーはstdio（デスクトップMCPクライアントのデフォルト）で起動し、停止するまで実行され続けます。

開発とデバッグ

SDKにはCLIと対話型インスペクターが同梱されています：

mcp dev app/server.py        # launch + open the MCP Inspector in a browser
mcp run app/server.py        # run the server (same behavior as python -m app.server)

AIクライアントの接続

ローカルMCPサーバーはstdio上で実行されます。AIクライアントがサーバープロセスを起動し、stdin/stdoutを介して通信します。設定形式はクライアントのmcpServersブロックです。

Claude Desktop（Windows）

%APPDATA%\Claude\claude_desktop_config.jsonを編集し（Settings → Developer → Edit Configから開く）、完全に終了して再起動します：

{
  "mcpServers": {
    "ai-student-assistant": {
      "command": "C:\\Users\\ASUS\\mcp project\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\ASUS\\mcp project\\app\\server.py"]
    }
  }
}

要件：

• 絶対パス — Claude DesktopはシェルのPATHや作業ディレクトリを引き継ぎません。

• where python / where gitを使用して、正確なインタープリターパスを確認してください。

• 保存後、Claude Desktopを完全に再起動し、コネクタ/メッセージボックスメニューでサーバーとそのツールを探してください。

• 失敗した場合のログ：%APPDATA%\Claude\logs\mcp*.log。

代替手段

• MCP Inspector（設定不要）：mcp dev app/server.pyで、すべてのツールを手動で呼び出すためのGUIが提供されます。デモに最適です。

• Cursor — .cursor/mcp.jsonは同一のmcpServers形式を使用します。

• サーバーはトランスポート非依存です。同じMCPServerを後でStreamable HTTP経由で提供できます（今後の改善を参照）。

使用例

ユーザー: 現在オープンしているGitHub Issueは何ですか？

エージェントはget_open_issuesを呼び出し（リポジトリなし → 自分に割り当てられたIssue）、次のように要約します：

あなたに割り当てられたオープンIssueが2件あります：「Fix login bug」（#1、bug）と「Add CI pipeline」（#2）。

ユーザー: 今後7日以内に期限が来る課題は何ですか？

エージェントは今日から計算したstart/endを指定してget_upcoming_deadlinesを呼び出します：

今週の期限：Quiz 3（Math、Aug 12）、Project Proposal Draft（ENG101、Aug 11）、Graph Traversal Assignment（CS101、Aug 13）。

ユーザー: それらの課題のタスクを作成してください。

API統合

GitHub REST API

すべてのGitHubツールは、共有httpxクライアントを使用してREST APIを呼び出します。Authorization: Bearer <token>ヘッダーとAccept: application/vnd.github+jsonヘッダーを追加します。get_open_issuesではページネーションが処理されます（1ページ100件、最大MAX_RESULTS件）。レート制限エラーと検証エラーは、型付き例外に変換され、ツールレイヤーが読みやすいエラーメッセージとしてレンダリングします。

LMSモックプロバイダー

モックプロバイダーは、「今日」に近い日付を持つ小さなJSONストアで、デモには常に表示するデータがあります。実際のLMSクライアントが実装するのと同じインターフェースを実装しているため、後で実際の統合に交換できます。

タスクストア

タスクストアはSQLAlchemyを介したSQLiteです。実行時に必要な唯一のコンポーネントです。GitHubとLMSはオプションです（モックを提供）。

データベース

データベースはSQLiteで、デフォルトではdata/tasks.dbに保存されます（DATABASE_PATHで設定可能）。SQLAlchemy 2.0の宣言型ORMを使用し、スキーマはdb/models.pyで定義されています。

スキーマ概要

スキーマはstatusとpriorityにCHECK制約、(issue_id) WHERE issue_id IS NOT NULLの部分一意インデックス、および(assignment_id) WHERE assignment_id IS NOT NULLの部分一意インデックスを使用します。外部キーはPRAGMA foreign_keys=ONで強制されます。

テスト

フルスイートを実行します：

pytest

テストスイートは、インメモリClient(server)を介したツール呼び出し、respxを使用したGitHubサービス層、一時SQLiteデータベースを使用したタスクサービスをカバーします。すべての外部APIはモックされており、実際の認証情報は不要です。

セキュリティ

• GitHubトークンは環境変数から読み取られ、ログに記録されることはありません。

• サーバーはローカルで実行され、デフォルトではネットワークポートを開きません。

• SQLiteファイルの権限はOSのデフォルトです。マルチユーザーシステムでは、ファイルへのアクセスを制限してください。

• PIIは収集されません。サーバーは設定したデータのみを保存します。

制限事項

• LMSはモックであり、実際の統合ではありません。

• GitHub APIはIssueの読み書きに対応していますが、PRや他のリソースには対応していません。

• タスクトラッカーはシングルユーザーです（認証なし、共有なし）。

• SQLiteは複数プロセスによる同時書き込み向けに設計されていません。

今後の改善

• LMSモックを、同じインターフェースの背後にある実際のプロバイダー（Canvas、Moodle）に置き換える。

• リモートアクセス用にStreamable HTTP経由でMCPサーバーを提供する。

• GitHubトークンのOAuthフローを追加する。

• ワークロードサマリーを使用する自然言語プランナーを追加する。

• サーバーをデスクトップアプリとしてパッケージ化する。

プロジェクトアーキテクチャ

リポジトリは3つの論理レイヤーに分かれています：

• tools/ — MCPアダプター：各ファイルがClaudeツール呼び出しをサービスにマッピングします。

• services/ — ビジネスロジック：GitHub REST呼び出し、LMSモック、タスクCRUD。

• db/ — SQLAlchemyモデルとセッション管理。

テストはtests/にあり、インメモリMCPクライアントを使用します。

デモシナリオ

デモでは、AIアシスタントに「今日は何をすべき？」と尋ねます。アシスタントはget_workload_summaryを呼び出し、オープンIssue、今日/今週の締め切り、期限切れタスクを含む統合スナップショットを取得します。次に、保留中の項目を優先順位付けし、GitHub Issueからタスクを作成するか、締め切りをタスクとして追加することを提案するかもしれません。

面接でのトークポイント

• MCPツール設計: 各ツールは単一責任を持ち、型付き入力と予測可能な出力を持ちます。

• テスト容易性: 外部APIをモックすることで、CIで決定的なテストが可能になります。

• サービス分離: ビジネスロジックをMCPレイヤーから分離することで、ツールを追加してもコアが安定します。

• 重複安全な統合: create_task_from_issueとcreate_tasks_from_deadlinesは、冪等インポートを保証します。

• 拡張性: LMSプロバイダーはモックから実際のAPIに交換でき、サーバーは後でStreamable HTTPに移行できます。

エージェントがcreate_tasks_from_deadlinesを呼び出します（サーバーはすでにsource/source_idの重複排除を処理しているため、再実行しても重複は発生しません）：

3件のタスクを作成しました。スキップされたタスク：0件（重複なし）。

ユーザー： どのタスクから優先して作業すべきですか？

エージェントがget_workload_summaryとget_overdue_tasksを呼び出し、優先度と期限に基づいて判断します：

最初：「CIパイプラインの不安定なテストを修正」（期限切れ、高優先度）。次に：プロジェクト提案書（明日期限）、クイズ3（2日後期限）…

API統合

GitHub

• エンドポイント： GET /issues（自分に割り当てられたもの）、GET|POST /repos/{owner}/{repo}/issues、GET|PATCH /repos/{owner}/{repo}/issues/{number}。

• 認証： Authorization: Bearer <GITHUB_TOKEN>。パブリックリポジトリでは匿名アクセスが許可されていますが、401エラーが発生した場合は明確な「認証が必要です」エラーが返されます。

• レート制限： x-ratelimit-remaining: 0を含む403エラーと429エラーは、rate_limitedエラーにマッピングされます。

• プルリクエスト： issuesエンドポイントはPRも返しますが、pull_requestキーによってフィルタリングされます。

• すべてのネットワーク/タイムアウト/エラー状態は、ドメイン例外に変換されます（セキュリティを参照）。

LMS

このプロジェクトでは、正当な/アクセス可能な大学LMS APIは想定されていなかったため、LMSは小さなインターフェース（LMSService）の背後にあり、現実的なモック実装（MockLMSService）を使用しています。このモックは：

• 今日からの相対的な期限を持つコースカタログをシードし、

• コースを検証し（未知のコース→not_found）、

• 日付と範囲を検証します（不正な入力→invalid_input）。

後で実際のプロバイダーを追加する場合：同じインターフェースを実装し、LMS_PROVIDER=realを設定します。保護されたページはスクレイピングされていません。認証をバイパスするものは何もありません。 モックは実際のサービスのように動作するため、アプリケーションの残りの部分は変更なしでテストできます。

データベース

DATABASE_PATH（デフォルトはdata/tasks.db）にあるSQLiteファイル、MVPでは1つのテーブル：

CREATE TABLE tasks (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    title       TEXT    NOT NULL,
    description TEXT,
    status      TEXT    NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','completed')),
    priority    TEXT    NOT NULL DEFAULT 'medium'
                    CHECK (priority IN ('low','medium','high','urgent')),
    due_date    TEXT,                      -- ISO-8601 (date or timestamp)
    source      TEXT,                      -- 'github' | 'lms' | NULL
    source_id   TEXT,                      -- e.g. GitHub issue number
    source_url  TEXT,
    created_at  TEXT NOT NULL,
    updated_at  TEXT NOT NULL
);

CREATE INDEX idx_tasks_status    ON tasks(status);
CREATE INDEX idx_tasks_due_date  ON tasks(due_date);
CREATE INDEX idx_tasks_priority  ON tasks(priority, due_date);

CREATE UNIQUE INDEX uq_tasks_source ON tasks(source, source_id)
    WHERE source IS NOT NULL AND source_id IS NOT NULL;

各決定の重要性：

• (source, source_id)に対する部分ユニークインデックス — SQLiteは通常のUNIQUEではNULLを異なる値として扱うため、重複インポートを許容し、複数の「個人用」（ソースなし）タスクを禁止してしまいます。WHERE source IS NOT NULLの部分インデックスにより、まさにデータベース層でインポートを冪等にします。これにより、create_task_from_issue / create_tasks_from_deadlinesを繰り返し安全に呼び出すことができます。

• status/priorityをTEXT + CHECKとして — SQLiteには列挙型がありません。CHECKは整合性を提供し、Pythonのenum.Enumが型安全性のために値をミラーリングします。

• ISO-8601 UTCタイムスタンプをソート可能な文字列として — 辞書順序は時系列順序と等しく、タイムゾーンの曖昧さがなく、JSONに適しています。

• source + source_id + source_url は、タスクが常にその発信元のIssueまたは課題に遡れるように、来歴を保持します。

テスト

pytest          # runs the whole suite: mocked GitHub, mock LMS, SQLite tasks, MCP client

スコープ（tests/）：

MCPツールは、SDKのインメモリクライアント（async with Client(server)）を使用して実際のプロトコル接続に対してテストされます — FastAPIのTestClientと同じパターンです。サブプロセス、ポート、認証情報は不要です。

セキュリティ

• シークレットは環境変数にのみ存在します（.envはgitignoreされ、.env.exampleにはプレースホルダーがあります）。

• 最小権限： 特定のリポジトリに対してIssuesの読み取りおよび書き込みのみに制限された、きめ細かいGitHub PAT — 完全なrepoスコープは使用しません。

• シークレットのログ記録なし： 編集フィルターがログからAuthorizationの値を削除します。また、サーバーはstdoutに何も出力しないため（ログはstderrに出力されます）、stdioプロトコルストリームはクリーンな状態を保ちます。

• 入力検証： ツール境界でのPydantic + サービス内でのドメイン検証。

• パラメータ化されたSQL（SQLAlchemy経由） — 文字列連結によるクエリはありません。

• 制御されたエラー公開： AIは構造化エラー（code、message）を受け取ります。生のスタックトレースはサーバーログにのみ出力されます。

• 最小限のクライアント公開： .envトークンはサーバープロセスによって読み取られ、クライアント設定を介して渡されることはありません。

インタビュートーキングポイントのインタビューに焦点を当てた議論も参照してください。

制限事項

意図的に正直な注意事項：

• LMSはモックです。 LMS_PROVIDER=mockが唯一のプロバイダーです。実際のAPIアダプター、エクスポートされたカレンダー、またはその他の認可されたデータソースを追加して置き換える必要があります（LMSServiceインターフェースを介して交換可能）。

• SQLiteはシングルユーザーです。 並行性の保証、ネットワークアクセス、バックエンドレプリケーションはありません。個人アシスタントとして意図的に設計されています。

• まだOAuth / HTTPトランスポートはありません。 GitHubトークンは静的なシークレットです。サーバーはstdio上で実行されます。ローカルでの個人使用には適していますが、リモート/ホステッドでの使用にはOAuthとStreamable HTTPが必要になります。

• Issue作成は、本文のMarkdownの明示的な割り当てや指定をサポートしていません（自由テキストのみ） — 意図的に小さく保たれています。

• 期限の粒度は時間単位 — タイムゾーン変換はありません。日付はユーザーが指定したISO-8601形式で比較されます。

• インポートは、変更可能なソースアイテムをスナップショットとして記述します：GitHub Issueが後で編集された場合でも、既に作成されたタスクは更新されません（バグではなく、設計上の動作です）。

将来の改善点

• 実際のLMSServiceアダプター（公式APIまたは.icsカレンダーエクスポート）

• Googleカレンダー統合（期限管理）

• Slack/Teams通知（期限切れタスク）

• PostgreSQLバックエンド（リポジトリはすでにこれを抽象化しています）

• GitHubのOAuth + Streamable HTTPトランスポート + Dockerデプロイメント

• タスク履歴/監査テーブル、Issue更新のタスクへの再同期

• よりリッチなエージェントワークフロー（自動トリアージ、週次「スタンドアップ」レポートリソース）

プロジェクトアーキテクチャ

依存関係の順に並んだレイヤー：

app/tools       MCP adapters — type-hinted params, docstrings as descriptions, guard() → {ok, data, error}
app/services    GitHubService · LMSService (mock) · TaskService — business logic + cross-service workflows
app/database    Database (engine/session) · TaskRepository (all SQL)
app/models      SQLAlchemy ORM (Task) · Pydantic schemas (TaskCreate/Out, GitHubIssue, Deadline)
app/config.py   validated env config
app/exceptions  domain error hierarchy → AI-readable codes

依存性注入： app/server.pyがコンポジションルートです — 設定→データベース→サービス→MCPServerを構築し、必要なサービスでツール関数を登録します。グローバルなものはありません。テストでは、同じグラフをフェイクで組み立てます。

エラーフロー： ツール→サービス→リポジトリ/APIがStudentAssistantErrorを発生させる→guard()が{ok: false, error: {code, message}}をレンダリングします。予期しない例外はログに記録され（stderr）、汎用的なinternal_errorメッセージとして返されます。

デモシナリオ

1. きめ細かいGitHubトークンを作成し、.envにGITHUB_TOKENを設定します。

2. タスクデータベースをシード：python -m scripts.seed_demo（いくつかのタスクを作成し、1つは期限切れ）。

3. サーバーを起動：python -m app.server（またはmcp dev app/server.pyでインスペクターを起動）。

4. Claude Desktop / インスペクターをサーバーに接続します。

5. 質問：「今週取り組むべきことは何ですか？」 → エージェントがget_workload_summaryを呼び出し、オープンなGitHub Issue + 今後の期限 + 保留中/期限切れのタスクを組み合わせて、優先順位付けされた回答を提供します。

6. 質問：「今週期限のすべての課題のタスクを作成してください。」 → エージェントがcreate_tasks_from_deadlinesを呼び出します。

7. データベースで確認：

   sqlite3 data/tasks.db "SELECT title, due_date, source FROM tasks ORDER BY due_date;"

   → source = 'lms'の新しい行が、期限ごとに1つ表示されます。同じ質問を再実行すると、ツールは重複する代わりにskippedを報告します。

インタビュートーキングポイント

以下の決定事項について説明できるように準備してください：

1. なぜMCPなのか？ 標準化されたプロトコルであるため、1つのサーバーがあらゆるAIクライアントで動作します。ツールは発見され（tools/list）、呼び出され（tools/call）、モデルに説明されます。名前と説明はLLMのUX契約です。

2. なぜ現在のMCP SDK v2なのか？ SDKはFastMCPをMCPServerに改名し、1つのプロセスで2025年と2026-07-28の両方のプロトコルリビジョンを提供するようになりました。pip install mcpでv2がインストールされます。保守されているライン（v1メンテナンスではない）で構築することは、弁護可能な選択です。

3. 薄いMCP層 / サービス層。 ツール関数はアダプターです。ロジックはインターフェースの背後にあるサービスに存在します。これにより、GitHub、LMS、タスクがネットワークなしでプラグイン可能かつテスト可能になります。

4. 冪等性のための部分ユニークインデックス。 SQLiteが(source, source_id)に部分インデックスを必要とする理由と、それがどのようにcreate_task_from_issue/create_tasks_from_deadlinesを、SQLの深さを示す小さな理にかなったデモとして安全にするのかを説明します。

5. GitHub 403のあいまいさ。 禁止 vs. レート制限は、x-ratelimit-remainingレスポンスヘッダーを介して明確に区別されます — 実際のAPI統合の微妙な点であり、伝説ではありません。

6. 最小権限トークン。 きめ細かいPATでIssues: Read & Writeのみ vs. 従来のrepoスコープトークン。「なぜ」を熟知しておいてください。

7. エラータクソノミー。 安定したAI可読コードにマッピングされた1つの例外階層。スタックトレースはログに限定されます。信頼性は後付けではなく、設計目標です。

8. プロトコル層のテスト。 インメモリClient(server)により、MCPの配線がクライアントが使用するのとまったく同じ方法でテストされます。

9. 正直なスコーピング。 LMSは明示的にモックされています。SQLiteはシングルユーザーです — 「個人の生産性ツール」であり、エンタープライズマルチユーザー製品を謳うものではありません。

ライセンス

MIT — LICENSEを参照。Copyright (c) 2026 Mahendra Vattikuti。