# hsh-erp-mcp

hsh-erp monorepo 的 MCP（Model Context Protocol）服务器子模块脚手架。

当前实现：一个 `echo` hello world 工具，零外部依赖。后续在此基础上扩展业务工具。

`tools/srm/`：从 hsh-erp 旧 `e2e/scripts/`（与测试同仓）迁来的 SRM 浏览器自动化脚本（采购订单导出 / 历史价批量下载 / 应标项目下载）。后续会把 `srm-export / srm-historical-price / srm-bid-download` 包装成 MCP tools（每个工具就是一个 `server.registerTool(...)`），当前仍以独立 tsx + `docker-run.sh` 在 Playwright Docker 镜像内跑。

## 快速开始

```sh
npm install            # 安装依赖（首次）
npm start              # 启动 stdio 服务器（= tsx src/index.ts）
npm run inspect        # 用 @modelcontextprotocol/inspector 在浏览器调试

# SRM 浏览器自动化（独立子项目）
npm run srm:export -- 6200039492              # 采购订单导出
npm run srm:export:headed -- 6200039492       # headed 调试
```

## 项目结构

```
mcp/
├── package.json       # 依赖与脚本（type=module, tsx 直接执行 TS）；npm scripts 含 srm:export 系列
├── tsconfig.json      # ES2022 + NodeNext
├── src/
│   └── index.ts       # 服务器入口 + createServer() 工厂 + registerTool()
├── tools/
│   └── srm/           # 从 e2e/scripts/ 迁来（详见 tools/srm/README.md）
│       ├── srm-export.ts            # 采购订单 Excel
│       ├── srm-historical-price.ts  # 历史价批量下载
│       ├── srm-bid-download.ts      # 应标项目批量下载
│       ├── env.ts                   # 凭据读取
│       ├── docker-run.sh            # Playwright Docker 一键封装
│       ├── package.json             # 子项目依赖（playwright + tsx）
│       ├── tsconfig.json
│       ├── .env.example             # SRM_USERNAME / SRM_PASSWORD 模板
│       └── README.md
└── ...
```

## 如何添加新工具

在 `src/index.ts` 的 `createServer()` 里继续调用 `server.registerTool(...)`：

```ts
server.registerTool(
  'my-tool',
  {
    description: '...',
    inputSchema: z.object({ ... }),  // zod v4 单 schema，handler 类型由 SDK 推导
  },
  async (args) => ({
    content: [{ type: 'text', text: '...' }],
  })
);
```

每个工具的 `inputSchema` 必须是单一 zod schema，handler 返回值结构：
```ts
{ content: [{ type: 'text', text: '...' }], isError?: boolean }
```

## 调试

`npm run inspect` 启动 inspector 后浏览器操作：
1. Connect
2. Tools 标签
3. 选工具，填参数，Call

也可在 inspector 里观察 `initialize` / `tools/list` / `tools/call` 的 JSON-RPC 消息体，确认 stdout 通道无杂输出。

## 硬约束

- **stdout 是 JSON-RPC 协议流**——禁止 `console.log` / `process.stdout.write`，调试只准走 `console.error`。
- zod 锁 v4，import 用 `zod/v4`，**不要** 混 v3。

## 子模块工作流（与 hsh-erp monorepo 一致）

子模块内提交 → 推送子模块远端 → 根仓库 `git add mcp` 提交新 SHA。