搜索语雀文档

Instructions

Implementation Reference

• src/index.ts:323-392 (handler)

  The handler function for the 'search-yuque-docs' tool. Resolves the namespace, performs the search using the browser-based helper, formats the results as Markdown list, and returns structured content.

  async ({ query, 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 docs = await searchYuqueDocsByBrowser(finalNamespace, query, YUQUE_CONFIG);
  
      if (docs.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `没有找到匹配 "${query}" 的文档。\n\n知识库: ${finalNamespace}`,
            },
          ],
        };
      }
  
      // 格式化输出
      let output = `# 搜索结果\n\n`;
      output += `**关键词**: ${query}\n`;
      output += `**知识库**: ${finalNamespace}\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:310-322 (schema)

  Input schema definition for the tool, including title, description, and Zod validation for 'query' (required string) and 'namespace' (optional string).

    {
      title: "搜索语雀文档",
      description: `在指定的知识库中搜索文档。
  
  会在文档标题和描述中进行关键词匹配。`,
      inputSchema: {
        query: z.string().describe("搜索关键词"),
        namespace: z
          .string()
          .optional()
          .describe("知识库命名空间 (例如: username/repo)，如果未提供则使用默认命名空间"),
      },
    },

• src/index.ts:308-393 (registration)

  Registers the 'search-yuque-docs' tool with the MCP server using server.registerTool, specifying name, schema, and handler.

  server.registerTool(
    "search-yuque-docs",
    {
      title: "搜索语雀文档",
      description: `在指定的知识库中搜索文档。
  
  会在文档标题和描述中进行关键词匹配。`,
      inputSchema: {
        query: z.string().describe("搜索关键词"),
        namespace: z
          .string()
          .optional()
          .describe("知识库命名空间 (例如: username/repo)，如果未提供则使用默认命名空间"),
      },
    },
    async ({ query, 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 docs = await searchYuqueDocsByBrowser(finalNamespace, query, YUQUE_CONFIG);
  
        if (docs.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: `没有找到匹配 "${query}" 的文档。\n\n知识库: ${finalNamespace}`,
              },
            ],
          };
        }
  
        // 格式化输出
        let output = `# 搜索结果\n\n`;
        output += `**关键词**: ${query}\n`;
        output += `**知识库**: ${finalNamespace}\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/lib/browser-api.ts:321-331 (helper)

  Helper function implementing the search logic: lists all documents in the namespace using browser scraping and filters those whose title contains the query keyword (case-insensitive).

  export async function searchYuqueDocsByBrowser(
    namespace: string,
    query: string,
    config: YuqueConfig
  ): Promise<YuqueDocListItem[]> {
    // 先获取所有文档，然后在客户端过滤
    const allDocs = await listYuqueDocsByBrowser(namespace, config);
    return allDocs.filter((doc) =>
      doc.title.toLowerCase().includes(query.toLowerCase())
    );
  }

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

  Utility function to format each document in the search results as a Markdown list item with key metadata.

  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;