ToolScope

扫描 Mac 上的所有工具，让人类和 AI Agent 都能查询。

ToolScope 把安装在你 Mac 上的 GUI 应用和 CLI 工具——来自 Homebrew、npm、pipx、uv、/Applications 以及 $PATH——集中到一个本地 SQLite 数据库。你可以按能力搜索、审计清理，或者通过 MCP 让 AI Agent 查询。只读：它从不卸载任何东西。

为什么

• 你忘了自己装过什么。 多年累计的 brew install、npm install -g 和 pipx install 留下几百条记录；brew list 只是一大段没有使用信号的文字墙。

• 你只记得要做的事，不记得工具名。 你想「转码视频」，却想不起那是 ffmpeg。ToolScope 搜索的是描述和 AI 生成的能力注释，而不只是名称。

• AI Agent 看不到你的机器。 当编程 Agent 接手一个任务时，对「这台 Mac 能做什么？」没有结构化答案。ToolScope 用一次 MCP 工具调用回答这个问题。

Related MCP server: WEATHGARDS

功能

• 一次性扫描六个来源，写入 ~/.toolscope/toolscope.db 中的 SQLite；重新扫描时 UPSERT 就地更新，并保留原有的 first_seen

• 按能力跨名称、手写描述和 AI 生成描述搜索

• 通过幂等的 zsh preexec 钩子跟踪使用情况（usage.count、usage.last_used），让你知道什么工具其实早已不用

• 本地 Web 仪表盘（React + TypeScript，无 UI 框架）：六个视图——概览卡片、可搜索工具列表、未使用视图、使用统计（Top 20 + 30 天趋势）、首次运行引导和 LLM 设置——外加 ⌘K 命令面板与详情抽屉

• 支持三个工具的 stdio MCP 服务器，方便 Agent 集成

• 导出 Brewfile，方便机器迁移

• doctor 环境自检

• 可选：通过任何与 OpenAI 兼容的 endpoint 生成一行中文能力说明；provider、model、key 在仪表盘的 Settings 标签页或 toolscope config 中配置（本地以 0600 权限保存，无需环境变量）

• 可选：用轻量 Electron 外壳包裹仪表盘

快速开始

要求 macOS 和 Python 3.12+。

pipx install toolscope
toolscope scan                  # ~13s; prints per-source counts; missing sources count 0
toolscope list                  # everything recorded so far
toolscope search video --json   # capability search; parseable JSON envelope
toolscope serve                 # dashboard at http://127.0.0.1:8421

CLI 参考

列表类命令默认输出可读文本，使用 --json 时输出 JSON 信封：{"items": [...], "total": N}。

Usage tracking:

toolscope hook-install   # run once; new shells log each command to ~/.toolscope/usage.log

Machine migration:

toolscope scan
toolscope export --out Brewfile
brew bundle --file=Brewfile

For AI Agents

同一 JSON 契约上的两个集成入口。

CLI。 列命令支持 --json 并输出 {"items": [...], "total": N}；单对象命令直接打印对象。tool 对象的字段为 id, name, kind, version, path, origin, description, ai_description, usage:{count,last_used}|null。

toolscope search video --json
toolscope info ffmpeg --json
toolscope stats --json

HTTP API。 toolscope serve 在 127.0.0.1:8421 上通过 JSON 暴露相同数据，所有列表接口都返回上述信封：/api/tools、/api/tools/{id}、/api/search?q=、/api/stats、/api/usage/log、/api/usage/stats、/api/export（Brewfile 下载）、/api/doctor、/api/hook/snippet 以及 POST /api/scan。Agent 也可以管理 LLM 设置：GET/PUT /api/settings、GET /api/settings/providers、POST /api/settings/test。API key 始终只以掩码形式返回，绝不返回完整明文。

MCP。 先安装额外依赖：pipx install "toolscope[mcp]"。然后按 Claude Code 风格的 mcpServers 配置把服务注册到你的客户端：

{
  "mcpServers": {
    "toolscope": {
      "command": "toolscope",
      "args": ["mcp"]
    }
  }
}

共暴露三个工具：

• search_tools(query, kind?) — 能力搜索（「这台机器能否做 X」），返回上述信封

• get_tool(name) — 返回单个 tool 对象；未找到时返回文本 null（这是正常结果，不是错误）

• machine_stats() — 返回 {total, by_kind, never_used}

Screenshots

截图暂缺，等首台真机整机抓取后再补——计划中的截图列表见 docs/screenshots.md。

工作原理

scan 从六个来源收集信息，按 (name, kind, origin) 作为唯一键 UPSERT 到 ~/.toolscope/ 下的 SQLite 中。之后即便某些条目不再存在于系统里，也会被保留而不会删除。

某个来源的管理器缺失时，扫描不会失败；该来源会被标记为跳过且计数为 0。

开发

git clone <repo-url> && cd toolscope
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest -q                              # backend suite must be green
cd frontend && npm install && npm run build      # dashboard build; tsc must be clean
cd .. && toolscope serve                         # serves frontend/dist at :8421

可选桌面外壳：见 desktop/（npm install && npm start）。

License

MIT

中文说明

ToolScope 把 Mac 上经年累月装下的几十个 GUI 应用与上百个 CLI 工具收进一个本地 SQLite 库（~/.toolscope/），回答三个问题：我装过什么 / 它能干嘛 / 我用过没。只读产品，不卸载任何东西。

pipx install toolscope            # 需 MCP 时：pipx install "toolscope[mcp]"
toolscope scan                    # 全量扫描六来源，输出各来源计数；缺失来源计 0 跳过
toolscope search 视频 --json      # 能力搜索：跨名称与描述匹配，支持中文关键词
toolscope serve                   # 浏览器打开 http://127.0.0.1:8421 看板
toolscope config                  # 可选：配置 LLM 供应商/模型/Key（看板「设置」页签同源，Key 打码 0600 存储）
toolscope hook-install            # 可选：安装 zsh 钩子记录使用度（幂等）
toolscope export --out Brewfile   # 迁移新机时配合 brew bundle 还原环境

看板含六个视图（概览 / 列表 / 未使用 / 使用统计 / 引导 / 设置）、⌘K 命令面板和详情抽屉。AI Agent 接入见上文 For AI Agents：CLI 全部命令支持 --json 信封输出；HTTP API 覆盖同一数据面（/api/tools、/api/search?q=、/api/usage/stats、/api/settings 等）；或按 mcpServers 写法把 toolscope mcp 注册为 stdio MCP server（三工具：search_tools / get_tool / machine_stats）。许可证 MIT。