# datajud-mcp-server

An MCP server for querying the [CNJ DataJud](https://datajud-wiki.cnj.jus.br/) public API — Brazil's national judicial process database — by unified CNJ process number. Unofficial; not affiliated with or endorsed by the CNJ.

Every process number is validated offline before ever touching the network, successful lookups are cached, and every replica shares one Redis-coordinated rate limit budget kept safely under the CNJ's documented cap. See `docs/architecture.md` for the full design and `docs/adr/` for the reasoning behind each major decision.

## Requirements

- [Bun](https://bun.sh) 1.3+ (package manager)
- Node.js 24+ (runtime)
- Docker (for Redis in local dev, and for building the production image)
- A DataJud API key — see [Compliance](#compliance) below

## Quickstart

```bash
git clone <this-repo-url>
cd datajud-mcp-server
bun install
cp .env.example .env
docker compose up -d redis
```

### Option A — HTTP transport

```bash
bun run dev
```

In another terminal, call a tool over Streamable HTTP:

```bash
curl -s http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: <your-datajud-api-key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_lawsuit_by_number",
      "arguments": { "processNumber": "0000832-35.2018.4.01.3202" }
    }
  }'
```

The `Authorization` header carries your DataJud key for that request — a bare token is accepted and normalized; `APIKey <token>` also works. No key is stored server-side; it's forwarded to DataJud and otherwise only ever touches Redis as part of a cache/rate-limit key, never as a value (`docs/adr/0009-no-credential-persistence.md`).

`GET /health` is a liveness check; `GET /ready` additionally confirms Redis is reachable.

### Option B — stdio transport

```bash
DATAJUD_API_KEY=<your-datajud-api-key> bun run dev:stdio
```

stdio mode needs no Redis — it falls back to in-process cache and rate-limit adapters, correct for a single local user (`docs/adr/0004`, `docs/adr/0008`). Speak JSON-RPC over stdin/stdout to call the same tools as above.

Either transport should have a `tools/call` round-trip working in well under ten minutes from a fresh clone.

### Claude Desktop (stdio)

Add to Claude Desktop's MCP config:

```json
{
  "mcpServers": {
    "datajud": {
      "command": "node",
      "args": ["/absolute/path/to/datajud-mcp-server/src/main-stdio.ts"],
      "env": {
        "DATAJUD_API_KEY": "<your-datajud-api-key>"
      }
    }
  }
}
```

## Tools

| Tool | Network call? | Purpose |
|---|---|---|
| `validate_process_number` | no | Validate a CNJ process number offline and explain its structure. Call this first when a number's origin is uncertain. |
| `search_lawsuit_by_number` | yes | Look up a lawsuit by its unified CNJ process number. Returns one record per instance (grau) it appears in. |
| `list_courts` | no | List every court queryable through DataJud, with its alias and judiciary segment. |

Full input/output schemas and the error taxonomy are documented in `docs/mcp-tools.md`.

## Development

```bash
bun run test           # unit + integration + e2e
bun run test:coverage  # same, with coverage thresholds enforced
bun run test:live      # opt-in: hits the real DataJud API (needs DATAJUD_API_KEY), never runs in CI
bun run lint
bun run typecheck
bun run verify         # lint + typecheck + test:coverage + build — the same gate CI runs
```

Or run everything, app included, in Docker:

```bash
docker compose up --build
```

See `docs/contributing.md` for the branch model, commit convention, and PR checklist, and `docs/deployment.md` for how `staging`/`production` deploy to Coolify.

## Compliance

- **Unofficial client.** This project is not built, reviewed, or endorsed by the CNJ.
- **Rate limit.** The CNJ DataJud public API is capped at 120 requests/minute per key. This server enforces a distributed token bucket under that cap by default (`DATAJUD_RATE_LIMIT_PER_MINUTE`, `DATAJUD_RATE_LIMIT_SAFETY_FACTOR`) — see the [DataJud access terms](https://datajud-wiki.cnj.jus.br/api-publica/acesso) for the authoritative limit.
- **User-supplied key.** The server never ships or embeds a DataJud API key. Get your own from the [CNJ *Acesso*](https://datajud-wiki.cnj.jus.br/api-publica/acesso) page and supply it per-request (HTTP) or via `DATAJUD_API_KEY` (stdio/local).
- **Public metadata only.** DataJud exposes public judicial process metadata (parties' names are not returned by the API itself); this server does not add, infer, or cache any additional personal data beyond what DataJud returns.

## Security

See [SECURITY.md](SECURITY.md) for the vulnerability reporting process and what this project does (and does not) store.

## License

[MIT](LICENSE)