Skip to content

AGENT-INSTALL.md

Latest commit

 

History

History
168 lines (113 loc) · 4.77 KB

AGENT-INSTALL.md

File metadata and controls

168 lines (113 loc) · 4.77 KB

Claude Code — Yuque Plugin Installation (Agent Guide)

For AI agents to auto-install. Human-readable but optimized for machine execution.

Prerequisites Check

Run these commands to verify your environment:

# Check Claude Code CLI is available
claude --version
# ✅ Expected: version string (e.g., "claude-code 1.x.x")
# ❌ If "command not found": install via `npm i -g @anthropic-ai/claude-code`

# Check Node.js version (>= 18 required)
node --version
# ✅ Expected: v18.x.x or higher
# ❌ If below 18: upgrade via nvm (`nvm install 18 && nvm use 18`)

# Check npx is available
npx --version
# ✅ Expected: version string
# ❌ If missing: comes with npm, reinstall Node.js

Installation Method 1: Marketplace Plugin (Recommended)

This installs both the MCP server and all skills (personal + group editions).

Install

claude plugin marketplace add yuque/yuque-ecosystem

Verify Installation

claude plugin list | grep -i yuque
# ✅ Expected: "yuque/yuque-ecosystem" appears in the list
# ❌ If not listed: retry installation or use Method 2

Configure Token

After marketplace installation, you still need to set your Yuque API token:

# Set the token as an environment variable
export YUQUE_TOKEN="your_token_here"

Note: The marketplace plugin reads the token from the YUQUE_TOKEN environment variable. Add it to your shell profile (~/.zshrc or ~/.bashrc) for persistence.

Installation Method 2: MCP Server Only

Use this if you only need the 25 MCP tools without skills, or if the marketplace is unavailable.

Install

claude mcp add yuque-mcp -- npx -y yuque-mcp --token=$YUQUE_TOKEN

Important: Make sure $YUQUE_TOKEN is set before running this command. If not:

export YUQUE_TOKEN="your_token_here"
claude mcp add yuque-mcp -- npx -y yuque-mcp --token=$YUQUE_TOKEN

Verify MCP Connection

claude mcp list | grep -i yuque
# ✅ Expected: "yuque-mcp" appears with status "connected" or "configured"
# ❌ If not listed: check token and retry

Post-Installation Verification

After either installation method, verify the integration is working:

Test 1: Check MCP Tools Are Available

claude mcp list
# Look for "yuque-mcp" in the output
# Should show ~25 tools available

Test 2: Quick Functional Test

Inside a Claude Code session, try calling a Yuque tool:

> Use the yuque_get_user tool to get my user info

Expected: Returns your Yuque user profile (username, avatar, etc.)

Skills Installation (Optional — for Method 2)

If you used Method 2 (MCP only), you can manually add skills:

# Clone or navigate to the ecosystem repo
cd /path/to/yuque-ecosystem

# Skills are in plugins/yuque-personal/skills/ and plugins/yuque-group/skills/
# Claude Code auto-discovers skills from the plugin directory

Note: Method 1 (Marketplace) includes all skills automatically.

Available After Installation

MCP Tools (25)

Category Tools
Document Management yuque_search, yuque_get_doc, yuque_create_doc, yuque_update_doc, yuque_delete_doc, yuque_get_doc_history
Knowledge Base yuque_list_repos, yuque_get_repo, yuque_create_repo, yuque_update_repo, yuque_delete_repo, yuque_get_toc
User & Group yuque_get_user, yuque_list_groups, yuque_get_group, yuque_list_group_repos
Collaboration yuque_list_comments, yuque_create_comment, yuque_delete_comment
Statistics yuque_get_doc_stats, yuque_get_repo_stats, yuque_get_group_stats, yuque_get_group_member_stats, yuque_get_trending_docs, yuque_get_active_members

Skills (Marketplace install only)

Personal (8): smart-search, smart-summary, daily-capture, reading-digest, note-refine, knowledge-connect, style-extract, stale-detector

Group (6): smart-search, weekly-report, knowledge-report, meeting-notes, tech-design, onboarding-guide

Troubleshooting

Error Cause Fix
command not found: claude Claude Code CLI not installed npm i -g @anthropic-ai/claude-code
YUQUE_TOKEN not set Missing API token export YUQUE_TOKEN="your_token"
npx: command not found Node.js/npm not installed Install Node.js >= 18
MCP server fails to start Token invalid or expired Regenerate at https://www.yuque.com/settings/tokens
Plugin not found in marketplace Network or registry issue Try Method 2 (MCP direct) as fallback
ECONNREFUSED or timeout Network/firewall blocking yuque.com Check connectivity: curl -I https://www.yuque.com

Uninstall

# Remove marketplace plugin
claude plugin remove yuque/yuque-ecosystem

# Or remove MCP server
claude mcp remove yuque-mcp