# Research Scout Provider

[![CI](https://github.com/CaBsCrypto/research-scout-provider/actions/workflows/ci.yml/badge.svg)](https://github.com/CaBsCrypto/research-scout-provider/actions/workflows/ci.yml)

Independent English/Spanish TypeScript provider that turns caller-supplied source metadata and excerpts into deterministic, traceable research fixtures. It exposes an HTTP API and an MCP-shaped `stdio` tool.

Proveedor TypeScript independiente en inglés/español que convierte metadatos y extractos proporcionados por el cliente en resultados de investigación deterministas y trazables. Expone una API HTTP y una herramienta MCP por `stdio`.

> This service does not fetch source URLs or perform live fact-checking. It never contacts Stellar Bazaar. The public deployment is a standalone demonstration endpoint.

Live deployment: [https://research-scout-provider.vercel.app](https://research-scout-provider.vercel.app)

## Public API

After deployment, the following routes are available:

| Method | Route | Purpose |
| --- | --- | --- |
| `GET` | `/` | Provider metadata and route discovery |
| `GET` | `/health` | Health and operating-mode status |
| `POST` | `/v1/research` | Produce cited findings from supplied sources |

Example request:

```bash
curl -X POST "$PROVIDER_URL/v1/research" \
  -H "content-type: application/json" \
  -d '{
    "query": "What is Stellar used for?",
    "locale": "en",
    "maxSources": 5,
    "sources": [{
      "title": "Example source",
      "url": "https://example.com/article",
      "excerpt": "Caller-provided evidence.",
      "publisher": "Example",
      "publishedAt": "2026-01-01T00:00:00Z"
    }]
  }'
```

The response contains `summary`, individually cited `findings`, normalized `citations`, explicit `limitations`, and `mode: "local_fixture"`. Select Spanish with `"locale": "es"`.

La respuesta incluye `summary`, `findings` con citas individuales, `citations` normalizadas, `limitations` explícitas y `mode: "local_fixture"`. Usa `"locale": "es"` para español.

## Input limits

- Query: 2–500 characters.
- Sources: 1–25 entries; only HTTP(S) URLs are accepted.
- Source title: up to 300 characters; excerpt: up to 2,000 characters.
- `maxSources`: 1–10, default 5.
- Local Node server request body: maximum 64 KiB.
- No credentials, wallet data, payment data, or secrets should be submitted.

## Local development

Requires Node.js 20 or newer.

```bash
npm ci
npm run check
npm start
```

The local HTTP server listens on `http://127.0.0.1:8787`. To run MCP over `stdio` after building:

```bash
npm run build
npm run start:mcp
```

The MCP tool is named `research_with_sources`. Its input and output contract matches the HTTP endpoint.

## Deploy to Vercel

This repository includes `vercel.json` and three serverless entry points under `api/`. Deploy it as a separate Vercel project:

```bash
npx vercel
npx vercel --prod
```

No environment variables are required. Vercel rewrites `/`, `/health`, and `/v1/research` to their corresponding serverless functions.

## Safety and data policy

- No outbound network requests or browser automation.
- No persistence, authentication, payments, wallets, or credential handling.
- Stable source IDs are derived from source URLs with SHA-256 when omitted.
- Output synthesizes only caller-supplied text and is not independent verification.
- No integration with or publication to Stellar Bazaar.

See [`service-card.json`](./service-card.json) for machine-readable discovery.

## License

Apache License 2.0. See [`LICENSE`](./LICENSE).