# @archimedes-market/mcp

**Ask before you install.**

Your coding agent picks dependencies on your behalf, often without you reading a line of them. This MCP server lets it check whether those packages are actually safe first — against [Archimedes](https://archimedes.market), which scores public GitHub repositories for **security, code quality, license health and completeness** (0–100 each) across a corpus of 3,000+ repos that grows daily.

```
> add a date library to this project

  check_dependencies(["date-fns", "moment", "dayjs"])

  ⚠ 1 dependency warrants review before shipping:
  - moment/moment: trust 61/100, security 48/100 — archimedes.market/r/moment/moment
```

## Trust tools

- **`check_dependencies(packages[])`** — the main one. Pass npm package names (`"express"`, `"@scope/pkg"`) or GitHub coordinates (`"owner/repo"`), up to 30. Returns overall + security score, trust badge and a report link for each. Call it before installing packages, when reviewing a `package.json` or lockfile, or when choosing between libraries. npm names are resolved to their GitHub repo automatically.
- **`check_repo_trust(owner, repo)`** — the full report for one repository: per-dimension scores, finding counts by severity, headline findings, detected licence, language, stars.
- **`search_trust_reports(query?, asset_class?, min_score?)`** — search the scored corpus. *"What are the most trustworthy MCP servers?"* Best-scoring first.

**An unscanned repo is not a bad repo.** If Archimedes hasn't looked at something yet, the tool says `not_scanned` and gives you a URL to scan it free — it never implies absence of a report means absence of quality.

## Bounty tools

- **`search_bounties`** — open engineering bounties by query, category, funding status, price band.
- **`get_bounty_details(id)`** — full requirements, deliverables and acceptance tests for one bounty.
- **`get_platform_stats()`** — aggregate counters. Cached upstream 60s.

Every bounty is funded in Stripe escrow before engineers see it, and every submission is AI-verified (Semgrep + LLM code review + licence scan) before the buyer sees it.

## Install

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "archimedes": {
      "command": "npx",
      "args": ["-y", "@archimedes-market/mcp"]
    }
  }
}
```

Restart Claude Desktop. The three tools (`search_bounties`, `get_bounty_details`, `get_platform_stats`) will appear in the available tools list.

### Cursor

Settings → MCP → Add server. Use the same config block as above.

### Continue / other stdio clients

Point the client at:

```
npx -y @archimedes-market/mcp
```

### Non-stdio clients (server-side agents, hosted bots)

Skip this package entirely — call the hosted HTTP endpoint directly:

```
POST https://archimedes.market/api/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_bounties",
    "arguments": { "query": "MCP server", "limit": 5 }
  }
}
```

Full docs: <https://archimedes.market/mcp>

## Example agent queries

> "Find me open Archimedes bounties for KiCad PCB review under $3,000."

> "Are there any MCP-server bounties on Archimedes right now? Show me the top 5 by payout, then give me the full requirements for the highest-paying one."

> "How active is Archimedes right now? How much has been paid out?"

The tools return both a human-readable text block (for the model to reason over) and a structured payload (for downstream tooling).

## Configuration

| Env var | Default | Purpose |
|---------|---------|---------|
| `ARCHIMEDES_PUBLIC_API_URL` | `https://archimedes.market` | Override the upstream base URL (preview deployments, local dev) |
| `ARCHIMEDES_MCP_USER_AGENT` | `mcp-archimedes/0.2 (+https://archimedes.market)` | Override the `User-Agent` sent on outbound calls |

## Health check

Verify the bridge can reach the upstream API before wiring it into a client:

```bash
npx @archimedes-market/mcp --probe
```

Exit code 0 means upstream is reachable. Non-zero with stderr diagnostic on failure.

## Privacy

The Archimedes public API logs `query_hash` (SHA-256 of normalized params) and `ip_hash` (HMAC with daily-rotated salt) per call — never raw queries or raw IPs. 90-day retention. Zero-result queries are aggregated to inform what bounties Archimedes should source next.

## License

MIT. See [LICENSE](LICENSE).

## Links

- Hosted MCP endpoint: <https://archimedes.market/api/mcp>
- REST API: <https://archimedes.market/api/public/bounties>
- Browse bounties: <https://archimedes.market/bounties>
- MCP spec: <https://modelcontextprotocol.io>