<!-- 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+.

```bash
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:

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

Machine migration:

```bash
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`.

```bash
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:

```json
{
  "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](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

```bash
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](LICENSE)

---

## 中文说明

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

```bash
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](#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。