Practera MCP Server

Practera MCP サーバー

AI エージェントが Practera の GraphQL API とローカルのプロジェクト概要データに直接アクセスできる MCP（Model Context Protocol）サーバーです。Cursor、Claude Desktop、または任意の MCP クライアントを接続して、学習プログラムの作成、アセスメントの管理、学習者としての課題提出、レビューの実施、Practera モノレポ全体でのテストスイートの実行ができます。

Practera MCP を使う理由

この MCP サーバーを使うと、エージェントは次のことができます。

• 既存のプロジェクトを分析し、対象者や学年に合わせて再構成する
• アセスメントの設計案を作成し、質問を自動生成する
• 教育機関や LMS のデータ形式をまたいでプログラムをインポート／エクスポートする
• アセスメントを提出し、レビューのワークフローを管理する
• スキルを指定して、5,400 件以上の体験学習プロジェクト概要のライブラリを検索する
• Cursor から Practera の全リポジトリでテストスイートを実行する

クイックスタート（Cursor — ローカル開発）

1. このリポジトリを他の Practera リポジトリと並べてクローンします。
2. 依存関係をインストールします：npm install
3. Practera の任意のリポジトリに .cursor/mcp.json を追加します（Cursor の設定を参照）。
4. Cursor の MCP パネルを再読み込みすると、practera サーバーが表示されます。

別途サーバープロセスを起動する必要はありません。Cursor が stdio 経由で MCP サーバーを自動的に起動します。

トランスポート

stdio（Cursor ローカル — 推奨）

Cursor がサブプロセスとしてサーバーを起動します。別途 npm run dev を実行する必要はありません。

# For manual testing / debugging
npm run dev:stdio

SSE（リモート／共有）

複数のクライアントで 1 つのインスタンスを共有する場合に使用する、Server-Sent Events 対応の HTTP サーバーです。

npm run dev        # → http://localhost:3000/sse

MCP クライアントを http://localhost:3000/sse に接続します。

Cursor の設定

リポジトリに .cursor/mcp.json を作成します（または、すべてのワークスペースに適用する場合は ~/.cursor/mcp.json に追加します）。

{
  "mcpServers": {
    "practera": {
      "command": "node",
      "args": [
        "/absolute/path/to/practera-mcp-server/dist/stdio.js"
      ],
      "env": {
        "PRACTERA_REGION": "local",
        "AUTH_EMAIL": "[email protected]",
        "GRAPHQL_URL": "http://localhost:8000",
        "WORKSPACE_ROOT": "/absolute/path/to/practera-workspace"
      }
    }
  }
}

ソースを変更した後は、practera-mcp-server で npm run build を実行し、dist/stdio.js を再ビルドしてください。

本番リージョンでは、AUTH_EMAIL／GRAPHQL_URL を省略し、各ツール呼び出しで apikey を渡してください。

認証

API キー（本番）

各ツール呼び出しで apikey を渡します。キーは apikey HTTP ヘッダーとして GraphQL API に転送されます。

devLogin（ローカル／ステージングのみ）

apikey を省略し、AUTH_EMAIL を設定します（または各ツール呼び出しで email を渡します）。サーバーは devLogin GraphQL ミューテーションを呼び出し、JWT を自動的に取得します。region=local または region=stage の場合にのみ機能します。

利用可能なツール

汎用／読み取り専用

ツール	説明
mcp_practera_get_project	マイルストーン、アクティビティ、タスクを含むプロジェクト全体のツリー
mcp_practera_get_assessment	質問と回答の選択肢を含むアセスメントの詳細
mcp_practera_search_project_briefs	スキルのキーワードでローカルのプロジェクト概要カタログを検索

作成（管理者／コーディネーターのロールが必要）

ツール	GraphQL オペレーション	説明
create_experience	createExperience	教育機関内に新しいプログラムを作成
create_milestone	createMilestone	エクスペリエンスにマイルストーンを追加
create_activity	createActivity	マイルストーンにアクティビティを追加
create_assessment	createAssessment	アクティビティにアセスメントを作成
add_question	createAssessmentQuestion	アセスメントに質問を追加
add_task_to_activity	addTaskToActivity	アクティビティにタスク（リソース／リンク）を追加
enroll_user	enrollUser	ユーザーをエクスペリエンスに登録
import_experience	importExperienceData	JSON エクスポートからエクスペリエンスのコンテンツを一括インポート
export_experience	exportExperience	エクスペリエンスの構造を JSON としてエクスポート

学生（学習者）

ツール	GraphQL オペレーション	説明
list_experiences	experiences	現在のユーザーのすべてのエクスペリエンスを一覧表示
get_milestones	project.milestones	プロジェクトのマイルストーンとアクティビティを取得
get_tasks	tasks(activityId:)	アクティビティのタスクを取得
submit_assessment	submitAssessment	アセスメントを提出
get_feedback	submission(id:)	レビューのフィードバックを含む提出内容の詳細を取得

レビュー担当者

ツール	GraphQL オペレーション	説明
list_pending_reviews	reviews(status: "pending")	レビュー待ちの評価を一覧表示します
submit_review	submitReview	完了したレビューを送信します

テスト

ツール	説明
run_tests	任意の Practera リポジトリでテストスイートを実行します — npm/cargo/docker をシェルから呼び出します

run_tests のパラメーター

パラメーター	必須	説明
repo	はい	対象リポジトリ：core-graphql-api、login-api、app-v2、practera、practera-mcp-server、practera-devops-center
suite	はい	対象のスイート（下の表を参照）
pattern	いいえ	テストファイル／名前のフィルター（Jest の対象では --testPathPattern として渡されます）
workspaceRoot	いいえ	ワークスペースルートの絶対パス。設定されていない場合は WORKSPACE_ROOT 環境変数を使用します。

利用可能なテストスイート

リポジトリ	スイート	コマンド
core-graphql-api	unit	npm test（Jest、カバレッジ付き）
core-graphql-api	integration	npm run test:integration
core-graphql-api	parity	npm run test:parity
login-api	unit	npx vitest run tests/unit
login-api	integration	npx vitest run tests/integration
login-api	full	npm run test:coverage
app-v2	unit	npm test -- --watch=false
practera	phpunit	docker exec practera-core ./vendor/bin/phpunit
practera-mcp-server	typecheck	npm run typecheck
practera-devops-center	cargo	cargo test

MCP リソース

リソース URI	説明
practera://project/current	現在のプロジェクトデータ（GraphQL）
practera://assessments/{assessmentId}	ID で指定した評価
practera://briefs/{briefId}	ローカルカタログのプロジェクト概要

MCP プロンプト

プロンプト	目的
project-analysis	プロジェクトの構造と学習設計の品質を分析します
assessment-analysis	評価の構造と質問の品質を評価します
skill-brief-selection	カタログからスキルに合致する概要を検索します
complex-brief-finder	スキル、複雑さ、期間に基づいて概要を照合します

環境変数

変数	説明
PORT	HTTP ポート（デフォルトは開発環境で 3000、本番環境で 80）
NODE_ENV	環境（development、production）
GRAPHQL_URL	ローカルの GraphQL エンドポイントを上書きします
PRACTERA_REGION	デフォルトのリージョン：local、stage、usa、aus、euk
AUTH_EMAIL	devLogin のデフォルトメールアドレス（local/stage）
WORKSPACE_ROOT	ワークスペースルートの絶対パス — run_tests で使用します

GraphQL リージョン

リージョン	エンドポイント
local	http://localhost:8000（または GRAPHQL_URL）
stage	https://core-graphql-api.p2-stage.practera.com/
usa	https://core-graphql-api.usa.practera.com/
aus	https://core-graphql-api.aus.practera.com/
euk	https://core-graphql-api.euk.practera.com/

ビルドとデプロイ

# Build
npm run build       # compiles TS + copies src/data → dist/

# Run SSE server (compiled)
npm start

# Run stdio (compiled — use in production Cursor config)
npm run start:stdio

AWS App Runner

apprunner.yaml は、ポート 80 で SSE サーバーを実行する App Runner サービスを設定します。

AWS Lambda（古い設定）

serverless.yml は存在しますが、Lambda ハンドラーのエクスポートは現在接続されていません。本番環境へのデプロイには App Runner を使用してください。

ロードマップ

• GraphQL の読み取りアクセス（プロジェクト、評価）
• 作成者向け CRUD ツール（エクスペリエンス、マイルストーン、アクティビティ、評価、質問、タスクの作成、登録）
• エクスペリエンス JSON のインポート／エクスポート
• 学生向けツール（一覧表示、提出、フィードバック）
• レビュアー向けツール（保留中の項目の一覧表示、レビューの提出）
• プロジェクト概要の検索（5,400 件以上の概要、スキルベース）
• Cursor 連携用の stdio トランスポート
• リポジトリをまたいだテスト実行用の run_tests ツール
• Metrics API（calculateMetrics から LLM が読み取り可能なレポートを生成）
• OAuth 2.1（現在は骨組みのみで、無効）
• MCP リソースに認証コンテキストを引き継ぐ
• レビューワークフロー管理用の assign_reviewer、handle_review ツール
• メディアアセットの生成

ライセンス

MIT