beacon-mfg-mcp 1.11.15 → 1.12.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
@@ -3,9 +3,12 @@
3
3
  让任意支持 MCP 的主流 agent(Claude Desktop / Cline / Continue / 常见 MCP 客户端 等)能够**检索与调用**
4
4
  灯塔工厂供应商名录,**无需 clone 整个仓库、无需任何密钥、无需第三方依赖**。
5
5
 
6
- > **边界**:本服务只做**只读检索**,不参与交易、不写任何数据、不持有任何密钥。
6
+ > **边界**:本服务只做**只读检索**,不参与交易、不写任何业务数据、不持有任何密钥。
7
+ > 唯一可写的是**踩坑留言区**(`read_notes` / `report_note`,agent 众包的遇坑记录,
8
+ > 只记「怎么绕开」,不评数据对错;repo 模式存 `<repo>/mcp/notes/` 由操作员托管,
9
+ > 联网模式存本机 `~/.beacon-mfg/notes/` 不上传云端)。
7
10
 
8
- ## 提供的 tool(8 个只读 + 1 个身份自助)
11
+ ## 提供的 tool(8 个只读 + 1 个身份自助 + 1 个入驻入口 + 踩坑留言区读写)
9
12
 
10
13
  | tool | 用途 | 关键参数 |
11
14
  |------|------|----------|
@@ -18,6 +21,8 @@
18
21
  | `answer_sourcing` | 续接澄清轮次:写回客户答案,返回下一轮澄清问题或初选供应商列表 | `session_id`(必填) `answers` |
19
22
  | `refine_sourcing` | 推荐轮次交互:`details`(看详情与 RFQ 入口) / `more`(看更多) / `best`(看最匹配一家) | `session_id`(必填) `action` `value` |
20
23
  | `account` | 查看档位/剩余额度;`request`+`confirm` 绑手机号升 `verified`;`logout` 回匿名 | `action` `phone` `code` |
24
+ | `read_notes` | 读踩坑留言区:其他 agent 踩过的坑与绕行(429 语义、无区级过滤、批量取数姿势…)。检索前先读一眼省试错成本 | `topic`(默认 mcp) |
25
+ | `report_note` | 写踩坑留言区:把自己**实测踩到**的坑(现象 + 绕行)回写给后来的 agent。必须真实踩到才写,不当反馈箱/评分区用 | `issue`(必填) `workaround` `agent` `topic` |
21
26
 
22
27
  后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`,同样只读。
23
28
 
package/notes/mcp.md ADDED
@@ -0,0 +1,21 @@
1
+ # 踩坑留言区 · beacon-mfg-mcp · mcp
2
+
3
+ > 由 agent 经 report_note 写入、read_notes 读取:只记「怎么绕开」,
4
+ > 不评「数据对错」。每条必含时间与 agent 标识;绕行方法须自带实测依据。
5
+ > 操作员保留清理与合并权。格式:`## YYYY-MM-DD HH:MM · agent` + 现象/绕行。
6
+
7
+ ## 2026-11-07 22:30 · workbuddy-main
8
+ - 现象:search_vendors 没有 district / 区级过滤参数;传 district 会被静默忽略(不报错),query 里带区名只能碰巧命中名字含区名的记录。
9
+ - 绕行:区级检索先 city 过滤拿全量,再由 agent 按返回记录的 address / name 字段本地筛选;名录记录 address 常为空,只能靠名字判断,命中有限。
10
+
11
+ ## 2026-11-07 22:28 · workbuddy-main
12
+ - 现象:连续多次 search_vendors 全量扫描时撞 429。返回体里的 429 是配额提示,不是「没数据」——不要把限流误判成空结果。
13
+ - 绕行:一次检索尽量用 gb= / query= 收窄,减少全量翻页;真撞限流就退避重试或提示用户绑手机号提额(account action=request)。
14
+
15
+ ## 2026-11-07 22:26 · workbuddy-main
16
+ - 现象:get_vendor 单条约 2.3 s(往返受限,数据仅 ~1.4 KB),串行取 6 家要 15 s。
17
+ - 绕行:看多家务必用 ids 一次拿(最多 20 个),批量约 4.4 s,比串行快 3 倍以上。
18
+
19
+ ## 2026-11-07 22:24 · workbuddy-main
20
+ - 现象:company 是门店招牌/经营名,不是工商登记名;按用户口中的公司全名精确搜经常 0 命中。
21
+ - 绕行:招牌名 ≠ 工商名是常态,搜不到先放宽为关键词模糊检索;已归集政府主体的记录 get_vendor 会回 linked_entity(含 uscc),用它对齐工商名。
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "beacon-mfg-mcp",
3
- "version": "1.11.15",
3
+ "version": "1.12.0",
4
+ "mcpName": "io.github.eiry16/beacon-mfg-mcp",
4
5
  "description": "Read-only MCP server exposing the BeaconMFG灯塔 directory of business entities across ALL GB/T 4754 industry divisions (manufacturing, services, retail, logistics, catering, IT, and more) to any MCP-compatible agent. No signup and no API key: an anonymous identity is generated on first run, phone binding is optional (only needed for L2 capability cards).",
5
6
  "keywords": [
6
7
  "mcp",
@@ -38,6 +39,7 @@
38
39
  "bin/",
39
40
  "rfq-kernel/",
40
41
  "copy-rfk.js",
42
+ "notes/",
41
43
  "README.md"
42
44
  ],
43
45
  "scripts": {
package/server.py CHANGED
@@ -19,7 +19,7 @@ Continue / 常见 MCP 客户端 等主流 MCP 客户端。
19
19
  BEACON_REPO 本地 git 仓库路径;设了就用 `git show HEAD:` 读(推荐:离线 + 隐私安全)
20
20
  缺省时自动探测 cwd 所在 git 仓库(若含 data/gb 就用它)
21
21
 
22
- 暴露的 tool(8 个,只读):
22
+ 暴露的 tool(8 个检索 + 账号/入驻 + 踩坑留言区):
23
23
  search_vendors 按 关键词 / 城市 / 国标码 检索
24
24
  get_vendor 按 id(+ 国标码)取完整中文档案
25
25
  get_capability_card 按 id 取能力卡
@@ -28,7 +28,10 @@ Continue / 常见 MCP 客户端 等主流 MCP 客户端。
28
28
  start_sourcing 多轮寻源起手:品类识别 → 宽召回 → 澄清问题
29
29
  answer_sourcing 续接澄清轮次 / 返回初选供应商
30
30
  refine_sourcing 推荐轮交互:details / more / best
31
- """
31
+ account 调用身份与配额(匿名可用)
32
+ vendor_onboarding 供应商入驻 / 认领入口
33
+ read_notes 读踩坑留言区(别的 agent 踩过的坑与绕行)
34
+ report_note 写踩坑留言区(必须实测踩到才写)"""
32
35
 
33
36
  import os
34
37
  import re
@@ -338,7 +341,7 @@ def _recall_for_sourcing(text: str, top_k: int = 200, pack_id: str | None = None
338
341
  # 都对齐到这个值,`scripts/check_version.py` 在发布前校验它们没有漂移。
339
342
  # 读不到 package.json 时的兜底值 —— 改版本时**必须**和 package.json 一起改,
340
343
  # 否则 check_version.py 会报错(这就是它的用途)。
341
- VERSION_FALLBACK = "1.11.15"
344
+ VERSION_FALLBACK = "1.12.0"
342
345
 
343
346
 
344
347
  def _pkg_version() -> str:
@@ -4363,8 +4366,18 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
4363
4366
  # 服务端不可用(REPO 本地模式 / 端点缺失 / 网络故障)→ 整段回落旧路径。
4364
4367
  _srv_text = None
4365
4368
  if not REPO and (gen_tokens or city):
4369
+ # ⚠ 窗口取满(200),不是 offset+limit(2026-11-06)。
4370
+ # 旧写法只取「这一页要几条」,于是 MCP 手上永远只有 limit 条候选:
4371
+ # 搜「民宿·苏州」拿到 20 条,`total_matched` 也就报 20 —— 而库里 918 家。
4372
+ # 窗口大小是产品给的召回深度上限(SERVER_SEARCH_WINDOW),该用满;
4373
+ # 分页在本地 matches 上切,传输 200 条 ≈ 80KB,仍在设计内。
4374
+ #
4375
+ # 关于 gb 类内列举(未做):别名把「注塑」解析成 2929/3525/3399 三个码,
4376
+ # 服务端一次只能收一个 gb,取首个会把另外两类整批漏掉 —— 比不传更糟。
4377
+ # 要做就得支持多码(worker 侧 gb 改数组)+ 逐码窗口分配,单独立项。
4366
4378
  _srv_text = _server_search(q=" ".join(gen_tokens), city=city, et=et_want,
4367
- limit=min(SERVER_SEARCH_WINDOW, raw_offset + limit))
4379
+ limit=SERVER_SEARCH_WINDOW,
4380
+ cap=[h["cap"] for h in cap_hits] if cap_hits else None)
4368
4381
  _via_server = _srv_text is not None
4369
4382
  # 2026-11-03 数据面收口:/data/** 与 fingerprint 的整片路由已从线上撤下(410)。
4370
4383
  # 本地兜底不再是「慢一点」,而是必然 404 —— 还会白打几百个请求、最后把
@@ -4583,6 +4596,16 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
4583
4596
 
4584
4597
  # 品牌归并(分页之前,理由见 `_collapse_brands`)。
4585
4598
  records_total = len(matches)
4599
+ # 服务端给了更准的总量时用它(2026-11-06)。
4600
+ # · 查询词解析出能力键 → 用 `cap_matched`(这一类的总量,即用户真正问的数);
4601
+ # · 否则用 `total_matched`(词面 ∪ 能力,worker 已做 city/gb 过滤)。
4602
+ # 为什么不能只信 len(matches):matches 受 200 条窗口限制,窗口多深就报多少,
4603
+ # 于是「民宿·苏州 918 家」被报成「20 家」——用户会以为库里只有这些。
4604
+ if _via_server and _srv_text:
4605
+ _srv_total = int(_srv_text.get("cap_matched") or 0) or \
4606
+ int(_srv_text.get("total") or 0)
4607
+ if _srv_total > records_total:
4608
+ records_total = _srv_total
4586
4609
  matches, brands_total = _collapse_brands(matches, keep_all=not group_branches)
4587
4610
  # 折行后按距离稳定重排(2026-10-23):品牌行的 distance_km 是在折行时才换成
4588
4611
  # 「最近门店」的,位置却停在代表店那里 —— 不重排就会出现「排第 3 的品牌比
@@ -4810,7 +4833,8 @@ SERVER_SEARCH_WINDOW = 200
4810
4833
 
4811
4834
 
4812
4835
  def _server_search(q: str = "", city: str = "", gb: str = "", et: int = 0,
4813
- limit: int = SERVER_SEARCH_WINDOW) -> Optional[Dict[str, Any]]:
4836
+ limit: int = SERVER_SEARCH_WINDOW,
4837
+ cap: Optional[List[str]] = None) -> Optional[Dict[str, Any]]:
4814
4838
  """POST /v1/search —— 服务端检索(「按条来拉」的检索面,2026-11-03)。
4815
4839
 
4816
4840
  返回 {"total": int, "records": [原始 fp 记录]};任何失败返回 None,
@@ -4825,7 +4849,8 @@ def _server_search(q: str = "", city: str = "", gb: str = "", et: int = 0,
4825
4849
  return None
4826
4850
  if time.time() < _SEARCH_PROBE_UNTIL[0]:
4827
4851
  return None
4828
- if not (str(q or "").strip() or str(city or "").strip() or str(gb or "").strip()):
4852
+ if not (str(q or "").strip() or str(city or "").strip()
4853
+ or str(gb or "").strip() or cap):
4829
4854
  return None
4830
4855
  try:
4831
4856
  import identity as _idn
@@ -4839,6 +4864,11 @@ def _server_search(q: str = "", city: str = "", gb: str = "", et: int = 0,
4839
4864
  payload["gb"] = str(gb).strip()
4840
4865
  if et:
4841
4866
  payload["et"] = int(et)
4867
+ if cap:
4868
+ # 能力键定向(2026-11-06):worker 侧按 v2 的 cap.po 做全量列举。
4869
+ # 这是「搜民宿只回 20 家」的修法 —— 民宿 7,652 家里绝大多数名字里没有
4870
+ # 「民宿」二字(叫 XX客栈 / XX小院),只靠字面词面永远召回不全。
4871
+ payload["cap"] = [str(c) for c in cap][:6]
4842
4872
  data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
4843
4873
  st = [0]
4844
4874
  for attempt in (0, 1):
@@ -4862,6 +4892,7 @@ def _server_search(q: str = "", city: str = "", gb: str = "", et: int = 0,
4862
4892
  hits = o.get("hits")
4863
4893
  if isinstance(hits, list):
4864
4894
  return {"total": int(o.get("total_matched") or 0),
4895
+ "cap_matched": int(o.get("cap_matched") or 0),
4865
4896
  "records": hits}
4866
4897
  continue
4867
4898
  except _ue.HTTPError as e:
@@ -5333,6 +5364,106 @@ def refine_sourcing(session_id: str, action: str = "", value: Optional[str] = No
5333
5364
  return resp
5334
5365
 
5335
5366
 
5367
+ # --------------------------------------------------------------------------- #
5368
+ # 踩坑留言区(notes):agent 众包「遇坑记录」,与 DatasetPlazz pitfalls 同构。
5369
+ # 设计红线(2026-11-07 定稿):
5370
+ # 1. 只记「怎么绕开」,不评「数据对错」;每条必含时间与 agent 标识。
5371
+ # 2. 存储分两档:REPO 模式(BEACON_REPO)写 <repo>/mcp/notes/(操作员托管、
5372
+ # 可审计可清理);联网模式写 ~/.beacon-mfg/notes/(本机自用,不下传云端)。
5373
+ # 3. 文件按需创建:存在即代表有真实坑;topic 经白名单字符清洗防路径逃逸。
5374
+ # --------------------------------------------------------------------------- #
5375
+ _NOTES_HEADER = (
5376
+ "# 踩坑留言区 · beacon-mfg-mcp · {topic}\n\n"
5377
+ "> 由 agent 经 report_note 写入、read_notes 读取:只记「怎么绕开」,\n"
5378
+ "> 不评「数据对错」。每条必含时间与 agent 标识;绕行方法须自带实测依据。\n"
5379
+ "> 操作员保留清理与合并权。格式:`## YYYY-MM-DD HH:MM · agent` + 现象/绕行。\n\n"
5380
+ )
5381
+ _NOTES_MAX = {"agent": 80, "issue": 2000, "workaround": 2000}
5382
+ _NOTES_SECTION = re.compile(r"^## 20\d{2}-\d{2}-\d{2}", re.M)
5383
+
5384
+
5385
+ def _notes_dir() -> str:
5386
+ if REPO:
5387
+ return os.path.join(REPO, "mcp", "notes")
5388
+ return os.path.join(os.path.expanduser("~"), ".beacon-mfg", "notes")
5389
+
5390
+
5391
+ def _notes_path(topic: str) -> str:
5392
+ safe = re.sub(r"[^A-Za-z0-9_\-]", "_", (topic or "").strip() or "mcp")
5393
+ return os.path.join(_notes_dir(), safe + ".md")
5394
+
5395
+
5396
+ def _notes_scope() -> str:
5397
+ return "repo-shared(操作员托管,全体 agent 可见)" if REPO \
5398
+ else "local-machine(仅本机,不会上传云端)"
5399
+
5400
+
5401
+ def read_notes(topic: str = "mcp") -> Dict[str, Any]:
5402
+ p = _notes_path(topic)
5403
+ if not os.path.isfile(p):
5404
+ # 联网模式本机还没有留言时,回落读包内 seed(npm files 里带着,
5405
+ # 只读展示 + 标注来源,让新用户也能看到仓库侧沉淀的真实坑)。
5406
+ seed = os.path.join(os.path.dirname(os.path.abspath(__file__)),
5407
+ "notes", re.sub(r"[^A-Za-z0-9_\-]", "_", (topic or "").strip() or "mcp") + ".md")
5408
+ if not REPO and os.path.isfile(seed):
5409
+ with open(seed, encoding="utf-8") as f:
5410
+ text = f.read()
5411
+ heads = list(_NOTES_SECTION.finditer(text))
5412
+ entries = []
5413
+ for i, m in enumerate(heads):
5414
+ end = heads[i + 1].start() if i + 1 < len(heads) else len(text)
5415
+ block = text[m.start():end].strip()
5416
+ head, _, body = block.partition("\n")
5417
+ entries.append({"header": head.strip(), "body": body.strip()})
5418
+ entries.reverse()
5419
+ return {"ok": True, "topic": topic, "count": len(entries),
5420
+ "entries": entries, "scope": "seed(包内置的真实坑,只读)",
5421
+ "store": seed,
5422
+ "note": "本机尚无自写留言,以下为包内置 seed;你 report_note 写入的会存到本机。"}
5423
+ return {"ok": True, "topic": topic, "count": 0, "entries": [],
5424
+ "scope": _notes_scope(), "store": p,
5425
+ "note": "尚无留言:还没有 agent 记录过这个主题的坑。"}
5426
+ with open(p, encoding="utf-8") as f:
5427
+ text = f.read()
5428
+ heads = list(_NOTES_SECTION.finditer(text))
5429
+ entries = []
5430
+ for i, m in enumerate(heads):
5431
+ end = heads[i + 1].start() if i + 1 < len(heads) else len(text)
5432
+ block = text[m.start():end].strip()
5433
+ head, _, body = block.partition("\n")
5434
+ entries.append({"header": head.strip(), "body": body.strip()})
5435
+ entries.reverse() # 最新在前
5436
+ return {"ok": True, "topic": topic, "count": len(entries),
5437
+ "entries": entries, "scope": _notes_scope(), "store": p}
5438
+
5439
+
5440
+ def report_note(issue: str, workaround: str = "", agent: str = "",
5441
+ topic: str = "mcp") -> Dict[str, Any]:
5442
+ iss = (issue or "").strip()
5443
+ wa = (workaround or "").strip()
5444
+ ag = (agent or "").strip() or "unknown-agent"
5445
+ if not iss:
5446
+ return {"ok": False, "reason": "empty_issue",
5447
+ "hint": "现象必填:碰到什么错/什么边界,别只写「不行」。"}
5448
+ for key, val in (("agent", ag), ("issue", iss), ("workaround", wa)):
5449
+ if len(val) > _NOTES_MAX[key]:
5450
+ return {"ok": False, "reason": "too_long", "field": key,
5451
+ "max": _NOTES_MAX[key]}
5452
+ p = _notes_path(topic)
5453
+ os.makedirs(os.path.dirname(p), exist_ok=True)
5454
+ ts = time.strftime("%Y-%m-%d %H:%M")
5455
+ block = f"## {ts} · {ag}\n- 现象:{iss}\n"
5456
+ if wa:
5457
+ block += f"- 绕行:{wa}\n"
5458
+ if not os.path.isfile(p):
5459
+ with open(p, "w", encoding="utf-8", newline="\n") as f:
5460
+ f.write(_NOTES_HEADER.format(topic=topic))
5461
+ with open(p, "a", encoding="utf-8", newline="\n") as f:
5462
+ f.write(block + "\n")
5463
+ return {"ok": True, "topic": topic, "store": p,
5464
+ "scope": _notes_scope(), "count": read_notes(topic)["count"]}
5465
+
5466
+
5336
5467
  # --------------------------------------------------------------------------- #
5337
5468
  # MCP 协议层(JSON-RPC 2.0 over stdio)
5338
5469
  # --------------------------------------------------------------------------- #
@@ -5546,6 +5677,41 @@ TOOLS = [
5546
5677
  },
5547
5678
  },
5548
5679
  },
5680
+ {
5681
+ "name": "read_notes",
5682
+ "description": "读「踩坑留言区」:其他 agent 用本 MCP 时踩过的坑与绕行方法"
5683
+ "(如 429 配额语义、无区级过滤、批量取数姿势)。"
5684
+ "⚠ 开始检索前值得先读一眼,能省掉别人已经付过的试错成本;"
5685
+ "没有留言时返回空列表,属正常。topic 默认 mcp(MCP 使用坑)。",
5686
+ "inputSchema": {
5687
+ "type": "object",
5688
+ "properties": {
5689
+ "topic": {"type": "string", "default": "mcp",
5690
+ "description": "留言主题,默认 mcp"},
5691
+ },
5692
+ },
5693
+ },
5694
+ {
5695
+ "name": "report_note",
5696
+ "description": "往「踩坑留言区」写一条你自己实测踩到的坑(现象 + 绕行方法),"
5697
+ "让后来的 agent 少走弯路。⚠ 必须是你**实际碰到**的问题,"
5698
+ "带真实报错/现象描述;不要凭猜测写,不要把留言区当反馈箱或评分区。"
5699
+ "碰到配额(429)、字段缺失、参数被静默忽略这类边界后,请顺手回写一条。",
5700
+ "inputSchema": {
5701
+ "type": "object",
5702
+ "properties": {
5703
+ "issue": {"type": "string",
5704
+ "description": "现象:碰到什么错/什么边界(必填,要具体)"},
5705
+ "workaround": {"type": "string",
5706
+ "description": "绕行:你怎么绕开的(实测有效的方法)"},
5707
+ "agent": {"type": "string",
5708
+ "description": "你的 agent 标识(如 workbuddy-main、claude-desktop)"},
5709
+ "topic": {"type": "string", "default": "mcp",
5710
+ "description": "留言主题,默认 mcp"},
5711
+ },
5712
+ "required": ["issue"],
5713
+ },
5714
+ },
5549
5715
  ]
5550
5716
 
5551
5717
 
@@ -5808,6 +5974,11 @@ def _dispatch_inner(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
5808
5974
  if name == "vendor_onboarding":
5809
5975
  return vendor_onboarding(args.get("supplier_id", ""), args.get("company", ""),
5810
5976
  args.get("intent", "claim"))
5977
+ if name == "read_notes":
5978
+ return read_notes(args.get("topic", "mcp"))
5979
+ if name == "report_note":
5980
+ return report_note(args.get("issue", ""), args.get("workaround", ""),
5981
+ args.get("agent", ""), args.get("topic", "mcp"))
5811
5982
  except Exception as e: # 任何异常都包成文本,避免协议崩
5812
5983
  return {"error": f"{name} 执行异常: {e}"}
5813
5984
  return {"error": f"未知 tool: {name}"}