# Fairquery Agent Trust & Data Safety (MCP server)

[![CI](https://github.com/fairquery/fairquery-agent-trust-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/fairquery/fairquery-agent-trust-mcp/actions/workflows/ci.yml)

One MCP server for AI agents that handle untrusted data. It covers four jobs:

- **PII and secret redaction**: check text before it reaches an LLM.
- **Email checks**: syntax, typos, disposable and role addresses, plus MX/SPF/DMARC in the paid tool.
- **Sanctions screening**: OFAC, EU, UK and UN lists.
- **Dependency vulnerabilities**: lookups against OSV.dev.

**Free tools need no token or account and run on your machine.** Paid tools are optional. They call public Fairquery Apify Actors with *your own* `APIFY_TOKEN`, and runs are billed to your Apify account.

## Tools

| Tool | Cost | What it does |
|---|---|---|
| `pii_list_detectors` | Free (local) | Catalog of detectors, redaction styles, and pricing for every paid tool |
| `pii_scan_text` | Free (local) | Finds PII and secrets in text. Findings are paged and show masked values only |
| `pii_redact_text` | Free (local) | Redacts with placeholder, mask or hash style. Can return a placeholder map |
| `pii_restore_text` | Free (local) | Puts the original values back into placeholder text (e.g. an LLM answer) using that map; lists placeholders the map does not cover |
| `pii_guard_documents` | $0.0015/doc + $0.0002/finding | Adds NER names/addresses, URLs and PDFs, and restore mode |
| `email_check_syntax` | Free (local) | Syntax, normalization, typo suggestions, disposable/role/free-provider flags |
| `email_validate_deliverability` | $0.00079/email | DNS/MX, null MX, SPF/DMARC, mail provider, verdict |
| `sanctions_list_sources` | Free (local) | Lists covered, issuing authorities, disclaimer |
| `sanctions_screen_names` | $0.003/name + $0.007/call | Fuzzy screening against OFAC SDN/Consolidated, EU, UK and UN |
| `osv_query_packages` | Free (api.osv.dev) | Vulnerable or not, plus advisory IDs, for up to 200 exact versions |
| `osv_get_vulnerability` | Free (api.osv.dev) | Full OSV advisory records |
| `osv_audit_dependencies` | $0.0005/package + $0.0015/vuln | Manifest/lockfile audit with severity, fixes and recommended version |
| `trust_screen_lead` | $0.00079/email + $0.003/name + $0.007/call | Email check and sanctions screening in parallel, merged into a pass/review/block decision per lead |

Every tool description has WHAT / WHEN / WHEN NOT / COST / RETURNS / EXAMPLE sections. Outputs are paged (`limit`, `offset`, `nextOffset`, `hasMore`). Errors use named codes: `APIFY_TOKEN_MISSING`, `APIFY_TOKEN_INVALID`, `APIFY_PAYMENT_REQUIRED`, `APIFY_ACTOR_RUN_FAILED`, `APIFY_TIMEOUT`, `INPUT_EMPTY`, `INPUT_TOO_LARGE`, `INVALID_ECOSYSTEM`, `OSV_FETCH_FAILED` and `VULN_NOT_FOUND`.

Paid tools use these Apify Actors: `fairquery/llm-data-guard-pii-secrets`, `fairquery/email-validator-mx-disposable`, `fairquery/sanctions-watchlist-screener` and `fairquery/osv-dependency-vulnerability-check`.

## When to use which tool

| You want to… | Use | Cost |
|---|---|---|
| Check a prompt, ticket or log for PII and secrets before it reaches an LLM | `pii_scan_text`, then `pii_redact_text` | Free, local |
| Put the original values back into the LLM's answer after `pii_redact_text` | `pii_restore_text` | Free, local |
| Also catch names and addresses, or scan PDFs or URLs | `pii_guard_documents` | Paid |
| Catch typos, disposable or role addresses on a signup form | `email_check_syntax` | Free, local |
| Check that an email's domain can receive mail (MX, null MX, SPF/DMARC) | `email_validate_deliverability` | Paid |
| See which sanctions lists are covered and the disclaimer | `sanctions_list_sources` | Free, local |
| Screen people or companies against OFAC, EU, UK and UN sanctions lists | `sanctions_screen_names` | Paid |
| Get a pass/review/block decision for a new lead (email and name together) | `trust_screen_lead` | Paid |
| Find out whether exact package versions have known vulnerabilities | `osv_query_packages`, then `osv_get_vulnerability` for details | Free (api.osv.dev) |
| Audit a whole manifest or lockfile with severity, fixed and recommended versions | `osv_audit_dependencies` | Paid |

Start with the free tools. Use a paid tool only when you need what it adds; each paid call runs an Apify Actor billed to your own token.

## Install

Requires Node.js 20 or later. `APIFY_TOKEN` is optional and only needed for paid tools. Get one at <https://console.apify.com/settings/integrations>.

Quick start (stdio):

```bash
npx -y @fairquery/agent-trust-mcp
```

The configs below run the [npm package](https://www.npmjs.com/package/@fairquery/agent-trust-mcp) with `npx -y`: no clone or build step needed.

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "fairquery-trust": {
      "command": "npx",
      "args": ["-y", "@fairquery/agent-trust-mcp"],
      "env": { "APIFY_TOKEN": "<optional-your-apify-token>" }
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "fairquery-trust": {
      "command": "npx",
      "args": ["-y", "@fairquery/agent-trust-mcp"],
      "env": { "APIFY_TOKEN": "<optional-your-apify-token>" }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)
```json
{
  "inputs": [{ "type": "promptString", "id": "apify-token", "description": "Apify token (optional, paid tools only)", "password": true }],
  "servers": {
    "fairquery-trust": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fairquery/agent-trust-mcp"],
      "env": { "APIFY_TOKEN": "${input:apify-token}" }
    }
  }
}
```

### From source / Docker
```bash
git clone https://github.com/fairquery/fairquery-agent-trust-mcp && cd fairquery-agent-trust-mcp
npm ci && npm run build && node dist/index.js            # stdio
node dist/index.js --http                                # Streamable HTTP on http://127.0.0.1:3000/mcp (PORT, HOST env)
docker build -t fairquery-trust-mcp . && docker run -i --rm -e APIFY_TOKEN fairquery-trust-mcp
```

### MCPB bundle (Smithery local install, Claude Desktop)
`manifest.json` describes an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle that runs this server locally over stdio. The bundle asks for one optional, sensitive setting: **your own** Apify API token. Leave it empty to use only the free tools.
```bash
npm run build:mcpb   # -> build/fairquery-agent-trust-mcp-<version>.mcpb (dist + production node_modules)
npm run test:mcpb    # unpack, initialize, tools/list, free call, paid call without token -> APIFY_TOKEN_MISSING
```

`build:mcpb` also writes `<name>-smithery.mcpb`, the file to upload to Smithery. It is the same bundle with only `manifest.json` changed: each tool also carries its `inputSchema`, `outputSchema` and `annotations`, taken from the server's own `tools/list`. Smithery's publish API needs these for its server card, but the MCPB 0.3 manifest schema allows only `name`/`description` per tool, so the canonical `.mcpb` keeps the spec-valid manifest. `test:mcpb` tests both bundles and checks that they differ only in those tool schemas.

## Tests
```bash
npm run smoke        # initialize + tools/list + guide/annotation checks, no token
npm run test:live    # every free tool live, ReDoS probes, paid tools without token -> APIFY_TOKEN_MISSING
npm run test:paid    # also ONE paid call per family using APIFY_TOKEN from env (costs < $0.02)
```

## Security
See [SECURITY.md](SECURITY.md). Free tools never contact Apify or Fairquery, and the code contains no secrets.

## Disclaimer
Sanctions results come from automated fuzzy matching and are not a certified screening service. Review every potential match yourself. Email checks do not probe SMTP mailboxes.

## License
MIT © Fairquery