リファレンス GUILDUO

Guilduo API・MCPリファレンス：endpointと操作例

RESTとMCPは同じ作業ルールを使います。実際の入力は、このDocsの根拠となる公開OpenAPIとMCPスキーマを確認し、接続中サーバーの契約に合わせてください。

REST・MCP・Appwriteを区別する

通常のMCP接続は/mcpを使います。/mcp-nextは検証レーンです。Appwrite APIへWorkerのQuest経路を送る設定に置き換えません。

用途	URL	利用方法
ブラウザ	https://app.guilduo.com/	Guilduo / Relay Forge
Remote MCP	https://mcp.guilduo.com/mcp	OAuth対応AIクライアント
Worker REST	https://mcp.guilduo.com/v1/quests	OpenAPIの/v1経路
Appwrite API	https://api.guilduo.com/v1	Appwrite SDKとWorkerの接続先

一般のMCP利用者はOAuthを使います。OpenAPIはOAuthとAppwrite JWTのBearer認証を定義しています。固定APIキーを通常利用者へ配る方式ではありません。

api/openapi.jsonがRESTの経路・入力・応答を、api/mcp-tools.jsonがツール名・入力・出力を定義します。必須フィールド、enum、文字数制限は呼び出し前に確認します。

ツール発見は認証・Agent許可の代わりではありません。get_current_agent_contextで接続主体と実効スコープを読み、操作対象の現在状態を取得します。

以下はlist_questsの読み取り入力です。結果のquests、total、nextCursorを確認します。nextCursorがあればcursorとして次の呼び出しへ渡します。

OAuth MCPを接続し、get_current_agent_contextで本人のAgentと必要なquests:readを確認します。
上記入力でlist_questsを呼び、Web AppのBacklogと比較します。
対象IDをget_questのquestIdへ渡し、詳細とupdatedAtを読みます。IDを表示名から推測しません。
RESTなら認証済みでGET /v1/quests?view=backlog&kind=todo&limit=5を使います。未認証の401を保存や通信の失敗と混同しません。

json

{
  "view": "backlog",
  "kind": "todo",
  "limit": 5
}

CLIは人間・CI向けのRESTクライアントです。書き込みは--executeを付けた場合に実行します。OAuth MCPのツール発見とCLIを同じ接続方式として扱いません。

用途	MCP	REST
一覧・詳細	list_quests / get_quest	GET /v1/quests / GET /v1/quests/{questId}
階層	get_quest_tree	GET /v1/quests/tree
作成・編集	create_quest / update_quest	POST /v1/quests / PATCH /v1/quests/{questId}
Handoff	transition_quest_handoff	POST /v1/quests/{questId}/handoff
Human依頼	request_human_review	POST /v1/quests/{questId}/review-requests
Human一覧	list_human_requests	GET /v1/human-requests
人の回答	MCP書き込みなし	本人Web認証のPOST /v1/quests/{questId}/review-response

assign_quest_to_agentとrequest_human_reviewはプレビュー後に最新expectedUpdatedAtで実行します。transition_quest_handoffはexpectedStateを使います。
create_questとupdate_questに未定義のdryRunを追加しません。入力がadditionalProperties=falseのツールは未定義フィールドを許しません。
401は認証、403は許可や主体、409は競合を確認します。requestKeyはHuman依頼の同じラウンドの再送用で、一般のQuest作成の再送保証ではありません。
競合時は最新状態を読み、再プレビューします。古いtimestampで連続再送したり、一般更新で人の回答を作ったりしません。
ツール数と版数は更新されます。接続中のtools/listと公開契約を比較し、必要なツール名とスキーマで互換性を確認します。

公開GitHubの資料をもとに編集しています。仕様の詳細は原文を確認できます。

内容確認日: 2026-10-05 · 公開資料の版: 5125178