# toolscout

**Describe a task, get the best open source tools for it, each with an honest trust label, and nothing installed without your permission.**

*toolscout* is an [MCP](https://modelcontextprotocol.io) server plus an [Agent Skill](https://agentskills.io) for AI coding agents. It works with Claude Code and other MCP-compatible agents.

```
You:   I want shapes in my SVG map animation to morph smoothly into each other.

Agent: 🟢 flubber: smooth shape-to-shape SVG animation
          6.9k stars · MIT · ~480k npm downloads/month
          Trust: widely used, licensed, no known vulnerabilities
          Note: no code changes for about 4 years (stable, but not actively maintained)
          Install: npm install flubber. Shall I install it?
```

## Why

Keyword search misses good tools when they describe themselves in other words. In our first test, a plain GitHub search for "morph svg shapes" did not return [flubber](https://github.com/veltman/flubber), the best-known library for exactly that. Searching several phrasings across several registries, plus maintainer keywords and topics, found it in the top results.

## What it does

1. **Searches broadly**: several phrasings and keywords across GitHub and the npm registry, merging hits that point to the same project.
2. **Checks fit**: the agent reads the top candidates' READMEs to confirm they really do the task.
3. **Checks trust**: stars, downloads, license, last code change, archive and deprecation status, OpenSSF Scorecard and known vulnerabilities (OSV), via [deps.dev](https://deps.dev), GitHub and npm.
4. **Asks before installing**: always, with the exact command. Red-labelled tools need an explicit "I understand the risk".

## Trust labels

| Label | Meaning |
|---|---|
| 🟢 Green | Widely used, maintained, licensed, no known vulnerabilities. **Not a guarantee of safety.** |
| 🟠 Orange | Reasons for caution: few users, not maintained for 18+ months, unclear license, low security score, a package that points to a different repository, or not checkable. |
| 🔴 Red | A known concrete problem: archived, deprecated, known vulnerability or malicious package report. |

**Look-alike packages.** Any npm package can claim any repository as its source, so a fake package could borrow a famous repository's stars ("star-jacking"). A repository's stars count for a package only when the link is confirmed, by signed build provenance (SLSA) or by the repository's own `package.json`. Otherwise the package is judged on its own downloads.

The exact thresholds are in [`src/trust.ts`](src/trust.ts) and explained in [`docs/trust-rules.md`](docs/trust-rules.md).

## Tools

| Tool | What it does |
|---|---|
| `search_repositories` | Searches GitHub and npm with several queries and keywords; returns merged, ranked candidates. |
| `assess_repository` | Returns the trust label, reasons and facts for one repository or npm package. |
| `read_readme` | Returns a GitHub README, clearly marked as untrusted content. |

## Install

Requirements: [Node.js](https://nodejs.org) 18 or newer and git.

```bash
git clone https://github.com/oemajans/toolscout.git
cd toolscout
npm install
npm run build
```

### Claude Code

From the `toolscout` folder:

```bash
claude mcp add toolscout -- node "$(pwd)/dist/index.js"
```

If search results say no GitHub token was found, register the server with the token passed explicitly (it is then stored in your local Claude Code config, not in this repository):

```bash
claude mcp add toolscout -e GITHUB_TOKEN=your-token-here -- node "$(pwd)/dist/index.js"
```

Then copy the skill so the agent knows how to use the tools:

```bash
mkdir -p ~/.claude/skills && cp -r skills/toolscout ~/.claude/skills/
```

### Other MCP clients

Add a stdio server that runs `node /full/path/to/toolscout/dist/index.js`. Most clients use a JSON config like this:

```json
{
  "mcpServers": {
    "toolscout": {
      "command": "node",
      "args": ["/full/path/to/toolscout/dist/index.js"],
      "env": { "GITHUB_TOKEN": "your-token-here" }
    }
  }
}
```

For the skill, copy `skills/toolscout` to the skills folder your agent reads; see your agent's documentation.

## GitHub token (optional, recommended)

Without a token, GitHub allows 10 searches per minute and 60 other requests per hour, so fewer candidates get checked. The tool tells you when this happens.

To create a token with **no permissions** (it can only read public repositories):

1. Open <https://github.com/settings/personal-access-tokens/new>.
2. Name it `toolscout`, pick an expiration, choose **Public repositories**, and add no permissions.
3. Generate it and store it as the environment variable `GITHUB_TOKEN`, or put it in your MCP client's `env` setting.

Never commit your token to a repository. Each user needs their own token; sharing tokens to get around GitHub's limits is against GitHub's terms.

## Data sources and limits

Only official, public APIs are used. No web pages are scraped.

| Source | Used for | Pace |
|---|---|---|
| GitHub REST API | Search, repository facts, README | Search: 30/min with a token, 10/min without |
| npm registry API | Search, downloads | At most 1 request per second |
| [deps.dev](https://deps.dev) API | Stars, license, OpenSSF Scorecard, deprecation, OSV vulnerabilities | Polite pacing, cached for a day |

Responses are cached on your computer in `~/.cache/toolscout` to avoid repeat requests. deps.dev data is licensed CC-BY 4.0 by Google.

## Privacy

toolscout runs on your computer. It sends your search phrases to the APIs above and nothing else. It does not collect personal data, has no telemetry, and does not store or republish data from these services beyond the local cache. It never calls an AI model itself; your agent does the thinking.

## How well does search work?

`npm run benchmark` checks whether a known good tool shows up for six real tasks from a map-animation video project. Current result: the expected tool is in the top 5 for 5 of 6 tasks (flubber #5, d3-geo #1, mapshaper #3, yt-dlp #2, gsap #3). The miss is PDF text extraction: Mozilla's pdf.js ranks #25 because many PDF tools compete for the same words. The agent sees the top 25 and reads READMEs before recommending, but the number tells you where search alone stands.

## Limitations

- A green label means "no known problems found", not "safe". Always review what you install.
- Search covers GitHub and npm only for now. GitLab, Codeberg, Hugging Face and crates.io are planned.
- Trust checks for npm packages (deprecation, vulnerabilities) need the npm package name.
- The agent decides the final ranking after reading READMEs, so results vary between agents and models.

## Development

```bash
npm run build      # compile TypeScript to dist/
npm test           # unit tests for trust rules and URL handling
npm run try-search -- "shape morph" "#morph"   # manual search check ("#" marks a keyword)
npx tsx scripts/try-mcp.ts                      # end-to-end check over MCP
```

## License

[MIT](LICENSE). Not affiliated with or endorsed by Anthropic, GitHub, npm or Google.