Ops MCP Server (Finamatik)

Servidor Ops MCP

Um servidor MCP (Python, SDK oficial mcp, FastMCP) que permite ao Claude Desktop, Claude Code ou qualquer cliente MCP trabalhar com os dados operacionais de uma empresa por meio de dez ferramentas tipadas e auditadas sobre contatos, negócios, tarefas, notas, inventário e pedidos de venda, além de três recursos e um prompt de briefing. Construído e testado com dados de exemplo pela Finamatik. O backend SQLite é uma única classe (backend.py) e é a única coisa a ser substituída por um CRM, ERP ou sistema de projetos real.

Ferramenta	Tipo	Salvaguarda
search_contacts(query, limit)	leitura	consulta com pelo menos 2 caracteres, limite máximo de 50
get_contact(contact_id)	leitura	visão completa: negócios, tarefas abertas, últimas notas, últimos pedidos
list_tasks(status, assignee, due_before, limit)	leitura	data ISO validada
check_inventory(sku, low_stock_only)	leitura
pipeline_summary()	leitura	negócios por etapa, valor em aberto, fechamento em 30 dias
add_note(contact_id, text)	escrita	1 a 2.000 caracteres, contato deve existir
create_task(contact_id, title, due_date, assignee)	escrita	sem datas de vencimento passadas, enum de responsável
complete_task(task_id)	escrita	idempotente
update_deal_stage(deal_id, stage)	escrita	enum de etapa
create_order(contact_id, sku, qty, dry_run=true)	escrita	verificação de estoque; visualize primeiro, confirme apenas com dry_run=false

Modelo de segurança: anotações de ferramentas (readOnlyHint, destructiveHint, idempotentHint) para que os clientes possam perguntar antes de gravações; OPS_MCP_READ_ONLY=1 remove as ferramentas de escrita da lista de ferramentas por completo; cada chamada é anexada a audit.jsonl (timestamp, ferramenta, argumentos, ok ou erro, duração); erros de validação retornam como erros de ferramenta MCP que o modelo pode tratar.

Instalação e execução

pip install finamatik-ops-mcp
finamatik-ops-mcp                        # stdio, what Claude Desktop uses; seeds sample data on first start
OPS_MCP_READ_ONLY=1 finamatik-ops-mcp    # read only: the write tools are not registered at all

Os dados ficam em ~/.finamatik-ops-mcp/ (ops.db e audit.jsonl). Mova com OPS_MCP_HOME, ou aponte para arquivos específicos com OPS_MCP_DB e OPS_MCP_AUDIT.

Claude Desktop, claude_desktop_config.json:

{ "mcpServers": { "ops-mcp": { "command": "finamatik-ops-mcp", "env": { "OPS_MCP_READ_ONLY": "0" } } } }

Claude Code: claude mcp add ops-mcp -- finamatik-ops-mcp

Remoto: OPS_MCP_TRANSPORT=streamable-http finamatik-ops-mcp serve /mcp na porta 8000; coloque autenticação na frente dele.

A partir do código-fonte:

git clone https://github.com/finamatik/ops-mcp-server && cd ops-mcp-server
pip install -e ".[test]"
python3 server.py                       # same server, run from the checkout
python3 -m pytest tests -q              # 6 end to end tests through a real MCP client
npx @modelcontextprotocol/inspector --config inspector.config.json --server ops-mcp

Requer Python 3.10 ou posterior e o SDK oficial mcp 1.27 ou posterior (fixado abaixo de 2.0; o SDK 2.x renomeou o FastMCP).

Arquivos

finamatik_ops_mcp/server.py ferramentas, recursos, prompt e o ponto de entrada main(). finamatik_ops_mcp/backend.py camada de dados e seed de exemplo (40 contatos, 25 negócios, 30 tarefas, 10 SKUs, 20 pedidos). server.py e backend.py na raiz são adaptadores finos para que python3 server.py ainda funcione a partir de um checkout. tests/test_server.py. inspector.config.json. server.json é o manifesto do registro MCP. .github/workflows/publish.yml publica uma release do GitHub para o PyPI com publicação confiável.

Licença MIT, direitos autorais Finamatik Business Solutions FZE LLC. Perguntas e uso em produção: info@finamatik.com.