# Ollama Web Tools MCP

Python 3.12+ MCP server preserving the Ruby oracle's `web_search` and `web_fetch`
contracts and adding `cluesift_domain_fetch`. It uses the official Python MCP SDK,
stdio by default, and stateless JSON streamable HTTP at `/` with `--http`.

## Configuration

Production (`prod` or `production` in the first set of `ENVIRONMENT`,
`CLUESIFT_ENV`, or `ENV`) requires `OLLAMA_KEY_POOL_FILE`. The reloadable UTF-8
JSON document has exactly this useful shape; array order is strict priority and
duplicates are removed while preserving first occurrence:

```json
{"keys":["primary-ollama-tools-key","secondary-ollama-tools-key"]}
```

The file is re-read when its mtime changes or after a two-second TTL. Outside
production only, comma-separated `OLLAMA_CLOUD_API_KEYS`, then `OLLAMA_API_KEY`,
are fallback inputs. Keys are never logged; diagnostics identify them only by the
first 12 lowercase hex characters of SHA-256.

Optional Ollama timeouts: `OLLAMA_OPEN_TIMEOUT=10`, `OLLAMA_READ_TIMEOUT=60`,
`OLLAMA_WRITE_TIMEOUT=30`. ClueSift aliases use complete endpoint URLs (not base
URLs):

* `cluesift-test`: `CLUESIFT_ARTIFACT_TEST_URL` and `_TOKEN`
* `cluesift-prod`: `CLUESIFT_ARTIFACT_PROD_URL` and `_TOKEN`

Each pair must be wholly present or absent. Callback timeout defaults are
`CLUESIFT_ARTIFACT_OPEN_TIMEOUT=2`, `...READ_TIMEOUT=5`, and
`...WRITE_TIMEOUT=5`. Callback failures are content-free telemetry and never
replace a successful fetch result.
Callback URLs are complete absolute HTTP(S) endpoints, may use only their
scheme's default port, and may not contain userinfo, a query, or a fragment.
Fetched public URLs reject trailing-dot hosts rather than canonicalizing them.

## Run and develop

```bash
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ollama-web-tools-mcp
.venv/bin/ollama-web-tools-mcp --http --port 8767
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/pytest
```

The three tools are exactly `web_search`, `web_fetch`, and
`cluesift_domain_fetch`. The ClueSift tool accepts only `url`, `artifact_target`,
`request_id`, and `case_id`; see the copied implementation brief for its full
security and delivery contract.