mn-docs-mcp 0.3.2 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +2 -1
  2. package/mcp/lib.mjs +7 -13
  3. package/package.json +1 -2
  4. package/src/content/docs/reference/js-runtime.md +72 -16
  5. package/.env.example +0 -4
package/README.md CHANGED
@@ -26,7 +26,8 @@ pnpm preview # 预览构建结果
26
26
 
27
27
  本项目内置一个本地MCPServer，支持stdio与HTTPStream两种方式，返回纯文本片段，适合AI直接调用。
28
28
 
29
- embedding模型使用本地BGE-small-zh-v1.5(ONNX)，首次启动会自动下载到 `.mcp/models`。模型文件约95.8MB，向量维度为512。
29
+ embedding模型使用本地BGE-small-zh-v1.5(ONNX)，首次启动会自动下载到transformers.js默认缓存目录。模型文件约95.8MB，向量维度为512。
30
+ 模型下载使用固定remoteHost镜像https://hf-mirror.com，不再依赖.env配置。
30
31
 
31
32
  ### 快速开始(npx)
32
33
 
package/mcp/lib.mjs CHANGED
@@ -5,7 +5,6 @@ import { fileURLToPath } from 'node:url';
5
5
  import matter from 'gray-matter';
6
6
  import { env, pipeline } from '@huggingface/transformers';
7
7
  import { Agent, ProxyAgent, setGlobalDispatcher } from 'undici';
8
- import dotenv from 'dotenv';
9
8
 
10
9
  const __filename = fileURLToPath(import.meta.url);
11
10
  const __dirname = path.dirname(__filename);
@@ -104,10 +103,6 @@ function logDownloadProgress(info) {
104
103
  }
105
104
  }
106
105
 
107
- function loadEnv() {
108
- dotenv.config({ path: path.join(ROOT_DIR, '.env') });
109
- }
110
-
111
106
  function setupProxy() {
112
107
  if (proxyInitialized) return;
113
108
  proxyInitialized = true;
@@ -123,25 +118,22 @@ function setupProxy() {
123
118
 
124
119
  async function getExtractor() {
125
120
  if (extractorPromise) return extractorPromise;
126
- loadEnv();
127
121
  setupProxy();
128
122
 
129
123
  // 抑制 Hugging Face Transformers 的警告输出
130
- env.cacheDir = path.join(MCP_DIR, 'models');
131
124
  env.allowRemoteModels = true;
132
125
  env.disableProgressBars = true; // 禁用库自带的进度条
133
126
  env.disableSymlinksWarning = true; // 禁用符号链接警告
127
+ env.remoteHost = 'https://hf-mirror.com';
134
128
 
135
129
  // 设置日志级别为 error，避免 info/warning 级别日志干扰
136
130
  if (!process.env.LOG_LEVEL) {
137
131
  process.env.LOG_LEVEL = 'error';
138
132
  }
139
133
 
140
- if (process.env.HF_ENDPOINT) {
141
- env.HF_ENDPOINT = process.env.HF_ENDPOINT;
142
- }
143
-
144
- const modelDir = path.join(env.cacheDir, 'Xenova', 'bge-small-zh-v1.5');
134
+ const modelDir = env.cacheDir
135
+ ? path.join(env.cacheDir, 'Xenova', 'bge-small-zh-v1.5')
136
+ : null;
145
137
  const create = async () =>
146
138
  pipeline('feature-extraction', MODEL_ID, {
147
139
  progress_callback: logDownloadProgress,
@@ -166,7 +158,9 @@ async function getExtractor() {
166
158
  // 清除上次的进度状态，为重试做准备
167
159
  lastDownloadProgress = -1;
168
160
  logInfo(`模型下载失败，准备重试(${attempt}/${MAX_EXTRACTOR_RETRIES})...`);
169
- await fs.rm(modelDir, { recursive: true, force: true });
161
+ if (modelDir) {
162
+ await fs.rm(modelDir, { recursive: true, force: true });
163
+ }
170
164
  }
171
165
  }
172
166
  throw new Error('模型加载失败');
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "mn-docs-mcp",
3
3
  "type": "module",
4
- "version": "0.3.2",
4
+ "version": "0.5.0",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "https://github.com/Temsys-Shen/marginnote-addon-docs.git"
@@ -14,7 +14,6 @@
14
14
  "@huggingface/transformers": "^3.7.3",
15
15
  "@pagefind/default-ui": "^1.4.0",
16
16
  "astro": "^5.6.1",
17
- "dotenv": "^16.4.5",
18
17
  "fastmcp": "^3.34.0",
19
18
  "gray-matter": "^4.0.3",
20
19
  "sharp": "^0.34.2",
package/src/content/docs/reference/js-runtime.md CHANGED
@@ -1,28 +1,84 @@
1
1
  ---
2
- title: JavaScript 原生环境
3
- description: MarginNote 插件运行时的 JavaScriptCore 能力边界与常见误区。
2
+ title: JavaScript原生环境
3
+ description: MarginNote插件运行时的JavaScriptCore能力边界、内置对象与常见误区。
4
4
  ---
5
+ MarginNote插件运行在JavaScriptCore中，而不是浏览器环境。这意味着标准JavaScript内置对象可用，但浏览器相关API通常不存在，且宿主会额外注入自己的对象与能力。
5
6
 
6
- MarginNote 插件的 JS 运行环境是 **JavaScriptCore**（不是浏览器）。因此很多“浏览器 JS”里理所当然的能力，在插件里可能不存在或行为不同。
7
+ ## 内置对象一览
7
8
 
8
- ## 你仍然拥有的标准能力
9
+ 下表列出当前运行环境中可见的标准JavaScript内置对象/函数/常量。
9
10
 
10
- - `Math` / `Date` / `JSON` / `RegExp`
11
- - 基本语法与原型链
12
- - 通过 JSB 导出的 Objective‑C 对象与方法（本项目的 API 参考主体）
11
+ | 对象 | 说明 |
12
+ | -------------------------------------------------------------------------------------------------------------------- | --------------------------- |
13
+ | [AggregateError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/AggregateError) | 多重Promise错误的聚合类型 |
14
+ | [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) | 数组类型 |
15
+ | [ArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) | 原始二进制缓冲区 |
16
+ | [Atomics](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Atomics) | 共享内存的原子操作 |
17
+ | [BigInt](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigInt) | 任意精度整数 |
18
+ | [BigInt64Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array) | 64位有符号BigInt类型化数组 |
19
+ | [BigUint64Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array) | 64位无符号BigInt类型化数组 |
20
+ | [Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) | 布尔包装对象 |
21
+ | [DataView](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/DataView) | ArrayBuffer的通用视图 |
22
+ | [Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date) | 日期与时间 |
23
+ | [Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error) | 基础错误类型 |
24
+ | [EvalError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/EvalError) | eval相关错误类型 |
25
+ | [FinalizationRegistry](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) | 对象回收后的清理回调注册表 |
26
+ | [Float16Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Float16Array) | 16位浮点类型化数组 |
27
+ | [Float32Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Float32Array) | 32位浮点类型化数组 |
28
+ | [Float64Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Float64Array) | 64位浮点类型化数组 |
29
+ | [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function) | 函数对象 |
30
+ | [Int8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int8Array) | 8位有符号整型数组 |
31
+ | [Int16Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int16Array) | 16位有符号整型数组 |
32
+ | [Int32Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array) | 32位有符号整型数组 |
33
+ | [Intl](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl) | 国际化格式化API |
34
+ | [Iterator](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Iterator) | 迭代器基类与协议入口 |
35
+ | [JSON](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON) | JSON解析与序列化 |
36
+ | [Map](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map) | 键值映射集合 |
37
+ | [Math](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Math) | 数学常量与函数 |
38
+ | [Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | 数字包装对象 |
39
+ | [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) | 对象基类 |
40
+ | [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) | 异步结果表示 |
41
+ | [Proxy](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) | 对象拦截与代理 |
42
+ | [RangeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RangeError) | 越界错误类型 |
43
+ | [ReferenceError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | 引用错误类型 |
44
+ | [Reflect](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Reflect) | 反射API |
45
+ | [RegExp](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp) | 正则表达式 |
46
+ | [Set](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set) | 去重集合 |
47
+ | [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | 字符串包装对象 |
48
+ | [Symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol) | 唯一标识符 |
49
+ | [SyntaxError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) | 语法错误类型 |
50
+ | [TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError) | 类型错误类型 |
51
+ | [URIError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/URIError) | URI处理错误类型 |
52
+ | [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | 8位无符号整型数组 |
53
+ | [Uint8ClampedArray](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray) | 8位无符号整型数组(范围钳制) |
54
+ | [Uint16Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array) | 16位无符号整型数组 |
55
+ | [Uint32Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array) | 32位无符号整型数组 |
56
+ | [WeakMap](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) | 弱引用键值映射 |
57
+ | [WeakRef](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakRef) | 弱引用对象 |
58
+ | [WeakSet](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) | 弱引用集合 |
59
+ | [WebAssembly](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly) | WebAssembly接口 |
60
+ | [decodeURI](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) | 解码完整URI |
61
+ | [decodeURIComponent](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) | 解码URI片段 |
62
+ | [encodeURI](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) | 编码完整URI |
63
+ | [encodeURIComponent](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) | 编码URI片段 |
64
+ | [escape](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/escape) | 旧式字符串转义 |
65
+ | [eval](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/eval) | 执行字符串代码 |
66
+ | [isFinite](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/isFinite) | 判断是否为有限数值 |
67
+ | [isNaN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/isNaN) | 判断是否为NaN |
68
+ | [parseFloat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/parseFloat) | 解析浮点数 |
69
+ | [parseInt](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/parseInt) | 解析整数 |
70
+ | [unescape](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/unescape) | 旧式字符串反转义 |
71
+ | [globalThis](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/globalThis) | 全局对象引用 |
72
+ | [Infinity](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Infinity) | 正无穷常量 |
73
+ | [NaN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/NaN) | 非数值常量 |
74
+ | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined) | 未定义常量 |
13
75
 
14
- ## 常见误区
76
+ ## 环境差异与建议
15
77
 
16
- ### 1) 没有原生 `fetch`
17
-
18
- 插件环境里通常**没有**浏览器的 `fetch`。网络请求应使用已导出的 Objective‑C 网络类，完整用法见 [网络请求](/guides/network-requests/) 教程（`NSURLConnection`、`NSMutableURLRequest`、`NSOperationQueue` 等）。
19
-
20
- ### 2) 可能没有 `setTimeout` / `setInterval`
21
-
22
- 纯 JSCore 环境通常**不包含**这两个定时器函数（它们属于浏览器/宿主实现）。在插件里推荐使用 `NSTimer` 实现延时/轮询。
78
+ - 插件环境没有原生fetch。需要网络请求时，请使用已导出的Objective‑C网络类。
79
+ - 插件环境没有setTimeout/setInterval。建议使用NSTimer完成延时与轮询。
23
80
 
24
81
  ## 相关
25
82
 
26
83
  - [NSTimer](/reference/foundation/ns-timer/)
27
84
  - [网络请求](/guides/network-requests/)
28
-
package/.env.example DELETED
@@ -1,4 +0,0 @@
1
- # HuggingFace mirror for model download
2
- HF_ENDPOINT=https://hf-mirror.com
3
- # Optional
4
- # MCP_HTTP_PORT=8788