# SZLCSC MCP

面向 **国内立创商城 SZLCSC** 的 MCP Server，提供器件搜索、国内人民币小批量价格/库存、参数化选型、替代料比较、Datasheet 下载、EasyEDA EDA 资产、Altium SchLib/PcbLib/STEP 转换和长期器件库管理。

当前版本：**v0.5.0**

## 主要能力

- 国内 `szlcsc.com` 搜索与 C 编号 / MPN 查询。
- 国内现货、MOQ、包装与人民币阶梯价格；缺失值始终保持 unknown，不当成 0。
- 参数化搜索、工程单位解析、器件并排比较和替代料评分。
- Datasheet 批量同步、失败诊断与 manifest。
- EasyEDA Symbol / Footprint / SVG / OBJ / STEP 获取。
- `altium-cruncher` 驱动的 SchLib / PcbLib / 3D placement / merge。
- C 编号作为采购记录主键，`MPN + package` 作为 CAD 去重键。
- Altium 转换结果的 pin/pad/3D 自动检查 + 强制人工复核提示。


## v0.5.0：长期器件库搜索 / 审计 / 安全修复

在 v0.4.5 的 `classified/ + flat/` 双视图归档之上，新增三个本地库管理工具：

- `szlcsc_library_search`：完全离线按 C 编号、MPN、品牌、封装、分类、库存、Datasheet/SchLib/PcbLib/STEP 状态检索，并支持 relevance/price/stock/mpn 排序。
- `szlcsc_library_audit`：只读检查 classified 主资产、flat 镜像 SHA256、CAD owner/index、`cad_shared` 和 Altium 文件存在性。
- `szlcsc_library_repair`：默认 `dry_run=true`；只修复可确定恢复的 flat 镜像和 CAD owner/index 一致性，**不会**重新下载 Datasheet，也不会重新生成 CAD；classified 主文件缺失只报告 unresolved。

推荐维护流程：

```text
szlcsc_library_audit(...)
        ↓
szlcsc_library_repair(dry_run=true)
        ↓ 人工确认计划
szlcsc_library_repair(dry_run=false)
        ↓
szlcsc_library_audit(...)
```

正式测试要求已纳入仓库：

- [`docs/test-plans/FULL_TEST_PLAN.md`](docs/test-plans/FULL_TEST_PLAN.md)
- [`docs/test-plans/ALTIUM_TEST_PLAN.md`](docs/test-plans/ALTIUM_TEST_PLAN.md)
- [`docs/test-plans/RELEASE_ACCEPTANCE.md`](docs/test-plans/RELEASE_ACCEPTANCE.md)

## v0.4.5：分类长期库 + 平铺浏览库

器件通过 `szlcsc_library_add` 入库后，Datasheet、SchLib、PcbLib、STEP 会同时进入两种视图：

```text
szlcsc-library/
├─ library-index.json
├─ classified/
│  ├─ datasheets/<立创类目>/类型-型号-C编号.pdf
│  ├─ schlib/<立创类目>/类型-型号-C编号.SchLib
│  ├─ pcblib/<立创类目>/类型-型号-C编号.PcbLib
│  ├─ 3d/<立创类目>/类型-型号-C编号.step
│  └─ reports/<立创类目>/类型-型号-C编号-*.json
├─ flat/
│  ├─ 类型-型号-C编号.pdf
│  ├─ 类型-型号-C编号.SchLib
│  ├─ 类型-型号-C编号.PcbLib
│  └─ 类型-型号-C编号.step
└─ merged/
```

例如：

```text
电压基准芯片-TPR3333-S3TR-C5291487.pdf
电压基准芯片-TPR3333-S3TR-C5291487.SchLib
电压基准芯片-TPR3333-S3TR-C5291487.PcbLib
电压基准芯片-TPR3333-S3TR-C5291487.step
```

`classified/` 是长期主存：先按资产类型分离，再按立创类目分级。`flat/` 是平铺镜像，少量器件时方便直接查看。若数据源只返回末级类目，则只有一级分类；若返回完整 `一级/二级/末级` 路径，会自动逐级保存。

`szlcsc_library_merge` 优先读取 classified 归档，因此临时 `altium/Cxxxx` 转换目录删除后，已归档 CAD 仍可继续复用和合并。

## Altium 实机状态

v0.4.4 已在 Windows + Altium Designer 完成实机验证：

- `altium-cruncher 2026.8.11.1`
- `altium-monkey 2026.8.11.post1`
- `wn-geometer 2026.6.10`
- `easyeda-import`: PASS
- `merge`: PASS
- 3D download / placement: PASS
- C2040 smoke: PASS
- C2040：57 个 Symbol 引脚 ↔ 57 个 Footprint 焊盘，人工检查匹配
- STEP：0°，0.0 mils 悬高，Altium Designer 可正常打开

C2040 的 source EasyEDA 报告仍保留 `51/57 off-grid pin hotspots` warning；该 warning 没有被静默忽略，但本次人工检查没有发现结构性阻断缺陷。

详见 [`docs/test-reports/v0.4.4-altium-live.md`](docs/test-reports/v0.4.4-altium-live.md)。v0.4.5 本地回归为 **60 passed**。v0.5.0 新增长期库管理回归后为 **67 passed**；详见 [`docs/test-reports/v0.5.0.md`](docs/test-reports/v0.5.0.md)。

## 安装

Python 3.11+：

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\pip.exe install -e .
```

MCP command：

```text
<项目路径>\.venv\Scripts\szlcsc-mcp.exe
```

也可以：

```bash
uv tool install .
```

## 可选：Altium 转换器

SZLCSC MCP 不捆绑第三方 `altium-cruncher`。Windows 可运行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-altium-cruncher.ps1
```

或手动：

```powershell
uv tool install altium-cruncher
uv tool update-shell
altium-cruncher version
```

随后调用：

```text
szlcsc_altium_setup()
szlcsc_altium_status()
```

只有 `ready=true` 且 `status="ready"` 才表示 Altium 工具链可测试。

## 常用 MCP Tools

| Tool | 用途 |
|---|---|
| `szlcsc_search` | 关键词 / MPN / C编号检索 |
| `szlcsc_parametric_search` | 工程参数约束筛选 |
| `szlcsc_get_part` | 器件完整详情 |
| `szlcsc_compare_parts` | 多器件对比 |
| `szlcsc_find_alternatives` | 替代料候选与评分 |
| `szlcsc_sync_datasheets` | 批量 Datasheet + manifest |
| `szlcsc_eda_assets` | EasyEDA Symbol / Footprint / OBJ / STEP |
| `szlcsc_altium_setup` | Altium 工具链诊断 |
| `szlcsc_altium_smoke_test` | SchLib/PcbLib/3D/merge 冒烟测试 |
| `szlcsc_altium_import` | 单器件 Altium 转换 |
| `szlcsc_altium_import_batch` | 批量 Altium 转换 |
| `szlcsc_altium_review` | 转换报告检查 |
| `szlcsc_library_add` | 长期器件库入库 + CAD 去重 + 双视图归档 |
| `szlcsc_library_status` | 器件库索引与分类状态 |
| `szlcsc_library_search` | 离线检索长期库与 CAD/资产过滤 |
| `szlcsc_library_audit` | classified/flat/CAD owner 完整性审计 |
| `szlcsc_library_repair` | dry-run 优先的安全镜像/索引修复 |
| `szlcsc_library_sync` | 刷新价格/库存等采购元数据 |
| `szlcsc_library_merge` | 按分类合并 SchLib/PcbLib |
| `szlcsc_parse_barcode` | 立创包装袋二维码解析 |

完整 Agent 工作规则见 [`skills/szlcsc/SKILL.md`](skills/szlcsc/SKILL.md)。

## 示例

参数化选型：

```text
szlcsc_parametric_search(
  query="3.3V 电压基准",
  package="SOT-23",
  in_stock=true,
  max_price=5,
  constraints={
    "output_voltage": "=3.3V",
    "accuracy": "<=0.2%",
    "tempco": "<=30ppm/°C"
  }
)
```

入长期库：

```text
szlcsc_library_add(
  identifiers=["C2040", "C5291487"],
  library_root="D:/Components/SZLCSC-Library",
  altium_output_root="D:/Components/Altium",
  import_missing=true,
  dedupe_cad=true
)
```

库内搜索：

```text
szlcsc_library_search(
  library_root="D:/Components/SZLCSC-Library",
  query="TPR3333",
  in_stock=true,
  has_pcblib=true,
  has_step=true,
  sort_by="price"
)
```

审计与修复：

```text
szlcsc_library_audit(library_root="D:/Components/SZLCSC-Library")
szlcsc_library_repair(library_root="D:/Components/SZLCSC-Library", dry_run=true)
# 确认 actions 后再 dry_run=false
```

按分类合并：

```text
szlcsc_library_merge(
  library_root="D:/Components/SZLCSC-Library",
  output_dir="D:/Components/SZLCSC-Library/merged"
)
```

## 数据与安全原则

- 国内采购结论以 `szlcsc.com` 为准，不静默替换成国际 LCSC 美元价格。
- 默认比较最小采购数量对应的人民币阶梯价。
- 不逆向、不绕过验证码、登录、WASM 签名或其他访问控制。
- Datasheet 支持立创附件 CDN 和受控的官方厂商 HTTPS PDF 域名；普通资产仍限制在 SZLCSC/LCSC 域名。
- EasyEDA/Altium 自动转换不等于制造正确性证明。投板前仍必须核对制造商 Datasheet、Pin 1、引脚编号、焊盘尺寸和 3D 方位。

## License

MIT。`altium-cruncher` 是独立第三方工具，使用其自己的许可证；本项目不 vendoring 其源码。