内容
<div align="center">
<img src="docs/brand/shelf-readme-banner.png" alt="Shelf" width="100%">
# Shelf
**您构建工具。Shelf 让它们保持可用。**
一个用于存储您为自己编写的脚本、开发服务器和一次性任务的本地库，具备记住启动命令、实时状态和日志等功能。此外，还包含一个捆绑的 MCP 服务器，允许 Claude、Cursor 和 Codex 查询您构建的工具、启动它，并诚实地记录缺少的功能。
[**下载 macOS 版本**](https://shelfmcp.com/download) · [shelfmcp.com](https://shelfmcp.com) · MIT · 无需账户
</div>
---
<!-- TODO: record shelf-demo.gif (shot list in the copy pack), then restore:
-->
## 功能介绍
- **一键启动，无需繁琐操作。** 将 Shelf 指向一个项目文件夹。它会扫描脚本、端口、包管理器和 `DESIGN.md`，并建议启动配置。接受后，工具将存活在您的库中。
- **状态真实，不会撒谎。** 基于端口的工具在 TCP 就绪检查实际成功之前，不会报告正在运行。实时日志、停止、重启。
- **代理可以查看您的 Shelf。** 本地标准输入/输出 MCP 服务器公开您的库 - 列出工具、检查就绪状态、启动、停止、读取日志。
- **能力差距，记录在案。** 当库中没有与代理请求的任务匹配的工具时，Shelf 会记录下来，而不是临时应对。计划，而不是无声失败。
- **快速打开** （`⌘K`）、菜单栏模式和 `shelf://` URL 方案。
## 安装
下载已签名并经过公证的 DMG：
**[shelfmcp.com/download](https://shelfmcp.com/download)**
打开它，将 Shelf 拖入应用程序文件夹，从 Spotlight 启动。Shelf 会从 GitHub 版本中自动更新自己。
**要求：** **基于 Apple Silicon 的 macOS** （M1 或更新版本）。无 Intel 版本。无需账户，无需订阅。
## 使用
1. 点击 **添加工具** （或按 `⌘N`）。
2. 选择一个项目文件夹 - Shelf 会建议启动命令、端口、标签和 `DESIGN.md`（如果可能）。
3. 打开工具并点击 **启动** - 或使用 **快速打开** （`⌘K`）跳转到工具，并按 `⌘↵` 启动/停止。
4. 查看状态和实时日志；根据需要使用 **停止** / **重启**。
5. 从详细视图中打开 URL、文件夹、编辑器（Cursor/VS Code）或终端。
### 菜单栏和 `shelf://`
Shelf 可以位于菜单栏中（设置 → 菜单栏）。全局显示/隐藏默认为 `⌘⇧Space`。
```bash
open 'shelf://open'
open 'shelf://quick-open'
open 'shelf://tools/<id>/launch'
open 'shelf://launch?name=Photo%20Prepper'
```
操作链接（`launch`、`stop`、`restart`）需要在 Shelf 中确认，因此网页或另一个应用程序无法无声控制本地工具。
## MCP - 为代理提供 Shelf
**最简单的路径：** 打开 Shelf → **MCP 连接** → 连接 Claude、Cursor 或 Codex。Shelf 会为您编写客户端 MCP 配置（Claude：退出并重新打开；Cursor：重新加载 MCP；Codex：重启 / 新 CLI 会话），然后询问 *"列出我的 Shelf 工具。"*
Shelf 公开一个本地标准输入/输出 MCP 服务器，该服务器读取和写入与 GUI **相同** 的库，并且可以启动和停止工具。打包的应用程序在 `Shelf.app/Contents/Resources/mcp/` 中附带一个独立的捆绑包。
手动配置（优先使用 Shelf 内的 **MCP 连接**）：
```json
{
"mcpServers": {
"shelf": {
"command": "node",
"args": [
"/Applications/Shelf.app/Contents/Resources/mcp/mcp/server.js"
]
}
}
}
```
**能力智能是描述性和本地的。** 代理可以发现已声明的接口并记录缺少的能力，但 Shelf 不会连接到或调用子 MCP 服务器。它公开您的工具，仅此而已。
示例提示：
> “哪个 Shelf 工具可以批量优化图像？”
>
> “如果无法填充 PDF 表单，请记录该能力差距并解释原因。”
<details>
<summary><strong>所有 MCP 工具</strong></summary>
`shelf_list_tools`、`shelf_get_tool`、`shelf_find_capability`、`shelf_check_tool_readiness`、
`shelf_record_capability_gap`、`shelf_list_capability_gaps`、`shelf_find_free_port`、
`shelf_inspect_project`、`shelf_upsert_tool`、`shelf_remove_tool`、`shelf_launch_tool`、
`shelf_stop_tool`、`shelf_get_status`、`shelf_get_logs`、`shelf_list_receipts`、
`shelf_clear_receipts`、`shelf_list_collections`、`shelf_get_design_md`。
资源：`shelf://tools/{id}/design-md`。
</details>
代理的项目技能： [.cursor/skills/shelf-register/SKILL.md](.cursor/skills/shelf-register/SKILL.md).
## 数据存储位置
Shelf 知道的一切都以纯 JSON 格式存储在一个文件夹中，您可以读取、备份或删除：
```
~/Library/Application Support/Shelf/
├── library.json 您的工具
├── capability-gaps.json 代理需要的但未找到的内容
└── receipts.json 启动时间、启动记录
```
**无需账户。无需云同步。无需遥测。**
Shelf 只进行一次 outbound 网络请求，即安装时的首次启动调查。有效载荷是您的调查答案（您首先存储了什么、您的角色、您如何听说 Shelf、您使用的代理）、可选的名称和电子邮件（您可以跳过），以及应用程序版本和平台。无工具名称、无文件路径、无重复内容。端点是
[`site/src/app/api/onboarding/route.ts`](site/src/app/api/onboarding/route.ts) 如果您想阅读它而不是相信我们。
MCP 响应会掩盖匹配 `TOKEN|SECRET|PASSWORD|KEY` 的环境键。
## 安全注意事项
- 命令通过 `/bin/zsh -lc` 运行，因此您的登录 PATH（nvm/fnm）可用。
- Shelf 以 **您** 的身份启动命令。 它不会沙盒化命令。 如果您存储了危险的内容，Shelf 将忠实地运行它。
- 不支持交互式提示和 `sudo`。
---
## 开发
需要 macOS 和 Node.js 20+。
```bash
npm install
npm run electron:dev
```
在 `http://127.0.0.1:5173` 启动 Vite 渲染器并打开 Electron 外壳。
### 本地桌面构建
```bash
npm run install:desktop
```
构建 Shelf，打包 `Shelf.app`，并将其复制到 `/Applications`（当权限允许时）和桌面。优先从 `/Applications` 打开 **Shelf** - 当存在两个副本时，MCP Connect 会写入持久路径。不要在 `node_modules` 中启动原始 Electron 二进制文件。
本地未签名构建的首次启动：右键单击 → **打开** 如果 Gatekeeper 阻止它。已发布的 DMG 已签名并获得公证，不需要此操作。
### MCP 服务器构建
```bash
npm run mcp:build
```
在 `dist-mcp/mcp/server.js` 中生成一个独立的捆绑包，其中包含 MCP SDK 依赖项。
### 市场网站
Next.js 站点位于 [`site/`](site/)。参见 [`site/README.md`](site/README.md) 进行设置。
<details>
<summary><strong>脚本</strong></summary>
| 命令 | 用途 |
|---|---|
| `npm run electron:dev` | 具有热重载的开发应用程序 |
| `npm run build` | 编译共享 + Electron + MCP + Vite |
| `npm run mcp` | 在标准输入/输出上构建并运行 MCP 服务器 |
| `npm run typecheck` | TypeScript 检查 |
| `npm run smoke` | Shell/端口就绪性烟雾测试 |
| `npm run smoke:quick-open` | 快速打开排名助手 |
| `npm run smoke:capabilities` | 能力迁移、排名、就绪性和间隙持久性 |
| `npm run smoke:import` | 智能项目导入检查器 |
| `npm run smoke:receipts` | 运行收据存储 |
| `npm run smoke:receipt-export` | 收据过滤 + JSON/CSV 导出 |
| `npm run smoke:shelf-url` | `shelf://` URL 解析器 |
| `npm run smoke:adopt` | 采用/停止由另一个 ProcessManager 启动的工具 |
| `npm run smoke:library-safety` | 损坏库的备份和关闭恢复 |
| `npm run smoke:claude-connect` | 一键式 Claude Desktop 配置合并 |
| `npm run smoke:cursor-connect` | 一键式 Cursor MCP 配置合并 |
| `npm run smoke:codex-connect` | 一键式 Codex `config.toml` 插入 |
| `npm run smoke:mcp-path` | 优先使用 `/Applications` MCP 路径而不是桌面路径 |
| `npm run smoke:electron` | 库 + ProcessManager 集成烟雾测试 |
| `npm run smoke:mcp` | MCP 客户端端到端烟雾测试 |
| `npm run smoke:all` | 完整的产品前烟雾门控 |
</details>
CI 在 `main` 分支的推送和 PR 上运行 `npm run typecheck` 和 `npm run smoke:all`（在 macOS 上）。
## 状态
v0.5.x. 早期 - 独自构建，目前仅有大约一个人认真使用。欢迎提出问题和直接反馈。
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
