Kontomierz-MCP

Servidor MCP (Model Context Protocol) para o Kontomierz.pl — uma plataforma polonesa de finanças pessoais. Permite que assistentes de IA (Claude Desktop, LibreChat, Cline) leiam e gerenciem suas contas bancárias, transações, orçamentos e pagamentos agendados — tudo por meio de uma única API. Desenvolvido em Python, roda localmente ou no Docker.

GitHubExperimente este MCPPatrocinado

Documentação

Kontomierz-MCP

Servidor MCP (Model Context Protocol) para Kontomierz.pl — uma plataforma polonesa de finanças pessoais. Ele expõe 27 ferramentas para contas, transações, orçamentos, pagamentos agendados, dados de referência, gráficos e histórico de patrimônio, para que assistentes compatíveis com MCP possam trabalhar com o Kontomierz por meio de um único servidor local.

A versão 2.0.0 substitui a antiga ponte SSE/REST por stdio e Streamable HTTP autenticado, restrito apenas a loopback. Datas públicas usam ISO YYYY-MM-DD, meses de orçamento usam YYYY-MM, e operações de escrita são desabilitadas a menos que o operador do servidor as habilite explicitamente.

Requisitos

Python 3.11+ para uso local. Os locks de dependências Linux x64 exatos do repositório cobrem Python 3.11, 3.12 e 3.13.
Uma conta Kontomierz.pl com uma chave de API, a menos que você use o backend mock determinístico.
Docker apenas se você quiser reproduzir ou executar o artefato de contêiner exato.

Início Rápido

1. Instalar e configurar

git clone https://github.com/paulomac1000/kontomierz-mcp.git
cd kontomierz-mcp

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

cp .env.example .env
# Edit .env and set KONTOMIERZ_API_KEY

O servidor lê .env do diretório de trabalho atual sem sobrescrever variáveis já presentes no ambiente do processo.

Para uma demonstração local sem E/S, nenhuma chave de API real é necessária:

KONTOMIERZ_MOCK_DATA=1 kontomierz-mcp

2. Executar com stdio

Stdio é o transporte padrão e recomendado para um cliente MCP local:

kontomierz-mcp

As ferramentas de leitura estão disponíveis imediatamente. Escritas comuns exigem a porta de operador independente:

export ENABLE_WRITE_OPERATIONS=1
kontomierz-mcp

Ferramentas destrutivas exigem a porta de escrita e listas de permissão exatas de capacidades/recursos de propriedade do servidor. Por exemplo:

export ENABLE_WRITE_OPERATIONS=1
export MCP_STDIO_ALLOWED_DESTRUCTIVE_CAPABILITIES=destroy_wallet
export MCP_STDIO_ALLOWED_DESTRUCTIVE_RESOURCES=wallet:123
kontomierz-mcp

Curingas não são aceitos para recursos destrutivos.

3. Conectar um cliente MCP

Um cliente stdio pode iniciar o executável diretamente. Por exemplo, uma configuração no estilo Claude Desktop é:

{
  "mcpServers": {
    "kontomierz": {
      "command": "/absolute/path/to/kontomierz-mcp/.venv/bin/kontomierz-mcp",
      "env": {
        "KONTOMIERZ_API_KEY": "your_api_key_here"
      }
    }
  }
}

Use o mecanismo de ambiente/segredo confiável do seu cliente quando disponível. Não exponha a chave de API por meio de argumentos de ferramenta. Adicione ENABLE_WRITE_OPERATIONS=1 ao ambiente de processo confiável somente quando escritas forem pretendidas.

Streamable HTTP

O modo HTTP é opcional. Ele é deliberadamente restrito a loopback e exige autenticação Bearer.

export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=9101
export MCP_HTTP_AUTH_TOKEN="$(.venv/bin/python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export MCP_HTTP_PRINCIPAL=local-operator
export MCP_HTTP_ALLOWED_CAPABILITIES=read

kontomierz-mcp

Endpoints:

Endpoint	Autenticação	Finalidade
`POST /mcp`	Token Bearer obrigatório	Endpoint MCP Streamable HTTP
`GET /health/live`	Público	Apenas verificação de processo ativo; sem E/S upstream
`GET /health/ready`	Token Bearer obrigatório	Prontidão limitada e ciente de dependências

Verifique a integridade:

curl http://127.0.0.1:9101/health/live
curl -H "Authorization: Bearer $MCP_HTTP_AUTH_TOKEN" \
  http://127.0.0.1:9101/health/ready

Principais HTTP são somente leitura por padrão. Para permitir escritas comuns, tanto a política de capacidades HTTP quanto a porta de escrita global devem permiti-las:

export MCP_HTTP_ALLOWED_CAPABILITIES=read,write
export ENABLE_WRITE_OPERATIONS=1

Chamadas HTTP destrutivas exigem adicionalmente destructive além de listas de permissão exatas de capacidades e recursos:

export MCP_HTTP_ALLOWED_CAPABILITIES=read,write,destructive
export MCP_HTTP_ALLOWED_DESTRUCTIVE_CAPABILITIES=destroy_wallet
export MCP_HTTP_ALLOWED_DESTRUCTIVE_RESOURCES=wallet:123
export ENABLE_WRITE_OPERATIONS=1

A autenticação nunca concede acesso de escrita por si só.

Docker

O Dockerfile intencionalmente não reconstrói o projeto a partir de código-fonte arbitrário. Ele consome o wheel dist/ verificado, o wheelhouse de runtime, o lock de runtime, checksums e SOURCE_REVISION produzidos pelo caminho de artefato exato e, em seguida, executa o servidor como um usuário não root.

Para reproduzir a imagem de CI localmente, use Python 3.12 e o helper do repositório com um checkout ai-skills na revisão exata registrada em trusted-executable-sources.lock.yaml:

.venv/bin/python scripts/local_exact_gate.py --ai-skills-root ../ai-skills

Esse comando executa as verificações de padrões/qualidade de propriedade do repositório, materializa o conjunto de artefatos exato e constrói kontomierz-mcp:<git-sha>. Consulte Prontidão de produção para o caminho reprodutível completo.

Para Streamable HTTP dentro do Docker, a publicação comum de -p não é suficiente porque o servidor é obrigado a vincular a loopback. No Linux, use rede do host ou uma ponte de loopback equivalente. Stdio não precisa de exposição de rede.

Ferramentas Disponíveis (27)

Contas

Ferramenta	Risco	Descrição
`list_accounts`	LEITURA	Listar contas bancárias e carteiras com saldos
`create_wallet`	ESCRITA	Criar uma carteira de dinheiro
`update_wallet`	ESCRITA	Atualizar uma carteira de dinheiro
`destroy_wallet`	DESTRUTIVA	Excluir uma carteira de dinheiro

Transações

Ferramenta	Risco	Descrição
`list_transactions`	LEITURA	Listar transações com paginação e filtros
`get_transaction`	LEITURA	Obter uma transação
`create_transaction`	ESCRITA	Criar uma transação
`update_transaction`	ESCRITA	Atualizar uma transação
`delete_transaction`	DESTRUTIVA	Excluir uma transação

Orçamentos

Ferramenta	Risco	Descrição
`list_budgets`	LEITURA	Listar orçamentos de um mês
`create_budget`	ESCRITA	Criar um orçamento de categoria ou grupo de categorias
`update_budget`	ESCRITA	Atualizar um limite de orçamento
`delete_budget`	DESTRUTIVA	Excluir um orçamento
`copy_budgets_from_last_month`	ESCRITA	Copiar os orçamentos do mês anterior

Agendamentos

Ferramenta	Risco	Descrição
`list_scheduled_transactions`	LEITURA	Listar ocorrências de pagamentos agendados
`get_schedule`	LEITURA	Obter uma definição de agendamento
`create_schedule`	ESCRITA	Criar um agendamento de pagamento
`update_schedule`	ESCRITA	Atualizar um agendamento de pagamento
`delete_schedule`	DESTRUTIVA	Excluir um agendamento de pagamento
`mark_schedule_paid`	ESCRITA	Marcar uma ocorrência como paga
`mark_schedule_unpaid`	ESCRITA	Marcar uma ocorrência como não paga

Dados de referência

Ferramenta	Risco	Descrição
`list_categories`	LEITURA	Listar a árvore de categorias
`list_tags`	LEITURA	Listar tags do usuário
`list_currencies`	LEITURA	Listar moedas

Gráficos e patrimônio

Ferramenta	Risco	Descrição
`get_pie_chart`	LEITURA	Obter dados de detalhamento de transações
`list_wealth_points`	LEITURA	Listar pontos do histórico de patrimônio

Introspecção

Ferramenta	Risco	Descrição
`describe_kontomierz_capabilities`	LEITURA	Descrever o catálogo de ferramentas governado e o estado ativo da política

O catálogo governado em src/kontomierz_mcp/tool_definitions*.py é a fonte da verdade para assinaturas e descrições. tools/list expõe os esquemas públicos.

Contrato Público

A versão 2.0.0 intencionalmente restringe a superfície MCP:

os objetos de entrada das ferramentas são fechados (additionalProperties: false);
os tipos escalares são estritos em vez de coerção cruzada;
datas públicas usam YYYY-MM-DD e meses de orçamento usam YYYY-MM;
a conversão localizada de DD-MM-YYYY do Kontomierz é interna ao adaptador;
os metadados públicos de resultado expõem um target_ref opaco, não a identidade de destino derivada de credenciais;
os tamanhos de resposta e corpo upstream são limitados;
falhas de mutação são classificadas de forma conservadora.

Uma criação confirmada com HTTP 201 que não retorna identidade estável não é adivinhada a partir de campos não exclusivos. Casos observados de orçamento/agendamento retornam:

{"created": true, "reconciliation_required": true}

O chamador deve reconciliar antes de uma mutação dependente. Se a conclusão em si for incerta — por exemplo, após um timeout, perda de transporte, falha ambígua do servidor ou resposta de mutação bem-sucedida malformada/oversized — a operação retorna AMBIGUOUS_OUTCOME e não é repetida automaticamente.

Consulte Contrato de ferramenta e API upstream para o comportamento detalhado.

Configuração

Toda a configuração é feita por meio de variáveis de ambiente; .env.example é o modelo completo.

Núcleo

Variável	Padrão	Descrição
`KONTOMIERZ_API_KEY`	—	Obrigatório para o backend real
`KONTOMIERZ_MOCK_DATA`	`0`	Usar dados determinísticos em memória em vez do Kontomierz
`KONTOMIERZ_API_BASE_URL`	`https://secure.kontomierz.pl/k4`	URL base da API upstream; destinos reais devem ser HTTPS
`KONTOMIERZ_API_TIMEOUT`	`30`	Timeout de solicitação upstream em segundos
`KONTOMIERZ_BODY_MODE`	`form`	Escritas reais são codificadas em formulário; o modo real de `json` é rejeitado
`MCP_TRANSPORT`	`stdio`	`stdio`, `http` ou `streamable-http`
`MCP_HOST`	`127.0.0.1`	Host de bind HTTP; HTTP não loopback é rejeitado
`MCP_PORT`	`9101`	Porta do Streamable HTTP
`ENABLE_WRITE_OPERATIONS`	`0`	Porta de operador independente para mutações
`LOG_LEVEL`	`INFO`	Verborragia do log de aplicação

Limites de runtime

Variável	Padrão	Descrição
`MCP_MAX_CONCURRENCY`	`8`	Máximo de chamadas de dependência em execução
`MCP_MAX_PENDING_INVOCATIONS`	`16`	Máximo de invocações admitidas em execução + na fila
`MCP_READINESS_TIMEOUT`	`5`	Timeout da sonda de dependência de prontidão
`MCP_READINESS_CACHE_SECONDS`	`10`	Duração do cache de prontidão
`MCP_HTTP_MAX_REQUEST_BODY_BYTES`	`1048576`	Limite do corpo da solicitação HTTP; máximo rígido é 4 MiB

Autorização

Variável	Finalidade
`MCP_STDIO_ALLOWED_DESTRUCTIVE_CAPABILITIES`	IDs exatos de capacidades destrutivas permitidos via stdio
`MCP_STDIO_ALLOWED_DESTRUCTIVE_RESOURCES`	IDs exatos de recursos destrutivos permitidos via stdio
`MCP_HTTP_AUTH_TOKEN`	Token Bearer de alta entropia obrigatório para HTTP
`MCP_HTTP_PRINCIPAL`	Identidade estável de propriedade do servidor mapeada para o token HTTP
`MCP_HTTP_ALLOWED_CAPABILITIES`	Classes de capacidades HTTP; padrão é `read`
`MCP_HTTP_ALLOWED_DESTRUCTIVE_CAPABILITIES`	IDs exatos de capacidades destrutivas permitidos via HTTP
`MCP_HTTP_ALLOWED_DESTRUCTIVE_RESOURCES`	IDs exatos de recursos destrutivos permitidos via HTTP

Segurança

Somente leitura por padrão. Escritas exigem ENABLE_WRITE_OPERATIONS=1; HTTP também exige a classe de capacidade correspondente.
Autorização destrutiva exata. Operações destrutivas precisam de listas de permissão explícitas de capacidades e recursos; recursos curinga são rejeitados.
HTTP somente loopback. Bind HTTP remoto é rejeitado. /mcp e /health/ready exigem autenticação Bearer.
Identidade de propriedade do servidor. Principais, identidade de destino, política de capacidades, listas de permissão de recursos e habilitação de escrita não podem vir de argumentos de ferramenta controlados pelo modelo.
Sem repetição automática de mutações. Escritas com conclusão incerta permanecem AMBIGUOUS_OUTCOME até serem reconciliadas.
Dados limitados. Entradas, corpos de solicitação, respostas upstream, respostas de ferramentas e eventos de auditoria são limitados.
Auditoria protegida. Registros de auditoria de invocação excluem chaves de API, tokens Bearer, resultados protegidos brutos e argumentos brutos.

O projeto é projetado para uma única conta Kontomierz configurada. Hospedagem pública multi-tenant e seleção de destino entre contas não são suportadas.

Testes e Desenvolvimento

Para desenvolvimento comum:

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m ruff format --check .
python -m mypy src/kontomierz_mcp
python -m bandit -q -r src/kontomierz_mcp

pytest simples exclui a suíte de evidências external. A cobertura é aplicada em 85%.

A CI hospedada também exercita os gráficos de dependências Linux x64 bloqueados exatos em Python 3.11, 3.12 e 3.13, clientes MCP oficiais via stdio e Streamable HTTP autenticado, instalação exata do wheel fora da árvore de origem e a imagem não root vinculada à revisão.

A suíte de mutação ao vivo do Kontomierz é deliberadamente difícil de iniciar e deve ser executada apenas contra uma conta descartável exclusiva verificada. Não a execute contra uma conta pessoal normal. Consulte Prontidão de produção para suas portas de segurança explícitas e requisitos de limpeza.

Padrões e Evidências

O repositório usa a revisão de autoridade ai-skills imutável registrada em trusted-executable-sources.lock.yaml para verificação estrutural de propriedade do repositório. Isso prova quais bytes de verificador a CI executou; não é, por si só, aprovação respaldada por provedor.

O status formal L2+/adopted é intencionalmente separado do status de merge e exige controles de provedor externos e evidências independentes. As evidências atuais e o trabalho administrativo restante estão documentados em:

Compatibilidade

A versão 2.0.0 é intencionalmente incompatível com o transporte legado 1.x e o contrato público. Em particular, SSE e a ponte REST não autenticada foram removidos, datas/meses são canonicalizados, a semântica de paginação é conservadora, a omissão de atualização difere de uma string vazia explícita, operações destrutivas têm listas de permissão exatas, e os metadados de resultado não expõem mais a identidade interna do alvo.

Referência Rápida

Métrica	Valor
Versão	2.0.0
Python	3.11+; bloqueios exatos de CI Linux x64 para 3.11–3.13
MCP SDK	`mcp==2.0.0`
Ferramentas	27: 12 LEITURA, 11 ESCRITA, 4 DESTRUTIVAS
Transportes	stdio; HTTP Streamable de loopback autenticado
Modo padrão	stdio somente leitura
Licença	MIT

Licença

MIT