<!-- Logo placeholder: docs/assets/logo.svg -->

ToolScope

Scan every tool on your Mac and make it queryable by humans and AI agents.

ToolScope catalogs the GUI applications and CLI tools installed on your machine — via Homebrew, npm, pipx, uv, /Applications and $PATH — into a local SQLite database you can search by capability, audit for cleanup, or query from an AI agent over MCP. Read-only: it never uninstalls anything.

Why

• You forget what you installed. Years of brew install, npm install -g and pipx install leave hundreds of entries; brew list is a wall of text with no usage signal.
• You remember the task, not the tool name. You want "transcode video" but can't recall that it's ffmpeg. ToolScope searches descriptions and AI-generated capability notes, not just names.
• AI agents can't see your machine. When a coding agent picks up a task it has no structured answer to "what can this Mac do?" ToolScope answers that in one MCP tool call.

Features

• One-shot scan of six sources into SQLite at ~/.toolscope/toolscope.db; re-scans UPSERT in place and preserve first_seen
• Capability search across names, hand-written descriptions and AI-generated descriptions
• Usage tracking through an idempotent zsh preexec hook (usage.count, usage.last_used) so you know what is actually dead
• Local web dashboard (React + TypeScript, no UI framework): six views — overview cards, searchable tool list, unused view, usage statistics (Top 20 + 30-day trend), first-run guide and LLM settings — plus a ⌘K command palette and detail drawer
• stdio MCP server with three tools for agent integration
• Brewfile export for machine migration
• doctor environment self-check
• Optional one-line Chinese capability descriptions generated via any OpenAI-compatible endpoint; provider/model/key configured in the dashboard Settings tab or toolscope config (stored 0600 locally, no env vars needed)
• Optional thin Electron shell wrapping the dashboard

Quickstart

Requires macOS and 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 reference

Listing commands print human-readable text by default and the JSON envelope {"items": [...], "total": N} with --json.

Command	What it does
toolscope scan	Scan all six sources, UPSERT into the DB, print per-source counts
toolscope list [--json]	List every recorded tool (--kind / --sort / --unused-days filters)
toolscope search QUERY [--json]	Search across name / description / ai_description
toolscope info NAME [--json]	Single-tool detail; exits non-zero when not found
toolscope serve [--host H] [--port P]	Serve API + dashboard, port 8421 by default
toolscope stats [--json]	{total, by_kind, never_used} overview
toolscope mcp	Start the stdio MCP server
toolscope hook	Print the zsh preexec snippet
toolscope hook-install	Install the snippet into ~/.zshrc; idempotent, safe to re-run
toolscope export [--out FILE] [--json]	Emit a Brewfile (casks + formulae sections)
toolscope doctor [--json]	Environment check: source managers, frontend build, DB health
toolscope config	Show LLM settings (masked key); subcommands config set provider/base-url/model/api-key/clear-api-key and config test
toolscope describe	Optional LLM pass filling blank ai_description; reads settings from config (or env vars); exits 2 with setup guidance when no API key

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

Two integration surfaces over the same JSON contract.

CLI. Listing commands accept --json and print {"items": [...], "total": N}; single-object commands print the object directly. A tool object carries 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 exposes the same data over JSON on 127.0.0.1:8421, all list endpoints returning the envelope above: /api/tools, /api/tools/{id}, /api/search?q=, /api/stats, /api/usage/log, /api/usage/stats, /api/export (Brewfile download), /api/doctor, /api/hook/snippet, and POST /api/scan. LLM settings are manageable from agents too: GET/PUT /api/settings, GET /api/settings/providers, POST /api/settings/test. API keys are only ever returned masked, never in full.

MCP. Install the extra first: pipx install "toolscope[mcp]". Then register the server with your client — Claude Code style mcpServers config:

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

Three tools are exposed:

• search_tools(query, kind?) — capability search ("can this machine do X"); returns the envelope above
• get_tool(name) — single tool object, or the literal text null when not found (a normal result, not an error)
• machine_stats() — {total, by_kind, never_used}

Screenshots

Placeholder pending first full-machine capture — planned shots are listed in docs/screenshots.md.

How it works

scan collects from six sources and UPSERTs on (name, kind, origin) into SQLite under ~/.toolscope/. Entries that later disappear from the system are kept, not deleted.

Source	kind values	Collected via	Manager missing
/Applications, ~/Applications	app	Info.plist parsing	n/a on macOS
Homebrew	formula, cask	brew list --formula/--cask --versions	skipped, counted 0
$PATH directories	binary	executable files across PATH entries	empty result
npm global packages	npm	npm ls -g --json --depth=0	skipped, counted 0
pipx environments	pipx	pipx list --json	skipped, counted 0
uv tools	uv	uv tool list	skipped, counted 0

A source whose manager binary is absent never fails the scan; it is reported as skipped with count 0.

Development

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

Optional desktop shell: see 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。