┌─────────────────────────────────────────────────────────┐
│              Agente (Claude / LangChain / …)            │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Protocol
                    stdio │ ou HTTP (SSE / streamable-http)
┌────────────────────────▼────────────────────────────────┐
│                    MCP Server (FastMCP)                  │
│                                                         │
│   ┌──────────┐   ┌───────────┐   ┌──────────────────┐  │
│   │  Tools   │   │ Resources │   │    Prompts       │  │
│   └────┬─────┘   └─────┬─────┘   └──────────────────┘  │
│        │               │                                │
│   ┌────▼───────────────▼────────────────────────────┐   │
│   │              Repositories                       │   │
│   │   BaseRepository → QueryRepository              │   │
│   │                  → SchemaRepository             │   │
│   └────────────────────┬────────────────────────────┘   │
│                        │                                │
│   ┌────────────────────▼────────────────────────────┐   │
│   │           Database (asyncpg Pool)               │   │
│   └────────────────────┬────────────────────────────┘   │
│                        │                                │
│   ┌────────────────────▼────────────────────────────┐   │
│   │         Config (Pydantic Settings + .env)       │   │
│   └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                         │ TCP
┌────────────────────────▼────────────────────────────────┐
│                     PostgreSQL                          │
└─────────────────────────────────────────────────────────┘

mcp-postgres/
│
├── .env                             # Configuração activa (não commitado)
├── .env.example                     # Template documentado de todas as variáveis
├── pyproject.toml                   # Dependências, scripts, ruff, mypy, pytest
├── .gitignore
├── claude_mcp_config.json           # Config pronta para Claude Desktop / Claude Code
│
├── src/
│   └── mcp_postgres/
│       ├── __init__.py
│       ├── server.py                # Entry point: cria FastMCP e selecciona transporte
│       │
│       ├── config/
│       │   ├── __init__.py
│       │   └── settings.py          # Pydantic Settings — DATABASE_URL ou POSTGRES_*
│       │
│       ├── database/
│       │   ├── __init__.py
│       │   └── connection.py        # Singleton pool asyncpg + context managers
│       │
│       ├── repositories/
│       │   ├── __init__.py
│       │   ├── base.py              # fetch_all, fetch_one, execute, transaction
│       │   ├── query_repository.py  # SQL arbitrário com guard de writes
│       │   └── schema_repository.py # Introspection: tabelas, colunas, índices, FK, stats
│       │
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── query_tools.py       # execute_query, execute_query_one, execute_statement
│       │   └── schema_tools.py      # list_schemas/tables/indexes/fks, get_table_stats
│       │
│       ├── resources/
│       │   ├── __init__.py
│       │   └── schema_resources.py  # URIs: postgres://schema/…
│       │
│       └── prompts/
│           ├── __init__.py
│           └── sql_prompts.py       # explore_database, analyse_table, write_query, optimise_query
│
└── tests/
    ├── __init__.py
    ├── conftest.py
    └── tools/
        ├── test_query_repository.py
        └── test_schema_repository.py

cd mcp-postgres

# Instalar dependências
uv sync

# Com dependências de desenvolvimento
uv sync --extra dev

cp .env.example .env
# editar .env com os dados do teu ambiente

DATABASE_URL=postgresql://user:password@host:5432/dbname

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=mydb
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secret

MCP_TRANSPORT=sse
MCP_HOST=0.0.0.0
MCP_PORT=8080

# Modo stdio (padrão)
uv run mcp-postgres

# Modo SSE — servidor HTTP na porta 8080
MCP_TRANSPORT=sse uv run mcp-postgres

# Modo desenvolvimento com MCP Inspector
uv run mcp dev src/mcp_postgres/server.py

-- Exemplo com parâmetro
SELECT id, name FROM users WHERE active = $1
params: [true]

POSTGRES_ALLOW_WRITES=true

# Todos os testes
uv run pytest

# Com coverage
uv run pytest --cov=src/mcp_postgres --cov-report=html

# Verbose
uv run pytest -v

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory", "/caminho/para/mcp-postgres",
        "run", "mcp-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/db"
      }
    }
  }
}

MCP_TRANSPORT=sse MCP_PORT=8080 uv run mcp-postgres

# LangChain + MCP
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "postgres": {
        "url": "http://localhost:8080/sse",
        "transport": "sse",
    }
})
tools = await client.get_tools()

MCP_TRANSPORT=streamable-http MCP_PORT=8080 uv run mcp-postgres

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync
EXPOSE 8080
CMD ["uv", "run", "mcp-postgres"]

docker run -p 8080:8080 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
  -e MCP_TRANSPORT=sse \
  mcp-postgres