# baihua-mcp-server

百花（Baihua）能力的 **MCP server**：把知识库检索/读笔记、家庭记账/任务等**只读**能力，以标准
[Model Context Protocol](https://modelcontextprotocol.io)（stdio）工具暴露给**任意 MCP 客户端**
（Claude Desktop / Cursor / DeepSeek Harness 的 `dsh-mcp-client` 等）。

## 关于百花（Baihua）

[百花](https://github.com/luminsw/baihua) 是一个面向本地/局域网的家庭服务端，提供知识库（笔记/全文·语义搜索/Anki 卡片）、家庭数据（记账/任务/打卡/成就/病历本）、AI 推理（本机 OpenVINO/OVMS + 云端模型路由 + 算力池互联）与 `bh` 运维 CLI；服务组成 `Baihua.Family`(8788) · `Baihua.AI`(8791) · `Baihua.Vault`(8790) · `Baihua.Web`(5177)。

**定位：百花 = 能力提供方，DSH（DeepSeek Harness）= 编排与交互面。** 本仓库是「百花 → 任意 MCP 客户端」的标准通道；DSH 内同族插件：

- [`baihua-dsh-plugin`](https://github.com/luminsw/baihua-dsh-plugin) — 百花 Web → DSH 桥（agent 会话 + `bh_*` 运维 + 设置页状态卡片）
- [`baihua-local-ai-dsh-plugin`](https://github.com/luminsw/baihua-local-ai-dsh-plugin) — DSH → 百花本地 AI（省线上 token）
- [`hysteria-dsh-plugin`](https://github.com/luminsw/hysteria-dsh-plugin) — 本机 Hysteria 2 代理管理

## 提供的能力

| 工具 | 说明 |
|---|---|
| `baihua_vault_search` | 搜索百花知识库（全文/语义），返回命中的笔记片段 |
| `baihua_vault_list` | 列出全部知识库（名称/路径/来源） |
| `baihua_vault_read_note` | 读取一条笔记（markdown 全文） |
| `baihua_budget_summary` | 家庭记账汇总（本月收入/支出/结余/分类） |
| `baihua_tasks_list` | 家庭任务/待办列表（标题/状态/时间） |

## 运行

```bash
npm install
node src/index.js
```

连接目标经环境变量配置（默认本机回环，k8s/容器部署填 ClusterIP）：

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `BAIHUA_VAULT_URL` | `http://127.0.0.1:8790` | 百花 Vault（知识库检索/笔记） |
| `BAIHUA_FAMILY_URL` | `http://127.0.0.1:8788` | 百花 Family（记账/任务） |

## 接入 MCP 客户端

### DeepSeek Harness（dsh-mcp-client）

```yaml
# ~/.dsh/profiles/web/cordis.patch.yml → insert 列表
- id: dsh-mcp-client
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    servers:
      baihua:
        command: node
        args: ['/path/to/baihua-mcp-server/src/index.js']
        env:
          BAIHUA_VAULT_URL: 'http://127.0.0.1:8790'
          BAIHUA_FAMILY_URL: 'http://127.0.0.1:8788'
```

接入后 DSH 内工具名带 `mcp__baihua__` 前缀（如 `mcp__baihua__baihua_vault_search`）。

### 其他 MCP 客户端（Claude Desktop / Cursor 等）

按客户端的 MCP server 配置方式指向 `node /path/to/baihua-mcp-server/src/index.js`（stdio）即可。

## 安全

- 全部工具**只读**：不写入、不执行、不启停任何东西。
- 默认指向本机回环地址；放局域网/公网前请先确认百花管理 API 已按 `BAIHUA_ADMIN_ALLOWED_NETS` 收敛访问范围。

## License

MIT