Yuque MCP

yuque-mcp

中国語の説明: README.zh-CN.md

このフォルダーは、Yuque 用のカスタム MCP サーバーを構築するために用意されています。

目標

Codex が以下を実行できるよう、Yuque MCP サーバーを構築します。

• Yuque のリポジトリとドキュメントを検索する
• ドキュメントの内容を Markdown／raw モードで読み取る
• 必要に応じてドキュメントを作成／更新／削除する
• ローカルファイルからドキュメントを作成し、ローカルファイルを使ってドキュメントを更新する
• リポジトリ（ナレッジベース）を作成／更新／削除する
• グループを作成／更新／削除する
• グループメンバーを管理する（list/add/remove）
• 複合操作を実行する（get_my_repositories、get_repository_overview、search_and_read、create_document_with_toc）
• リポジトリの目次ノードを更新する
• Yuque のコンテンツをリサーチ用ナレッジベースとして使用する

含まれるドキュメント

• docs/00-project-brief.md
• docs/01-scope-v1.md
• docs/02-architecture.md
• docs/03-tool-contract.md
• docs/04-api-mapping.md
• docs/05-security.md
• docs/06-implementation-plan.md
• docs/07-test-plan.md
• docs/08-codex-integration.md
• docs/09-release-notes-zh.md
• docs/10-registry-publish.md
• docs/11-weekly-maintenance.md
• docs/12-complaint-and-takedown.md
• CHANGELOG.md
• CONTRIBUTING.md
• SECURITY.md
• DISCLAIMER.md
• tasks/TODO.md

セッション開始

新しい Codex セッションでは、次の手順で始めてください。

1. docs/01-scope-v1.md と docs/03-tool-contract.md を読みます。
2. Node + TypeScript の MCP サーバーのひな形を作成します。
3. 読み取り専用ツールを実装します。
4. グループ／リポジトリ／ドキュメントの CRUD と TOC 更新用の書き込みツールを追加します。
5. テストを実行し、Codex MCP 設定を追加します。

クイックスタート（ローカル）

npm install
npm run build

必須の環境変数：

• YUQUE_TOKEN
• YUQUE_ENDPOINT（任意、デフォルトは https://www.yuque.com/api/v2/）
• YUQUE_TIMEOUT_MS（任意、デフォルトは 10000）
• YUQUE_MAX_RETRIES（任意、デフォルトは 2。読み取り専用の再試行のみ）
• YUQUE_ALLOW_WRITE（任意、デフォルトは false）
• YUQUE_WRITE_NAMESPACE_ALLOWLIST（任意、リポジトリ／ドキュメント／TOC の書き込みを許可する namespace のカンマ区切りリスト）
• YUQUE_WRITE_GROUP_ALLOWLIST（任意、グループの書き込みを許可するグループ login のカンマ区切りリスト）
• YUQUE_ALLOW_DELETE（任意、デフォルトは false）
• YUQUE_DELETE_NAMESPACE_ALLOWLIST（任意、削除を許可する対象のカンマ区切りリスト。リポジトリ／ドキュメントには namespace、グループには login を指定）
• YUQUE_FILE_ROOT（任意、デフォルトは現在の作業ディレクトリ。ファイルベースのドキュメントツールで使用）
• YUQUE_FILE_MAX_BYTES（任意、デフォルトは 1048576）
• YUQUE_FILE_ALLOWED_EXTENSIONS（任意、デフォルトは .md,.markdown,.txt）

書き込みの安全対策：

• すべての書き込みツールは、デフォルトでブロックされています。
• 書き込みを有効にするには、YUQUE_ALLOW_WRITE=true を設定します。
• 書き込み許可リストは任意で設定できます。
  • YUQUE_WRITE_NAMESPACE_ALLOWLIST=team/sandbox,team/test
  • YUQUE_WRITE_GROUP_ALLOWLIST=sandbox-team

削除の安全対策：

• yuque_delete_doc、yuque_delete_repo、yuque_delete_group は、デフォルトでブロックされています。
• テスト用リポジトリのみで削除を有効にするには、次のように設定します。
  • YUQUE_ALLOW_WRITE=true
  • YUQUE_ALLOW_DELETE=true
  • YUQUE_DELETE_NAMESPACE_ALLOWLIST=your/test-namespace,your-test-group-login
• 削除ツールには confirm: true と、正確な confirm_text も必要です。
  • ドキュメント：DELETE DOC <namespace>/<docRef>
  • リポジトリ：DELETE REPO <namespace>
  • グループ：DELETE GROUP <login>

最新の主な更新：

• yuque_get_doc／yuque_update_doc／yuque_delete_doc は、slug または doc_id のいずれかをサポートします。
• yuque_list_docs はページネーション（offset、limit）をサポートします。
• yuque_search_docs は、リポジトリ全体のドキュメントをページネーションで走査するようになりました。
• ドキュメント形式は markdown、html、lake をサポートし、公開範囲は 0 | 1 | 2 をサポートします。
• TOC の更新では、追加フィールド（editNode、url、open_window、visible）をサポートします。
• グループメンバーツール：yuque_list_group_users、yuque_add_group_user、yuque_remove_group_user。
• ファイルベースのツールは、ルートディレクトリ、拡張子の許可リスト、最大サイズによって制限されます。

開発モードで実行：

npm run dev

コンパイル済みサーバーを実行：

npm run start

ローカル MCP スモークテストを実行（テスト用 namespace のみ）：

YUQUE_SMOKE_NAMESPACE=your/test-namespace npm run smoke

クリーンアップ付きの書き込みスモークテストスイートを実行（テスト用 namespace で作成／更新／TOC 更新／削除）：

YUQUE_SMOKE_NAMESPACE=your/test-namespace \
YUQUE_SMOKE_ENABLE_WRITE=true \
YUQUE_ALLOW_WRITE=true \
YUQUE_ALLOW_DELETE=true \
YUQUE_DELETE_NAMESPACE_ALLOWLIST=your/test-namespace \
npm run smoke

推奨スタック

• Node.js 20+
• TypeScript
• @modelcontextprotocol/sdk
• ネイティブの fetch または軽量な HTTP クライアント
• 入力検証用の zod

オープンソースのガバナンス

• 貢献ガイド：CONTRIBUTING.md
• セキュリティポリシー：SECURITY.md
• 週次メンテナンスチェックリスト：docs/11-weekly-maintenance.md
• 苦情および削除要請に関するポリシー：docs/12-complaint-and-takedown.md
• 免責事項：DISCLAIMER.md