Skip to content

About

Shimane University public course information API and MCP on Cloudflare Workers

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

島根大学 公開授業情報AI連携基盤

Cloudflare Workers + Hono + D1 を前提にした、公開授業情報の蓄積型 API 基盤です。

運用方針

  • Cloudflare 上では Workers + D1 + Queues のみを使い、R2 や有料アドオンは使いません。
  • 原本 HTML/PDF は Cloudflare に保存せず、必要な fixture のみ test/fixtures/parsers/ を Git 管理します。
  • wrangler.jsonc では observability を明示的に有効化せず、追加のログ/トレース課金リスクを避けます。
  • カスタムドメインは k-tkms.com の Cloudflare zone 上で shimadai.k-tkms.com のようなサブドメインを Worker に割り当てる前提です。
  • 取得処理は Cloudflare Queues で小分けに実行し、Workers Free の subrequest 制限を回避します。
  • 無料枠を超えない限り 0 円運用を維持し、超過時は free tier の制限エラーで止まる前提です。

主要コマンド

  • npm run dev: ローカル開発
  • npm run test: テスト実行
  • npm run typegen: Wrangler の binding 型生成
  • npm run cf-typecheck: 型生成 + TypeScript 検査

提供エンドポイント

  • 公開 REST API: /api/courses/*, /api/guides/*, /api/notices/*
  • 管理 API: /admin/fetch, /admin/reparse, /admin/jobs
  • OpenAPI: /openapi.json, /docs
  • MCP: /mcp

MCP

  • POST /mcp で authless の公開 MCP を提供します。
  • 公開するのは courses, guides, notices の検索・詳細取得だけで、既存 REST API と同じ公開データ範囲に限定します。
  • ツール:
    • search_courses, get_course
    • search_guides, get_guide
    • search_notices, get_notice
  • リソース:
    • shimadai://meta/service-overview
    • shimadai://meta/api-guide
    • shimadai://courses/{id}
    • shimadai://guides/{id}
    • shimadai://notices/{id}
  • プロンプト:
    • course_advising
    • deadline_check
  • ブラウザ系クライアントや MCP Inspector で使えるよう、localhost:5173 と同一ホストを既定で許可します。
  • 必要なら MCP_ALLOWED_ORIGINS にカンマ区切りで origin を追加できます。

前提

  • ADMIN_API_KEY は wrangler secret put ADMIN_API_KEY で設定します。
  • D1 の実 ID は wrangler.jsonc を更新して使います。
  • Queue school-api-fetch-queue を作成し、wrangler.jsonc の producer / consumer binding を使います。
  • ローカルでは wrangler dev のローカルシミュレーションを使います。

原本の扱い

  • Cloudflare 側には原本 HTML/PDF を保存しません。
  • Cloudflare 側に保持するのは正規化済みデータ、出典 URL、取得日時、ハッシュ、パース用メタデータのみです。
  • パーサ回帰確認や構造変更追従に使う原本は test/fixtures/parsers/ に Git 管理で保持します。
  • POST /admin/reparse は Cloudflare に保存済み原本を読むのではなく、source_url を再取得して再パースします。

現在の Cloudflare 設定

  • D1 school-api-db は Takemasa0302@gmail.com の Cloudflare アカウントに作成済み database_id: f6e12d2c-fbd9-4e78-9ca0-760a5d46a750
  • Queue school-api-fetch-queue は同アカウントに作成済み
  • 初期 migration は D1 に適用済み
  • ローカル開発用の ADMIN_API_KEY は .dev.vars に設定済み
  • k-tkms.com zone は同アカウント上で active な Cloudflare zone として存在

課金アラートについて

  • このリポジトリ内には Cloudflare の請求アラートを自動作成する設定はまだありません。
  • Cloudflare API で通知ポリシーの確認を試しましたが、現在の API 権限では alerting/v3 が 10000 Authentication error で確認できませんでした。
  • D1 の billing notifications は Cloudflare dashboard 上で Rows Read / Rows Written を対象に設定可能です。
  • 実運用前に Cloudflare dashboard の Notifications で billing usage alert を追加してください。

About

Shimane University public course information API and MCP on Cloudflare Workers

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages