# vigilix-mcp

<!-- mcp-name: io.github.zekinht0/vigilix-mcp -->

**Official French data for AI agents: companies (SIREN), legal notices (BODACC), addresses and natural/industrial hazards. Pay per call in USDC on Base via [x402](https://x402.org). No account, no API key.**

`vigilix-mcp` is a local [MCP](https://modelcontextprotocol.io) server (stdio) that exposes the paid endpoints of [siren.vigilix.fr](https://siren.vigilix.fr) as MCP tools. Each call is paid on the fly from a wallet you control, with strict spending guardrails.

## Tools

| Tool | What it does | Price per call |
|---|---|---|
| `search_french_company` | Search companies by name → SIREN, status, NAF code, city | $0.002 |
| `get_french_company` | Company profile by SIREN: status, head office, directors, headcount, revenue | $0.005 |
| `check_bodacc_notices` | BODACC legal notices: insolvency proceedings, strike-off, latest notices | $0.005 |
| `geocode_french_address` | Address → GPS coordinates, normalized address, INSEE code | $0.003 |
| `reverse_geocode_france` | GPS coordinates → nearest French address | $0.003 |
| `french_address_risk_report` | Natural and industrial hazard report (Géorisques) for an address or point | $0.02 |

Prices are paid in USDC on Base mainnet. **You are not charged when a call fails or finds nothing** (invalid input, not found, upstream source unavailable). Invalid arguments are rejected locally before any network call.

## Quick start

Without a wallet the server runs in **discovery mode**: every tool answers with its real price (read live from the API) and how to enable payments, and never pays. This is a safe way to check the installation.

To make paid calls, set `EVM_PRIVATE_KEY` to the private key of a **dedicated** wallet (see [Wallet & safety](#wallet--safety)).

### Claude Desktop

Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "vigilix": {
      "command": "npx",
      "args": ["-y", "vigilix-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x…dedicated wallet key…",
        "VIGILIX_MAX_PRICE_USD": "0.05",
        "VIGILIX_SESSION_BUDGET_USD": "1.00"
      }
    }
  }
}
```

### Claude Code

```bash
# Discovery mode (no wallet)
claude mcp add vigilix -- npx -y vigilix-mcp

# Paid mode: type the key without echo so it does not land in your shell history
read -rs EVM_PRIVATE_KEY
claude mcp add vigilix --scope user -e EVM_PRIVATE_KEY="$EVM_PRIVATE_KEY" -- npx -y vigilix-mcp
unset EVM_PRIVATE_KEY
```

### Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project — never commit it):

```json
{
  "mcpServers": {
    "vigilix": {
      "command": "npx",
      "args": ["-y", "vigilix-mcp"],
      "env": { "EVM_PRIVATE_KEY": "0x…dedicated wallet key…" }
    }
  }
}
```

Any other MCP client that can launch a stdio server works the same way: command `npx -y vigilix-mcp`, plus the environment variables below.

## Configuration

| Variable | Purpose | Default |
|---|---|---|
| `EVM_PRIVATE_KEY` | Private key of the dedicated paying wallet. Optional (discovery mode without it). | — |
| `VIGILIX_MAX_PRICE_USD` | Maximum price accepted for a single call | `0.05` |
| `VIGILIX_SESSION_BUDGET_USD` | Maximum total spend per server process (session) | `1.00` |
| `VIGILIX_API_URL` | API base URL (for testing only) | `https://siren.vigilix.fr` |

## Wallet & safety

- **Use a dedicated wallet** holding only a few dollars of USDC on Base. Never use your main wallet: MCP clients store the key in plain text in their configuration file.
- No ETH is needed: payments are gasless USDC authorizations (EIP-3009) settled by the x402 facilitator.
- Before signing anything, the server checks the payment request returned by the API and **refuses to pay** unless all of these hold:
  - network is Base mainnet (`eip155:8453`), scheme `exact`;
  - asset is USDC on Base (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`);
  - recipient (`payTo`) is exactly the vigilix address `0x376d3415E3AC9E9090396737c81bB4C62a3839dF`, hard-coded in the package;
  - the amount is at most the tool's listed price above **and** at most `VIGILIX_MAX_PRICE_USD`;
  - the session budget (`VIGILIX_SESSION_BUDGET_USD`) is not exceeded.
- **Price changes:** the listed prices are part of the package. If the API ever raises a price, calls to that tool are refused until you update `vigilix-mcp` (`npx -y vigilix-mcp@latest`, or restart your MCP client so `npx` fetches the new version).
- The key is never logged, written to disk or included in tool results; it is removed from the process environment at startup. Only the wallet's public address is printed (on stderr) at startup.
- Every paid result includes a `payment` block (`amount_usd`, `tx`, `network`, `session_spent_usd`) so you can verify the transaction on [Basescan](https://basescan.org).

## Output

Successful calls return the API's JSON as structured content:

```json
{
  "data": { "...": "API response" },
  "payment": { "amount_usd": "0.002", "tx": "0x…", "network": "base", "session_spent_usd": "0.002" }
}
```

## Data sources & licences

Data comes from official French open data, redistributed under the [Licence Ouverte / Etalab 2.0](https://www.etalab.gouv.fr/licence-ouverte-open-licence/):

- Companies: INSEE Sirene and RNE (INPI)
- Legal notices: BODACC (DILA)
- Addresses: Base Adresse Nationale (BAN) via IGN Géoplateforme
- Hazards: Géorisques (Ministère de la Transition écologique, BRGM)

API documentation for agents: [llms.txt](https://siren.vigilix.fr/llms.txt) · [OpenAPI](https://siren.vigilix.fr/openapi.json)

## Development

```bash
npm install
npm test                  # unit tests (builds first; includes a check against the live OpenAPI)
npm run test:integration  # read-only checks of the real 402 for each tool, no payment
npm run gen:schemas       # regenerate input schemas from the live OpenAPI
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
```

## En français

`vigilix-mcp` est un serveur MCP local qui donne aux agents IA l'accès aux données officielles françaises : entreprises (SIREN), annonces BODACC, géocodage d'adresses et rapport de risques Géorisques. Chaque appel est payé à l'unité en USDC sur Base via x402, sans compte ni clé d'API. Sans clé, le serveur fonctionne en mode découverte : il indique le prix réel de chaque outil sans rien payer. Pour payer, utilisez **un wallet dédié** contenant seulement quelques dollars d'USDC. Le serveur vérifie avant chaque paiement le réseau, l'actif, le destinataire, le prix maximal et le budget de session. Vous n'êtes pas débité si l'appel échoue ou ne trouve rien. Si un prix augmente côté API, mettez à jour le paquet.

## License

MIT