mn-docs-mcp 0.5.1 → 0.6.0

package/README.md

@@ -24,11 +24,30 @@ pnpm preview  # 预览构建结果
 
 ## 本地MCP搜索
 
-本项目内置一个本地MCPServer，支持stdio与HTTPStream两种方式，返回纯文本片段，适合AI直接调用。
+本项目内置一个本地MCPServer，支持stdio与HTTPStream两种方式，面向AI开发问答提供“两步检索”工作流：先发现相关文档，再按需读取全文。
 
 embedding模型使用本地BGE-small-zh-v1.5(ONNX)，首次启动会自动下载到transformers.js默认缓存目录。模型文件约95.8MB，向量维度为512。
 模型下载使用镜像https://hf-mirror.com
 
+### 工具设计
+
+- `discover_docs`
+  - 用于第一步检索。
+  - 支持`hybrid`、`keyword`、`semantic`三种模式。
+  - 返回按文档聚合的结果：`doc_id`、`title`、`url`、`summary`、`matched_by`、`snippets[]`。
+  - 适合回答“先找到该看哪篇文档”。
+
+- `read_doc`
+  - 用于第二步读取全文。
+  - 支持通过`doc_id`、`slug`或`url`读取指定文档。
+  - 返回完整文档内容与章节标题，适合继续回答“完整字段有哪些”“完整API是什么”“示例代码在哪里”。
+
+### 推荐调用顺序
+
+1. 先调用`discover_docs`定位最相关文档。
+2. 若结果里已出现明确目标文档，再调用`read_doc`读取整篇文档。
+3. 当问题涉及字段、方法、返回值、完整API或完整示例时，不要只依赖片段，应该继续读取全文。
+
 ### 快速开始(npx)
 
 ### MCP配置示例(npx)

package/mcp/lib.mjs

@@ -11,6 +11,38 @@ const __dirname = path.dirname(__filename);
 
 const DEFAULT_ROOT = path.resolve(__dirname, '..');
 
+const MODEL_ID = 'Xenova/bge-small-zh-v1.5';
+const MODEL_DIM = 512;
+const INDEX_VERSION = 2;
+const MAX_EXTRACTOR_RETRIES = 3;
+
+const QUERY_SYNONYMS = {
+	mn: ['marginnote'],
+	marginnote: ['mn'],
+	卡片: ['笔记', '脑图节点'],
+	笔记: ['卡片'],
+	字段: ['属性'],
+	属性: ['字段'],
+	方法: ['函数'],
+	comment: ['comments', '评论'],
+	comments: ['comment', '评论'],
+	markdown: ['md'],
+};
+
+const DOC_ALIAS_HINTS = {
+	MbBookNote: ['笔记', '卡片', '脑图节点', 'mn卡片', '笔记对象'],
+	Note: ['创建笔记', '新建笔记', '笔记工厂'],
+	MbTopic: ['笔记本', '脑图', '卡片组'],
+	MbBook: ['文档', '书本', '书籍'],
+};
+
+let extractorPromise;
+let proxyInitialized = false;
+const IS_STDIO = process.env.MCP_STDIO === '1';
+const IS_SILENT = process.env.MCP_SILENT === '1';
+const NO_COLOR = process.env.MCP_NO_COLOR === '1';
+let lastDownloadProgress = -1;
+
 function resolveRootDir() {
 	const envRoot = (process.env.MN_DOCS_ROOT || '').trim();
 	if (envRoot && fsSyncExists(path.join(envRoot, 'src', 'content', 'docs'))) return envRoot;
@@ -35,16 +67,6 @@ const DOCS_DIR = path.join(ROOT_DIR, 'src', 'content', 'docs');
 const MCP_DIR = path.join(ROOT_DIR, '.mcp');
 const INDEX_PATH = path.join(MCP_DIR, 'index.json');
 
-const MODEL_ID = 'Xenova/bge-small-zh-v1.5';
-const MODEL_DIM = 512;
-let extractorPromise;
-let proxyInitialized = false;
-const MAX_EXTRACTOR_RETRIES = 3;
-const IS_STDIO = process.env.MCP_STDIO === '1';
-const IS_SILENT = process.env.MCP_SILENT === '1';
-const NO_COLOR = process.env.MCP_NO_COLOR === '1';
-let lastDownloadProgress = -1;
-
 function logInfo(message) {
 	if (IS_SILENT) return;
 	if (IS_STDIO) {
@@ -74,12 +96,11 @@ function formatBytes(bytes) {
 function logDownloadProgress(info) {
 	if (IS_SILENT) return;
 	if (info?.status === 'download') {
-		// 清除当前行（如果之前有内容）
 		if (IS_STDIO) {
-			process.stderr.write('\r\x1b[K'); // 清除整行
+			process.stderr.write('\r\x1b[K');
 			process.stderr.write(color('开始下载模型...', '38;5;45') + '\n');
 		} else {
-			process.stdout.write('\r\x1b[K'); // 清除整行
+			process.stdout.write('\r\x1b[K');
 			console.log(color('开始下载模型...', '38;5;45'));
 		}
 		lastDownloadProgress = -1;
@@ -94,7 +115,7 @@ function logDownloadProgress(info) {
 		const suffix = loaded && total ? ` ${loaded}/${total}` : '';
 		const line = `${color('模型下载进度', '38;5;45')}: ${pct}%${suffix}`;
 		if (IS_STDIO) {
-			process.stderr.write(`\r\x1b[K${line}`); // \x1b[K 清除从光标到行尾的内容
+			process.stderr.write(`\r\x1b[K${line}`);
 			if (pct === 100) process.stderr.write('\n');
 		} else {
 			process.stdout.write(`\r\x1b[K${line}`);
@@ -109,8 +130,7 @@ function setupProxy() {
 	const proxyUrl = (process.env.HTTPS_PROXY || process.env.HTTP_PROXY || process.env.ALL_PROXY || '').trim();
 	if (!proxyUrl) return;
 	try {
-		const dispatcher = new ProxyAgent(proxyUrl);
-		setGlobalDispatcher(dispatcher);
+		setGlobalDispatcher(new ProxyAgent(proxyUrl));
 	} catch {
 		setGlobalDispatcher(new Agent());
 	}
@@ -119,21 +139,14 @@ function setupProxy() {
 async function getExtractor() {
 	if (extractorPromise) return extractorPromise;
 	setupProxy();
-	
-	// 抑制 Hugging Face Transformers 的警告输出
+
 	env.allowRemoteModels = true;
-	env.disableProgressBars = true; // 禁用库自带的进度条
-	env.disableSymlinksWarning = true; // 禁用符号链接警告
+	env.disableProgressBars = true;
+	env.disableSymlinksWarning = true;
 	env.remoteHost = 'https://hf-mirror.com';
-	
-	// 设置日志级别为 error，避免 info/warning 级别日志干扰
-	if (!process.env.LOG_LEVEL) {
-		process.env.LOG_LEVEL = 'error';
-	}
-	
-	const modelDir = env.cacheDir
-		? path.join(env.cacheDir, 'Xenova', 'bge-small-zh-v1.5')
-		: null;
+	if (!process.env.LOG_LEVEL) process.env.LOG_LEVEL = 'error';
+
+	const modelDir = env.cacheDir ? path.join(env.cacheDir, 'Xenova', 'bge-small-zh-v1.5') : null;
 	const create = async () =>
 		pipeline('feature-extraction', MODEL_ID, {
 			progress_callback: logDownloadProgress,
@@ -151,16 +164,11 @@ async function getExtractor() {
 					message.includes('fetch failed') ||
 					message.includes('ConnectTimeoutError');
 
-				if (!shouldRetry || attempt === MAX_EXTRACTOR_RETRIES) {
-					throw error;
-				}
+				if (!shouldRetry || attempt === MAX_EXTRACTOR_RETRIES) throw error;
 
-				// 清除上次的进度状态，为重试做准备
 				lastDownloadProgress = -1;
 				logInfo(`模型下载失败，准备重试(${attempt}/${MAX_EXTRACTOR_RETRIES})...`);
-				if (modelDir) {
-					await fs.rm(modelDir, { recursive: true, force: true });
-				}
+				if (modelDir) await fs.rm(modelDir, { recursive: true, force: true });
 			}
 		}
 		throw new Error('模型加载失败');
@@ -239,8 +247,69 @@ async function walkFiles(dir) {
 	return results;
 }
 
-function makeId(slug, index) {
-	return `${slug}::${index}`;
+function makeDocId(slug) {
+	return slug;
+}
+
+function makeChunkId(docId, index) {
+	return `${docId}::${index}`;
+}
+
+function uniqueList(values) {
+	const set = new Set();
+	for (const value of values) {
+		const normalized = normalizeWhitespace(String(value || ''));
+		if (!normalized) continue;
+		set.add(normalized);
+	}
+	return [...set];
+}
+
+function normalizeForMatch(text) {
+	return normalizeWhitespace(String(text || '').toLowerCase())
+		.replace(/[`"'“”‘’()[\]{}:;,.!?/\\|<>+=_*&#%-]+/g, ' ')
+		.trim();
+}
+
+function splitIdentifierWords(text) {
+	const value = String(text || '')
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+		.replace(/[_/-]+/g, ' ');
+	return uniqueList(value.split(/\s+/));
+}
+
+function tokenize(text) {
+	const normalized = normalizeForMatch(text);
+	if (!normalized) return [];
+	const matches = normalized.match(/[a-z0-9]+|[\p{Script=Han}]+/gu);
+	if (!matches) return [];
+	const tokens = [];
+	for (const match of matches) {
+		tokens.push(match);
+		if (/^[\p{Script=Han}]+$/u.test(match) && match.length >= 2) {
+			for (let i = 0; i < match.length - 1; i += 1) {
+				tokens.push(match.slice(i, i + 2));
+			}
+		}
+	}
+	return uniqueList(tokens);
+}
+
+function buildAliasCandidates({ title, slug, description, headings, plainText }) {
+	const slugTail = slug.split('/').pop() || slug;
+	const firstSentence = plainText.split(/[。！？.!?]/)[0] || '';
+	const aliases = [
+		title,
+		description,
+		slugTail,
+		slugTail.replace(/-/g, ' '),
+		...splitIdentifierWords(title),
+		...splitIdentifierWords(slugTail),
+		...headings.slice(0, 6),
+		firstSentence,
+		...(DOC_ALIAS_HINTS[title] || []),
+	];
+	return uniqueList(aliases);
 }
 
 async function embedText(text) {
@@ -257,9 +326,9 @@ export async function buildIndex() {
 	await fs.mkdir(MCP_DIR, { recursive: true });
 
 	const files = await walkFiles(DOCS_DIR);
-	const docs = [];
+	const documents = [];
+	const chunks = [];
 	const tasks = [];
-	let counter = 0;
 
 	for (const file of files) {
 		const rel = path.relative(DOCS_DIR, file).replace(/\\/g, '/');
@@ -268,20 +337,44 @@ export async function buildIndex() {
 		const parsed = matter(raw);
 		const frontmatterTitle = typeof parsed.data?.title === 'string' ? parsed.data.title.trim() : '';
 		const frontmatterSlug = typeof parsed.data?.slug === 'string' ? parsed.data.slug.trim() : '';
-		const content = stripMarkdown(parsed.content);
-		const chunks = splitByHeadingAndParagraph(content);
-		const pageTitle = frontmatterTitle || (chunks[0]?.heading || slug.split('/').pop() || slug);
-		const url = slugToUrl(frontmatterSlug || slug);
+		const frontmatterDescription =
+			typeof parsed.data?.description === 'string' ? parsed.data.description.trim() : '';
+		const rawMarkdown = parsed.content.trim();
+		const plainText = stripMarkdown(parsed.content);
+		const chunkEntries = splitByHeadingAndParagraph(rawMarkdown);
+		const pageTitle = frontmatterTitle || (chunkEntries[0]?.heading || slug.split('/').pop() || slug);
+		const finalSlug = frontmatterSlug || slug;
+		const url = slugToUrl(finalSlug);
+		const headings = uniqueList(chunkEntries.map((chunk) => chunk.heading).filter(Boolean));
+		const docId = makeDocId(finalSlug);
+		const aliases = buildAliasCandidates({
+			title: pageTitle,
+			slug: finalSlug,
+			description: frontmatterDescription,
+			headings,
+			plainText,
+		});
+
+		documents.push({
+			doc_id: docId,
+			title: pageTitle,
+			slug: finalSlug,
+			url,
+			description: frontmatterDescription,
+			aliases,
+			headings,
+			raw_markdown: rawMarkdown,
+			plain_text: plainText,
+		});
 
-		for (const chunk of chunks) {
+		chunkEntries.forEach((chunk, index) => {
 			tasks.push({
-				id: makeId(slug, counter++),
-				url,
-				title: pageTitle,
+				chunk_id: makeChunkId(docId, index),
+				doc_id: docId,
 				section: chunk.heading,
 				text: chunk.text,
 			});
-		}
+		});
 	}
 
 	const total = tasks.length;
@@ -300,14 +393,12 @@ export async function buildIndex() {
 
 	for (const task of tasks) {
 		const embedding = await embedText(task.text);
-		docs.push({ ...task, embedding });
+		chunks.push({ ...task, embedding });
 		done += 1;
 		renderProgress(false);
-		// 让出事件循环，避免长时间阻塞MCP握手/请求处理
-		if (done % 10 === 0) {
-			await new Promise((resolve) => setImmediate(resolve));
-		}
+		if (done % 10 === 0) await new Promise((resolve) => setImmediate(resolve));
 	}
+
 	if (IS_STDIO ? process.stderr.isTTY : process.stdout.isTTY) {
 		const stream = IS_STDIO ? process.stderr : process.stdout;
 		stream.write(`\r索引构建完成：${done}/${total}\n`);
@@ -316,26 +407,34 @@ export async function buildIndex() {
 	}
 
 	const payload = {
-		version: 1,
+		version: INDEX_VERSION,
 		generatedAt: new Date().toISOString(),
 		source: {
 			root: 'src/content/docs',
-			split: 'heading+paragraph',
+			split: 'document+heading+paragraph',
 			model: MODEL_ID,
 			dim: MODEL_DIM,
 		},
-		docs,
+		documents,
+		chunks,
 	};
 	await fs.writeFile(INDEX_PATH, JSON.stringify(payload, null, 2));
-	return { count: docs.length, path: INDEX_PATH };
+	return {
+		documentCount: documents.length,
+		chunkCount: chunks.length,
+		path: INDEX_PATH,
+	};
 }
 
 export async function loadIndex() {
 	const { INDEX_PATH } = getPaths();
 	const raw = await fs.readFile(INDEX_PATH, 'utf-8');
 	const data = JSON.parse(raw);
-	if (!Array.isArray(data?.docs)) {
-		throw new Error('索引文件格式错误，未找到docs数组');
+	if (data?.version !== INDEX_VERSION) {
+		throw new Error('索引版本过旧，需要重建');
+	}
+	if (!Array.isArray(data?.documents) || !Array.isArray(data?.chunks)) {
+		throw new Error('索引文件格式错误，未找到documents或chunks数组');
 	}
 	return data;
 }
@@ -363,7 +462,7 @@ function cosineSimilarity(a, b) {
 	let dot = 0;
 	let normA = 0;
 	let normB = 0;
-	for (let i = 0; i < a.length; i++) {
+	for (let i = 0; i < a.length; i += 1) {
 		dot += a[i] * b[i];
 		normA += a[i] * a[i];
 		normB += b[i] * b[i];
@@ -371,15 +470,221 @@ function cosineSimilarity(a, b) {
 	return dot / (Math.sqrt(normA) * Math.sqrt(normB) || 1);
 }
 
-export async function searchDocs(query, topK = 5) {
+function expandQueryTerms(query) {
+	const normalizedQuery = normalizeForMatch(query);
+	const baseTerms = tokenize(query);
+	const expanded = new Set(baseTerms);
+	for (const key of Object.keys(QUERY_SYNONYMS)) {
+		if (normalizedQuery.includes(normalizeForMatch(key))) {
+			expanded.add(key);
+		}
+	}
+	for (const term of baseTerms) {
+		for (const synonym of QUERY_SYNONYMS[term] || []) {
+			expanded.add(synonym);
+		}
+	}
+	return [...expanded];
+}
+
+function countContains(text, terms) {
+	const normalized = normalizeForMatch(text);
+	if (!normalized) return 0;
+	let count = 0;
+	for (const term of terms) {
+		if (normalized.includes(normalizeForMatch(term))) count += 1;
+	}
+	return count;
+}
+
+function makeSnippetSummary(text, maxLength = 180) {
+	const compact = normalizeWhitespace(text);
+	if (compact.length <= maxLength) return compact;
+	return `${compact.slice(0, maxLength - 1)}...`;
+}
+
+function scoreDocument(doc, query, terms) {
+	const title = normalizeForMatch(doc.title);
+	const slug = normalizeForMatch(doc.slug);
+	const url = normalizeForMatch(doc.url);
+	const aliasText = normalizeForMatch(doc.aliases.join(' '));
+	const headingText = normalizeForMatch(doc.headings.join(' '));
+	const bodyText = normalizeForMatch(doc.plain_text);
+	const exactQuery = normalizeForMatch(query);
+	let score = 0;
+	const matchedBy = new Set();
+
+	if (exactQuery && (title === exactQuery || slug === exactQuery || url === exactQuery)) {
+		score += 12;
+		matchedBy.add('title_exact');
+	}
+
+	for (const alias of doc.aliases) {
+		if (normalizeForMatch(alias) === exactQuery && exactQuery) {
+			score += 10;
+			matchedBy.add('alias_match');
+			break;
+		}
+	}
+
+	if (exactQuery && slug.includes(exactQuery)) {
+		score += 6;
+		matchedBy.add('slug_match');
+	}
+	if (exactQuery && title.includes(exactQuery) && title !== exactQuery) {
+		score += 5;
+		matchedBy.add('title_match');
+	}
+	if (exactQuery && aliasText.includes(exactQuery)) {
+		score += 4;
+		matchedBy.add('alias_match');
+	}
+
+	const titleHits = countContains(doc.title, terms);
+	const slugHits = countContains(doc.slug, terms);
+	const aliasHits = countContains(doc.aliases.join(' '), terms);
+	const headingHits = countContains(doc.headings.join(' '), terms);
+	const bodyHits = countContains(doc.plain_text, terms);
+
+	if (titleHits > 0) matchedBy.add('title_match');
+	if (slugHits > 0) matchedBy.add('slug_match');
+	if (aliasHits > 0) matchedBy.add('alias_match');
+	if (bodyHits > 0) matchedBy.add('keyword_body');
+
+	score += titleHits * 2.8;
+	score += slugHits * 2.4;
+	score += aliasHits * 2.2;
+	score += headingHits * 1.4;
+	score += Math.min(bodyHits, 6) * 0.8;
+
+	if (/^[a-z][a-z0-9]+(?:[A-Z][a-z0-9]+)+$/.test(query.trim()) && doc.title === query.trim()) {
+		score += 8;
+		matchedBy.add('title_exact');
+	}
+
+	return { score, matchedBy: [...matchedBy] };
+}
+
+function scoreChunk(chunk, terms, queryEmbedding) {
+	const keywordHits = countContains(chunk.text, terms) + countContains(chunk.section, terms) * 0.8;
+	let score = keywordHits * 1.1;
+	let semanticScore = null;
+	if (queryEmbedding) {
+		semanticScore = cosineSimilarity(queryEmbedding, chunk.embedding);
+		score += Math.max(semanticScore, 0) * 4;
+	}
+	return {
+		score,
+		semanticScore,
+	};
+}
+
+function buildDocSummary(snippets) {
+	if (!snippets.length) return '';
+	const joined = snippets
+		.slice(0, 2)
+		.map((snippet) => snippet.text)
+		.join(' ');
+	return makeSnippetSummary(joined, 220);
+}
+
+export async function discoverDocs(query, options = {}) {
+	const trimmedQuery = normalizeWhitespace(query || '');
+	if (!trimmedQuery) throw new Error('query不能为空');
+
+	const topK = Number(options.topK || 5);
+	const mode = ['hybrid', 'keyword', 'semantic'].includes(options.mode) ? options.mode : 'hybrid';
 	const index = await loadIndex();
-	const queryEmbedding = await embedText(query);
+	const terms = expandQueryTerms(trimmedQuery);
+	const queryEmbedding = mode === 'keyword' ? null : await embedText(trimmedQuery);
+	const chunkMap = new Map();
+
+	for (const chunk of index.chunks) {
+		const result = scoreChunk(chunk, terms, mode === 'semantic' || mode === 'hybrid' ? queryEmbedding : null);
+		const list = chunkMap.get(chunk.doc_id) || [];
+		list.push({
+			section: chunk.section || '',
+			text: chunk.text,
+			score: result.score,
+			semanticScore: result.semanticScore,
+		});
+		chunkMap.set(chunk.doc_id, list);
+	}
+
+	const results = index.documents
+		.map((doc) => {
+			const docScore = scoreDocument(doc, trimmedQuery, terms);
+			const scoredChunks = (chunkMap.get(doc.doc_id) || [])
+				.filter((item) => item.score > 0 || item.semanticScore === null || item.semanticScore > 0.18)
+				.sort((a, b) => b.score - a.score);
+
+			const bestChunk = scoredChunks[0];
+			let score = docScore.score;
+			if (bestChunk) {
+				score += bestChunk.score;
+				if (bestChunk.semanticScore && bestChunk.semanticScore > 0.25) {
+					docScore.matchedBy.push('semantic');
+				}
+			}
+			if (mode === 'semantic' && bestChunk?.semanticScore != null) {
+				score += Math.max(bestChunk.semanticScore, 0) * 3;
+			}
+
+			const snippets = scoredChunks.slice(0, 3).map((item) => ({
+				section: item.section,
+				text: makeSnippetSummary(item.text, 260),
+				score: Number(item.score.toFixed(4)),
+			}));
+
+			return {
+				doc_id: doc.doc_id,
+				title: doc.title,
+				url: doc.url,
+				score,
+				summary: buildDocSummary(snippets),
+				matched_by: uniqueList(docScore.matchedBy),
+				snippets,
+			};
+		})
+		.filter((doc) => doc.score > 0)
+		.sort((a, b) => b.score - a.score)
+		.slice(0, topK)
+		.map((doc) => ({
+			...doc,
+			score: Number(doc.score.toFixed(4)),
+		}));
+
+	return {
+		query: trimmedQuery,
+		mode,
+		results,
+	};
+}
 
-	const scored = index.docs.map((doc) => ({
-		text: doc.text,
-		score: cosineSimilarity(queryEmbedding, doc.embedding),
-	}));
+function findDocument(index, identifier) {
+	const docId = normalizeWhitespace(identifier.doc_id || '');
+	const slug = normalizeWhitespace(identifier.slug || '');
+	const url = normalizeWhitespace(identifier.url || '');
 
-	scored.sort((a, b) => b.score - a.score);
-	return scored.slice(0, topK).map((item) => item.text);
+	return index.documents.find((doc) => {
+		if (docId && doc.doc_id === docId) return true;
+		if (slug && doc.slug === slug) return true;
+		if (url && doc.url === url) return true;
+		return false;
+	});
+}
+
+export async function readDoc(identifier = {}) {
+	const index = await loadIndex();
+	const doc = findDocument(index, identifier);
+	if (!doc) {
+		throw new Error('未找到匹配的文档，请提供有效的doc_id、slug或url');
+	}
+	return {
+		doc_id: doc.doc_id,
+		title: doc.title,
+		url: doc.url,
+		headings: doc.headings,
+		content: doc.raw_markdown,
+	};
 }

package/mcp/server-http.mjs

@@ -1,8 +1,9 @@
 import { FastMCP } from 'fastmcp';
 import { z } from 'zod';
-import { buildIndex, getPaths, isIndexStale, loadIndex, searchDocs } from './lib.mjs';
+import { buildIndex, discoverDocs, getPaths, isIndexStale, loadIndex, readDoc } from './lib.mjs';
 
-const TOOL_NAME = 'search_docs';
+const DISCOVER_TOOL_NAME = 'discover_docs';
+const READ_TOOL_NAME = 'read_doc';
 const PORT = Number(process.env.MCP_HTTP_PORT || 8788);
 const IS_SILENT = process.env.MCP_SILENT === '1';
 const NO_COLOR = process.env.MCP_NO_COLOR === '1';
@@ -72,7 +73,7 @@ async function ensureIndex() {
 			await buildIndex();
 		}
 	} catch {
-		console.error(`未找到索引，开始重建：${INDEX_PATH}`);
+		console.error(`未找到可用索引，开始重建：${INDEX_PATH}`);
 		await buildIndex();
 	}
 }
@@ -87,32 +88,101 @@ function initIndexInBackground() {
 	return initPromise;
 }
 
+async function ensureReady() {
+	if (initPromise) {
+		await initPromise;
+	} else {
+		await initIndexInBackground();
+	}
+}
+
+function renderJsonPayload(payload) {
+	return {
+		structuredContent: payload,
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify(payload, null, 2),
+			},
+		],
+	};
+}
+
+function renderError(message) {
+	return {
+		content: [{ type: 'text', text: message }],
+		isError: true,
+	};
+}
+
 const server = new FastMCP({
 	name: 'marginnote-docs-mcp',
 	version: '0.1.0',
 });
 
 server.addTool({
-	name: TOOL_NAME,
-	description: '在本地文档索引中检索相关文本片段',
+	name: DISCOVER_TOOL_NAME,
+	description:
+		[
+			'发现与当前问题最相关的MarginNote文档。这个工具适合做第一步检索：先找对文档，再决定是否读取全文。',
+			'推荐用法：当用户问某个类、对象、字段、方法、返回值、示例、完整API时，先调用discover_docs。',
+			'如果结果已经出现明确目标文档，再调用read_doc读取整篇文档，不要只依赖片段回答“字段有哪些”“完整API是什么”。',
+			'当query中包含类名、方法名、属性名时，优先使用mode=hybrid或mode=keyword。',
+			'返回结果按文档聚合，每项包含doc_id、title、url、summary、matched_by和snippets，便于继续跳转。',
+		].join('\n'),
 	parameters: z.object({
-		query: z.string().describe('检索关键词或问题'),
-		top_k: z.number().optional().describe('返回片段数量'),
+		query: z.string().describe('用户的问题、关键词或API名，例如“mn卡片字段”“MbBookNote comments”“创建新笔记的方法”'),
+		top_k: z
+			.number()
+			.int()
+			.min(1)
+			.max(20)
+			.optional()
+			.describe('返回文档数量，默认5。通常3到8足够。'),
+		mode: z
+			.enum(['hybrid', 'keyword', 'semantic'])
+			.optional()
+			.describe('检索模式。默认hybrid；keyword适合精确API名；semantic适合自然语言描述。'),
 	}),
-	execute: async ({ query, top_k }) => {
-		const topK = Number(top_k || 5);
-		if (!query.trim()) {
-			return { content: [{ type: 'text', text: 'query不能为空' }] };
+	execute: async ({ query, top_k, mode }) => {
+		try {
+			await ensureReady();
+			const payload = await discoverDocs(query, {
+				topK: top_k,
+				mode,
+			});
+			return renderJsonPayload(payload);
+		} catch (error) {
+			return renderError(error?.message || 'discover_docs执行失败');
 		}
-		if (initPromise) {
-			await initPromise;
-		} else {
-			await initIndexInBackground();
+	},
+});
+
+server.addTool({
+	name: READ_TOOL_NAME,
+	description:
+		[
+			'读取某篇MarginNote文档的全文。这个工具适合做第二步检索：在discover_docs确认目标文档后，拉取完整字段、方法、返回值和示例。',
+			'推荐优先使用discover_docs返回的doc_id调用read_doc，避免slug或url歧义。',
+			'当用户追问“还有哪些字段”“完整API”“相关示例”“完整方法签名”时，应继续调用read_doc，而不是只根据片段猜测。',
+		].join('\n'),
+	parameters: z
+		.object({
+			doc_id: z.string().optional().describe('discover_docs返回的doc_id，最推荐使用'),
+			slug: z.string().optional().describe('文档slug，例如reference/marginnote/mb-book-note'),
+			url: z.string().optional().describe('文档URL，例如/reference/marginnote/mb-book-note/'),
+		})
+		.refine((value) => Boolean(value.doc_id || value.slug || value.url), {
+			message: 'doc_id、slug、url至少需要提供一个',
+		}),
+	execute: async ({ doc_id, slug, url }) => {
+		try {
+			await ensureReady();
+			const payload = await readDoc({ doc_id, slug, url });
+			return renderJsonPayload(payload);
+		} catch (error) {
+			return renderError(error?.message || 'read_doc执行失败');
 		}
-		const results = await searchDocs(query, topK);
-		return {
-			content: results.map((text) => ({ type: 'text', text })),
-		};
 	},
 });
 
@@ -126,5 +196,4 @@ await server.start({
 
 renderSplash();
 
-// 默认自动构建，异步启动避免阻塞握手
 setTimeout(() => initIndexInBackground(), 0);

package/mcp/server.mjs

@@ -1,8 +1,9 @@
 import { FastMCP } from 'fastmcp';
 import { z } from 'zod';
-import { buildIndex, getPaths, isIndexStale, loadIndex, searchDocs } from './lib.mjs';
+import { buildIndex, discoverDocs, getPaths, isIndexStale, loadIndex, readDoc } from './lib.mjs';
 
-const TOOL_NAME = 'search_docs';
+const DISCOVER_TOOL_NAME = 'discover_docs';
+const READ_TOOL_NAME = 'read_doc';
 const IS_SILENT = process.env.MCP_SILENT === '1';
 const NO_COLOR = process.env.MCP_NO_COLOR === '1';
 
@@ -26,7 +27,6 @@ function stringWidth(text) {
 	for (const char of plain) {
 		const code = char.codePointAt(0);
 		if (!code) continue;
-		// CJK / Fullwidth / Wide characters
 		const isWide =
 			(code >= 0x1100 && code <= 0x115f) ||
 			(code === 0x2329 || code === 0x232a) ||
@@ -76,7 +76,7 @@ async function ensureIndex() {
 			await buildIndex();
 		}
 	} catch {
-		logError(`未找到索引，开始重建：${INDEX_PATH}`);
+		logError(`未找到可用索引，开始重建：${INDEX_PATH}`);
 		await buildIndex();
 	}
 }
@@ -91,6 +91,33 @@ function initIndexInBackground() {
 	return initPromise;
 }
 
+async function ensureReady() {
+	if (initPromise) {
+		await initPromise;
+	} else {
+		await initIndexInBackground();
+	}
+}
+
+function renderJsonPayload(payload) {
+	return {
+		structuredContent: payload,
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify(payload, null, 2),
+			},
+		],
+	};
+}
+
+function renderError(message) {
+	return {
+		content: [{ type: 'text', text: message }],
+		isError: true,
+	};
+}
+
 const logger = IS_SILENT
 	? {
 			debug() {},
@@ -114,26 +141,68 @@ const server = new FastMCP({
 });
 
 server.addTool({
-	name: TOOL_NAME,
-	description: '在本地文档索引中检索相关文本片段',
+	name: DISCOVER_TOOL_NAME,
+	description:
+		[
+			'发现与当前问题最相关的MarginNote文档。这个工具适合做第一步检索：先找对文档，再决定是否读取全文。',
+			'推荐用法：当用户问某个类、对象、字段、方法、返回值、示例、完整API时，先调用discover_docs。',
+			'如果结果已经出现明确目标文档，再调用read_doc读取整篇文档，不要只依赖片段回答“字段有哪些”“完整API是什么”。',
+			'当query中包含类名、方法名、属性名时，优先使用mode=hybrid或mode=keyword。',
+			'返回结果按文档聚合，每项包含doc_id、title、url、summary、matched_by和snippets，便于继续跳转。',
+		].join('\n'),
 	parameters: z.object({
-		query: z.string().describe('检索关键词或问题'),
-		top_k: z.number().optional().describe('返回片段数量'),
+		query: z.string().describe('用户的问题、关键词或API名，例如“mn卡片字段”“MbBookNote comments”“创建新笔记的方法”'),
+		top_k: z
+			.number()
+			.int()
+			.min(1)
+			.max(20)
+			.optional()
+			.describe('返回文档数量，默认5。通常3到8足够。'),
+		mode: z
+			.enum(['hybrid', 'keyword', 'semantic'])
+			.optional()
+			.describe('检索模式。默认hybrid；keyword适合精确API名；semantic适合自然语言描述。'),
 	}),
-	execute: async ({ query, top_k }) => {
-		const topK = Number(top_k || 5);
-		if (!query.trim()) {
-			return { content: [{ type: 'text', text: 'query不能为空' }] };
+	execute: async ({ query, top_k, mode }) => {
+		try {
+			await ensureReady();
+			const payload = await discoverDocs(query, {
+				topK: top_k,
+				mode,
+			});
+			return renderJsonPayload(payload);
+		} catch (error) {
+			return renderError(error?.message || 'discover_docs执行失败');
 		}
-		if (initPromise) {
-			await initPromise;
-		} else {
-			await initIndexInBackground();
+	},
+});
+
+server.addTool({
+	name: READ_TOOL_NAME,
+	description:
+		[
+			'读取某篇MarginNote文档的全文。这个工具适合做第二步检索：在discover_docs确认目标文档后，拉取完整字段、方法、返回值和示例。',
+			'推荐优先使用discover_docs返回的doc_id调用read_doc，避免slug或url歧义。',
+			'当用户追问“还有哪些字段”“完整API”“相关示例”“完整方法签名”时，应继续调用read_doc，而不是只根据片段猜测。',
+		].join('\n'),
+	parameters: z
+		.object({
+			doc_id: z.string().optional().describe('discover_docs返回的doc_id，最推荐使用'),
+			slug: z.string().optional().describe('文档slug，例如reference/marginnote/mb-book-note'),
+			url: z.string().optional().describe('文档URL，例如/reference/marginnote/mb-book-note/'),
+		})
+		.refine((value) => Boolean(value.doc_id || value.slug || value.url), {
+			message: 'doc_id、slug、url至少需要提供一个',
+		}),
+	execute: async ({ doc_id, slug, url }) => {
+		try {
+			await ensureReady();
+			const payload = await readDoc({ doc_id, slug, url });
+			return renderJsonPayload(payload);
+		} catch (error) {
+			return renderError(error?.message || 'read_doc执行失败');
 		}
-		const results = await searchDocs(query, topK);
-		return {
-			content: results.map((text) => ({ type: 'text', text })),
-		};
 	},
 });
 
@@ -143,5 +212,4 @@ await server.start({
 
 renderSplash();
 
-// 默认自动构建，异步启动避免阻塞握手
 setTimeout(() => initIndexInBackground(), 0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mn-docs-mcp",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Temsys-Shen/marginnote-addon-docs.git"

package/src/content/docs/reference/global/global-variables.md

@@ -1,32 +1,238 @@
 ---
 title: 全局入口对象（Global Variables）
-description: MarginNote 插件运行时直接注入到 JS 环境的全局变量清单与用法入口。
+description: MarginNote插件运行时直接注入到JS环境的全局变量清单与用法入口。
 ---
+本页列出MarginNote插件运行时可直接使用的全局变量名。这些全局名对应的对象通常是单例、工厂对象、或系统级入口。
 
-本页列出 **MarginNote 插件运行时可直接使用的全局变量名**（你在 JS 里直接输入即可访问）。这些全局名对应的对象通常是 **单例**、**工厂对象**、或 **系统级入口**。
-
-> 说明：本页仅做“可发现性索引”。每个对象的完整属性/方法请进入对应参考页。
-
-## 全局变量清单
-
-| 全局变量名 | 对应原生类/说明 | 核心用途 | 参考 |
-| :--- | :--- | :--- | :--- |
-| `JSB` | Bridge | 定义类、日志输出、require | [JSB](/reference/global/jsb/) |
-| `self` | `JSExtension` 实例 | 当前插件实例（仅实例方法内可用） | [self](/reference/global/self/) |
-| `Application` | `JSBApplication` | App 全局单例：路径、HUD、openURL、studyController | [Application](/reference/global/application/) |
-| `Database` | `MbModelTool` 单例 | 笔记/笔记本/文档数据库访问 | [Database](/reference/global/database/) |
-| `Note` | 笔记工厂（全局） | 创建新笔记：`Note.createWithTitleNotebookDocument(...)` | [Note](/reference/global/note/) |
-| `UndoManager` | `JSBUndoManager` 单例 | undoGrouping/撤销重做 | [UndoManager](/reference/utility/undo-manager/) |
-| `SpeechManager` | `JSBSpeechManager` 单例 | 语音朗读 | [SpeechManager](/reference/utility/speech-manager/) |
-| `ZipArchive` | `JSBZipArchive` | zip 压缩/解压 | [ZipArchive](/reference/utility/zip-archive/) |
-| `MenuController` | 菜单控制器（全局） | 表格化菜单视图 | [MenuController](/reference/utility/menu-controller/) |
-| `PopupMenu` | 弹出菜单（全局） | 轻量弹出菜单 | [PopupMenu](/reference/global/popup-menu/) |
-| `PopupMenuItem` | 弹出菜单项（全局） | 菜单项对象 | [PopupMenuItem](/reference/global/popup-menu-item/) |
-| `SQLiteDatabase` | `JSBSQLiteDatabase` | SQLite 连接器 | [SQLiteDatabase](/reference/utility/sqlite-database/) |
-| `NSFileManager` | `NSFileManager` 单例 | 文件管理 | [NSFileManager](/reference/foundation/ns-file-manager/)（待补齐：全量接口） |
-| `NSUserDefaults` | `NSUserDefaults` 单例 | 偏好设置存储 | [NSUserDefaults](/reference/foundation/ns-user-defaults/) |
-| `NSNotificationCenter` | `NSNotificationCenter` 单例 | 通知中心 | [NSNotificationCenter](/reference/foundation/ns-notification-center/) |
-| `UIApplication` | `UIApplication` 单例 | iOS 应用级入口（openURL 等） | [UIApplication](/reference/uikit/uiapplication/) |
-| `UIPasteboard` | `UIPasteboard` 单例 | 系统剪贴板 | [UIPasteboard](/reference/uikit/uipasteboard/) |
-| `UIDevice` | `UIDevice` 单例 | 设备信息 | [UIDevice](/reference/uikit/uidevice/) |
-| `UIScreen` | `UIScreen` 单例 | 屏幕信息 | [UIScreen](/reference/uikit/uiscreen/) |
+> 说明：本页仅做索引。每个对象的完整属性/方法请进入对应参考页。
+
+## 全局与入口
+
+<table>
+  <colgroup>
+    <col style="width:28%">
+    <col style="width:44%">
+    <col style="width:28%">
+  </colgroup>
+  <thead>
+    <tr>
+      <th>名称</th>
+      <th>用途</th>
+      <th>参考</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>JSB</code></td>
+      <td>Bridge入口</td>
+      <td><a href="/reference/global/jsb/">JSB</a></td>
+    </tr>
+    <tr>
+      <td><code>self</code></td>
+      <td>当前实例上下文</td>
+      <td><a href="/reference/global/self/">self</a></td>
+    </tr>
+    <tr>
+      <td><code>Application</code></td>
+      <td>App入口</td>
+      <td><a href="/reference/global/application/">Application</a></td>
+    </tr>
+    <tr>
+      <td><code>Database</code></td>
+      <td>数据库访问</td>
+      <td><a href="/reference/global/database/">Database</a></td>
+    </tr>
+    <tr>
+      <td><code>Note</code></td>
+      <td>创建笔记</td>
+      <td><a href="/reference/global/note/">Note</a></td>
+    </tr>
+    <tr>
+      <td><code>PopupMenu</code></td>
+      <td>弹出菜单</td>
+      <td><a href="/reference/global/popup-menu/">PopupMenu</a></td>
+    </tr>
+    <tr>
+      <td><code>PopupMenuItem</code></td>
+      <td>菜单项</td>
+      <td><a href="/reference/global/popup-menu-item/">PopupMenuItem</a></td>
+    </tr>
+    <tr>
+      <td><code>SearchManager</code></td>
+      <td>搜索与索引（<code>Application.sharedInstance().searchManager</code>）</td>
+      <td><a href="/reference/global/search-manager/">SearchManager</a></td>
+    </tr>
+  </tbody>
+</table>
+
+## MarginNote核心
+
+下表覆盖 `/reference/marginnote/`目录下的全部参考页，用于快速定位对象定义与用法入口。
+
+<table>
+  <colgroup>
+    <col style="width:28%">
+    <col style="width:44%">
+    <col style="width:28%">
+  </colgroup>
+  <thead>
+    <tr>
+      <th>名称</th>
+      <th>用途</th>
+      <th>参考</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>StudyController</code></td>
+      <td>学习入口（从<code>Application</code>获取）</td>
+      <td><a href="/reference/marginnote/study-controller/">StudyController</a></td>
+    </tr>
+    <tr>
+      <td><code>NotebookController</code></td>
+      <td>脑图与大纲（从<code>StudyController</code>获取）</td>
+      <td><a href="/reference/marginnote/notebook-controller/">NotebookController</a></td>
+    </tr>
+    <tr>
+      <td><code>ReaderController</code></td>
+      <td>阅读区控制（从<code>StudyController</code>获取）</td>
+      <td><a href="/reference/marginnote/reader-controller/">ReaderController</a></td>
+    </tr>
+    <tr>
+      <td><code>DocumentController</code></td>
+      <td>单文档控制（从<code>ReaderController</code>获取）</td>
+      <td><a href="/reference/marginnote/document-controller/">DocumentController</a></td>
+    </tr>
+    <tr>
+      <td><code>MindMapView</code></td>
+      <td>脑图视图（从<code>NotebookController</code>获取）</td>
+      <td><a href="/reference/marginnote/mindmap-view/">MindMapView</a></td>
+    </tr>
+    <tr>
+      <td><code>OutlineView</code></td>
+      <td>大纲视图</td>
+      <td><a href="/reference/marginnote/outline-view/">OutlineView</a></td>
+    </tr>
+    <tr>
+      <td><code>MindMapNode</code></td>
+      <td>脑图节点（来自<code>MindMapView</code>/选中列表）</td>
+      <td><a href="/reference/marginnote/mindmap-node/">MindMapNode</a></td>
+    </tr>
+    <tr>
+      <td><code>MbBookNote</code></td>
+      <td>笔记对象</td>
+      <td><a href="/reference/marginnote/mb-book-note/">MbBookNote</a></td>
+    </tr>
+    <tr>
+      <td><code>MbTopic</code></td>
+      <td>笔记本对象</td>
+      <td><a href="/reference/marginnote/mb-topic/">MbTopic</a></td>
+    </tr>
+    <tr>
+      <td><code>MbBook</code></td>
+      <td>文档对象</td>
+      <td><a href="/reference/marginnote/mb-book/">MbBook</a></td>
+    </tr>
+    <tr>
+      <td><code>NoteComment</code></td>
+      <td>评论结构</td>
+      <td><a href="/reference/marginnote/note-comment/">NoteComment</a></td>
+    </tr>
+    <tr>
+      <td><code>JSExtension</code></td>
+      <td>插件主类</td>
+      <td><a href="/reference/marginnote/jsextension/">JSExtension</a></td>
+    </tr>
+    <tr>
+      <td><code>MbModelTool</code></td>
+      <td>数据库协议</td>
+      <td><a href="/reference/marginnote/mb-model-tool/">MbModelTool</a></td>
+    </tr>
+  </tbody>
+</table>
+
+## Utility
+
+<table>
+  <colgroup>
+    <col style="width:28%">
+    <col style="width:44%">
+    <col style="width:28%">
+  </colgroup>
+  <thead>
+    <tr>
+      <th>名称</th>
+      <th>用途</th>
+      <th>参考</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>UndoManager</code></td>
+      <td>撤销与刷新</td>
+      <td><a href="/reference/utility/undo-manager/">UndoManager</a></td>
+    </tr>
+    <tr>
+      <td><code>SpeechManager</code></td>
+      <td>语音朗读</td>
+      <td><a href="/reference/utility/speech-manager/">SpeechManager</a></td>
+    </tr>
+    <tr>
+      <td><code>ZipArchive</code></td>
+      <td>ZIP压缩解压</td>
+      <td><a href="/reference/utility/zip-archive/">ZipArchive</a></td>
+    </tr>
+    <tr>
+      <td><code>MenuController</code></td>
+      <td>菜单视图</td>
+      <td><a href="/reference/utility/menu-controller/">MenuController</a></td>
+    </tr>
+    <tr>
+      <td><code>SQLiteDatabase</code></td>
+      <td>执行SQL</td>
+      <td><a href="/reference/utility/sqlite-database/">SQLiteDatabase</a></td>
+    </tr>
+    <tr>
+      <td><code>SQLiteResultSet</code></td>
+      <td>读取结果</td>
+      <td><a href="/reference/utility/sqlite-result-set/">SQLiteResultSet</a></td>
+    </tr>
+    <tr>
+      <td><code>SQLiteStatement</code></td>
+      <td>缓存语句</td>
+      <td><a href="/reference/utility/sqlite-statement/">SQLiteStatement</a></td>
+    </tr>
+  </tbody>
+</table>
+
+## 其它对象
+
+本页不再列出Foundation/UIKit/QuartzCore与JavaScript原生环境的全量对象清单；它们的参考条目请在侧边栏对应分组中查阅。下面仅给出常见入口与例子。
+
+### Foundation
+
+多数Foundation类可直接使用（通常以类/单例形式导出）。例：
+
+- [NSFileManager](/reference/foundation/ns-file-manager/)
+- [NSData](/reference/foundation/ns-data/)
+- [NSTimer](/reference/foundation/ns-timer/)
+
+### UIKit
+
+可用UIKit搭原生UI（视图/控制器/控件等）。例：
+
+- [UIApplication](/reference/uikit/uiapplication/)
+- [UIViewController](/reference/uikit/uiview-controller/)
+- [UIButton](/reference/uikit/uibutton/)
+
+### QuartzCore
+
+图层/动画相关能力主要来自QuartzCore。例：
+
+- [CALayer](/reference/quartzcore/calayer/)
+- [CAShapeLayer](/reference/quartzcore/cashape-layer/)
+- [CATransaction](/reference/quartzcore/catransaction/)
+
+### JavaScript原生环境
+
+插件运行在JavaScriptCore中，标准JavaScript内置对象可用但非浏览器环境；详见：[JavaScript原生环境](/reference/js-runtime/)