mcp-server-xtrust

# mcp-server-xtrust

MCP (Model Context Protocol) server for **[xtrust.info](https://xtrust.info)** — a Ukrainian business directory with trust signals. Ask your AI assistant *"знайди компанію Розетка, який у неї ЄДРПОУ?"* and it will answer with the company's contacts, rating, phone/website reputation and the official legal-entity record from the Ukrainian state registry (ЄДР).

This package is a thin stdio bridge to the site's native MCP endpoint (`https://xtrust.info/mcp`). Tools are discovered at startup, so the package never goes stale.

## Tools

| Tool | Description | Auth |
|------|-------------|------|
| `lookup_company` | Look up a company by slug or name: contacts, rating, phone reputation (KtoZvonil), site trust (Truster) and the official ЄДР legal entity (name, ЄДРПОУ, status, director) | none |
| `search_companies` | Search companies by name prefix, optionally filtered by city (Ukrainian); returns matches with rating and link | none |
| `post_review` | Post a company review on behalf of an authenticated user (labelled as AI-agent-generated, shown separately, does not affect the human trust rating) | OAuth bearer |

## Install

### Claude Code

```bash
claude mcp add xtrust -- npx -y mcp-server-xtrust
```

### Claude Desktop

```json
{
  "mcpServers": {
    "xtrust": {
      "command": "npx",
      "args": ["-y", "mcp-server-xtrust"]
    }
  }
}
```

### Cursor / Windsurf / other MCP clients

Any client that speaks stdio MCP works the same way: command `npx`, args `-y mcp-server-xtrust`.

### Remote (no install)

MCP clients that support remote servers can skip this package entirely and connect straight to:

```
https://xtrust.info/mcp
```

## Configuration

| Env var | Meaning |
|---------|---------|
| `XTRUST_MCP_URL` | Override the endpoint URL (default `https://xtrust.info/mcp`) |
| `XTRUST_TOKEN` | OAuth bearer token — only needed for `post_review`. Discovery: [`/.well-known/oauth-protected-resource`](https://xtrust.info/.well-known/oauth-protected-resource) |

## Example

> **User:** Знайди компанію Розетка, який у неї ЄДРПОУ?
>
> **Assistant:** *(calls `search_companies`, then `lookup_company`)* Знайшов: «Розетка» на xtrust.info — інтернет-магазин, Київ. Офіційна юрособа в ЄДР: ТОВ «РОЗЕТКА.УА», ЄДРПОУ 37193071, стан — зареєстровано…

## Development

```bash
npm install
npm run build
npm test
```

## Related

- [xtrust.info](https://xtrust.info) — the service itself (uk/ru/en)
- API docs: [xtrust.info/.well-known/api-catalog](https://xtrust.info/.well-known/api-catalog)

## License

MIT © [xtrust.info](https://xtrust.info)