mn-docs-mcp 0.1.0 → 0.2.0

package/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write  # Required for OIDC
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - uses: pnpm/action-setup@v4
+        with:
+          version: '10'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm publish --provenance --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ""

package/README.md

@@ -24,54 +24,38 @@ pnpm preview  # 预览构建结果
 
 ## 本地MCP搜索
 
-本项目内置一个本地MCPServer，支持stdio与HTTP两种方式，返回纯文本片段，适合AI直接调用。
+本项目内置一个本地MCPServer，支持stdio与HTTPStream两种方式，返回纯文本片段，适合AI直接调用。
 
 embedding模型使用本地BGE-small-zh-v1.5(ONNX)，首次启动会自动下载到 `.mcp/models`。模型文件约95.8MB，向量维度为512。
 
-可选配置：
+### 快速开始(npx)
 
-```
-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
-```
-
-以上两种启动方式会在检测到文档更新时自动重建索引。
+### MCP配置示例(npx)
 
-### 强制重建索引
-
-```bash
-pnpm mcp:force-build
+```json
+{
+  "mcpServers": {
+    "mn-docs": {
+      "command": "npx",
+      "args": [
+        "mn-docs-mcp"
+      ]
+    }
+  }
+}
 ```
 
-### MCP配置
+### MCP配置示例(本地clone)
 
 ```json
 {
   "mcpServers": {
-    "mn-docs": {
-      "command": "pnpm",
+    "mn-docs-local": {
+      "command": "node",
       "args": [
-        "mcp"
+        "mcp/cli.mjs"
       ],
-      "cwd": "path/to/this/repository"
+      "cwd": "/path/to/this/repository"
     }
   }
 }

package/{scripts/mcp → mcp}/cli.mjs

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 const args = process.argv.slice(2);
 
 let mode = 'stdio';
 let port;
 let prebuild = false;
-let silent = true;
+let silent = false;
 
 for (let i = 0; i < args.length; i += 1) {
 	const arg = args[i];
@@ -25,6 +29,10 @@ for (let i = 0; i < args.length; i += 1) {
 		silent = false;
 		continue;
 	}
+	if (arg === '--silent') {
+		silent = true;
+		continue;
+	}
 	if (arg === '--port' && args[i + 1]) {
 		port = args[i + 1];
 		i += 1;
@@ -41,7 +49,8 @@ for (let i = 0; i < args.length; i += 1) {
 				'  --http            启动HTTPStream模式(默认stdio)',
 				'  --port <port>     HTTP端口(默认8788)',
 				'  --prebuild        启动后后台预构建索引',
-				'  --verbose         输出日志(默认静默)',
+				'  --verbose         输出日志(覆盖--silent)',
+				'  --silent          关闭开屏与日志',
 				'  --stdio           显式使用stdio模式',
 			].join('\n') + '\n'
 		);
@@ -49,13 +58,27 @@ for (let i = 0; i < args.length; i += 1) {
 	}
 }
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packagePath = path.join(__dirname, '../package.json');
+let version = '0.0.0';
+try {
+	const raw = fs.readFileSync(packagePath, 'utf-8');
+	version = JSON.parse(raw).version || version;
+} catch {}
+
 if (mode === 'stdio') {
 	process.env.MCP_STDIO = '1';
 	process.env.MCP_SILENT = silent ? '1' : '0';
+	process.env.MN_DOCS_VERSION = version;
+	process.env.MN_DOCS_MODE = 'stdio';
 	if (prebuild) process.env.MCP_PREBUILD = '1';
 	await import('./server.mjs');
 } else {
 	if (port) process.env.MCP_HTTP_PORT = String(port);
+	process.env.MN_DOCS_VERSION = version;
+	process.env.MN_DOCS_MODE = 'http';
+	if (port) process.env.MN_DOCS_PORT = String(port);
 	if (prebuild) process.env.MCP_PREBUILD = '1';
 	await import('./server-http.mjs');
 }

package/{scripts/mcp → mcp}/server-http.mjs

@@ -4,6 +4,29 @@ import { buildIndex, getPaths, isIndexStale, loadIndex, searchDocs } from './lib
 
 const TOOL_NAME = 'search_docs';
 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';
+
+function color(text, code) {
+	if (NO_COLOR) return text;
+	return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+function renderSplash() {
+	if (IS_SILENT) return;
+	const version = process.env.MN_DOCS_VERSION || '0.0.0';
+	const mode = process.env.MN_DOCS_MODE || 'http';
+	const port = process.env.MN_DOCS_PORT || String(PORT);
+	const lines = [
+		color('╭──────────────────────────────────────────────────────────────╮', '38;5;45'),
+		color('│  mn-docs-mcp', '38;5;45') + color(` v${version}`, '38;5;214') + color('  (Charm风格启动)         │', '38;5;45'),
+		color('│                                                              │', '38;5;45'),
+		color(`│  模式: ${mode.padEnd(12)}  端口: ${port.padEnd(6)}  状态: 已启动          │`, '38;5;39'),
+		color('│                                                              │', '38;5;45'),
+		color('╰──────────────────────────────────────────────────────────────╯', '38;5;45'),
+	];
+	process.stdout.write(lines.join('\n') + '\n');
+}
 
 async function ensureIndex() {
 	const { INDEX_PATH } = getPaths();
@@ -67,8 +90,7 @@ await server.start({
 	},
 });
 
-// 不阻塞握手，启动后再初始化索引
-// 默认不自动构建，避免阻塞握手；仅在首次查询时构建
-if (process.env.MCP_PREBUILD === '1') {
-	setTimeout(() => initIndexInBackground(), 1000);
-}
+renderSplash();
+
+// 默认自动构建，异步启动避免阻塞握手
+setTimeout(() => initIndexInBackground(), 0);

package/{scripts/mcp → mcp}/server.mjs

@@ -4,12 +4,33 @@ import { buildIndex, getPaths, isIndexStale, loadIndex, searchDocs } from './lib
 
 const TOOL_NAME = 'search_docs';
 const IS_SILENT = process.env.MCP_SILENT === '1';
+const NO_COLOR = process.env.MCP_NO_COLOR === '1';
 
 function logError(...args) {
 	if (IS_SILENT) return;
 	console.error(...args);
 }
 
+function color(text, code) {
+	if (NO_COLOR) return text;
+	return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+function renderSplash() {
+	if (IS_SILENT) return;
+	const version = process.env.MN_DOCS_VERSION || '0.0.0';
+	const mode = process.env.MN_DOCS_MODE || 'stdio';
+	const lines = [
+		color('╭──────────────────────────────────────────────────────────────╮', '38;5;45'),
+		color('│  mn-docs-mcp', '38;5;45') + color(` v${version}`, '38;5;214') + color('  (Charm风格启动)         │', '38;5;45'),
+		color('│                                                              │', '38;5;45'),
+		color(`│  模式: ${mode.padEnd(12)}  状态: 已启动                         │`, '38;5;39'),
+		color('│                                                              │', '38;5;45'),
+		color('╰──────────────────────────────────────────────────────────────╯', '38;5;45'),
+	];
+	process.stderr.write(lines.join('\n') + '\n');
+}
+
 async function ensureIndex() {
 	const { INDEX_PATH } = getPaths();
 	try {
@@ -85,7 +106,7 @@ await server.start({
 	transportType: 'stdio',
 });
 
-// 默认不自动构建，避免阻塞握手；仅在首次查询时构建
-if (process.env.MCP_PREBUILD === '1') {
-	setTimeout(() => initIndexInBackground(), 1000);
-}
+renderSplash();
+
+// 默认自动构建，异步启动避免阻塞握手
+setTimeout(() => initIndexInBackground(), 0);

package/package.json

@@ -1,19 +1,13 @@
 {
   "name": "mn-docs-mcp",
   "type": "module",
-  "version": "0.1.0",
-  "bin": {
-    "mn-docs-mcp": "scripts/mcp/cli.mjs"
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Temsys-Shen/marginnote-addon-docs.git"
   },
-  "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"
+  "bin": {
+    "mn-docs-mcp": "mcp/cli.mjs"
   },
   "dependencies": {
     "@astrojs/starlight": "^0.37.4",
@@ -26,5 +20,12 @@
     "sharp": "^0.34.2",
     "undici": "^6.19.8",
     "zod": "^3.25.76"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
   }
-}
+}

package/.vscode/extensions.json

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

package/.vscode/launch.json

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