Frisian MCP (Django)

frisian-mcp

API を自動検出する Django MCP ゲートウェイです。

frisian-mcp は、既存の Django REST Framework の ViewSet を、ボイラープレートなしで Model Context Protocol ツールに変換します。パッケージを追加して URL を 1 つ含めるだけで、すべての ViewSet アクションが呼び出し可能な MCP ツールになります。名前、説明、入力スキーマはシリアライザーから自動的に生成されます。

トークン効率に優れたエージェントのワークフロー向けに設計されています。 50 個のアクションを持つ Django アプリが読み込む tools/list スキーマは 500～2,000 トークンです。従来のフラットな MCP では 15,000～25,000 トークンになるところを大幅に削減できます。また、60 台のデバイスに対する一括書き込みの応答は、完全なエコーでは約 10,800 トークンですが、わずか 24 トークンです。同じインターフェースでありながら、エージェントが推論を始める前に消費されるコンテキストを 2 桁削減できます。詳しい数値はトークン効率をご覧ください。

バージョン： 1.1.1 | ライセンス： Apache 2.0 | Python： 3.11+ | Django： 5.x

pip install frisian-mcp

プロジェクトサイト： https://frisian-mcp.com/

実際に評価できるよう、稼働中の MCP サーバーを https://frisian-mcp.com/ でホストしています。MCP 対応クライアントを接続すると、実際のインターフェースを使ってディスパッチャーパターンと簡潔なエンベロープの動作を確認できます。同じサイトでは、MCP で利用できるディスパッチャーを通じてプロジェクトのドキュメントも提供しているため、コーディングエージェント（Claude Code、Codex、Gemini CLI など）は直接接続し、frisian-mcp を独自のプロジェクトに組み込む際の作業コンテキストとして、インストール、設定、デコレーターのリファレンスを利用できます。

---

概要

機能	詳細
自動検出	起動時に URL パターンを走査し、すべての ViewSet アクションを MCP ツールとして登録します
ボイラープレート不要	名前、説明、入力スキーマを DRF シリアライザーから自動的に生成します
@mcp_dispatcher	1 つのツールで複数のアクションに対応します。組み込みのヘルプモードとアクションごとの検証を備えています
@mcp_tool	カスタムロジック向けに、単一関数のツールを明示的に登録します
@mcp_resource	resources/list / resources/read を通じてサーバー側のコンテンツを公開します
フィルターのイントロスペクション	SearchFilter、OrderingFilter、DjangoFilterBackend を list のスキーマプロパティに反映します
許可リスト／拒否リスト	FRISIAN_MCP_TOOL_ALLOWLIST / FRISIAN_MCP_TOOL_DENYLIST で公開範囲を細かく制御します
ディスパッチグループ	FRISIAN_MCP_DISPATCH_GROUPS で N 個のツールを 1 つのディスパッチャーにまとめます。action="help" で検出できます
遅延検出	最初のリクエスト時に URL スキャンを実行するため、後から読み込まれるプラグインの ViewSet も検出できます
OAuth 2.0	contrib.oauth — 認可コード（PKCE）とクライアントクレデンシャルに対応し、トークンを HMAC でハッシュ化します
静的トークン	contrib.tokens — 内部エージェント向けの HMAC ハッシュ化 Bearer トークンです
エージェントごとのスコープ設定	contrib.agents — クレデンシャルごとのツール許可リストに対応し、非アクティブな接続はフェイルクローズします
権限ティア	FRISIAN_MCP_TOKEN_TIER_MAP / FRISIAN_MCP_MAX_TIER でロールを読み取り／書き込みの制限に対応付けます
ホストアプリのスコープ設定	SyncInvocation が viewset.initial() を呼び出し、ホストの RBAC、クエリーセットのフィルタリング、スロットリングを適用します
ツールミドルウェア	FRISIAN_MCP_TOOL_MIDDLEWARE — 監査ログ、レート制限、ハートビートに対応します
レート制限	RateLimitMiddleware — Redis 不要の、組み込みスライディングウィンドウ方式です
プラグ可能なバックエンド	ドットパス設定を使って、カスタムの検出バックエンドと呼び出しバックエンドを指定できます
SSE 対応	Accept: text/event-stream によって、任意の応答を単一の SSE イベントでラップします
MCP 2025-11-25	Streamable HTTP、ping、initialize、tools/list、tools/call、resources/list に対応します

---

トークン効率

ディスパッチャーパターンと簡潔な書き込みエンベロープが存在する理由は、ただ一つです。エージェントのコンテキストウィンドウには限りがあり、従来の MCP の形式（ViewSet のアクションごとにツールを一つ用意し、書き込みのたびにシリアライズ済みの全データをエコーする方式）では、エージェントが有用な作業を始める前に、その予算を使い切ってしまいます。

実際の統合で測定した数値は次のとおりです。

シナリオ	デフォルトの MCP 形式	frisian-mcp	削減率
50 アクションの Django アプリに対する tools/list	約 15,000～25,000 トークン	FRISIAN_MCP_DISPATCH_GROUPS 使用時は 500～2,000 トークン	約 95%
大規模なインフラストラクチャ Django アプリに対する tools/list	1,737 個のフラットなツール	15 個のディスパッチャーツール	ツールの表面積を約 99% 削減
60 デバイスの一括作成レスポンス	約 10,798 トークン（全データをエコー）	24 トークン（簡潔なエンベロープ）	99.8%
200 デバイスの一括作成レスポンス	約 36,000 トークン	24 トークン（一定）	99.9%

一括書き込みによる節約量は、バッチサイズにかかわらず一定です。簡潔なエンベロープの形式は固定されており、書き込みを再実行しなくても、継続トークンを使って全レスポンスを取得できます。ディスパッチャーによる削減は FRISIAN_MCP_DISPATCH_GROUPS でオプトインできます（自動検出だけでは従来どおりのフラットな形式になります）。

設計の根拠と測定値の全容については、The Token Problem、Dispatcher Pattern、Write-Path Response Filtering を参照してください。

---

要件

• Python 3.11+
• Django 5.x
• Django REST Framework 3.14+

---

クイックスタート

1. インストールして INSTALLED_APPS に追加します：

# settings.py
INSTALLED_APPS = [
    ...
    "frisian_mcp",
]

2. ゲートウェイの URL を含めます：

# urls.py
from django.urls import include, path

urlpatterns = [
    ...
    path("mcp/", include("frisian_mcp.urls")),
]

以上です。自動検出が有効な場合（デフォルト）、URL ツリー内のすべての DRF ViewSet が MCP ツールになります。

# myapp/views.py — nothing changes here
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]

起動後、ゲートウェイは users.list、users.retrieve、users.create、users.update、users.partial_update、users.destroy を公開します。これらはすべて ViewSet から自動的に導出されます。

3. クライアント設定を生成します：

python manage.py mcp_config --token mytoken123

{
  "mcpServers": {
    "frisian-mcp": {
      "url": "http://localhost:8000/mcp/",
      "transport": "http",
      "headers": { "Authorization": "Bearer mytoken123" }
    }
  }
}

特定の MCP クライアントが要求する形式で出力するには --client を使用します。サーバーの URL とキーを上書きするには --url と --name を使用します。

4. インストールを検証します：

python manage.py mcp_doctor                # standard audit
python manage.py mcp_doctor --security     # extended OAuth security audit

設定を最初から最後まで確認し、エラーがある場合はゼロ以外の終了コードで終了します。インストールのたび、設定変更のたび、予期しない動作が発生したときの最初の診断手順として実行してください。チェック項目の全容については、mcp_doctor guide を参照してください。

---

アーキテクチャの概要

MCP Client
       │  JSON-RPC 2.0 over HTTP POST
       ▼
┌──────────────────────────────────────────────────┐
│  McpView  (DRF APIView)                           │
│  ├─ Authentication  (FRISIAN_MCP_AUTHENTICATION_CLASSES) │
│  ├─ Permissions     (FRISIAN_MCP_PERMISSION_CLASSES)     │
│  └─ Method dispatch                              │
│       ├─ initialize / initialized / ping / help  │
│       ├─ tools/list  ──────────────── ToolRegistry │
│       ├─ tools/call  ── ToolMiddleware ── Registry │
│       ├─ resources/list ───────── ResourceRegistry │
│       └─ resources/read ───────── ResourceRegistry │
└──────────────────────────────────────────────────┘
       │
┌──────────────────┐   ┌─────────────────────────┐
│  ToolRegistry    │   │  Auto-discovery          │
│  (module-level   │◄──│  (DRFSyncDiscovery)      │
│   singleton)     │   │  Walks URL patterns at   │
│                  │   │  AppConfig.ready()       │
└──────────────────┘   └─────────────────────────┘
       │
┌──────────────────────────────────────────────────┐
│  InvocationBackend  (SyncInvocation by default)  │
│  Builds synthetic DRF Request → calls ViewSet    │
│  action → returns ToolResult                     │
└──────────────────────────────────────────────────┘

• 検出と呼び出しを分離。 プラグイン可能なバックエンドが二つあり、それぞれを個別に置き換えられます。
• レジストリが信頼できる唯一の情報源。 @mcp_tool、@mcp_dispatcher、自動検出はすべて、同じ tool_registry シングルトンに登録します。
• ツールエラーは JSON-RPC エラーではなく isError: true。 権限拒否やハンドラーの例外は、通常の HTTP 200 レスポンス内で isError: true を返すため、セッションは維持されます。
• 適用箇所は二つ。 ゲートウェイレベルの権限で /mcp/ 全体へのアクセスを制御します。ツールレベルの権限ティアで、個々の tools/call 呼び出しを制御します。

---

ディスパッチャーパターン

専用のエージェントツールを構築するチーム向けに、frisian-mcp は @mcp_dispatcher パターンを提供します。一つの MCP ツール名で、内部の複数のアクションにルーティングできます。

from frisian_mcp import mcp_dispatcher, mcp_action

@mcp_dispatcher(name="tasks", description="Manage project tasks.")
class TasksDispatcher:

    @mcp_action(name="create", description="Create a task.")
    def create(self, request, params):
        task = Task.objects.create(title=params["title"])
        return {"id": task.pk}

    @mcp_action(name="list", description="List tasks by status.")
    def list(self, request, params):
        return {"tasks": list(Task.objects.values("id", "title", "status"))}

tools/list に表示されるツールは一つだけです。action="help" を指定して呼び出すと、利用可能なアクションの一覧を構造化形式で取得できます。メソッドの実行前に、アクションごとの JSON Schema 検証が行われます。

ツール数が重要で、フラットな一覧より段階的な情報開示が適している、エージェント向け API のためのパターンです。

大量の API では、FRISIAN_MCP_DISPATCH_GROUPS を使うと、追加のコードなしで、既存の自動検出ツールをディスパッチャーに自動的にまとめられます。

---

認証とセキュリティ

frisian-mcp は認証を DRF に委譲します。FRISIAN_MCP_AUTHENTICATION_CLASSES を通じて、どの DRF 認証クラスもそのまま使用できます。よくあるケースに対応する、すぐに使える contrib モジュールが 3 つ用意されています。

モジュール	提供する機能
frisian_mcp.contrib.tokens	内部エージェントとサービスアカウント向けの、HMAC ハッシュ化された静的 Bearer トークン
frisian_mcp.contrib.oauth	OAuth 2.0 の全機能 — 認可コード（PKCE）＋クライアントクレデンシャル、リダイレクト URI の許可リスト
frisian_mcp.contrib.agents	クレデンシャルごとのツール許可リスト。クレデンシャルが無効化されると、接続はフェイルクローズします

ゲートウェイレベルのアクセスは FRISIAN_MCP_PERMISSION_CLASSES で制御します。ツールレベルのアクセスは、権限ティア（read / read_write / admin）を FRISIAN_MCP_TOKEN_TIER_MAP でマッピングして制御します。クレデンシャルのティアにかかわらず、エンドポイント上のすべての呼び出し元の上限を設定するには FRISIAN_MCP_MAX_TIER を使用します。

デフォルトで強化されたセキュリティ対策（1.0.x）

デフォルト設定は、手軽にすぐ利用できることよりも、本番環境での安全性を重視しています。

• トークンとクライアントシークレットの保存には HMAC-SHA256 ダイジェストを使用します（FRISIAN_MCP_HMAC_KEY）。データベースのレコードが漏えいしても、そのまま再利用することはできません。生のシークレットが表示されるのは作成時の一度だけです。
• OAuth の動的クライアント登録は、デフォルトで無効です（FRISIAN_MCP_OAUTH_REGISTRATION_OPEN=False、FRISIAN_MCP_OAUTH_PKCE_AUTO_REGISTER=False、FRISIAN_MCP_OAUTH_AUTO_APPROVE=False）。運用者は Django 管理画面から OAuth クライアントをすべて事前登録します。明示的にオプトインしない限り、匿名での登録はできません。
• PKCE のデフォルト権限ティアは read です。 設定ミスによって、初回接続時に誤って書き込みや管理者のスコープが付与されることはありません。
• 権限を考慮したディスカバリー（FRISIAN_MCP_PERMISSION_AWARE_DISCOVERY=True）では、リクエストごとにディスパッチャーのアクション列挙を再構築します。read ティアのトークンからは list / retrieve アクションのみが見えます。write と admin のアクションは、実行時に拒否するだけでなく、tools/list からも隠されます。
• .well-known ディスカバリーメタデータは FRISIAN_MCP_OAUTH_PUBLIC_DISCOVERY によって制御されます。これを False に設定すると、OAuth メタデータエンドポイントは解析可能な JSON の 404 を返します。そのため、ディスカバリーを優先する MCP クライアントは、行き止まりの OAuth の連鎖に誘導されることなく、設定済みの Bearer にフォールバックできます。
• 認証器チェーンの順序は、正しく動作させるうえで必須ではなくなりました。 FrisianMcpTokenAuthentication と OAuthTokenAuthentication のどちらも、検索対象が見つからない場合は None を返すため、どちらの順序でも動作します。WWW-Authenticate チャレンジの形式を考慮した推奨規約は、トークンを先にすることです（docs/Getting Started/getting-started.md を参照）。
• SSE のキープアライブ構造を文書化しています。 パッケージが同期 WSGI ワーカー上での実行を検出すると、ワーカーのプールを使い果たさずに SSE をスケールできないため、実行時に一度だけ警告が表示されます。ASGI ワーカークラス（uvicorn.workers.UvicornWorker または uvicorn を直接使用）でのデプロイを推奨します。

認可パスの強化

未認証の OAuth 認可パス（AUTO_REGISTER）は、誰でも利用できるインターフェースです。リクエスト入力が示すのは呼び出し元の希望であり、呼び出し元に許可されている内容ではありません。設計の根拠については ADR-009 を、脅威モデルと推奨するデプロイパターンについてはセキュリティガイドを参照してください。

ルートごとの権限階層

FRISIAN_MCP_ROUTES は、read、read_write、admin の各サーフェスを個別のパスにマウントします。それぞれに独自のツール許可／拒否リストがあり、すべて拒否する状態を基準として権限の上限を設定します。あるルートで拒否されたツールは、そのルートには存在しません。呼び出し時に拒否されるだけでなく、ディスカバリーにも表示されず、呼び出しもできません。設定ミスは起動時に検出されます。匿名で特権サーフェスを提供することになるルートは、起動を拒否します。権限モデルとそのセキュリティ上の根拠については、ADR-010 を参照してください。

---

ドキュメント全文

設定の詳細、認証設定、デコレーター API、ミドルウェア、プラグイン可能なバックエンド、セキュリティガイド、トラブルシューティングについては、docs/ をご覧ください。

閲覧可能なドキュメント、稼働中の MCP サーバー、エージェントが利用できるドキュメントディスパッチャー（コーディングエージェントから直接参照できます）については、https://frisian-mcp.com/ をご覧ください。