beacon-mfg-mcp 1.5.8 → 1.6.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.
package/README.md CHANGED
@@ -1,138 +1,157 @@
1
- # Beacon-MFG 只读 MCP 服务
2
-
3
- 让任意支持 MCP 的主流 agent(Claude Desktop / Cline / Continue / 常见 MCP 客户端 等)能够**检索与调用**
4
- 灯塔工厂供应商名录,**无需 clone 整个仓库、无需任何密钥、无需第三方依赖**。
5
-
6
- > **边界**:本服务只做**只读检索**,不参与交易、不写任何数据、不持有任何密钥。
7
-
8
- ## 提供的 tool(8 个,全部只读)
9
-
10
- | tool | 用途 | 关键参数 |
11
- |------|------|----------|
12
- | `search_vendors` | 按 关键词 / 城市 / 国标码 检索,返回精简档案 | `query` `city` `gb` `limit` `offset` |
13
- | `get_vendor` | 按 id(+国标码)取完整中文档案 | `id`(必填) `gb`(可选,自动反查) |
14
- | `get_capability_card` | 按 id 取能力卡(工艺/设备/产能/认证等) | `id`(必填) |
15
- | `suggest_filters` | **把用户原话映射成候选国标小类码**,供改用 `gb=` | `query`(必填) `city` `limit` |
16
- | `list_industries` | **国标小类货架**(只列有数据的类,附企业条数),供按语义自己挑码 | `keyword` `parent` `limit` `offset` |
17
- | `start_sourcing` | 【客户 agent 自动触发】识别找厂/代工/采购/询价意图 → 品类识别→宽召回→需求解析→生成 1~2 轮澄清问题,返回 `session_id` | `demand_text`(必填) `audience_id` |
18
- | `answer_sourcing` | 续接澄清轮次:写回客户答案,返回下一轮澄清问题或初选供应商列表 | `session_id`(必填) `answers` |
19
- | `refine_sourcing` | 推荐轮次交互:`details`(看详情与 RFQ 入口) / `more`(看更多) / `best`(看最匹配一家) | `session_id`(必填) `action` `value` |
20
-
21
- 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`,同样只读。
22
-
23
- 所有返回都是 JSON 文本。找不到时返回 `{ "error": ... }` 或 `has_card:false`,不会抛协议错。
24
-
25
- ## 搜索语义
26
-
27
- **`query` 直接传用户原话即可**,不必自己拆词。服务端会先归一化:
28
-
29
- 1. **抽城市** —— 「找一下**苏州**做AI的企业」→ `city=苏州`,城市词不再参与关键词匹配;
30
- 2. **剔填充词** —— 的 / 找 / 一下 / 企业 / 有没有 …;
31
- 3. **认词条** —— 国标别名 / 国标类名 / **能力词**(如 AI·人工智能·机器学习·大模型)→ 走定向召回;
32
- 4. 剩下的部分才作为通用关键词做 **AND** 匹配。
33
-
34
- 返回体用 `query_parsed` 回显解析结果(抽走了哪个城市、剔了哪些词、认出了哪些词条),
35
- 便于调用方判断「命中少」到底是没这类企业、还是这句话没被读懂。
36
-
37
- **结果顺序**:`results` 先按**召回来源**分档(`via=text` 字面命中 → `via=cap_text` 只撞能力词面
38
- → `via=alias` 别名定向 → `via=cap` 能力定向),**同一档内**再按「关键词在**厂名**里成片出现」优先。
39
-
40
- > `score` 是**能力画像分**(有已发布能力卡才有分,无卡为 0),**不是相关度**,不要拿它反推排序;
41
- > 返回体的 `order_note` 里写死了这个口径。
42
-
43
- **遇到生词(命中很少)怎么办**:`query` 是字面子串匹配,而名录按国标小类归档 ——
44
- 客户说「机加工」,库里写的是「机械零部件加工」,字面不通。
45
-
46
- 1. 先正常检索:`search_vendors(query=<用户原话>, city=<城市>)`。
47
- 2. **命中 < 5 条(含 0)就换码**:返回体里的 `suggested_gb`(或 `hint`)已给出候选码;
48
- 不够味就调 `suggest_filters(query, city)` 拿更多候选。
49
- 3. 用 `search_vendors(gb=<码>, city=...)` 重试。**连候选都没有**(如「手机壳」)→
50
- 调 `list_industries` 看货架自己挑 1~3 个码。
51
-
52
- > 可直接放进 agent 系统提示词:*检索灯塔工厂名录时,若命中数少于 5 条,说明用户说的是口语/采购词:
53
- > 先看返回的 `suggested_gb`,或调 `suggest_filters` 拿候选国标小类码,再用 `gb=` 重试;
54
- > 仍无候选则调 `list_industries` 按语义挑码。**不要因为命中少就回答「没有这类企业」**。*
55
-
56
- ## 安装 / 接入
57
-
58
- 服务是**零第三方依赖**的单文件(`server.py`,仅用 Python 标准库),只需 Python 3.8+。
59
-
60
- ### 方式一 · npm 安装(推荐:无需 clone、无需填路径)
61
-
62
- ```bash
63
- npm i -g beacon-mfg-mcp
64
- ```
65
-
66
- **macOS / Linux**:
67
-
68
- ```jsonc
69
- {
70
- "mcpServers": {
71
- "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [] }
72
- }
73
- }
74
- ```
75
-
76
- **Windows(必须走 `cmd /c`)**:
77
-
78
- ```jsonc
79
- {
80
- "mcpServers": {
81
- "beacon-mfg": { "command": "cmd", "args": ["/c", "beacon-mfg-mcp"] }
82
- }
83
- }
84
- ```
85
-
86
- > ⚠️ **Windows 上写 `"command": "beacon-mfg-mcp"` 会 ENOENT**:npm 全局装出来的是
87
- > `beacon-mfg-mcp.cmd`(`.cmd` 包装器),不经过 shell 的进程启动方式解析不了它,
88
- > 客户端只会表现成「连不上 / 工具不出现」。`npx -y beacon-mfg-mcp` 同理(`npx` 自身也是 `.cmd`)。
89
- > 用上表的 `cmd /c` 写法即可。
90
-
91
- > 中文 Windows 无需额外设置编码:启动器已为 Python 子进程注入 UTF-8,`server.py` 另有兜底,
92
- > 即使宿主没带任何环境变量也不会乱码或崩。
93
-
94
- 不填 `BEACON_REPO` 时默认走 `https://beacon-mfg.pages.dev`,即开即用。
95
-
96
- ### 方式二 · 本地 git 仓库(离线可用)
97
-
98
- ```jsonc
99
- {
100
- "mcpServers": {
101
- "beacon-mfg": {
102
- "command": "python",
103
- "args": ["/绝对路径/到/beacon-mfg/mcp/server.py"],
104
- "env": { "BEACON_REPO": "/绝对路径/到/beacon-mfg" }
105
- }
106
- }
107
- }
108
- ```
109
-
110
- ### 方式三 · 远程 HTTP 端点(Streamable HTTP)
111
-
112
- `server.py` 本体是 stdio;`http_server.py` 是它的 HTTP 传输适配层(同一套业务逻辑)。
113
-
114
- ```bash
115
- MCP_PORT=8787 python http_server.py # 默认 0.0.0.0:8787,端点 /mcp,健康检查 /health
116
- ```
117
-
118
- ```jsonc
119
- { "mcpServers": { "beacon-mfg": { "type": "http", "url": "https://<你的地址>/mcp" } } }
120
- ```
121
-
122
- ## 环境变量
123
-
124
- | 变量 | 作用 |
125
- |---|---|
126
- | `BEACON_REPO` | 指定本地仓库根,改走本地只读模式(离线可用) |
127
- | `BEACON_SOURCE` | 覆盖默认数据源基址(HTTP 模式) |
128
- | `BEACON_MIRRORS` | 追加备用基址(逗号分隔),主源不可达时自动回退 |
129
- | `BEACON_MASK_PHONE` | 置 `1` 时对手机号隐私处理输出 |
130
-
131
- ## 分发与版本
132
-
133
- 两种发布渠道,版本号一致:
134
-
135
- - **npm**:`beacon-mfg-mcp`(<https://www.npmjs.com/package/beacon-mfg-mcp>)
136
- - **GitHub Release**:<https://github.com/eiry16/beacon-mfg/releases>(`mcp-v*` 标签)
137
-
138
- 变更说明见本目录 `RELEASE.md`。
1
+ # Beacon-MFG 只读 MCP 服务
2
+
3
+ 让任意支持 MCP 的主流 agent(Claude Desktop / Cline / Continue / 常见 MCP 客户端 等)能够**检索与调用**
4
+ 灯塔工厂供应商名录,**无需 clone 整个仓库、无需任何密钥、无需第三方依赖**。
5
+
6
+ > **边界**:本服务只做**只读检索**,不参与交易、不写任何数据、不持有任何密钥。
7
+
8
+ ## 提供的 tool(8 个只读 + 1 个身份自助)
9
+
10
+ | tool | 用途 | 关键参数 |
11
+ |------|------|----------|
12
+ | `search_vendors` | 按 关键词 / 城市 / 国标码 检索,返回精简档案 | `query` `city` `gb` `limit` `offset` |
13
+ | `get_vendor` | 按 id(+国标码)取完整中文档案 | `id`(必填) `gb`(可选,自动反查) |
14
+ | `get_capability_card` | 按 id 取能力卡(工艺/设备/产能/认证等) | `id`(必填) |
15
+ | `suggest_filters` | **把用户原话映射成候选国标小类码**,供改用 `gb=` | `query`(必填) `city` `limit` |
16
+ | `list_industries` | **国标小类货架**(只列有数据的类,附企业条数),供按语义自己挑码 | `keyword` `parent` `limit` `offset` |
17
+ | `start_sourcing` | 【客户 agent 自动触发】识别找厂/代工/采购/询价意图 → 品类识别→宽召回→需求解析→生成 1~2 轮澄清问题,返回 `session_id` | `demand_text`(必填) `audience_id` |
18
+ | `answer_sourcing` | 续接澄清轮次:写回客户答案,返回下一轮澄清问题或初选供应商列表 | `session_id`(必填) `answers` |
19
+ | `refine_sourcing` | 推荐轮次交互:`details`(看详情与 RFQ 入口) / `more`(看更多) / `best`(看最匹配一家) | `session_id`(必填) `action` `value` |
20
+ | `account` | 查看档位/剩余额度;`request`+`confirm` 绑手机号升 `verified`;`logout` 回匿名 | `action` `phone` `code` |
21
+
22
+ 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`,同样只读。
23
+
24
+ 所有返回都是 JSON 文本。找不到时返回 `{ "error": ... }` 或 `has_card:false`,不会抛协议错。
25
+
26
+ ## 身份与额度(不需要注册)
27
+
28
+ 首次运行会在 `~/.beacon-mfg/` 生成一个匿名身份(机器本地 UUID → 单向哈希),
29
+ **不采集硬件指纹、不收集任何个人信息**。匿名档 200 次检索 / 滚动 24 小时,
30
+ L0 名录与 L1 指纹全量可用。
31
+
32
+ 需要 **L2 加工资产(能力卡 / 厂商自述体)** 时再绑手机号(200 → 2000 次/24h,
33
+ 能力卡另有 300 条/日上限)。两条路等价,任选其一:
34
+
35
+ ```bash
36
+ npx beacon-mfg-mcp login # 终端交互式:输手机号 → 收码 → 完成
37
+ npx beacon-mfg-mcp status # 看当前档位、剩余额度、cid
38
+ npx beacon-mfg-mcp logout # 解绑本机令牌
39
+ ```
40
+
41
+ 或者在对话里让 agent 调 `account` 工具(`action=status|request|confirm|logout`)。
42
+ 手机号在服务端只存 HMAC 哈希,本地只存脱敏回显(`138****8000`)。
43
+
44
+ ## 搜索语义
45
+
46
+ **`query` 直接传用户原话即可**,不必自己拆词。服务端会先归一化:
47
+
48
+ 1. **抽城市** —— 「找一下**苏州**做AI的企业」→ `city=苏州`,城市词不再参与关键词匹配;
49
+ 2. **剔填充词** —— 的 / 找 / 一下 / 企业 / 有没有 …;
50
+ 3. **认词条** —— 国标别名 / 国标类名 / **能力词**(如 AI·人工智能·机器学习·大模型)→ 走定向召回;
51
+ 4. 剩下的部分才作为通用关键词做 **AND** 匹配。
52
+
53
+ 返回体用 `query_parsed` 回显解析结果(抽走了哪个城市、剔了哪些词、认出了哪些词条),
54
+ 便于调用方判断「命中少」到底是没这类企业、还是这句话没被读懂。
55
+
56
+ **结果顺序**:`results` 先按**召回来源**分档(`via=text` 字面命中 → `via=cap_text` 只撞能力词面
57
+ → `via=alias` 别名定向 → `via=cap` 能力定向),**同一档内**再按「关键词在**厂名**里成片出现」优先。
58
+
59
+ > `score` 是**能力画像分**(有已发布能力卡才有分,无卡为 0),**不是相关度**,不要拿它反推排序;
60
+ > 返回体的 `order_note` 里写死了这个口径。
61
+
62
+ **遇到生词(命中很少)怎么办**:`query` 是字面子串匹配,而名录按国标小类归档 ——
63
+ 客户说「机加工」,库里写的是「机械零部件加工」,字面不通。
64
+
65
+ 1. 先正常检索:`search_vendors(query=<用户原话>, city=<城市>)`。
66
+ 2. **命中 < 5 条(含 0)就换码**:返回体里的 `suggested_gb`(或 `hint`)已给出候选码;
67
+ 不够味就调 `suggest_filters(query, city)` 拿更多候选。
68
+ 3. 用 `search_vendors(gb=<码>, city=...)` 重试。**连候选都没有**(如「手机壳」)→
69
+ 调 `list_industries` 看货架自己挑 1~3 个码。
70
+
71
+ > 可直接放进 agent 系统提示词:*检索灯塔工厂名录时,若命中数少于 5 条,说明用户说的是口语/采购词:
72
+ > 先看返回的 `suggested_gb`,或调 `suggest_filters` 拿候选国标小类码,再用 `gb=` 重试;
73
+ > 仍无候选则调 `list_industries` 按语义挑码。**不要因为命中少就回答「没有这类企业」**。*
74
+
75
+ ## 安装 / 接入
76
+
77
+ 服务是**零第三方依赖**的单文件(`server.py`,仅用 Python 标准库),只需 Python 3.8+。
78
+
79
+ ### 方式一 · npm 安装(推荐:无需 clone、无需填路径)
80
+
81
+ ```bash
82
+ npm i -g beacon-mfg-mcp
83
+ ```
84
+
85
+ **macOS / Linux**:
86
+
87
+ ```jsonc
88
+ {
89
+ "mcpServers": {
90
+ "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [] }
91
+ }
92
+ }
93
+ ```
94
+
95
+ **Windows(必须走 `cmd /c`)**:
96
+
97
+ ```jsonc
98
+ {
99
+ "mcpServers": {
100
+ "beacon-mfg": { "command": "cmd", "args": ["/c", "beacon-mfg-mcp"] }
101
+ }
102
+ }
103
+ ```
104
+
105
+ > ⚠️ **Windows 上写 `"command": "beacon-mfg-mcp"` 会 ENOENT**:npm 全局装出来的是
106
+ > `beacon-mfg-mcp.cmd`(`.cmd` 包装器),不经过 shell 的进程启动方式解析不了它,
107
+ > 客户端只会表现成「连不上 / 工具不出现」。`npx -y beacon-mfg-mcp` 同理(`npx` 自身也是 `.cmd`)。
108
+ > 用上表的 `cmd /c` 写法即可。
109
+
110
+ > 中文 Windows 无需额外设置编码:启动器已为 Python 子进程注入 UTF-8,`server.py` 另有兜底,
111
+ > 即使宿主没带任何环境变量也不会乱码或崩。
112
+
113
+ 不填 `BEACON_REPO` 时默认走 `https://beacon-mfg.pages.dev`,即开即用。
114
+
115
+ ### 方式二 · 本地 git 仓库(离线可用)
116
+
117
+ ```jsonc
118
+ {
119
+ "mcpServers": {
120
+ "beacon-mfg": {
121
+ "command": "python",
122
+ "args": ["/绝对路径/到/beacon-mfg/mcp/server.py"],
123
+ "env": { "BEACON_REPO": "/绝对路径/到/beacon-mfg" }
124
+ }
125
+ }
126
+ }
127
+ ```
128
+
129
+ ### 方式三 · 远程 HTTP 端点(Streamable HTTP)
130
+
131
+ `server.py` 本体是 stdio;`http_server.py` 是它的 HTTP 传输适配层(同一套业务逻辑)。
132
+
133
+ ```bash
134
+ MCP_PORT=8787 python http_server.py # 默认 0.0.0.0:8787,端点 /mcp,健康检查 /health
135
+ ```
136
+
137
+ ```jsonc
138
+ { "mcpServers": { "beacon-mfg": { "type": "http", "url": "https://<你的地址>/mcp" } } }
139
+ ```
140
+
141
+ ## 环境变量
142
+
143
+ | 变量 | 作用 |
144
+ |---|---|
145
+ | `BEACON_REPO` | 指定本地仓库根,改走本地只读模式(离线可用) |
146
+ | `BEACON_SOURCE` | 覆盖默认数据源基址(HTTP 模式) |
147
+ | `BEACON_MIRRORS` | 追加备用基址(逗号分隔),主源不可达时自动回退 |
148
+ | `BEACON_MASK_PHONE` | 置 `1` 时对手机号隐私处理输出 |
149
+
150
+ ## 分发与版本
151
+
152
+ 两种发布渠道,版本号一致:
153
+
154
+ - **npm**:`beacon-mfg-mcp`(<https://www.npmjs.com/package/beacon-mfg-mcp>)
155
+ - **GitHub Release**:<https://github.com/eiry16/beacon-mfg/releases>(`mcp-v*` 标签)
156
+
157
+ 变更说明见本目录 `RELEASE.md`。
package/RELEASE.md CHANGED
@@ -1,45 +1,58 @@
1
- # Beacon-MFG 只读 MCP 服务
2
-
3
- 面向 Agent 的供应商名录检索服务:**只读**,不参与交易、不写入任何数据、不持有密钥。
4
-
5
- ## 八个 tool
6
-
7
- | tool | 用途 |
8
- |---|---|
9
- | `search_vendors` | 按关键词 / 城市 / 国标码检索 |
10
- | `get_vendor` | 按 id 取完整档案 |
11
- | `get_capability_card` | 按 id 取能力卡 |
12
- | `suggest_filters` | 把口语需求映射成候选国标小类码 |
13
- | `list_industries` | 浏览有数据的国标小类货架 |
14
- | `start_sourcing` / `answer_sourcing` / `refine_sourcing` | 多轮采购寻源 |
15
-
16
- ## 安装
17
-
18
- ```bash
19
- npm i -g beacon-mfg-mcp
20
- ```
21
-
22
- Windows 客户端配置需经 `cmd /c`:
23
-
24
- ```jsonc
25
- { "mcpServers": { "beacon-mfg": { "command": "cmd", "args": ["/c", "beacon-mfg-mcp"] } } }
26
- ```
27
-
28
- macOS / Linux:
29
-
30
- ```jsonc
31
- { "mcpServers": { "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [] } } }
32
- ```
33
-
34
- 也可直接用本 Release 的 tarball 解压运行:
35
-
36
- ```bash
37
- python server.py # stdio
38
- python http_server.py # Streamable HTTP,端点 /mcp
39
- ```
40
-
41
- 数据默认取自公开数据源,无需密钥、无需克隆仓库。
1
+ # Beacon-MFG 只读 MCP 服务 · v1.6.0
2
+
3
+ 面向 Agent 的供应商名录检索服务:**只读**,不参与交易、不写入任何数据、不持有密钥。
4
+
5
+ ## 本次更新(v1.6.0)
6
+
7
+ - **新增 `account` 工具**(`status` / `request` / `confirm` / `logout`):匿名档查额度、
8
+ 绑手机号升 `verified`、解绑回匿名。此前没有任何升级入口,verified 档等于空档。
9
+ - **新增 CLI**:`npx beacon-mfg-mcp login | status | logout`。MCP 客户端里能用工具,
10
+ 终端里也能自助——两条路并存,覆盖「还没接 agent 就先用起来」的场景。
11
+ - **修复**:所有身份请求现在显式带 `User-Agent`。此前 urllib 默认 UA 会被 Cloudflare
12
+ 以 `error code 1010` 拒绝,且失败是**静默降级**的,看起来像「网络不好」。
13
+ - **修复**:`identity.py` 补进 `package.json` 的 `files`。此前 npm 包里根本没有这个文件,
14
+ 装完即降级为「无身份」——服务端开强制鉴权后所有 npx 用户会集体 401。
15
+ - 服务端同步:匿名 200 次 / verified 2000 次(滚动 24h),L2 能力卡另有 300 条/日上限。
16
+
17
+ ## 九个 tool(8 只读 + 1 身份自助)
18
+
19
+ | tool | 用途 |
20
+ |---|---|
21
+ | `search_vendors` | 按关键词 / 城市 / 国标码检索 |
22
+ | `get_vendor` | 按 id 取完整档案 |
23
+ | `get_capability_card` | 按 id 取能力卡 |
24
+ | `suggest_filters` | 把口语需求映射成候选国标小类码 |
25
+ | `list_industries` | 浏览有数据的国标小类货架 |
26
+ | `start_sourcing` / `answer_sourcing` / `refine_sourcing` | 多轮采购寻源 |
27
+ | `account` | 查额度 / 绑手机号升 verified / 解绑(`action`) |
28
+
29
+ ## 安装
30
+
31
+ ```bash
32
+ npm i -g beacon-mfg-mcp
33
+ ```
34
+
35
+ Windows 客户端配置需经 `cmd /c`:
36
+
37
+ ```jsonc
38
+ { "mcpServers": { "beacon-mfg": { "command": "cmd", "args": ["/c", "beacon-mfg-mcp"] } } }
39
+ ```
40
+
41
+ macOS / Linux:
42
+
43
+ ```jsonc
44
+ { "mcpServers": { "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [] } } }
45
+ ```
46
+
47
+ 也可直接用本 Release 的 tarball 解压运行:
48
+
49
+ ```bash
50
+ python server.py # stdio
51
+ python http_server.py # Streamable HTTP,端点 /mcp
52
+ ```
53
+
54
+ 数据默认取自公开数据源,无需密钥、无需克隆仓库。
42
55
 
43
56
  ## 本次更新
44
57
 
45
- - 稳定性与接入体验改进。
58
+ - 稳定性与接入体验改进。
@@ -49,6 +49,10 @@ const child = spawnSync(chosen, [serverPy, ...process.argv.slice(2)], {
49
49
  env: Object.assign({}, process.env, {
50
50
  PYTHONUTF8: '1',
51
51
  PYTHONIOENCODING: 'utf-8',
52
+ // 不写 __pycache__:本服务由 npm 全局安装、跑在任意用户机器上,
53
+ // 字节码会落进包目录(或只读盘上 EPERM 报错)。服务是短命进程,
54
+ // 字节码缓存无收益,关掉更干净。
55
+ PYTHONDONTWRITEBYTECODE: '1',
52
56
  }),
53
57
  });
54
58
  process.exit(child.status === null ? 1 : child.status);
package/http_server.py CHANGED
@@ -26,6 +26,10 @@ import uuid
26
26
  import threading
27
27
  from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
28
28
 
29
+ # [no-bytecode-guard] 同 server.py:本文件随 npm 包分发、可被 `python http_server.py`
30
+ # 直接拉起(不经 bin/ 启动器),显式禁写 __pycache__,避免在包目录/只读盘留字节码。
31
+ sys.dont_write_bytecode = True
32
+
29
33
  # 保证可直接 `python http_server.py` 运行(同级 import server)
30
34
  sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
31
35