This release is a pre-release and may not be stable for production use.
mcp-investidor10-wallet
Assistente de investimentos que conecta um agente (Claude Code, Devin CLI, Codex, Gemini CLI) a uma carteira pública do Investidor10, com memória de longo prazo do investidor (teses, regras, decisões, insights), alertas de preço e um plugin de comportamento (skills, guardião de disciplina, persona e lembrete de memória).
Sem frontend — a interface é o cliente do agente. O servidor roda sobre stdio (o cliente inicia o processo; nenhuma porta é exposta).
Aviso: a fonte de dados é a API interna, não documentada, do Investidor10. Ela é pública e sem autenticação hoje, mas pode mudar ou ser desligada sem aviso. Falhas aparecem como erros estruturados explícitos — nunca como valores inventados.
Privacidade: leia docs/PRIVACY.md antes de instalar. Ele explica o que vai para onde, por que o ID da carteira deve ser tratado como senha e como o modo privacidade (
WALLET_MASK_VALUES) evita que valores em reais cheguem ao modelo.
Status
Roadmap: docs/ROADMAP.md.
As 19 tools estão implementadas (6 de dados da carteira/mercado + 13 de memória/alertas) — contratos completos em specs/001-mcp-investidor10-wallet/contracts/mcp-tools.md.
Instalação automática (recomendada)
Pré-requisito: uv (que traz Python 3.11+).
Um comando instala o produto completo — registra o servidor MCP e instala o plugin de comportamento nos CLIs de agente presentes na máquina (Claude Code, Devin CLI, Codex, Gemini CLI):
uvx mcp-investidor10-wallet install
O assistente pergunta apenas o ID da carteira (ver abaixo), valida que ela é pública e cuida do resto, com relatório em PT-BR.
O servidor fica registrado na versão exata do assistente
(uvx mcp-investidor10-wallet@<versão>), e não na mais recente do PyPI a cada
abertura. Para atualizar, rode uvx mcp-investidor10-wallet@latest install de
novo.
Opções:
| Flag | Efeito |
|---|---|
--mcp-only |
Registra apenas o servidor MCP (sem o plugin) — modo técnico |
--dry-run |
Simula e relata o que faria, sem alterar nada |
--clients claude,devin,codex,gemini |
Restringe os clientes alvo |
--wallet-id <id> |
Informa o ID sem pergunta (scripts/CI) |
--yes |
Pula confirmações de rotina |
O plugin de comportamento
O bundle inclui, além do servidor:
- 3 skills (
/analise-da-carteira,/check-de-tese,/resumo-de-dividendos) — roteiros com as regras do produto embutidas (bootstrap da memória, atraso de ~15 min das cotações, rendimento recorrente e nunca DY médio); - guardião de disciplina — subagente read-only que confronta decisões de investimento com as regras e teses que você salvou na memória;
- persona — instruções de papel injetadas no início de cada sessão;
- lembrete de memória — ao fim da sessão, propõe registrar decisões discutidas (sempre com sua confirmação; nunca grava sozinho).
Instalação manual do plugin (sem o assistente):
# Claude Code
claude plugin marketplace add rc-ventura/mcp-investidor10-wallet
claude plugin install investidor10-carteira@investidor10
# Devin CLI
devin plugins install rc-ventura/mcp-investidor10-wallet#plugin -y
# Codex CLI
codex plugin marketplace add rc-ventura/mcp-investidor10-wallet
codex plugin add investidor10-carteira@investidor10
# Gemini CLI
gemini extensions install https://github.com/rc-ventura/mcp-investidor10-wallet
Onde encontrar o seu WALLET_ID
Abra sua carteira no Investidor10 e copie o número da URL pública:
https://investidor10.com.br/carteira/SEU_ID
A carteira precisa ser pública — nas configurações do Investidor10, ative "carteira pública". O ID é o único identificador que o servidor usa; quem tiver o ID consegue ler os valores da carteira (o botão de mascarar do site é apenas cosmético — a API continua retornando tudo).
Configuração manual (sem o assistente)
O cliente do agente inicia o servidor como processo filho; por isso o comando configurado precisa existir no ambiente do cliente.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) —
apps GUI no macOS não herdam o PATH do shell: use o caminho absoluto do
uv (descubra com which uv):
{
"mcpServers": {
"carteira": {
"command": "/Users/<seu-usuario>/.local/bin/uv",
"args": ["tool", "run", "mcp-investidor10-wallet"],
"env": { "WALLET_ID": "SEU_ID" }
}
}
}
Claude Code:
claude mcp add carteira --scope user -- env WALLET_ID=SEU_ID uvx mcp-investidor10-wallet
Devin CLI:
devin mcp add -s user carteira -e WALLET_ID=SEU_ID -- uvx mcp-investidor10-wallet
Codex CLI:
codex mcp add carteira --env WALLET_ID=SEU_ID -- uvx mcp-investidor10-wallet
Gemini CLI:
gemini mcp add -s user -e WALLET_ID=SEU_ID carteira uvx mcp-investidor10-wallet
O cliente reinicia o servidor a cada sessão; depois de uma atualização, reinicie a sessão para carregar tools novas.
Solução de problemas
| Sintoma | Causa provável | Correção |
|---|---|---|
| "MCP failed to connect" (Claude Desktop) | PATH do shell não existe no app GUI | Use o caminho absoluto do uv (veja acima; which uv para descobrir) |
WALLET_ID não configurado + saída |
WALLET_ID ausente na config do cliente |
Adicione WALLET_ID no bloco env do servidor |
Carteira ... não encontrada ou não é pública |
ID errado ou carteira privada | Confira o ID na URL pública e deixe a carteira pública nas configurações do site |
Não foi possível validar a carteira ... (fonte indisponível) |
API fora do ar ou sem rede | Aviso não-bloqueante: o servidor sobe e as tools de dados informarão o erro |
Não foi possível preparar o diretório de memória ... |
Permissões de ~/.investidor10/ |
Corrija as permissões do diretório indicado e reinicie |
Onde ficam os dados
- Memória:
~/.investidor10/memory.json— arquivo local versionado com escrita atômica, compartilhado por todos os clientes da máquina. Vários clientes abertos ao mesmo tempo não perdem gravações: o servidor controla o acesso ao arquivo (memory.json.lock) e mantém um histórico de cada mudança (memory.json.log). Para quem tinha a memória no diretório do repositório: mova o arquivo commv ./memory.json ~/.investidor10/memory.jsonou definaWALLET_MEMORY_PATH. - Pasta sincronizada (Dropbox, iCloud, OneDrive): segura na mesma máquina; usar a mesma memória em duas máquinas ao mesmo tempo não é protegido (a sincronização pode gerar uma cópia em conflito). Use uma máquina por vez.
- Cache de API: apenas em memória de processo (TTL configurável).
- Nada é enviado a outro lugar pelo servidor — os resultados das tools entram no contexto do seu provedor de LLM (o agente), como qualquer tool.
Configuração (variáveis de ambiente)
| Variável | Obrigatória | Default | Uso |
|---|---|---|---|
WALLET_ID |
Sim | — | ID público da carteira (o servidor aborta sem ela) |
WALLET_MEMORY_PATH |
Não | ~/.investidor10/memory.json |
Caminho da memória (use um disco local) |
WALLET_MASK_VALUES |
Não | desligado | 1/true/yes/on ligam o modo privacidade: valores em R$ e quantidades não chegam ao modelo (ver PRIVACY.md) |
WALLET_CACHE_TTL_SECONDS |
Não | 600 |
TTL do cache em memória |
WALLET_CACHE_MAX_STALE_SECONDS |
Não | 86400 |
Idade máxima de cache expirado servido em queda da fonte (24h); mais antigo vira erro explícito |
Tools (19)
- Dados da carteira/mercado (6):
get_wallet_summary,get_wallet_allocation,get_wallet_positions,get_patrimony_history,get_earnings,get_asset_quote - Memória e alertas (13):
get_session_context(bootstrap da sessão — chame no início de toda sessão),get_wallet_goal,set_wallet_goal,save_thesis,get_theses,save_rule,get_rules,log_decision,record_decision_outcome,log_insight,create_price_alert,list_price_alerts,cancel_price_alert
Testes
uv run pytest # unit + contrato (API mockada com respx)
uv run pytest -m live # integração opt-in contra a API real
Limitações e riscos
- API interna não documentada: endpoints públicos mas sem contrato; podem mudar ou passar a exigir autenticação sem aviso.
- Cobertura de cotação:
get_asset_quotesó cobre ações B3; FIIs, ETFs internacionais, cripto e tesouro retornamasset_type_not_supported(ver learning lesson). Ativos dessas classes na carteira aparecem viaget_wallet_positions. - Detalhe de proventos:
get_earningsretorna o total do período; a tabela por pagamento existe no upstream e é candidata a uma tool futura (ver learning lesson). - Cotações com atraso (~15 min na B3) — o agente deve sempre mencionar.
- Uso pessoal/educacional: o agente sugere, nunca executa ordens.
Metadata
Release files for mcp-investidor10-wallet 0.4.0rc3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_investidor10_wallet-0.4.0rc3.tar.gz | 50.8 kB | With provenance | Details for mcp_investidor10_wallet-0.4.0rc3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_investidor10_wallet-0.4.0rc3-py3-none-any.whl | Python 3 | none | any | Details for mcp_investidor10_wallet-0.4.0rc3-py3-none-any.whl |
Total release size: 101.8 kB
Release files / mcp_investidor10_wallet-0.4.0rc3.tar.gz
| Download URL | mcp_investidor10_wallet-0.4.0rc3.tar.gz |
|---|---|
| Size | 50.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
50796148db62a4f69308ef5d83bb0dd532b2f2cd43ec92b939439d862ec2856e
|
|
BLAKE2b-256 checksum How to use checksums |
0204896e69a22e53637e71552c4cb3118a457ee19bffdcbbd9918a13fb11e785
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logRelease files / mcp_investidor10_wallet-0.4.0rc3-py3-none-any.whl
| Download URL | mcp_investidor10_wallet-0.4.0rc3-py3-none-any.whl |
|---|---|
| Size | 51.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
431154fa7342d0f72b6b5dd513c44efb18b0b31270684fca98d5c4c23d7ef18e
|
|
BLAKE2b-256 checksum How to use checksums |
306ec1da7e56cc0a137849d9426bcf4f84073449cea6a56bcad9d1b8582d030c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logSecurity for mcp-investidor10-wallet 0.4.0rc3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mcp_investidor10_wallet-0.4.0rc3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.