Populi

populi-mcp

Populi API v2 用の MCP サーバーです。Claude、Codex、Cursor、その他の Model Context Protocol クライアントから、Populi インスタンスの人物、入学、学務、請求データを検索できます。また、オプトインすると変更も行えます。

パッケージ： npm の @kisasa/populi-mcp。 コマンド： populi-mcp。 トランスポート： stdio。

動作の仕組み

Populi の API には、180 のモデルにわたって 697 のルートがあります。各ルートを個別のツールとして公開するとモデルのコンテキストを圧迫するため、このサーバーでは少数のツールセットと API リファレンス自体をモデルに提供します。

ツール	機能
populi_search_api	同梱のルートカタログ（applications、invoice、enrollments など）をキーワード検索します。
populi_describe_api	1 つのルートの完全なリファレンスを表示します。パス ID、型付きの必須フィールドと任意フィールド、expand オプション、フィルター条件、必要な Populi ロール、ドキュメントへのリンクが含まれます。
populi_get	任意のルートに GET リクエストを送信します。filter、expand、page、limit、およびすべてのページを 1 つのリストにまとめる all_pages に対応しています。
populi_download	ルートに GET リクエストを送信し、レスポンスを返す代わりにファイルに保存します。PDF／XLS／CSV エクスポート、成績証明書、Data Slicer の結果、ファイルやバックアップのダウンロード、および大きなエクスポートを会話に含めずに保存する場合に使用します。
populi_find_people	メールアドレスの完全一致および／または名前で人物を検索します。
populi_status	インスタンス、キーの種類（サンドボックスまたはライブ）、書き込みの有効状態、ファイルフォルダー、タイムアウトを表示します。verify: true を指定すると、キーを確認するためにライブリクエストを 1 回送信します。
populi_write	マルチパートのファイルアップロードを含め、任意のルートに POST／PUT／DELETE を送信します。POPULI_ALLOW_WRITES=true の場合にのみ利用できます。

これらを組み合わせることで、ドキュメント化された 492 の GET ルートすべて、205 の書き込みルート、ファイルのアップロードとダウンロードを含む API 全体に対応します。ツールは任意のパスを受け取るため、同梱のカタログにないルートも使用できます。

一般的なやり取りでは、モデルがルートを検索してパラメーターを確認し、サーバー側のフィルターを指定して populi_get を呼び出します。

カタログは公開 API ドキュメントから生成され、パッケージに同梱されています。そのため、検索と説明はオフラインで動作し、API リクエストも発生しません。

設定

変数	必須	説明
POPULI_BASE_URL	はい	インスタンスの URL です。例：https://yourschool.populiweb.com。末尾の /api2 は付けても付けなくてもかまいません。https が必須です。
POPULI_API_KEY	はい	API キートークンです。Populi で Account & Settings > API > Keys（Account Administrator）から取得します。ベアラートークンとして POPULI_BASE_URL にのみ送信されます。
POPULI_ALLOW_WRITES	いいえ	true に設定すると populi_write が有効になります。デフォルトは読み取り専用です。
POPULI_FILES_DIR	いいえ	ダウンロードの保存先およびアップロード元となる唯一のフォルダーです。デフォルトは ~/populi-mcp-files です。
POPULI_TIMEOUT_MS	いいえ	Populi リクエスト 1 回あたりのタイムアウト時間です。1000～600000 を指定します。デフォルトは 120000（2 分）です。各呼び出しで timeout_ms を指定することもできます。

キーの Populi ロールによって、アクセスできる範囲が決まります。キーでアクセスできないルートは、問題の内容を示す 403 を返します。populi_describe_api には、各ルートで必要なロールが記載されています。

まずはサンドボックスを使用

Populi は、サンドボックスインスタンスでのみ使用できる sk_sandbox_... キーを個別に発行します（ライブキーはライブ環境でのみ使用できます）。評価中は、このサーバーをサンドボックスに接続してください。

デフォルトは読み取り専用

POPULI_ALLOW_WRITES を設定しない場合、書き込みツールは登録されないため、モデルは変更を試みることさえできません。有効にすると、populi_write は破壊的操作としてマークされるため、承認を求めるクライアントは呼び出しのたびに確認します。Populi の DELETE は取り消せません。

インストール

Node.js 20 以降が必要です。以下のクライアントはすべて npx -y @kisasa/populi-mcp を実行するため、手動でインストールする必要はありません。

Claude Code

claude mcp add populi \
  -e POPULI_BASE_URL=https://yourschool.populiweb.com \
  -e POPULI_API_KEY=sk_sandbox_... \
  -- npx -y @kisasa/populi-mcp

Claude Desktop

claude_desktop_config.json を編集します（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。

{
  "mcpServers": {
    "populi": {
      "command": "npx",
      "args": ["-y", "@kisasa/populi-mcp"],
      "env": {
        "POPULI_BASE_URL": "https://yourschool.populiweb.com",
        "POPULI_API_KEY": "sk_sandbox_..."
      }
    }
  }
}

Windows で Claude Desktop が npx を見つけられない場合は、"command": "cmd" を使い、"args": ["/c", "npx", "-y", "@kisasa/populi-mcp"] を指定します。

Codex

codex mcp add populi \
  --env POPULI_BASE_URL=https://yourschool.populiweb.com \
  --env POPULI_API_KEY=sk_sandbox_... \
  -- npx -y @kisasa/populi-mcp

または、~/.codex/config.toml に記述します。

[mcp_servers.populi]
command = "npx"
args = ["-y", "@kisasa/populi-mcp"]

[mcp_servers.populi.env]
POPULI_BASE_URL = "https://yourschool.populiweb.com"
POPULI_API_KEY = "sk_sandbox_..."

Cursor

.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）に記述します。Cursor は ${env:NAME} を展開するため、キーをファイルに含めずに済みます。

{
  "mcpServers": {
    "populi": {
      "command": "npx",
      "args": ["-y", "@kisasa/populi-mcp"],
      "env": {
        "POPULI_BASE_URL": "https://yourschool.populiweb.com",
        "POPULI_API_KEY": "${env:POPULI_API_KEY}"
      }
    }
  }
}

その他の MCP クライアント

環境変数 POPULI_BASE_URL と POPULI_API_KEY を設定して、npx -y @kisasa/populi-mcp を stdio サーバーとして実行します。

複数のインスタンス

異なる名前（populi-sandbox、populi-live）でインスタンスごとにエントリを追加し、それぞれに独自のキーを設定します。

知っておくと便利な API の動作

• レート制限。 PST の午前3時から午後7時まではキーごとに毎分50リクエスト、夜間は毎分100リクエストで、さらに IP ごと、学校ごとの制限もあります。HTTP 429 の場合、呼び出しは待機時間を示すエラーを返します。その後の呼び出しは、制限中のキーにリクエストを送り続けるのではなく、残りの待機時間を示してすぐに失敗します。フィルターなしの呼び出しを何度も行うより、フィルターを使った呼び出しを1回行うことをおすすめします。
• リクエストは一度に1つ。 Populi では、一度に実行できる「負荷の大きい」呼び出し（Data Slicer、大規模なエクスポートなど）は1つだけです。そのため、クライアントが複数のリクエストを並行して送信しても、サーバーは順番に処理します。
• ページ。 リストが返すレコードは最大200件です。all_pages は最大500ページまでページをたどり、max_records（デフォルトは500、最大1,000,000件）に達すると停止します。上限を超えるページも全件が含まれるため、データが欠落することはありません。結果には処理がcompleteしたかどうかが示され、未完了の場合は再開に使えるnext_pageが返されます。途中でレート制限またはタイムアウトが発生した場合でも、すでに取得したページは破棄されずに返されます。
• フィルター。 Populi は認識できないフィルターフィールド名を無視し、「全員が一致する」ように見えるリスト全体を返します。populi_describe_api はルートで有効な条件名を一覧表示します。populi_find_people は人物検索に適切な条件名を使用します。
• GET パラメーター。 filter、expand、page、limit はparametersクエリ値で送信されます。ほとんどの HTTP クライアントは GET の本文を送信できないためです。これによって URL が約7 KBを超える場合（たとえば、数千件の ID を含むフィルターなど）、代わりに JSON 本文を付けたGETとしてリクエストを送信します。これは Populi のドキュメントで通常形式とされている方法です。POST／PUT／DELETEでは JSON 本文を送信します。
• 大きなレスポンスは、max_chars（デフォルトは40,000、最大1,000,000文字）で切り詰められ、リクエストを絞り込む方法についての注記が付加されます。内容全体をファイルに保存するには、代わりにpopuli_downloadを使用してください。
• ファイルのダウンロード。 ファイルを返すルート（PDF／XLS／CSV のエクスポート、成績証明書、Data Slicer の結果、ファイルのダウンロード）にはpopuli_downloadを使用して取得し、files フォルダーに書き込みます。既存のファイルは上書きせず、名前に-1、-2などを付けます。また、パスではなく名前だけを使用するため、フォルダー外に書き込むことはできません。populi_getはファイルレスポンスの内容を説明しますが、ファイル自体は表示できません。
• ファイルのアップロード。 populi_writeはfilesを受け取り、各項目には files フォルダー内のpathまたはcontent_base64を指定できます。ファイルはmultipart/form-dataで送信され、ファイル部分はfile、その他のフィールドは JSON のparameters部分として送信されます。Populi のアップロードルート（/people/{id}/upload_file、/people/{id}/update_profile_picture、/libraryresources/{id}/update_image、/libraryresources/{id}/digitalresources/upload）はこの形式を想定しています。安全上の上限として、このサーバーは100 MBを超えるファイルを拒否します。
• files フォルダーは境界です。 モデルが読み取れるアップロード元と、ダウンロードの保存先はPOPULI_FILES_DIR内に限られます。シンボリックリンクを経由する場合も含め、このフォルダーの外に出るパスは拒否されるため、プロンプトインジェクションで「SSH キーをアップロードして」と指示されても、読み取る対象がありません。より広いフォルダーを指定するのは、そのようにしたい場合に限ってください。
• タイムアウト。 Populi はタイムアウトを公開しておらず、Data Slicer などのレポートには時間がかかることがあるため、デフォルトは2分です。MCP クライアント側でも独自のツールタイムアウトが適用される場合があり、このサーバーから延長することはできません。長時間のレポートが途中で切れる場合は、クライアントの設定を確認してください。
• 学生データは機密情報です。 レコードには SSN、生年月日、成績、学資援助情報が含まれる場合があります。サーバーがリクエストやレスポンスの本文を記録することはなく、エラーにキーが表示されることもありませんが、ツールが返す内容はすべてモデルプロバイダーに送信されます。必要最小限の権限を持つキーと、必要なexpandのみを使用してください。

開発

git clone https://github.com/kisasa/populi-mcp.git
cd populi-mcp
npm install
npm run build      # compile to dist/
npm test           # unit + in-memory MCP tests, no network

実際のインスタンスに対して試してください。

POPULI_BASE_URL=https://yourschool.populiweb.com POPULI_API_KEY=sk_sandbox_... \
  npx @modelcontextprotocol/inspector node dist/index.js

API カタログの更新

data/catalog.jsonは、レンダリングされた API ドキュメントからスクレイピングしたものです（Populi は OpenAPI ファイルを公開していません）。

npm run build:catalog

Populi が API を変更したら、差分を確認してコミットしてください。

リリース

main へのプッシュのたびに .github/workflows/publish.yml によって公開が自動化されており、バージョンが新しい場合にのみ実行されます。リリースするには：

1. package.json の version と、server.json の両方の version フィールドを更新します。
2. main にマージします。ワークフローによって、npm（provenance 付き）、MCP Registry（io.github.kisasa/populi-mcp として）に公開され、GitHub リリースが作成されます。

npm 認証には、このリポジトリで設定されている場合は信頼されたパブリッシングを使用し、設定されていない場合はリポジトリシークレットの NPM_TOKEN を使用します。

ライセンス

MIT。Populi とは提携していません。「Populi」は所有者の商標です。