search-yuque-docs
Search for documents within Yuque knowledge bases by matching keywords in titles and descriptions to quickly find relevant documentation.
Instructions
在指定的知识库中搜索文档。
会在文档标题和描述中进行关键词匹配。
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | 搜索关键词 | |
| namespace | No | 知识库命名空间 (例如: username/repo)，如果未提供则使用默认命名空间 |
Input Schema (JSON Schema)
{
"properties": {
"namespace": {
"description": "知识库命名空间 (例如: username/repo)，如果未提供则使用默认命名空间",
"type": "string"
},
"query": {
"description": "搜索关键词",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
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;