# Carbs

A research MCP server that bundles **SearXNG** (meta-search) + **Crawl4AI**
(JS-rendered web scraping) behind one command. Runs 100% local.

## Quick start

```bash
make up        # generates .env (token) if needed, starts searxng + crawl4ai + carbs
```

MCP endpoint: `http://localhost:8765/mcp` (streamable-http).

Register in your agent (opencode example):

```jsonc
// ~/.config/opencode/opencode.jsonc
"mcp": {
  "carbs": {
    "type": "http",
    "url": "http://127.0.0.1:8765/mcp",
    "enabled": true
  }
}
```

For Claude Code / Codex, the same `http://127.0.0.1:8765/mcp` URL works in
their MCP configs.

## Tools

| Tool | Purpose |
|------|---------|
| `search` | Meta-search with academic bias, deduped |
| `search_json` | Raw SearXNG JSON (answers, infoboxes) |
| `scrape` | Single URL → clean markdown (with fallback chain) |
| `crawl_urls` | Batch crawl, concurrency-capped |
| `extract_structured` | LLM JSON extraction from a page |
| `deep_research` | Search → parallel scrape → synthesize |
| `health` | Backend status |

## Config

Everything is env-driven — see `src/carbs/config.py` for the full list
(`SEARXNG_URL`, `CRAWL4AI_URL`, `CRAWL4AI_API_TOKEN`, `LLM_PROVIDER`, cache
TTL, crawl concurrency, ports).

## Development

```bash
uv sync --dev
uv run pytest
uv run python -m carbs --http --host 127.0.0.1 --port 8765   # run MCP locally against running backends
```

## License

MIT