Viawb | MCP Gateway para ERPs

v0.3.1 — estávelpip: viawbPython ≥ 3.9asyncio suportado

Instalação

Instale o SDK via pip ou seu gerenciador de ambientes favorito.

Terminal
# pip
pip install viawb

# poetry
poetry add viawb

# uv
uv add viawb

Inicialização

Importe e instancie o cliente. A API key pode ser passada diretamente ou via variável de ambiente VIAWB_API_KEY.

Python
from viawb import ViaWBClient

# Passando a chave diretamente
client = ViaWBClient(api_key="vwb_sk_live_xxxxxxxxxxxxxxxxxxxx")

# Ou via variável de ambiente VIAWB_API_KEY
client = ViaWBClient()

client.tools

Interaja com as ferramentas MCP disponíveis para sua chave de acesso.

client.tools.list()→ list[Tool]

Retorna a lista de ferramentas MCP disponíveis para a chave autenticada.

Python
tools = client.tools.list()
print([t.name for t in tools])
# → ["erp.pedidos.get", "erp.clientes.get", ...]

client.tools.call(name, arguments, **opts)→ ToolResult

Executa uma ferramenta MCP com os argumentos fornecidos. A permissão é verificada antes da execução e o resultado é registrado no log de auditoria.

Python
result = client.tools.call(
    "erp.pedidos.get",
    {"pedido_id": "4421"},
    agent_id="crm-bot-v2",
)
 
print(result.content)  # dados do pedido

client.audit

Acesse e filtre o log de auditoria de chamadas realizadas pelo gateway.

Python
page = client.audit.list(
    agent_id="crm-bot-v2",
    status="deny",
    limit=50,
)

for entry in page.entries:
    print(entry.tool, entry.decision, entry.timestamp)

client.keys

Crie, liste e revogue chaves de acesso MCP programaticamente.

O valor secreto da chave (key.secret) é retornado somente na criação. Armazene-o imediatamente.

Python
# Criar chave
key = client.keys.create(
    name="bot-crm-producao",
    role="reader-comercial",
)
print(key.secret)  # salve agora!

# Listar chaves
keys = client.keys.list()

# Revogar chave
client.keys.revoke("key_01j9...")

Async / await

Use AsyncViaWBClient para integrar com frameworks assíncronos como FastAPI, asyncio ou qualquer pipeline de IA baseado em corrotinas.

Python — asyncio
import asyncio
from viawb import AsyncViaWBClient

async def consultar_pedido(pedido_id: str):
    async with AsyncViaWBClient() as client:
        result = await client.tools.call(
            "erp.pedidos.get",
            {"pedido_id": pedido_id},
        )
        return result.content

asyncio.run(consultar_pedido("4421"))

Erros e tipos

O SDK lança exceções tipadas para facilitar o tratamento de erros específicos.

Python
from viawb import ViaWBError, PermissionDeniedError, RateLimitedError

try:
    client.tools.call("erp.pedidos.delete", )
except PermissionDeniedError as e:
    # 403 — papel não tem escopo DELETE
    print(e.message, e.request_id)
except RateLimitedError:
    # 429 — limite do papel atingido
    print("rate limit atingido, aguardando...")
except ViaWBError as e:
    # erro genérico da API
    print(e.status_code, e.code)

Python SDK