CLAUDE.md•4.18 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
Yuque MCP Server is a Model Context Protocol (MCP) server that provides integration with Yuque (语雀), a popular Chinese documentation platform. It enables AI assistants to manage Yuque documents, repositories, and search functionality through a standardized MCP interface.
## Claude Code Integration
### Loading This Server in Claude Code
The easiest way to configure this MCP server is using the Claude Code CLI:
#### 🚀 Quick Setup (Recommended)
```bash
# Install the package globally first
npm install -g yuque-mcp-server
# Add to Claude Code with automatic configuration
claude mcp add -s local yuque yuque-mcp-server --env YUQUE_TOKEN=your_yuque_api_token_here
```
The `claude mcp add` command automatically:
- Configures the MCP server in your Claude Code settings
- Handles environment variables securely
- Sets up the proper command structure
#### Manual Configuration (Alternative)
If you prefer manual setup, edit `~/.claude/settings.json`:
```json
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp-server",
"env": {
"YUQUE_TOKEN": "your_yuque_api_token_here"
}
}
}
}
```
#### Local Development Setup
For development from this repository:
```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": ["path/to/this/project/dist/server.js"],
"env": {
"YUQUE_TOKEN": "your_yuque_api_token_here"
}
}
}
}
```
**Important**: After configuration, restart Claude Code to load the server.
### Available Tools
Once loaded, this server provides these MCP tools:
- `yuque_get_user` - Get current user information
- `yuque_get_repos` - List knowledge repositories
- `yuque_get_docs` - List documents in a repository
- `yuque_get_doc` - Get document details
- `yuque_create_doc` - Create new document
- `yuque_update_doc` - Update existing document
- `yuque_delete_doc` - Delete document
- `yuque_search_docs` - Search documents
## Development Commands
```bash
# Build the project
npm run build
# Development mode (watch and rebuild)
npm run dev
# Start the built server
npm start
# Release preparation (creates git tag, checks build)
npm run release
```
## Architecture
### Core Components
1. **src/server.ts** - Main MCP server entry point with two implementations:
- Functional approach with `createServer()` function
- Class-based approach with `YuqueMCPServer` class
- Both provide the same MCP tools interface
2. **src/yuque-client.ts** - Yuque API client:
- Handles HTTP requests to Yuque's API v2
- Provides typed interfaces for Yuque resources (User, Repo, Doc)
- Manages authentication via X-Auth-Token header
- Supports all CRUD operations for documents and repositories
3. **src/index.ts** - Alternative entry point (class-based implementation)
4. **src/tools/** - Modular tool definitions:
- `definitions.ts` - MCP tool definitions and schemas
- `handlers.ts` - Tool implementation logic
5. **src/config/** - Configuration management:
- `index.ts` - Server configuration and validation
## Environment Setup
Required environment variable:
```bash
export YUQUE_TOKEN="your_yuque_api_token"
```
The token must be created from Yuque's developer settings in your account.
## Build Configuration
- **TypeScript**: ES2022 target with ES2022 modules
- **Output**: `dist/` directory
- **Module system**: ES modules (`"type": "module"`)
- **Main entry**: `dist/server.js` (also configured as CLI tool)
## Testing
No test framework is currently configured. The project uses manual testing through MCP client connections.
## Deployment
The server is distributed as an npm package with a binary entry point. It can be:
1. Run directly as a subprocess from MCP clients
2. Integrated into Claude's MCP configuration
3. Used as a command-line tool
## Configuration Files
- `tsconfig.json` - TypeScript configuration
- `.gitignore` - Standard Node.js gitignore
- `claude-mcp-config.json` - Example MCP configuration for Claude
- `scripts/release.js` - Automated release preparation script