Skip to main content
Glama
README.md
# Ocean MCP + Ingestor

Servidor MCP **somente leitura** e ingestão de dados marítimos brasileiros (condições do mar,
marés, defeso, embarcações, onde vender pescado e base de conhecimento). Alimenta o agente
[`ocean-agent-api`](https://github.com/RodrigoGalvao9/ocean-agent-api).

O projeto está dividido entre execução local, ingestão automática e hospedagem em nuvem.
Qualquer pessoa pode usar o servidor como desenvolvedor, contanto que respeite as fontes,
os créditos dos serviços externos e as regras de uso não comercial das APIs.

| Componente | Comando | Hospedagem recomendada |
|---|---|---|
| Servidor MCP | `python -m ocean.server` | Render |
| Ingestão | `python -m ocean.ingestion.run <job>` | GitHub Actions |
| Banco PostgreSQL | migrations em `migrations/` | Neon ou Supabase |
| Busca vetorial | coleção configurada no Qdrant | Qdrant Cloud |
| Cache | Redis | Render Key Value ou Redis compatível |

## Uso público

O projeto oferece ferramentas MCP de consulta. Ele não altera o estado das fontes externas
e não expõe operações de escrita para seus consumidores.

O `MCP_AUTH_TOKEN` protege o servidor em produção. Quem consumir o MCP precisa enviar o mesmo
Bearer token usado pela API `ocean-agent-api`. O `/health` continua público e serve apenas para
confirmar que o processo está operacional.

## Regras do projeto

1. O servidor é **somente leitura**: nenhuma ferramenta escreve estado.
2. O caminho de requisição lê Postgres, Qdrant e cache. Somente fontes ao vivo podem acessar
   serviços externos, usando timeout, novas tentativas limitadas e fallback para cache marcado
   como `stale`.
3. Toda ferramenta devolve `MaritimeDataResponse` (`src/ocean/shared/provenance.py`), com fonte,
   data da consulta, momento do dado e limitações.
4. Interpretação determinística, como escala Beaufort e fase da maré, fica em `domain/services`.
   O modelo de linguagem explica o resultado, mas não calcula a regra.
5. `server` e `ingestion` nunca importam um ao outro. Esse limite arquitetural é verificado
   pelo `lint-imports` no CI.
6. GFW e Open-Meteo exigem uso não comercial. Verifique os termos das fontes antes de ampliar
   o projeto ou de oferecer o serviço a terceiros.

## Estrutura

```
src/ocean/
  server/       MCP: ferramentas, autenticação, /health
  ingestion/    jobs, parsers, coletores
  domain/       modelos e serviços de interpretação
  retrieval/    vector (Qdrant) e structured (Postgres)
  storage/      postgres (conexão, migrações, execuções), cache (Redis)
  shared/       config, logging, http, proveniência
migrations/     SQL do esquema (a ingestão é a dona do esquema)
content/knowledge/   documentos do RAG (Markdown com cabeçalho)
data/           tabelas curadas (CSV)
tests/
```

## Primeiros passos

```bash
python -m venv .venv
.\.venv\Scripts\Activate.ps1     # Windows PowerShell
# source .venv/bin/activate      # Linux/macOS
pip install -e ".[server,ingest,dev]"
Copy-Item .env.example .env       # Windows
# cp .env.example .env           # Linux/macOS
```

Edite o `.env` com as credenciais próprias. Nunca faça commit desse arquivo.
Use os nomes da seção "Variáveis de ambiente" abaixo.

```bash
pytest -q
ruff check .
lint-imports
```

Use Python **3.12** no desenvolvimento, na imagem Docker e no GitHub Actions.
Depois da primeira instalação bem-sucedida, fixe o ambiente com
`pip freeze > constraints.txt`.

## Variáveis de ambiente

Crie valores próprios em cada provedor. Não reutilize credenciais do repositório.

| Variável | Uso |
|---|---|
| `MCP_AUTH_TOKEN` | Protege o servidor MCP em produção |
| `DATABASE_URL` | Banco PostgreSQL acessado localmente ou pelo servidor |
| `DATABASE_URL_UNPOOLED` | URL direta do Neon, quando fornecida pelo provedor |
| `REDIS_URL` | Cache Redis |
| `QDRANT_URL` | Endpoint da instância Qdrant |
| `QDRANT_API_KEY` | Chave da instância Qdrant |
| `QDRANT_COLLECTION` | Coleção padrão, por exemplo `ocean_conhecimento` |
| `CLOUDFLARE_ACCOUNT_ID` | Conta usada para embeddings |
| `CLOUDFLARE_API_TOKEN` | Token Cloudflare com acesso ao modelo |

### Variáveis reservadas à ingestão

No GitHub Actions, configure estes secrets em
**Settings → Secrets and variables → Actions**:

- `DATABASE_URL_ADMIN`
- `QDRANT_URL`
- `QDRANT_API_KEY`
- `CLOUDFLARE_ACCOUNT_ID`
- `CLOUDFLARE_API_TOKEN`

`DATABASE_URL_ADMIN` é a URL de um usuário administrativo do PostgreSQL. Ela é usada somente
pelo workflow de ingestão e pelas migrations. O servidor público deve usar preferencialmente
`DATABASE_URL` associado a um usuário somente leitura.

### Rodar o servidor local

```bash
python -m ocean.server             # http://localhost:8000  (/health, MCP em /mcp)
```

Verifique a instalação:

```bash
curl http://localhost:8000/health
```

Resposta esperada:

```json
{"status":"ok"}
```

### Indexar a base de conhecimento

```bash
python -m ocean.ingestion.run knowledge_refresh
```

Os arquivos de `content/knowledge/*.md` vêm marcados `revisado: nao`: são rascunhos a revisar com fonte oficial.
A coleção padrão é `ocean_conhecimento` (não mexe na coleção antiga `conhecimento_maritimo`).

### Banco de dados local ou no Neon

Copie a URL PostgreSQL fornecida pelo painel do Neon ou Supabase para `DATABASE_URL` no `.env`.
Em conexões externas, normalmente a URL inclui `sslmode=require`.

```bash
python -m ocean.storage.postgres.migrate      # aplica migrations/*.sql
python -m ocean.ingestion.run ping            # confere a conexão e registra uma execução
```

Após configurar o segredo `DATABASE_URL_ADMIN`, os mesmos migrations e jobs podem rodar pelo
workflow **Ingestão** em **Actions → Ingestão → Run workflow**.

## Ferramentas MCP

| Ferramenta | Situação |
|---|---|
| `search_maritime_knowledge`, `list_knowledge_topics` | implementadas (aliases temporários: `buscar_conhecimento`, `listar_topicos`) |
| `get_tide_table`, `get_marine_conditions` | fase 2 |
| `get_fishing_closures` | fase 3 |
| `search_vessels` | fase 4 |
| `find_fish_markets` | fase 5 |

## Deploy

### Servidor MCP no Render

1. Clique em **New → Blueprint**.
2. Selecione o repositório e o arquivo `render.yaml`.
3. Preencha todas as variáveis marcadas `sync: false`.
4. Defina `MCP_AUTH_TOKEN` com o mesmo valor usado pela API consumidora.
5. Configure `DATABASE_URL` com uma conta PostgreSQL somente leitura.
6. Aguarde o health check em `/health`.

Na API separada `ocean-agent-api`, configure `MCP_SERVER_URL` com o endereço público do MCP
e `ALLOWED_TOOLS` com a lista de ferramentas disponíveis.

### Banco no Neon

O Neon pode hospedar o PostgreSQL usado pelo projeto.

```bash
npm i -g neon@latest
neon login
neon init -y --org-id <org-id> --project-id <project-id> --branch production --services postgres
neon deploy
```

O Neon grava as variáveis da branch no `.env` local ou `.env.local`.
Nunca copie as credenciais para o repositório ou para comentários.

### Ingestão no GitHub Actions

Crie os secrets administrativos descritos acima e execute
**Actions → Ingestão → Run workflow**, escolhendo o job desejado.

## Documentação

Visão do projeto e guia técnico (decisões, contrato, plano por fases): documentos "Ocean — Visão do Projeto"
e "Ocean — Guia Técnico".