Study Assistant

シラバス文書を検索可能な学習ナレッジベースに変換するローカル Model Context Protocol (MCP) サーバーです。サーバーは files/ementas から文書を読み取り、テキストを抽出し、Genkit と Ollama Cloud を使用して要約と構造化された詳細を生成します。

アーキテクチャ

このリポジトリは pnpm モノレポです。mcp パッケージには Express と MCP サーバーが含まれており、files/ementas はツールに公開される唯一の文書ディレクトリです。

サーバーは 127.0.0.1 にバインドし、以下を公開します:

• GET /health: シークレットやプロバイダー情報を含まないプロセスヘルス。

• /mcp: ステートレスな MCP Streamable HTTP エンドポイント。

• list_ementas: サポートされているファイルをメタデータとキャッシュされた要約とともに一覧表示します。

• get_ementa: 抽出されたテキストと構造化されたシラバス詳細を返します。

サポートされている形式は PDF、DOCX、Markdown、プレーンテキストです。シンボリックリンク、パス、およびサポートされていない拡張子は拒否されます。

Related MCP server: Educational Tutor MCP Server

要件

• Node.js 20 以降。

• pnpm 10 (Corepack で固定バージョンを提供できます)。

• Ollama Cloud API キー。

セットアップ

リポジトリのルートから依存関係をインストールします:

corepack pnpm install

mcp/.env.example をリポジトリルートの .env または mcp/.env にコピーし、API キーを指定します:

OLLAMA_API_KEY=your-key

デフォルトのモデルは gpt-oss:120b です。オプション設定は次のとおりです:

OLLAMA_MODEL=gpt-oss:120b
OLLAMA_BASE_URL=https://ollama.com
OLLAMA_TIMEOUT_MS=60000
MCP_PORT=3000

環境ファイルは Git によって無視されます。API キーをコミットしないでください。

アプリケーションは、pnpm がパッケージを起動するディレクトリに関係なく、両方の場所を明示的に解決します。既存のシステム環境変数が優先されます。両方のファイルが同じ変数を定義している場合、mcp/.env がルートの .env よりも優先されます。

シラバスファイルを files/ementas 内に直接配置し、開発サーバーを起動します:

corepack pnpm dev

MCP エンドポイントは http://127.0.0.1:3000/mcp で利用可能になります。

Codex に接続

サーバーが実行されている状態で、ローカルの Codex クライアントにその URL を登録します:

codex mcp add studyAssistant --url http://127.0.0.1:3000/mcp

同等の Codex 設定:

[mcp_servers.studyAssistant]
url = "http://127.0.0.1:3000/mcp"

この localhost エンドポイントはローカルの Codex クライアント向けです。リモートの ChatGPT クライアントには公開されません。

コマンド

リポジトリのルートから次のコマンドを実行します:

corepack pnpm dev       # Watch and run the TypeScript server
corepack pnpm build     # Build the production JavaScript
corepack pnpm start     # Run the compiled server
corepack pnpm typecheck # Check strict TypeScript types
corepack pnpm lint      # Run ESLint
corepack pnpm test      # Run the Vitest suite

dev と build はテストスイートを実行しません。本番コンパイルでも src/__tests__ は除外されるため、テストフィクスチャとモックはサーバーに読み込まれたり、dist に出力されたりすることはありません。

生成された分析は .cache/ementas.json に保存されます。キャッシュエントリは、ドキュメントのサイズまたは変更時刻が変更されたときに無効になります。有効なキャッシュ結果は、Ollama Cloud が一時的に利用できない場合でも使用可能です。

セキュリティと障害時の動作

API キーは環境から読み込まれ、Ollama の認証ヘッダーでのみ送信されます。ヘルスレスポンス、MCP レスポンス、アプリケーションログには含まれません。クラウドリクエストはタイムアウトを使用し、一時的な 429、500、502 の失敗を再試行します。1 つのファイルの失敗は list_ementas で分離されます。get_ementa は MCP ツールエラーを報告します。