メインコンテンツまでスキップ

Kuroco Skills リファレンス

このページでは、Kuroco Skills に含まれる 5 つのスキルについて詳しく説明します。

kuroco-docs - ドキュメント検索​

Kuroco 公式ドキュメントの検索・参照を支援するスキルです。

機能​

  • プラグインに同梱された公式ドキュメントの横断検索
  • 目的別クイックリファレンス（API、認証、フロントエンド、コンテンツ管理など）

使用例​

「Kuroco のエンドポイント設定方法を知りたい」
「ログイン API の仕様を調べたい」
「フィルタークエリの書き方を教えて」

同梱ドキュメントの構成​

ディレクトリ内容
tutorials/機能の使い方、実装手順、サンプルコード
reference/API 設定項目、Smarty プラグイン、フィルタークエリ
management/管理画面の各機能の詳細説明
faq/よくある質問と回答
about/Kuroco の概要、料金プラン、制限事項、用語集
troubleshooting/エラー解決、問題診断ガイド
information/お知らせ、リリース情報
update/アップデート情報

kuroco-api-content - API 連携 & コンテンツ管理​

Kuroco API の設計・実装およびコンテンツ管理（CRUD 操作）に関するベストプラクティスを提供するスキルです。 旧 kuroco-api-integration と kuroco-content-management を統合したスキルです。

機能​

API 連携:

  • エンドポイント設計パターン（URL 構造、主要モデル、オペレーション）
  • 3 つの認証方式（Cookie 認証 / トークン認証 / StaticToken 認証）
  • CORS 設定、キャッシュ戦略、流量制限
  • エラーハンドリングパターン

コンテンツ管理:

  • コンテンツ構造（Topics / TopicsGroup / TopicsCategory）
  • 拡張項目（カスタムフィールド）の設定・利用方法
  • Topics API のオペレーション（list / details / insert / update / delete / bulk_upsert）
  • フィルタークエリの構文と使い方
  • ファイルアップロード、CSV インポート/エクスポート

使用例​

「Kuroco の API でログインを実装したい」
「トークン認証の使い方を教えて」
「CORS のエラーが出る。設定方法は？」
「Kuroco でコンテンツ定義を作りたい」
「記事の一覧を API で取得したい」
「フィルターで特定カテゴリの記事だけ取得したい」

対応するキーワード​

Kuroco API エンドポイント設定 認証 CORS Cookie認証 トークン認証 StaticToken JWT 流量制限 credentials include 401エラー 403エラー 429エラー pageInfo ページネーション コンテンツ定義 Topics カテゴリ WYSIWYG ファイルアップロード CSVインポート ext_col filter order_by bulk_upsert topics_flg 拡張項目

主な認証方式の比較​

認証方式推奨ユースケース特徴
Cookie 認証Web アプリセッションベース。credentials: 'include' が必須
トークン認証モバイルアプリJWT ベース。ヘッダーにトークンを付与
StaticToken 認証サーバー間通信固定トークン。管理画面で設定

フィルタークエリの基本構文​

演算子例
=, !=filter=category_id = 1
>, >=, <, <=filter=ymd >= '2024-01-01'
containsfilter=subject contains 'キーワード'
in, not_infilter=category_id in [1, 2, 3]

kuroco-frontend-integration - フロントエンド統合 & AI 自動デプロイ​

Kuroco と Nuxt.js / Next.js の統合パターンおよび AI 自動デプロイワークフローを提供するスキルです。 旧 kuroco-ai-deployment の機能を統合しています。

実践的なチュートリアルは Kuroco サンプルサイトチュートリアル を参照してください。

機能​

フロントエンド統合:

  • Nuxt 3 / Nuxt 2 / Next.js（App Router / Pages Router）の統合パターン
  • 環境変数設定、プロジェクト構成例
  • 認証実装（ログイン / ログアウト / ログイン状態確認 / 会員登録）
  • SSG / SSR 設定
  • KurocoPages との連携
  • サードパーティ Cookie 問題への対応

AI 自動デプロイ:

  • デプロイワークフロー（サイト登録 → ビルド → アップロード → デプロイ）
  • 署名付き URL を使った一時ファイルアップロード
  • プレビューデプロイ / 本番デプロイ
  • フレームワーク自動検出（Nuxt / Next.js / Vite）

使用例​

「Nuxt3 で Kuroco のコンテンツを表示したい」
「Next.js で Kuroco の認証を実装したい」
「SSG で静的サイトを生成したい」
「Safari でログインできない（Cookie の問題）」
「Kuroco のサイトを自動デプロイしたい」
「プレビュー環境にデプロイして確認したい」

対応するキーワード​

Nuxt3 Next.js App Router SSG SSR useAsyncData $fetch composable useAuth KurocoPages credentials include サードパーティCookie AI自動デプロイ add_site temp-upload presigned URL kuroco_front/deploy artifact_url stage_url CI/CD

フレームワーク別の推奨​

フレームワーク推奨ユースケース
Nuxt.js 3.x新規 Vue プロジェクト（推奨）
Nuxt.js 2.x既存 Vue プロジェクト
Next.js 13+（App Router）新規 React プロジェクト
Next.js（Pages Router）既存 React プロジェクト

デプロイワークフロー​

1. サイト登録       → admin_api (add_site)
2. フロントビルド   → npm run build / nuxt generate
3. アップロード     → 署名付き URL → S3
4. デプロイ実行     → admin_api (KurocoFront deploy)
5. 完了            → stage_url（プレビュー） or production_url

kuroco-server-processing - Smarty プラグイン & バッチ処理​

Kuroco の Smarty テンプレートの完全リファレンスおよびバッチ処理・Webhook・トリガーを使った自動化パターンを提供するスキルです。 旧 kuroco-smarty-plugins と kuroco-webhook-processing を統合したスキルです。

機能​

Smarty プラグインリファレンス:

  • 206 個のプラグインの完全なリファレンス
  • カテゴリ別索引（API / 文字列 / 配列 / フォーム / 認証 / 外部連携 / ファイル / Vue.js）
  • Smarty 基本構文（変数代入、ループ、条件分岐、修飾子）
  • セキュリティ設定（IF_FUNCS / MODIFIER_FUNCS）

バッチ処理 & Webhook:

  • バッチ処理の設定方法と実行頻度
  • 内部 API 呼び出し（api_internal）
  • 外部 API 呼び出し（api_request）
  • トリガー処理（コンテンツ更新時 / フォーム送信時）
  • 外部サービス連携（Slack / メール / GitHub Actions）

使用例​

「Smarty で記事一覧を取得して表示したい」
「sendmail プラグインの使い方を教えて」
「Smarty で JSON をパースする方法は？」
「バッチ処理で毎日 CSV を生成したい」
「コンテンツ更新時に Slack に通知を送りたい」
「GitHub Actions でデプロイをトリガーしたい」

対応するキーワード​

Smartyプラグイン Smarty関数 Smarty修飾子 assign foreach escape date_format api_internal sendmail slack_post_message ai_completion write_file バッチ処理 Webhook 定期実行 cron Slack通知 GitHub Actions api_request トリガー カスタム処理

カテゴリ別リファレンス​

カテゴリ主なプラグイン
API・データ取得api_internal, assign_topics_list, assign_tag_list
文字列処理escape, truncate, date_format, translate
配列操作count, in_array, implode, explode
フォーム・UIfileupload, inquiry_input, pager
認証・権限rcms_auth, login, logout
外部連携sendmail, slack_post_message, ai_completion
ファイル操作write_file, put_file, read_file
Vue.js 連携rcms_vue_component, head_include

バッチ処理の実行頻度​

頻度用途
15 分毎頻繁な同期が必要な場合
30 分毎準リアルタイム処理
1 時間毎定期的な集計・更新
毎日（指定時刻）日次レポート、バックアップ

kuroco-admin-api - 管理 API 操作​

Kuroco の管理 API（admin_api）を CLI（kuroco-admin）で操作するスキルです。 Bash ツールからコマンド一発で API 実行・探索・スキーマ取得が可能です。

機能​

  • admin_api の 5 つのメタアクション（whoami / discover / schema / advise / execute）
  • kuroco-admin login によるセッション Cookie 認証（~/.kuroco-admin/cookies.txt、mode 0o600）
  • API 探索（discover アクション / advise アクション）
  • CLI 経由の API 実行（--columns でレスポンスカラム選択可能）

使用例​

「管理 API でコンテンツを作成して」
「このサイトのコンテンツ定義一覧を確認したい」
「管理 API でメンバー情報を取得したい」
「ターミナルから API 操作を実行したい」

対応するキーワード​

admin_api 管理API kuroco-admin admin CLI 管理API CLI discover advise Topics作成 Member登録

前提条件​

  • Bun ランタイムがインストール済みであること
  • kuroco-admin CLI がビルド済みまたは PATH に追加済みであること
  • kuroco-admin login --url <管理画面URL> でログイン済み、または KUROCO_ADMIN_URL / KUROCO_ADMIN_COOKIE 環境変数が設定済みであること

admin_api のリクエスト構造​

ゲートウェイはトップレベルの action パラメータでメタエンドポイントを選択します。action を省略すると、リクエストは module/controller（またはサービス）の実行に振り分けられます。コントローラ側の MODE=INSERT/UPDATE/DELETE は action とは無関係に併存します。

actionメソッド説明用途
whoamiGETセッション情報の取得（member_id、name1、name2、group_ids、expiresAt）認証確認
discoverGET利用可能な管理コントローラ・サービスの一覧API 構造の把握
schemaGET特定コントローラ／サービスのリクエスト・レスポンススキーマ取得パラメータ仕様の確認（MODE=<title> で oneOf を絞り込み可能）
zod_schemaGET生の Zod スキーマ JavaScript を取得外部のフロントエンド・管理ツールでスキーマを再利用
advisePOST自然言語のリクエストから AI が API 呼び出しを推奨やりたいことを伝えると API 手順とパラメータを回答
(指定なし)GET / POSTmodule + controller（書き込み時は MODE も）へディスパッチ実際の管理 API を実行

セキュリティ上の注意事項​

  • Cookie 値を表示・ログ出力しない（~/.kuroco-admin/cookies.txt は mode 0o600 で保護）
  • --verbose の出力をユーザーに見せない（HTTP ヘッダーに Cookie 値が含まれる）
  • 変更操作（INSERT / UPDATE / DELETE）は実行前にユーザーに確認
  • --dry-run を活用して書き込み前にリクエスト内容をプレビュー
  • API レスポンスのファイル保存はユーザー同意が必要（個人情報を含む可能性）

Admin MCP サーバ​

CLI に加えて、同等の管理操作を JSON-RPC 2.0 ベースの MCP サーバ として /direct/rcms_api/admin_mcp/ から提供しています。MCP 対応クライアントはこのエンドポイントを直接登録するだけで利用でき、CLI のビルドは不要です。

認証​

認証方式はリクエストのホストによって自動的に切り替わります。

ホスト方式補足
ROOT_MNG_URL管理セッション Cookie管理画面と同じログインフロー。direct.php 標準フローで自動復元されます。
ROOT_API_URLBearer トークン（Authorization ヘッダ）OAuth IdP アクセストークン（target_domain=AdminMCP、RFC 8707 準拠で audience 拘束）または、OAuth ハンドシェイクを張れないツール向けに AdminMCPServer::generateToken() で発行する特権 static トークン（api_id=-1）を受け付けます。

401 レスポンスには RFC 6750 準拠の WWW-Authenticate チャレンジが含まれ、resource_metadata で次のメタデータ文書を案内します。

/.well-known/oauth-protected-resource/direct/rcms_api/admin_mcp/

このエンドポイントは認証不要の公開エンドポイントで、MCP クライアントは事前認証なしで Authorization Server を発見できます。?MODE=protected_resource_metadata 経由でも到達可能です。

モジュールスコープ付き MCP サーバ​

/admin_mcp/ 以降のパスセグメントで、1 つの MCP サーバ（=1 認証情報）に複数の管理モジュールをバンドルできます。GitHub MCP の /x/<csv>/readonly パターンに準拠しています。

POST /direct/rcms_api/admin_mcp/                                     # 全ツール（管理／discovery のみ）
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5,member,services
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5/readonly
POST /direct/rcms_api/admin_mcp/x/topics_group                       # グループ定義 CRUD

認識される CSV エントリ（t_ai_agent.admin_mcp_modules の格納値と同じ識別子）:

エントリ意味
topics_group_<N>topics_group_id = N にスコープした topics レコード操作。各ツールの topics_group_id 引数は enum として制約され、許可外グループへの呼び出しは拒否されます。
topicsグループ制約なしの同等表現。discovery 専用で、ツール呼び出しは拒否されます。
topics_groupグループ定義の管理（t_topics_group の CRUD）。
servicesサービスモデル（Email、Slack など）。
<mt>その他任意の管理モジュール（member、ec、batch など）。

モジュール指定時の挙動:

  • 書き込み系コントローラは MODE 単位（INSERT / UPDATE / DELETE）にツール分割
  • レコード数がゼロのモジュールは読み取り系ツールが除外される
  • 空モジュールでは INSERT のみが表示される

パスに /readonly を付与すると、書き込み系ツールはリストから除外されます。

モジュール一覧（REST）​

GET /direct/rcms_api/admin_mcp/?MODE=tools

レスポンス:

{
  "modules": [
    {"module": "topics",   "type": "controller", "tool_count": 8},
    {"module": "member",   "type": "controller", "tool_count": 5},
    {"module": "services", "type": "service",    "tool_count": 4}
  ]
}

MCP プロトコル​

HTTP POST + JSON-RPC 2.0。サポートメソッド:

メソッド説明
initializeハンドシェイク・プロトコルバージョン交渉
notifications/initializedクライアント準備完了通知
ping接続確認
tools/list利用可能な管理ツール一覧（モジュールスコープ反映）
tools/call名前指定で管理ツールを実行

ツール名は {mt}-{verb} の畳まれた形式で生成されます。コントローラ名の語尾と MODE が動詞にマッピングされます（例: INSERT → create、_list_api → list）。

種別パターン例
List コントローラ（{mt}_list_api、MODE なし）{mt}-listtopics-list
List コントローラ + MODE{mt}-{mode}topics-accept
List コントローラの一括処理 MODE（DELETE 等）{mt}-bulk_{mode}topics-bulk_delete
用途特化型の list（{mt}_{spec}_list_api）{mt}-{spec}_listtopics-waiting_for_approval_list
Edit コントローラ INSERT{mt}-createtopics-create
Edit コントローラ UPDATE{mt}-updatetopics-update
Edit コントローラ DELETE{mt}-deletetopics-delete
Edit コントローラ VALIDATE{mt}-validatetopics-validate
サブエンティティのコントローラ（topics_group_edit_api など）{mt}-{sub}-{verb}topics-group-create
Fetch ヘルパー{mt}-fetchtopics-fetch
topics 専用の describe ツール（ハードコード）—topics-describe
サービスメソッド{mt}-{method}Email-send

実際のツール一覧はモジュールが公開するコントローラに依存します。スコープ URL に対して JSON-RPC の tools/list を発行して列挙してください。

呼び出し例:

POST /direct/rcms_api/admin_mcp/x/topics_group_1
Authorization: Bearer <token>
Content-Type: application/json

{"jsonrpc":"2.0","method":"tools/call",
 "params":{"name":"topics-create",
           "arguments":{"subject":"Hello","topics_group_id":1}},
 "id":3}

CLI と MCP の使い分け​

用途推奨
管理ログインを使ったローカル対話開発Admin CLI（kuroco-admin）
MCP ネイティブ対応クライアント（Claude Code / Claude Desktop など）Admin MCP サーバ
トークンローテーションを伴う CI／無人エージェントAdmin MCP サーバ（特権 static トークン）
エンドユーザー認可フロー（委任アクセス）Admin MCP サーバ（OAuth IdP target_domain=AdminMCP）
シェルスクリプトや CLI パイプとの混在Admin CLI（kuroco-admin）
どちらの経路も課金対象

/direct/rcms_api/admin_api/ と /direct/rcms_api/admin_mcp/ はともに /direct/ 配下のため、Kuroco の課金対象です。意図しない書き込みトラフィックを抑えるには、モジュールスコープ付き URL と /readonly の活用を推奨します。

Client CLI

Client API に CLI ベースでアクセスする場合は、別途 Client CLI（kuroco-client）も利用可能です。 詳細は Kuroco AI アーキテクチャ を参照してください。

関連ドキュメント​

サポート

お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。

フォームから問い合わせをする
Slackコミュニティに参加する