yuque-mcp-plus 0.2.0

package/RELEASE.md

@@ -0,0 +1,105 @@
+# Release Guide
+
+默认参考日期格式使用 `YYYY-MM-DD`。
+
+## 发布前检查
+
+发布前至少完成这些检查：
+
+- 确认 [package.json](/Users/program/code/code_mcp/yuque-mcp-plus/package.json) 的 `version` 已更新
+- 确认 [CHANGELOG.md](/Users/program/code/code_mcp/yuque-mcp-plus/CHANGELOG.md) 已补充本次变更
+- 确认 [README.md](/Users/program/code/code_mcp/yuque-mcp-plus/README.md) 和 [README.en.md](/Users/program/code/code_mcp/yuque-mcp-plus/README.en.md) 已同步
+- 运行 `npm run check`
+- 运行 `npm test`
+
+## 建议发布步骤
+
+### 1. 更新版本
+
+修改：
+
+- [package.json](/Users/program/code/code_mcp/yuque-mcp-plus/package.json)
+- [CHANGELOG.md](/Users/program/code/code_mcp/yuque-mcp-plus/CHANGELOG.md)
+
+建议规则：
+
+- 新增功能但不破坏兼容：升 `minor`
+- 纯文档或修复小问题：升 `patch`
+- 存在不兼容改动：升 `major`
+
+### 2. 执行本地验证
+
+```bash
+npm run check
+npm test
+```
+
+如果这一步失败，不要发布。
+
+### 3. 执行真实联调回归
+
+建议至少回归这些能力：
+
+- `yuque_get_default_repository`
+- `yuque_get_repository_toc_tree`
+- `yuque_create_toc_node`
+- `yuque_delete_toc_node`
+- `yuque_create_doc`
+- `yuque_move_document`
+
+如果这次改动涉及团队、版本或统计，再额外回归对应工具。
+
+### 4. 更新发布说明
+
+在 [CHANGELOG.md](/Users/program/code/code_mcp/yuque-mcp-plus/CHANGELOG.md) 中记录：
+
+- 新增工具
+- 行为变化
+- 兼容性说明
+- 已验证范围
+
+### 5. 打标签或对外发布
+
+如果你的发布流程需要 Git 标签，建议格式：
+
+```bash
+git tag v0.2.0
+```
+
+如果后续接 npm 或内部制品库，再补对应发布命令。
+
+## 升级说明模板
+
+可以按这个格式写每次升级说明：
+
+```md
+## v0.2.0
+
+### Added
+- 新增 `yuque_delete_toc_node`
+- 新增根节点自动删除策略
+
+### Changed
+- README 改为默认中文
+- 补充中英文速查示例
+
+### Verified
+- npm run check
+- npm test
+- 真实 Yuque 联调
+```
+
+## 回滚建议
+
+如果新版本有问题，优先按这个顺序处理：
+
+- 切回上一个稳定版本的代码
+- 恢复上一个稳定版本的 `package.json` 版本号和文档
+- 重新验证 `npm run check` 与 `npm test`
+- 如果问题来自真实 API 行为变化，优先在 [README.md](/Users/program/code/code_mcp/yuque-mcp-plus/README.md) 记录临时限制
+
+## 当前版本
+
+当前项目版本：
+
+- `0.2.0`

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "yuque-mcp-plus",
+  "version": "0.2.0",
+  "description": "Enhanced Yuque MCP server with default repo, TOC tree, parentUuid, and move support.",
+  "author": "michaeljou <864738795@qq.com>",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/MichealJou/yuque-mcp-plus.git"
+  },
+  "homepage": "https://github.com/MichealJou/yuque-mcp-plus#readme",
+  "bugs": {
+    "url": "https://github.com/MichealJou/yuque-mcp-plus/issues"
+  },
+  "keywords": [
+    "mcp",
+    "yuque",
+    "model-context-protocol",
+    "docs",
+    "knowledge-base"
+  ],
+  "bin": {
+    "yuque-mcp-plus": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "RELEASE.md"
+  ],
+  "scripts": {
+    "start": "node ./src/index.js",
+    "check": "node --eval \"import('./src/server.js')\"",
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "axios": "^1.12.2"
+  }
+}

package/src/config.js

@@ -0,0 +1,37 @@
+const DEFAULT_API_BASE_URL = "https://www.yuque.com/api/v2";
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_RETRIES = 3;
+
+function readNumberEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) {
+    return fallback;
+  }
+
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) ? value : fallback;
+}
+
+export function getConfig() {
+  const token = process.env.YUQUE_TOKEN;
+
+  return {
+    token,
+    apiBaseUrl: process.env.YUQUE_API_BASE_URL || DEFAULT_API_BASE_URL,
+    timeoutMs: readNumberEnv("YUQUE_TIMEOUT_MS", DEFAULT_TIMEOUT_MS),
+    retries: readNumberEnv("YUQUE_RETRIES", DEFAULT_RETRIES),
+    defaultRepoId: process.env.YUQUE_DEFAULT_REPO_ID || "",
+    defaultRepoNamespace: process.env.YUQUE_DEFAULT_REPO_NAMESPACE || ""
+  };
+}
+
+export function validateConfig(config = getConfig()) {
+  if (!config.token) {
+    return {
+      isValid: false,
+      error: "Missing YUQUE_TOKEN"
+    };
+  }
+
+  return { isValid: true };
+}

package/src/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { startServer } from "./server.js";
+
+async function main() {
+  await startServer();
+}
+
+const isDirectRun =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error("Failed to start yuque-mcp-plus:", error);
+    process.exit(1);
+  });
+}

package/src/server.js

@@ -0,0 +1,55 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError
+} from "@modelcontextprotocol/sdk/types.js";
+import { getConfig, validateConfig } from "./config.js";
+import { TOOLS, handleTool } from "./tools.js";
+import { YuqueClient } from "./yuque-client.js";
+
+export function createServer() {
+  const config = getConfig();
+  const validation = validateConfig(config);
+
+  if (!validation.isValid) {
+    throw new Error(validation.error);
+  }
+
+  const server = new Server(
+    {
+      name: "yuque-mcp-plus",
+      version: "0.2.0"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+
+  const client = new YuqueClient(config);
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+      return await handleTool(request.params.name, request.params.arguments || {}, client);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new McpError(ErrorCode.InternalError, message);
+    }
+  });
+
+  return server;
+}
+
+export async function startServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}