列出知识库文档

Instructions

Implementation Reference

• src/index.ts:410-492 (handler)

  The primary handler function for executing the 'list-yuque-docs' tool. It processes the input namespace, validates it, fetches book metadata via API, scrapes the document list using browser automation, formats the output as a markdown list, and returns it as MCP content.

  async ({ namespace }) => {
    try {
      const finalNamespace = namespace || YUQUE_CONFIG.namespace;
  
      if (!finalNamespace) {
        return {
          content: [
            {
              type: "text",
              text: `错误: 请提供知识库命名空间。\n\n示例: "username/repo"`,
            },
          ],
        };
      }
  
      if (!isValidNamespace(finalNamespace)) {
        return {
          content: [
            {
              type: "text",
              text: `错误: 命名空间格式无效。\n\n命名空间应该是 "username/repo" 的格式。`,
            },
          ],
        };
      }
  
      // 获取知识库信息
      const book = await fetchYuqueBook(finalNamespace, YUQUE_CONFIG);
      if (!book) {
        return {
          content: [
            {
              type: "text",
              text: `错误: 无法获取知识库 ${finalNamespace}。\n\n请检查命名空间是否正确，以及是否有访问权限。`,
            },
          ],
        };
      }
  
      // 获取文档列表（使用无头浏览器）
      const docs = await listYuqueDocsByBrowser(finalNamespace, YUQUE_CONFIG);
  
      if (docs.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `知识库 "${book.name}" 暂无文档。`,
            },
          ],
        };
      }
  
      // 格式化输出
      let output = `# 知识库文档列表\n\n`;
      output += `**知识库**: ${book.name}\n`;
      output += `**命名空间**: ${book.namespace}\n`;
      output += `**文档总数**: ${docs.length}\n\n`;
      output += `---\n\n`;
  
      docs.forEach((doc, index) => {
        output += formatDocListItem(doc, index + 1);
      });
  
      return {
        content: [
          {
            type: "text",
            text: output,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `错误: ${error instanceof Error ? error.message : "未知错误"}`,
          },
        ],
      };
    }
  }

• src/index.ts:398-408 (schema)

  Input schema definition for the tool, including title, description, and Zod schema for optional 'namespace' parameter.

    {
      title: "列出知识库文档",
      description: `列出指定知识库中的所有文档。
  
  返回文档列表，包括标题、slug、更新时间等基本信息。`,
      inputSchema: {
        namespace: z
          .string()
          .optional()
          .describe("知识库命名空间 (例如: username/repo)，如果未提供则使用默认命名空间"),
      },

• src/index.ts:396-397 (registration)

  The server.registerTool call that registers the 'list-yuque-docs' tool with its schema and handler.

  server.registerTool(
    "list-yuque-docs",

• src/lib/browser-api.ts:228-316 (helper)

  Core helper function that uses Puppeteer browser automation to scrape the Yuque knowledge base page for the list of documents, parsing links to extract titles and slugs.

  export async function listYuqueDocsByBrowser(
    namespace: string,
    config: YuqueConfig
  ): Promise<YuqueDocListItem[]> {
    let page = null;
    try {
      const browserInstance = await getBrowser();
      page = await browserInstance.newPage();
  
      // 设置 Cookie
      const domain = new URL(config.baseUrl).hostname;
      const cookies = parseCookies(config.cookie, domain);
      await page.setCookie(...cookies);
  
      // 访问知识库页面
      const url = `${config.baseUrl}/${namespace}`;
  
      await page.goto(url, {
        waitUntil: "networkidle2",
        timeout: 30000,
      });
  
      // 等待文档列表加载
      try {
        await page.waitForSelector(".book-item, .doc-item, a[href*='/" + namespace + "/']", { timeout: 10000 });
      } catch (e) {
        // 超时后继续尝试提取
      }
  
      // 提取文档列表
      const docs: any[] = await page.evaluate(() => {
        const items: any[] = [];
        // @ts-ignore
        const links = document.querySelectorAll('a[href]');
        
        links.forEach((link: any) => {
          const href = link.getAttribute('href');
          const text = link.textContent?.trim();
          
          // 匹配知识库文档链接
          if (href && text && href.includes('/') && !href.startsWith('http') && !href.includes('?')) {
            const parts = href.split('/').filter((p: string) => p);
            if (parts.length >= 3) {
              items.push({
                title: text,
                slug: parts[parts.length - 1],
                href: href,
              });
            }
          }
        });
        
        return items;
      });
  
      // 去重
      const uniqueDocs = Array.from(
        new Map(docs.map((doc: any) => [doc.slug, doc])).values()
      );
  
      // 转换为标准格式
      return uniqueDocs.map((doc, index) => ({
        id: index,
        slug: doc.slug,
        title: doc.title,
        description: "",
        user_id: 0,
        book_id: 0,
        format: "markdown",
        public: 1,
        status: 1,
        created_at: new Date().toISOString(),
        updated_at: new Date().toISOString(),
        published_at: new Date().toISOString(),
        word_count: 0,
        cover: null,
        hits: 0,
        likes_count: 0,
        comments_count: 0,
      }));
    } catch (error) {
      // 获取失败，返回空数组
      return [];
    } finally {
      if (page) {
        await page.close();
      }
    }
  }

• src/lib/utils.ts:90-109 (helper)

  Utility function to format each document item in the list as a markdown bullet list with key details like title, slug, word count, update time, etc.

  export function formatDocListItem(doc: YuqueDocListItem, index?: number): string {
    let output = "";
    if (index !== undefined) {
      output += `## ${index}. `;
    }
    output += `${doc.title}\n\n`;
    output += `- **Slug**: ${doc.slug}\n`;
    output += `- **格式**: ${doc.format}\n`;
    output += `- **字数**: ${doc.word_count}\n`;
    output += `- **更新时间**: ${new Date(doc.updated_at).toLocaleString("zh-CN")}\n`;
    output += `- **浏览量**: ${doc.hits}\n`;
  
    if (doc.description) {
      output += `- **描述**: ${doc.description}\n`;
    }
  
    output += `\n`;
  
    return output;
  }