mn-docs-mcp 0.1.0

package/scripts/mcp/server-http.mjs

@@ -0,0 +1,74 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { buildIndex, getPaths, isIndexStale, loadIndex, searchDocs } from './lib.mjs';
+
+const TOOL_NAME = 'search_docs';
+const PORT = Number(process.env.MCP_HTTP_PORT || 8788);
+
+async function ensureIndex() {
+	const { INDEX_PATH } = getPaths();
+	try {
+		await loadIndex();
+		const stale = await isIndexStale();
+		if (stale) {
+			console.error(`检测到文档更新，开始重建索引：${INDEX_PATH}`);
+			await buildIndex();
+		}
+	} catch {
+		console.error(`未找到索引，开始重建：${INDEX_PATH}`);
+		await buildIndex();
+	}
+}
+
+let initPromise = null;
+function initIndexInBackground() {
+	if (!initPromise) {
+		initPromise = ensureIndex().catch((error) => {
+			console.error('索引初始化失败：', error?.message || error);
+		});
+	}
+	return initPromise;
+}
+
+const server = new FastMCP({
+	name: 'marginnote-docs-mcp',
+	version: '0.1.0',
+});
+
+server.addTool({
+	name: TOOL_NAME,
+	description: '在本地文档索引中检索相关文本片段',
+	parameters: z.object({
+		query: z.string().describe('检索关键词或问题'),
+		top_k: z.number().optional().describe('返回片段数量'),
+	}),
+	execute: async ({ query, top_k }) => {
+		const topK = Number(top_k || 5);
+		if (!query.trim()) {
+			return { content: [{ type: 'text', text: 'query不能为空' }] };
+		}
+		if (initPromise) {
+			await initPromise;
+		} else {
+			await initIndexInBackground();
+		}
+		const results = await searchDocs(query, topK);
+		return {
+			content: results.map((text) => ({ type: 'text', text })),
+		};
+	},
+});
+
+await server.start({
+	transportType: 'httpStream',
+	httpStream: {
+		port: PORT,
+		endpoint: '/mcp',
+	},
+});
+
+// 不阻塞握手，启动后再初始化索引
+// 默认不自动构建，避免阻塞握手；仅在首次查询时构建
+if (process.env.MCP_PREBUILD === '1') {
+	setTimeout(() => initIndexInBackground(), 1000);
+}

package/scripts/mcp/server.mjs

@@ -0,0 +1,91 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { buildIndex, getPaths, isIndexStale, loadIndex, searchDocs } from './lib.mjs';
+
+const TOOL_NAME = 'search_docs';
+const IS_SILENT = process.env.MCP_SILENT === '1';
+
+function logError(...args) {
+	if (IS_SILENT) return;
+	console.error(...args);
+}
+
+async function ensureIndex() {
+	const { INDEX_PATH } = getPaths();
+	try {
+		await loadIndex();
+		const stale = await isIndexStale();
+		if (stale) {
+			logError(`检测到文档更新，开始重建索引：${INDEX_PATH}`);
+			await buildIndex();
+		}
+	} catch {
+		logError(`未找到索引，开始重建：${INDEX_PATH}`);
+		await buildIndex();
+	}
+}
+
+let initPromise = null;
+function initIndexInBackground() {
+	if (!initPromise) {
+		initPromise = ensureIndex().catch((error) => {
+			logError('索引初始化失败：', error?.message || error);
+		});
+	}
+	return initPromise;
+}
+
+const logger = IS_SILENT
+	? {
+			debug() {},
+			error() {},
+			info() {},
+			log() {},
+			warn() {},
+		}
+	: {
+			debug: (...args) => console.error(...args),
+			error: (...args) => console.error(...args),
+			info: (...args) => console.error(...args),
+			log: (...args) => console.error(...args),
+			warn: (...args) => console.error(...args),
+		};
+
+const server = new FastMCP({
+	name: 'marginnote-docs-mcp',
+	version: '0.1.0',
+	logger,
+});
+
+server.addTool({
+	name: TOOL_NAME,
+	description: '在本地文档索引中检索相关文本片段',
+	parameters: z.object({
+		query: z.string().describe('检索关键词或问题'),
+		top_k: z.number().optional().describe('返回片段数量'),
+	}),
+	execute: async ({ query, top_k }) => {
+		const topK = Number(top_k || 5);
+		if (!query.trim()) {
+			return { content: [{ type: 'text', text: 'query不能为空' }] };
+		}
+		if (initPromise) {
+			await initPromise;
+		} else {
+			await initIndexInBackground();
+		}
+		const results = await searchDocs(query, topK);
+		return {
+			content: results.map((text) => ({ type: 'text', text })),
+		};
+	},
+});
+
+await server.start({
+	transportType: 'stdio',
+});
+
+// 默认不自动构建，避免阻塞握手；仅在首次查询时构建
+if (process.env.MCP_PREBUILD === '1') {
+	setTimeout(() => initIndexInBackground(), 1000);
+}

package/src/client/jsb-api-footer.ts

@@ -0,0 +1,242 @@
+type JsbApi = {
+	protocol: string;
+	properties: string[];
+	instance_methods: string[];
+	class_methods: string[];
+	export_aliases: Record<string, string>;
+};
+
+const headerUrlLoaders = import.meta.glob('../definitions/**/*.h', {
+	query: '?url',
+	import: 'default',
+});
+
+type PageConfig = {
+	protocol: string;
+	only?: Array<'properties' | 'class' | 'instance' | 'aliases'>;
+};
+
+const GLOBAL_PAGE_PROTOCOL_MAP: Record<string, PageConfig> = {
+	'reference/global/application': { protocol: 'JSBApplication' },
+	'reference/global/database': { protocol: 'JSBMbModelTool' },
+	'reference/global/note': { protocol: 'JSBMbBookNote', only: ['class'] },
+	'reference/global/self': { protocol: 'JSBJSExtension' },
+};
+
+function getPageTitle(): string | null {
+	const h1 = document.querySelector('main h1');
+	const t = (h1 && h1.textContent ? h1.textContent : '').trim();
+	return t || null;
+}
+
+function protocolFromTitle(title: string): string {
+	return `JSB${title.replace(/\s+/g, '')}`;
+}
+
+function selectorGuessFromDecl(decl: string): string {
+	const stripped = decl.split('//', 1)[0].trim().replace(/;$/, '').trim();
+	const noPrefix = stripped.replace(/^[-+]\s*\([^)]*\)\s*/, '').trim();
+	if (!noPrefix.includes(':')) return noPrefix.split(/\s|\(/, 1)[0].trim();
+	const parts = noPrefix.split(':');
+	const labels = parts.slice(0, -1).map((p) => {
+		const tokens = p.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+		return tokens && tokens.length ? tokens[tokens.length - 1] : '';
+	});
+	return `${labels.join(':')}:`;
+}
+
+function jsNameFromObjcDecl(decl: string): string {
+	const stripped = decl.split('//', 1)[0].trim().replace(/;$/, '').trim();
+	const noPrefix = stripped.replace(/^[-+]\s*\([^)]*\)\s*/, '').trim();
+	if (!noPrefix.includes(':')) return noPrefix.split(/\s|\(/, 1)[0].trim();
+	const parts = noPrefix.split(':');
+	const labels = parts.slice(0, -1).map((p) => {
+		const tokens = p.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+		return tokens && tokens.length ? tokens[tokens.length - 1] : '';
+	});
+	if (!labels.length) return '';
+	let js = labels[0];
+	for (const lab of labels.slice(1)) {
+		if (!lab) continue;
+		js += lab[0].toUpperCase() + lab.slice(1);
+	}
+	return js;
+}
+
+function parseProtocolFromHeader(headerText: string, protocolName: string): JsbApi {
+	const lines = headerText.split(/\r?\n/);
+	let inProtocol = false;
+	const properties: string[] = [];
+	const instanceMethods: string[] = [];
+	const classMethods: string[] = [];
+	const exportAliases: Record<string, string> = {};
+	let pendingExportAs: string | null = null;
+
+	for (const raw of lines) {
+		const line = raw.trim();
+		if (!line || line.startsWith('#') || line.startsWith('//')) continue;
+		const start = line.match(/^@protocol\s+(\w+)\b/);
+		if (start) {
+			inProtocol = start[1] === protocolName;
+			pendingExportAs = null;
+			continue;
+		}
+		if (!inProtocol) continue;
+		if (line === '@end') break;
+
+		if (line.startsWith('JSExportAs(')) {
+			const m = line.match(/^JSExportAs\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,/);
+			if (m) pendingExportAs = m[1];
+			continue;
+		}
+		if (line.startsWith('@property')) {
+			const m = line.match(/([A-Za-z_][A-Za-z0-9_]*)\s*;\s*(?:(?:\/\/).*)?$/);
+			if (m) properties.push(m[1]);
+			continue;
+		}
+		if (line.startsWith('- (') || line.startsWith('+ (')) {
+			const jsName = pendingExportAs || jsNameFromObjcDecl(line);
+			const selector = selectorGuessFromDecl(line);
+			if (pendingExportAs) exportAliases[jsName] = selector;
+			pendingExportAs = null;
+			if (line.startsWith('+ (')) classMethods.push(jsName);
+			else instanceMethods.push(jsName);
+			continue;
+		}
+	}
+
+	const uniq = (arr: string[]) => Array.from(new Set(arr.filter(Boolean))).sort();
+	const sortedAliases = Object.fromEntries(
+		Object.entries(exportAliases).sort(([a], [b]) => a.localeCompare(b))
+	) as Record<string, string>;
+
+	return {
+		protocol: protocolName,
+		properties: uniq(properties),
+		instance_methods: uniq(instanceMethods),
+		class_methods: uniq(classMethods),
+		export_aliases: sortedAliases,
+	};
+}
+
+function el<K extends keyof HTMLElementTagNameMap>(
+	name: K,
+	attrs: Record<string, string> = {},
+	children: Node[] = []
+): HTMLElementTagNameMap[K] {
+	const node = document.createElement(name);
+	for (const [k, v] of Object.entries(attrs)) {
+		if (k === 'text') node.textContent = v;
+		else node.setAttribute(k, v);
+	}
+	for (const c of children) node.appendChild(c);
+	return node;
+}
+
+function code(text: string): HTMLElement {
+	return el('code', { text });
+}
+
+function renderApi(container: HTMLElement, api: JsbApi, only?: PageConfig['only']) {
+	const allowed = new Set(only ?? ['properties', 'class', 'instance', 'aliases']);
+	container.textContent = '';
+	if (allowed.has('properties') && api.properties.length) {
+		container.appendChild(el('h3', { text: '属性' }));
+		const ul = el('ul');
+		for (const p of api.properties) ul.appendChild(el('li', {}, [code(p)]));
+		container.appendChild(ul);
+	}
+	if (allowed.has('class') && api.class_methods.length) {
+		container.appendChild(el('h3', { text: '类方法' }));
+		const ul = el('ul');
+		for (const m of api.class_methods) ul.appendChild(el('li', {}, [code(`${m}()`)]));
+		container.appendChild(ul);
+	}
+	if (allowed.has('instance') && api.instance_methods.length) {
+		container.appendChild(el('h3', { text: '实例方法' }));
+		const ul = el('ul');
+		for (const m of api.instance_methods) ul.appendChild(el('li', {}, [code(`${m}()`)]));
+		container.appendChild(ul);
+	}
+	const aliasKeys = Object.keys(api.export_aliases || {});
+	if (allowed.has('aliases') && aliasKeys.length) {
+		container.appendChild(el('h3', { text: 'JSExportAs 别名' }));
+		const table = el('table');
+		const thead = el('thead');
+		const trh = el('tr');
+		trh.appendChild(el('th', { text: 'JS 名' }));
+		trh.appendChild(el('th', { text: 'ObjC selector（推断）' }));
+		thead.appendChild(trh);
+		table.appendChild(thead);
+		const tbody = el('tbody');
+		for (const jsName of aliasKeys) {
+			const tr = el('tr');
+			tr.appendChild(el('td', {}, [code(jsName)]));
+			tr.appendChild(el('td', {}, [code(api.export_aliases[jsName])])); 
+			tbody.appendChild(tr);
+		}
+		table.appendChild(tbody);
+		container.appendChild(table);
+	}
+}
+
+async function loadHeaderText(protocol: string): Promise<{ source: string; text: string } | null> {
+	const entries = Object.keys(headerUrlLoaders);
+	const targetKey = entries.find((k) => k.endsWith(`/${protocol}.h`));
+	if (!targetKey) return null;
+	const url = (await (headerUrlLoaders as any)[targetKey]()) as string;
+	const resp = await fetch(url);
+	if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+	return { source: targetKey.replace('../definitions/', ''), text: await resp.text() };
+}
+
+function getSlug(): string {
+	return location.pathname.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+export function initJsbApiFooter() {
+	const root = document.querySelector<HTMLElement>('[data-jsb-api]');
+	if (!root) return;
+
+	if (!location.pathname.startsWith('/reference/')) {
+		root.style.display = 'none';
+		return;
+	}
+
+	const statusEl = root.querySelector<HTMLElement>('[data-jsb-api-status]')!;
+	const protocolEl = root.querySelector<HTMLElement>('[data-jsb-api-protocol]')!;
+	const sourceEl = root.querySelector<HTMLElement>('[data-jsb-api-source]')!;
+	const bodyEl = root.querySelector<HTMLElement>('[data-jsb-api-body]')!;
+
+	const slug = getSlug();
+	const cfg = GLOBAL_PAGE_PROTOCOL_MAP[slug];
+
+	let protocol: string | null = cfg?.protocol ?? null;
+	if (!protocol) {
+		const title = getPageTitle();
+		if (!title) {
+			root.style.display = 'none';
+			return;
+		}
+		protocol = protocolFromTitle(title);
+	}
+
+	protocolEl.textContent = protocol;
+
+	(async () => {
+		try {
+			const loaded = await loadHeaderText(protocol);
+			if (!loaded) {
+				root.style.display = 'none';
+				return;
+			}
+			const api = parseProtocolFromHeader(loaded.text, protocol);
+			sourceEl.textContent = loaded.source;
+			renderApi(bodyEl, api, cfg?.only);
+			statusEl.textContent = '';
+		} catch (e: any) {
+			// Keep user-facing UI clean: hide the block on errors.
+			root.style.display = 'none';
+		}
+	})().catch(() => {});
+}

package/src/components/Footer.astro

@@ -0,0 +1,57 @@
+---
+import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
+---
+
+<section class="jsb-api sl-markdown-content" data-jsb-api>
+	<details class="jsb-api__details">
+		<summary class="jsb-api__summary">头文件 API 清单</summary>
+		<p class="jsb-api__meta">
+			<span data-jsb-api-status>正在加载…</span>
+		</p>
+		<p class="jsb-api__meta">
+			协议：<code data-jsb-api-protocol>—</code>，来源：<code data-jsb-api-source>—</code>
+		</p>
+		<div data-jsb-api-body></div>
+	</details>
+</section>
+
+<DefaultFooter />
+
+<script>
+	import { initJsbApiFooter } from '../client/jsb-api-footer';
+
+	initJsbApiFooter();
+</script>
+
+<style>
+	@layer starlight.components {
+		.jsb-api {
+			margin-top: 2rem;
+		}
+		.jsb-api__details {
+			border: 1px solid var(--sl-color-gray-6);
+			border-radius: 0.75rem;
+			padding: 0.75rem 1rem;
+			background: color-mix(in srgb, var(--sl-color-gray-7), transparent 70%);
+		}
+		.jsb-api__summary {
+			cursor: pointer;
+			font-weight: 600;
+		}
+		.jsb-api__meta {
+			margin-top: 0.75rem;
+			color: var(--sl-color-gray-3);
+			font-size: var(--sl-text-sm);
+		}
+		.jsb-api__meta code {
+			word-break: break-all;
+		}
+		.jsb-api :global(ul) {
+			margin-top: 0.5rem;
+		}
+		.jsb-api :global(table) {
+			margin-top: 0.75rem;
+			width: 100%;
+		}
+	}
+</style>