# CookLikeHOC MCP

一个轻量、只读、来源可追溯的 MCP 适配器，让 Codex、Claude、Cursor 等 MCP 客户端检索本地 [Gar-b-age/CookLikeHOC](https://github.com/Gar-b-age/CookLikeHOC) 菜谱。

> [!IMPORTANT]
> 本项目是独立社区适配器，不是 CookLikeHOC 官方项目，也不内置、镜像或发布任何上游菜谱、图片或索引。用户必须自行取得上游仓库，并遵守其内容与来源材料的权利声明。项目仍在等待上游维护者确认合作意愿。

## 为什么做这个项目

CookLikeHOC 已经拥有结构清晰的中文家常菜资料。本项目只负责把用户本地取得的 Markdown 检出转换为四个低风险 MCP 工具；菜单规划、人数换算和采购决策仍由连接它的 AI 客户端完成。

- 本地读取：运行时不依赖菜谱 API、账号或密钥。
- 默认只读：不会修改、删除或上传菜谱。
- 来源可追溯：每项结果都返回对应的上游 GitHub 文件链接。
- 中文搜索：支持常见食材同义词，例如土豆/马铃薯、番茄/西红柿。
- 结构化提取：从常见 Markdown 标题中解析配料、步骤和营养成分。

## MCP 工具

| 工具 | 用途 |
| --- | --- |
| `search_recipes` | 按菜名、食材、分类或多个关键词搜索，支持 `all` / `any` 匹配模式。 |
| `find_recipes_by_ingredients` | 根据已有食材排序菜谱，并返回配料覆盖率、已匹配和仍缺少的配料。 |
| `get_recipe` | 按搜索结果中的路径读取完整菜谱和来源链接。 |
| `list_categories` | 列出本地检出中的菜谱分类与数量。 |

## 快速开始

要求 Node.js 20 或更高版本。

```bash
git clone https://github.com/Gar-b-age/CookLikeHOC.git
git clone https://github.com/gaopengbin/cooklikehoc-mcp.git
cd cooklikehoc-mcp
npm ci
npm run build
```

### Codex

将下面的路径替换成你的绝对路径：

```bash
codex mcp add cooklikehoc \
  --env COOKLIKEHOC_DIR=/absolute/path/to/CookLikeHOC \
  -- node /absolute/path/to/cooklikehoc-mcp/dist/index.js
```

Windows PowerShell 示例：

```powershell
codex mcp add cooklikehoc `
  --env "COOKLIKEHOC_DIR=D:\gpb\CookLikeHOC" `
  -- node "D:\gpb\cooklikehoc-mcp\dist\index.js"
```

运行 `codex mcp get cooklikehoc` 检查配置，然后重启本地客户端或新开会话。

### 通用 MCP 配置

```json
{
  "mcpServers": {
    "cooklikehoc": {
      "command": "node",
      "args": ["/absolute/path/to/cooklikehoc-mcp/dist/index.js"],
      "env": {
        "COOKLIKEHOC_DIR": "/absolute/path/to/CookLikeHOC"
      }
    }
  }
}
```

## 可以这样问

> 我有鸡肉、土豆和葱。先用 CookLikeHOC 找出最匹配的菜，列出还缺少的配料，再读取第一道菜的完整做法和来源。

> 搜索包含西红柿或鸡蛋的炒菜，最多返回 5 道，并保留每道菜的原始来源链接。

## 配置

| 环境变量 | 必填 | 说明 |
| --- | --- | --- |
| `COOKLIKEHOC_DIR` | 是 | 本地 CookLikeHOC 仓库的绝对路径。 |
| `COOKLIKEHOC_SOURCE_BASE_URL` | 否 | 来源链接前缀，默认是上游仓库 `main` 分支。适合测试分支或镜像。 |

目录扫描会忽略 `.git`、`docs`、`docker_support`、`images`、`node_modules` 和所有 `README.md`，避免把说明文件误当成菜谱。

## 开发与验证

```bash
npm ci
npm run check
```

跨平台单元测试使用临时菜谱夹具，不依赖开发者电脑上的固定路径。若要验证真实上游数据：

```bash
COOKLIKEHOC_DIR=/absolute/path/to/CookLikeHOC npm run smoke
```

PowerShell：

```powershell
$env:COOKLIKEHOC_DIR = "D:\gpb\CookLikeHOC"
npm run smoke
```

CI 在 Windows、Linux 和 Node.js 20/22 上执行构建、单元测试及真实 MCP 冒烟测试。

## 设计边界

- 不把 CookLikeHOC 菜谱、图片或生成索引提交到本仓库。
- 不声称本项目得到 CookLikeHOC 或老乡鸡官方认可。
- 不替上游内容添加许可证；本仓库的 MIT License 只适用于适配器代码。
- 不默认提供写入、删除、账户同步或远程上传能力。
- 食材覆盖率来自 Markdown 配料列表的文本匹配，不应视为营养、医疗或过敏原建议。

## License

MIT，仅适用于本适配器代码。CookLikeHOC 内容及其引用素材不包含在本许可证中。