ToolScope

Mac의 모든 도구를 스캔하여 사람과 AI 에이전트가 조회할 수 있게 만듭니다.

ToolScope는 Homebrew, npm, pipx, uv, /Applications 및 $PATH를 통해 설치된 GUI 애플리케이션과 CLI 도구를 로컬 SQLite 데이터베이스(~/.toolscope/toolscope.db)에 정리합니다. 기능으로 검색하거나, 정리 대상을 감사하거나, MCP를 통해 AI 에이전트가 조회할 수도 있습니다. 읽기 전용이라 아무것도 삭제하지 않습니다.

왜 필요한가

• 설치한 것을 잊어버립니다. 수년간 brew install, npm install -g, pipx install을 반복하면 수백 개 항목이 쌓입니다. 하지만 brew list는 사용 여부를 알려주는 신호 하나 없는 텍스트 벽일 뿐입니다.

• 도구 이름이 아니라 작업이 기억납니다. "동영상 트랜스코딩"을 하고 싶지만 그게 ffmpeg라는 걸 기억하지 못하는 경우가 많습니다. ToolScope는 이름뿐 아니라 손으로 작성한 설명과 AI가 생성한 기능 설명까지 검색합니다.

• AI 에이전트는 내 머신을 볼 수 없습니다. 코딩 에이전트가 작업을 받아도 "이 Mac이 무엇을 할 수 있지?"라는 질문에 대한 구조화된 답이 없습니다. ToolScope는 MCP 도구 호출 한 번으로 그 답을 제공합니다.

Related MCP server: WEATHGARDS

기능

• 여섯 가지 소스를 한 번에 스캔해 ~/.toolscope/toolscope.db의 SQLite로 저장합니다. 재스캔하면 UPSERT 방식으로 갱신하며 first_seen은 보존됩니다.

• 이름, 수동 작성 설명, AI 생성 설명을 아우르는 기능 검색

• 멱등(idempotent) zvsh preexec hook을 통한 사용 추적(usage.count, usage.last_used)로 실제로 사용되지 않는 도구를 알 수 있습니다.

• 로컬 웹 대시보드(React + TypeScript, UI 프레임워크 없음): 여섯 가지 뷰(개요 카드, 검색 가능한 도구 목록, 미사용 도구 뷰, 사용량 통계(Top 20 + 30일 추이), 첫 실행 안내, LLM 설정)와 ⌘K 명령 팔레트, 상세 드로어를 제공합니다.

• 에이전트 연동용 세 도구를 갖춘 stdio MCP 입을 지원합니다.

• 머신 마이그레이션을 위한 Brewfile 내보내기

• doctor 환경 자가 점검

• 모든 OpenAI 호환 엔드포인트로 생성하는 선택형 한 줄 중국어 기능 설명. provider/model/key는 대시보드 설정 탭 또는 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 envelope({"items": [...], "total": N})를 출력합니다.

사용량 추적:

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

머신 마이그레이션:

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

AI 에이전트용

동일한 JSON 계약으로 제공되는 두 가지 통합 표면이 있습니다.

CLI. 목록 명령은 --json을 받아 {"items": [...], "total": N}을 출력하고, 단일 객체 명령은 객체 자체를 출력합니다. 도구 객체는 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으로 제공하며, 모든 목록 엔드포인트는 위의 envelope을 반환합니다: /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. LLM 설정도 에이전트에서 관리할 수 있습니다: GET/PUT /api/settings, GET /api/settings/providers, POST /api/settings/test. API 키는 항상 마스킹된 상태로만 반환되며 전체를 절대로 노출하지 않습니다.

MCP. 먼저 추가 패키지를 설치하세요: pipx install "toolscope[mcp]". 그런 다음 클라이언트에 서버를 등록하세요 — Claude Code 스타일 mcpServers 설정:

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

세 가지 도구가 제공됩니다:

• search_tools(query, kind?) — 기능 검색("이 머신으로 X를 할 수 있는가?"); 위 envelope을 반환합니다.

• get_tool(name) — 단일 도구 객체를 반환하거나, 없을 때는 문자 그대로의 텍스트 null을 반환합니다(오류가 아닌 정상 결과).

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

스크린샷

첫 전체 기기 캡처 전까지 자리 표시이며, 예정된 이미지의 목록은 docs/screenshots.md에 나와 있습니다.

작동 원리

scan은 여섯 소스에서 수집해 ~/.toolscope/ 아래 SQLite에 (name, kind, origin) 기준으로 UPSERT합니다. 나중에 시스템에서 사라진 항목도 삭제하지 않고 유지합니다.

매니저 바이너리가 없는 소스가 있어도 스캔은 실패하지 않습니다. 해당 소스는 건너뜀으로 보고되며 개수는 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).

라이선스

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 envelope 출력을 지원하고, HTTP API는 같은 데이터 표면(/api/tools, /api/search?q=, /api/usage/stats, /api/settings 등)을 제공하며, mcpServers 설정으로 toolscope mcp를 stdio MCP 서버로 등록할 수도 있습니다(세 가지 도구: search_tools / get_tool / machine_stats). 라이선스는 MIT입니다.