mn-docs-mcp 0.1.0

package/.env.example

@@ -0,0 +1,4 @@
+# HuggingFace mirror for model download
+HF_ENDPOINT=https://hf-mirror.com
+# Optional
+# MCP_HTTP_PORT=8788

package/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

package/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,99 @@
+# MarginNote 插件开发文档
+
+**本仓库为 MarginNote 官方插件接口文档与教程站点。**
+
+- **在线文档**：[https://mn-docs.museday.top](https://mn-docs.museday.top)
+- **仓库**：[https://github.com/Temsys-Shen/marginnote-addon-docs](https://github.com/Temsys-Shen/marginnote-addon-docs)
+
+基于 [Starlight](https://starlight.astro.build) 构建，提供完整的 API 参考、渐进式教程与 Cookbook 配方，供开发者为 MarginNote 编写插件时查阅与学习。
+
+## 文档内容
+
+- **API 参考**：全局与入口（JSB、Application、Database）、MarginNote 核心（JSExtension、控制器、脑图、笔记/笔记本/文档模型）、Foundation / UIKit / Utility 等接口说明。
+- **教程**：从快速开始到生命周期、笔记与数据库、脑图与选区、工具栏与命令、原生 UI、存储与文件。
+- **Cookbook 配方**：按任务组织的可运行示例（如批量改标题、导出笔记本、高亮笔记、选区追加为评论、插件设置页等）。
+
+## 本地开发与构建
+
+```bash
+pnpm install
+pnpm dev      # 本地开发，默认 http://localhost:4321
+pnpm build    # 构建静态站点到 ./dist/
+pnpm preview  # 预览构建结果
+```
+
+## 本地MCP搜索
+
+本项目内置一个本地MCPServer，支持stdio与HTTP两种方式，返回纯文本片段，适合AI直接调用。
+
+embedding模型使用本地BGE-small-zh-v1.5(ONNX)，首次启动会自动下载到 `.mcp/models`。模型文件约95.8MB，向量维度为512。
+
+可选配置：
+
+```
+MCP_HTTP_PORT=8788
+```
+
+如果你需要代理或镜像下载模型：
+
+```
+export HTTPS_PROXY=http://127.0.0.1:7890
+export HF_ENDPOINT=https://hf-mirror.com
+```
+
+### 启动stdio版MCP
+
+```bash
+pnpm mcp
+```
+
+### 启动HTTP版MCP
+
+```bash
+pnpm mcp-http
+```
+
+以上两种启动方式会在检测到文档更新时自动重建索引。
+
+### 强制重建索引
+
+```bash
+pnpm mcp:force-build
+```
+
+### MCP配置
+
+```json
+{
+  "mcpServers": {
+    "mn-docs": {
+      "command": "pnpm",
+      "args": [
+        "mcp"
+      ],
+      "cwd": "path/to/this/repository"
+    }
+  }
+}
+```
+
+## 项目结构
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   └── docs/          # 文档正文（入门、教程、Cookbook、API 参考）
+│   └── content.config.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+文档页面为 `src/content/docs/` 下的 `.md` / `.mdx` 文件，侧栏在 `astro.config.mjs` 中配置。
+
+## 声明
+
+**本仓库中的插件接口说明与示例基于 MarginNote 官方提供的 Objective-C 头文件与插件能力整理，作为 MarginNote 官方插件开发文档使用。**

package/astro.config.mjs

@@ -0,0 +1,126 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://astro.build/config
+export default defineConfig({
+	site: 'https://mn-docs.museday.top',
+	integrations: [
+		starlight({
+			title: 'MarginNote 插件开发文档',
+			customCss: ['/src/styles/starlight-overrides.css'],
+			components: {
+				Search: './src/components/Search.astro',
+				Footer: './src/components/Footer.astro',
+			},
+			social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/Temsys-Shen/marginnote-addon-docs' }],
+			sidebar: [
+				{
+					label: '入门',
+					items: [
+						{ label: '快速开始', slug: 'guides/getting-started' },
+					],
+				},
+				{
+					label: '教程与 Cookbook',
+					items: [
+						{ label: '生命周期与窗口', slug: 'guides/lifecycle-and-window' },
+						{ label: '笔记与数据库', slug: 'guides/notes-and-database' },
+						{ label: '脑图与选区', slug: 'guides/mindmap-and-selection' },
+						{ label: '工具栏与命令', slug: 'guides/toolbar-and-commands' },
+						{ label: '快捷键', slug: 'guides/shortcut-keys' },
+						{ label: '原生 UI', slug: 'guides/native-ui' },
+						{ label: '存储与文件', slug: 'guides/storage-and-files' },
+						{ label: '网络请求', slug: 'guides/network-requests' },
+						{
+							label: 'Cookbook 配方',
+							items: [
+								{ label: '批量修改笔记标题', slug: 'guides/cookbook/batch-rename-notes' },
+								{ label: '调用远程 API', slug: 'guides/cookbook/network-api-call' },
+								{ label: '导出当前笔记本', slug: 'guides/cookbook/export-notebook' },
+								{ label: '在脑图中高亮指定笔记', slug: 'guides/cookbook/focus-note-in-mindmap' },
+								{ label: '将选区追加为评论', slug: 'guides/cookbook/append-selection-as-comment' },
+								{ label: '插件设置页', slug: 'guides/cookbook/addon-settings' },
+								{ label: '在插件中嵌入 WebView 面板', slug: 'guides/cookbook/embed-webview-panel' },
+								{ label: 'WebView 内 JS 与插件 JS 双向通信', slug: 'guides/cookbook/webview-bidirectional-js' },
+							],
+						},
+					],
+				},
+				{
+					label: 'API 参考',
+					items: [
+						{
+							label: '全局与入口',
+							items: [
+								{ label: '全局入口对象', slug: 'reference/global/global-variables' },
+								{ label: 'JSB', slug: 'reference/global/jsb' },
+								{ label: 'Application', slug: 'reference/global/application' },
+								{ label: 'SearchManager', slug: 'reference/global/search-manager' },
+								{ label: 'Database', slug: 'reference/global/database' },
+								{ label: 'Note', slug: 'reference/global/note' },
+								{ label: 'PopupMenu', slug: 'reference/global/popup-menu' },
+								{ label: 'PopupMenuItem', slug: 'reference/global/popup-menu-item' },
+								{ label: 'self', slug: 'reference/global/self' },
+							],
+						},
+						{
+							label: 'MarginNote 核心',
+							items: [
+								{ label: 'JSExtension', slug: 'reference/marginnote/jsextension' },
+								{ label: 'StudyController', slug: 'reference/marginnote/study-controller' },
+								{ label: 'NotebookController', slug: 'reference/marginnote/notebook-controller' },
+								{ label: 'ReaderController', slug: 'reference/marginnote/reader-controller' },
+								{ label: 'DocumentController', slug: 'reference/marginnote/document-controller' },
+								{ label: 'MindMapView', slug: 'reference/marginnote/mindmap-view' },
+								{ label: 'OutlineView', slug: 'reference/marginnote/outline-view' },
+								{ label: 'MindMapNode', slug: 'reference/marginnote/mindmap-node' },
+								{ label: 'MbBookNote', slug: 'reference/marginnote/mb-book-note' },
+								{ label: 'NoteComment', slug: 'reference/marginnote/note-comment' },
+								{ label: 'MbTopic', slug: 'reference/marginnote/mb-topic' },
+								{ label: 'MbBook', slug: 'reference/marginnote/mb-book' },
+								{ label: 'MbModelTool', slug: 'reference/marginnote/mb-model-tool' },
+							],
+						},
+						{
+							label: 'Foundation',
+							autogenerate: { directory: 'reference/foundation' },
+						},
+						{
+							label: 'UIKit',
+							autogenerate: { directory: 'reference/uikit' },
+						},
+						{
+							label: 'QuartzCore',
+							autogenerate: { directory: 'reference/quartzcore' },
+						},
+						{
+							label: 'Utility',
+							autogenerate: { directory: 'reference/utility' },
+						},
+						{
+							label: '运行时边界',
+							items: [
+								{ label: 'JavaScript 原生环境', slug: 'reference/js-runtime' },
+								{ label: '隐藏的边界（The Black Box）', slug: 'reference/black-box' },
+							],
+						},
+						{
+							label: '附录',
+							items: [
+								{ label: '内建command清单', slug: 'reference/global/builtin-commands' },
+							],
+						},
+					],
+				},
+				{
+					label: '关于',
+					items: [
+						{ label: '贡献指南', slug: 'guides/contributing' },
+					],
+				},
+			],
+
+		}),
+	],
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "mn-docs-mcp",
+  "type": "module",
+  "version": "0.1.0",
+  "bin": {
+    "mn-docs-mcp": "scripts/mcp/cli.mjs"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "mcp": "MCP_STDIO=1 MCP_SILENT=1 node scripts/mcp/server.mjs",
+    "mcp-http": "node scripts/mcp/server-http.mjs",
+    "mcp:force-build": "node scripts/mcp/build-index.mjs"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.37.4",
+    "@huggingface/transformers": "^3.7.3",
+    "@pagefind/default-ui": "^1.4.0",
+    "astro": "^5.6.1",
+    "dotenv": "^16.4.5",
+    "fastmcp": "^3.34.0",
+    "gray-matter": "^4.0.3",
+    "sharp": "^0.34.2",
+    "undici": "^6.19.8",
+    "zod": "^3.25.76"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+ignoredBuiltDependencies:
+  - onnxruntime-node
+  - protobufjs
+  - tldjs

package/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill-rule="evenodd" d="M81 36 64 0 47 36l-1 2-9-10a6 6 0 0 0-9 9l10 10h-2L0 64l36 17h2L28 91a6 6 0 1 0 9 9l9-10 1 2 17 36 17-36v-2l9 10a6 6 0 1 0 9-9l-9-9 2-1 36-17-36-17-2-1 9-9a6 6 0 1 0-9-9l-9 10v-2Zm-17 2-2 5c-4 8-11 15-19 19l-5 2 5 2c8 4 15 11 19 19l2 5 2-5c4-8 11-15 19-19l5-2-5-2c-8-4-15-11-19-19l-2-5Z" clip-rule="evenodd"/><path d="M118 19a6 6 0 0 0-9-9l-3 3a6 6 0 1 0 9 9l3-3Zm-96 4c-2 2-6 2-9 0l-3-3a6 6 0 1 1 9-9l3 3c3 2 3 6 0 9Zm0 82c-2-2-6-2-9 0l-3 3a6 6 0 1 0 9 9l3-3c3-2 3-6 0-9Zm96 4a6 6 0 0 1-9 9l-3-3a6 6 0 1 1 9-9l3 3Z"/><style>path{fill:#000}@media (prefers-color-scheme:dark){path{fill:#fff}}</style></svg>

package/scripts/mcp/build-index.mjs

@@ -0,0 +1,9 @@
+import { buildIndex } from './lib.mjs';
+
+try {
+	const result = await buildIndex();
+	console.log(`索引构建完成，共${result.count}个片段。文件：${result.path}`);
+} catch (error) {
+	console.error('索引构建失败：', error?.message || error);
+	process.exit(1);
+}

package/scripts/mcp/cli.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+
+let mode = 'stdio';
+let port;
+let prebuild = false;
+let silent = true;
+
+for (let i = 0; i < args.length; i += 1) {
+	const arg = args[i];
+	if (arg === '--http') {
+		mode = 'http';
+		continue;
+	}
+	if (arg === '--stdio') {
+		mode = 'stdio';
+		continue;
+	}
+	if (arg === '--prebuild') {
+		prebuild = true;
+		continue;
+	}
+	if (arg === '--verbose') {
+		silent = false;
+		continue;
+	}
+	if (arg === '--port' && args[i + 1]) {
+		port = args[i + 1];
+		i += 1;
+		continue;
+	}
+	if (arg?.startsWith('--port=')) {
+		port = arg.split('=')[1];
+		continue;
+	}
+	if (arg === '--help' || arg === '-h') {
+		process.stderr.write(
+			[
+				'mn-docs-mcp 使用说明:',
+				'  --http            启动HTTPStream模式(默认stdio)',
+				'  --port <port>     HTTP端口(默认8788)',
+				'  --prebuild        启动后后台预构建索引',
+				'  --verbose         输出日志(默认静默)',
+				'  --stdio           显式使用stdio模式',
+			].join('\n') + '\n'
+		);
+		process.exit(0);
+	}
+}
+
+if (mode === 'stdio') {
+	process.env.MCP_STDIO = '1';
+	process.env.MCP_SILENT = silent ? '1' : '0';
+	if (prebuild) process.env.MCP_PREBUILD = '1';
+	await import('./server.mjs');
+} else {
+	if (port) process.env.MCP_HTTP_PORT = String(port);
+	if (prebuild) process.env.MCP_PREBUILD = '1';
+	await import('./server-http.mjs');
+}

package/scripts/mcp/lib.mjs

@@ -0,0 +1,303 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import matter from 'gray-matter';
+import { env, pipeline } from '@huggingface/transformers';
+import { Agent, ProxyAgent, setGlobalDispatcher } from 'undici';
+import dotenv from 'dotenv';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const ROOT_DIR = path.resolve(__dirname, '../..');
+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';
+
+function logInfo(message) {
+	if (IS_SILENT) return;
+	if (IS_STDIO) {
+		process.stderr.write(`${message}\n`);
+	} else {
+		console.log(message);
+	}
+}
+
+function loadEnv() {
+	dotenv.config({ path: path.join(ROOT_DIR, '.env') });
+}
+
+function setupProxy() {
+	if (proxyInitialized) return;
+	proxyInitialized = true;
+	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);
+	} catch {
+		setGlobalDispatcher(new Agent());
+	}
+}
+
+async function getExtractor() {
+	if (extractorPromise) return extractorPromise;
+	loadEnv();
+	setupProxy();
+	env.cacheDir = path.join(MCP_DIR, 'models');
+	env.allowRemoteModels = true;
+	if (process.env.HF_ENDPOINT) {
+		env.HF_ENDPOINT = process.env.HF_ENDPOINT;
+	}
+
+	const modelDir = path.join(env.cacheDir, 'Xenova', 'bge-small-zh-v1.5');
+	const create = async () => pipeline('feature-extraction', MODEL_ID);
+
+	extractorPromise = (async () => {
+		for (let attempt = 1; attempt <= MAX_EXTRACTOR_RETRIES; attempt += 1) {
+			try {
+				return await create();
+			} catch (error) {
+				const message = error?.message || String(error);
+				const shouldRetry =
+					message.includes('Protobuf parsing failed') ||
+					message.includes('Load model') ||
+					message.includes('fetch failed') ||
+					message.includes('ConnectTimeoutError');
+
+				if (!shouldRetry || attempt === MAX_EXTRACTOR_RETRIES) {
+					throw error;
+				}
+
+				logInfo(`模型下载失败，准备重试(${attempt}/${MAX_EXTRACTOR_RETRIES})...`);
+				await fs.rm(modelDir, { recursive: true, force: true });
+			}
+		}
+		throw new Error('模型加载失败');
+	})();
+
+	return extractorPromise;
+}
+
+export function getPaths() {
+	return { ROOT_DIR, DOCS_DIR, MCP_DIR, INDEX_PATH };
+}
+
+export function normalizeWhitespace(text) {
+	return text.replace(/\s+/g, ' ').trim();
+}
+
+export function stripMarkdown(raw) {
+	let text = raw;
+	text = text.replace(/```[\s\S]*?```/g, ' ');
+	text = text.replace(/`[^`]*`/g, ' ');
+	text = text.replace(/!\[[^\]]*\]\([^)]*\)/g, ' ');
+	text = text.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1');
+	text = text.replace(/<[^>]+>/g, ' ');
+	text = text.replace(/[*_~]+/g, ' ');
+	return normalizeWhitespace(text);
+}
+
+function slugToUrl(slug) {
+	let cleaned = slug.replace(/\\/g, '/');
+	if (cleaned.endsWith('/index')) cleaned = cleaned.slice(0, -'/index'.length);
+	if (cleaned === 'index') cleaned = '';
+	return '/' + cleaned;
+}
+
+function splitByHeadingAndParagraph(content) {
+	const lines = content.split(/\r?\n/);
+	let currentHeading = '';
+	let currentParagraph = [];
+	const chunks = [];
+	const flush = () => {
+		const text = normalizeWhitespace(currentParagraph.join(' '));
+		if (text) {
+			chunks.push({ heading: currentHeading, text });
+		}
+		currentParagraph = [];
+	};
+
+	for (const line of lines) {
+		const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
+		if (headingMatch) {
+			flush();
+			currentHeading = headingMatch[2].trim();
+			continue;
+		}
+		if (line.trim() === '') {
+			flush();
+			continue;
+		}
+		currentParagraph.push(line.trim());
+	}
+	flush();
+	return chunks;
+}
+
+async function walkFiles(dir) {
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	const results = [];
+	for (const entry of entries) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			results.push(...(await walkFiles(full)));
+		} else if (entry.isFile() && /\.(md|mdx)$/i.test(entry.name)) {
+			results.push(full);
+		}
+	}
+	return results;
+}
+
+function makeId(slug, index) {
+	return `${slug}::${index}`;
+}
+
+async function embedText(text) {
+	const extractor = await getExtractor();
+	const output = await extractor(text, { pooling: 'mean', normalize: true });
+	const list = typeof output.tolist === 'function' ? output.tolist() : output;
+	if (Array.isArray(list) && Array.isArray(list[0])) return list[0];
+	if (Array.isArray(list)) return list;
+	throw new Error('向量生成失败，输出格式不正确');
+}
+
+export async function buildIndex() {
+	const { DOCS_DIR, MCP_DIR, INDEX_PATH } = getPaths();
+	await fs.mkdir(MCP_DIR, { recursive: true });
+
+	const files = await walkFiles(DOCS_DIR);
+	const docs = [];
+	const tasks = [];
+	let counter = 0;
+
+	for (const file of files) {
+		const rel = path.relative(DOCS_DIR, file).replace(/\\/g, '/');
+		const slug = rel.replace(/\.(md|mdx)$/i, '');
+		const raw = await fs.readFile(file, 'utf-8');
+		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);
+
+		for (const chunk of chunks) {
+			tasks.push({
+				id: makeId(slug, counter++),
+				url,
+				title: pageTitle,
+				section: chunk.heading,
+				text: chunk.text,
+			});
+		}
+	}
+
+	const total = tasks.length;
+	let done = 0;
+	let lastRender = 0;
+	const renderProgress = (force = false) => {
+		if (IS_SILENT) return;
+		const stream = IS_STDIO ? process.stderr : process.stdout;
+		if (!stream.isTTY) return;
+		const now = Date.now();
+		if (!force && now - lastRender < 120) return;
+		lastRender = now;
+		stream.write(`\r索引构建中：${done}/${total}`);
+	};
+	renderProgress(true);
+
+	for (const task of tasks) {
+		const embedding = await embedText(task.text);
+		docs.push({ ...task, embedding });
+		done += 1;
+		renderProgress(false);
+		// 让出事件循环，避免长时间阻塞MCP握手/请求处理
+		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`);
+	} else {
+		logInfo(`索引构建完成：${done}/${total}`);
+	}
+
+	const payload = {
+		version: 1,
+		generatedAt: new Date().toISOString(),
+		source: {
+			root: 'src/content/docs',
+			split: 'heading+paragraph',
+			model: MODEL_ID,
+			dim: MODEL_DIM,
+		},
+		docs,
+	};
+	await fs.writeFile(INDEX_PATH, JSON.stringify(payload, null, 2));
+	return { count: docs.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数组');
+	}
+	return data;
+}
+
+async function getDocsLatestMtime() {
+	const { DOCS_DIR } = getPaths();
+	const files = await walkFiles(DOCS_DIR);
+	let latest = 0;
+	for (const file of files) {
+		const stat = await fs.stat(file);
+		if (stat.mtimeMs > latest) latest = stat.mtimeMs;
+	}
+	return latest;
+}
+
+export async function isIndexStale() {
+	const index = await loadIndex();
+	const generatedAt = Date.parse(index?.generatedAt || '');
+	if (!Number.isFinite(generatedAt)) return true;
+	const latestDocMtime = await getDocsLatestMtime();
+	return latestDocMtime > generatedAt;
+}
+
+function cosineSimilarity(a, b) {
+	let dot = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < a.length; i++) {
+		dot += a[i] * b[i];
+		normA += a[i] * a[i];
+		normB += b[i] * b[i];
+	}
+	return dot / (Math.sqrt(normA) * Math.sqrt(normB) || 1);
+}
+
+export async function searchDocs(query, topK = 5) {
+	const index = await loadIndex();
+	const queryEmbedding = await embedText(query);
+
+	const scored = index.docs.map((doc) => ({
+		text: doc.text,
+		score: cosineSimilarity(queryEmbedding, doc.embedding),
+	}));
+
+	scored.sort((a, b) => b.score - a.score);
+	return scored.slice(0, topK).map((item) => item.text);
+}