Bundled Notes MCP

Este servidor local expõe bundles, notas Markdown, tags/tarefas, quadros Kanban, templates personalizados, busca e Files & Photos pelo mesmo modelo Firebase usado pelo aplicativo web.

Contrato de segurança

• Toda ferramenta que altera estado retorna confirmation_required sem chamar a API, a menos que receba confirm=true.

• Arquivamento e restauração são explícitos. Exclusões permanentes têm nomes claros e removem recursivamente as subcoleções Firestore conhecidas.

• Atualizações usam update masks e preservam campos desconhecidos.

• Tokens de autenticação, compra e download nunca são retornados pelas ferramentas.

• Downloads autenticados retornam Base64 somente até 10 MiB e nunca expõem URLs assinadas ou tokens do Firebase Storage.

• Movimentações criam e verificam o destino antes de remover a origem, com rollback compensatório da cópia quando necessário.

• Exclusões de tag bloqueiam referências pendentes por padrão.

• Uploads respeitam o limite observado de 400 MiB, validam tamanho/metadados no Storage, relêem o catálogo e compensam falhas parciais.

• bundled_schema_status compara formas sanitizadas do Firestore com um contrato versionado sem retornar títulos, conteúdo, nomes de arquivo, IDs ou outros valores.

Consulte WRITES.md antes de habilitar mutações.

Related MCP server: Zero Brain MCP Server

Início rápido

Requer Python 3.11+ e uv.

uv sync --locked --extra dev

O bootstrap descobre a configuração pública atual do site e obtém um refresh token sem imprimir a senha ou o token:

uv run bundled-notes-bootstrap-auth --output .env

O helper solicita e-mail e senha interativamente. O .env é ignorado pelo Git e deve ser tratado como uma senha. Se a descoberta automática deixar de funcionar, informe a chave pública atual com --api-key.

Executar

Prefect Horizon (seu próprio deployment)

1. Faça fork deste repositório.

2. Entre no Prefect Horizon com GitHub e selecione o seu fork.

3. Use o entrypoint src/bundled_notes_mcp/server.py:mcp.

4. Use pyproject.toml como arquivo de dependências.

5. Cadastre somente as credenciais da sua conta Bundled Notes como secrets.

6. Mantenha Authentication habilitada e faça o deploy.

O endpoint será semelhante a https://seu-servidor.fastmcp.app/mcp. Cada fork e deployment deve representar uma única conta. Não conecte ao ChatGPT um deployment publicado por outra pessoa. Mantenha os payloads MCP de requisição e resposta desabilitados nos logs porque eles podem conter notas e metadados privados.

Local (stdio)

uv run bundled-notes-mcp

Exemplo de configuração no Codex; em ambientes compartilhados, use um gerenciador de secrets:

[mcp_servers.bundled-notes]
command = "uv"
args = ["--directory", "C:/Users/guipm/Desktop/MCPs/bundled-notes-mcp", "run", "bundled-notes-mcp"]

[mcp_servers.bundled-notes.env]
BUNDLED_FIREBASE_API_KEY = "..."
BUNDLED_FIREBASE_REFRESH_TOKEN = "..."
BUNDLED_FIREBASE_UID = "..."

Comece com bundled_status e bundled_list_bundles. Para uma escrita, chame uma vez sem confirmação, revise IDs e payload, depois repita com confirm=true.

Conectar ao ChatGPT

Depois de publicar o seu próprio fork, use estes metadados ao adicionar o MCP no ChatGPT:

Ative o modo de desenvolvedor em Configurações → Segurança e login, abra Plugins, selecione +, preencha os campos acima e conclua a autenticação. O passo a passo completo, incluindo validação e atualização do catálogo, está no guia de conexão com o ChatGPT.

Ferramentas

O catálogo da versão 0.3.0 expõe 43 ferramentas. A leitura de lembretes é suportada; criação e agendamento permanecem deliberadamente bloqueados até existir um contrato upstream validado end-to-end.

A busca filtra notas localmente porque o aplicativo também usa um índice/cache no cliente, não um endpoint Firestore de texto completo. Os limites são finitos por padrão; aumente-os deliberadamente em contas grandes.

Desenvolvimento

uv sync --locked --extra dev
uv run ruff format --check .
uv run ruff check .
uv run pytest
uv run fastmcp inspect src/bundled_notes_mcp/server.py:mcp
uv build

Consulte o índice de documentação, o mapa de arquitetura, o playbook para agentes, o guia de deploy, a manutenção de schema e os testes. O arquivo llms.txt contém o mapa compacto e o catálogo exato para agentes.

Limites conhecidos

• Endpoints Firebase e caminhos Firestore são detalhes de implementação, não uma promessa de compatibilidade.

• Escritas de lembretes continuam bloqueadas até que o contrato Android de agendamento/notificação possa ser validado end-to-end; persistir um documento Firestore sem garantir o disparo não é considerado suporte funcional.

• Importação do Google Keep permanece fora do MCP enquanto o fluxo oficial ainda estiver em desenvolvimento.

• Antes de excluir um arquivo da conta, desanexe-o das notas relevantes.

• Contadores do documento de usuário podem atrasar; as listagens são a fonte operacional deste servidor.