Inkdrop

Interaja com o banco de dados local do aplicativo de anotações Inkdrop por meio de sua API HTTP.

GitHub
56

Documentação

Servidor MCP do Inkdrop

Um servidor Model Context Protocol para a API do Servidor HTTP Local do Inkdrop.

Instalação

Leia a documentação aqui.

Componentes

Ferramentas

  1. read-note: Recupera o conteúdo completo da nota pelo seu ID no banco de dados.
    • Entradas obrigatórias:
      • noteId: O ID da nota a ser recuperada. Pode ser encontrado como _id na documentação da nota. Sempre começa com note:.
    • Entradas opcionais:
      • includeTemplate: Quando true e a nota possui um sourceTemplateId, também busca esse modelo e incorpora seu corpo (instruções de preenchimento e exemplos) como um bloco de texto extra. Padrão: false.
    • Observação: Se a nota foi criada a partir de um modelo, a resposta inclui um link de recurso para o modelo de origem, cujo corpo contém as instruções de preenchimento e exemplos.
  2. read-backlinks: Recupera backlinks de uma nota — as notas que linkam para ela.
    • Entradas obrigatórias:
      • noteId: O ID da nota para a qual encontrar backlinks. Sempre começa com note:.
    • Observação: Cada resultado é retornado como um link de recurso (inkdrop://note/<id>) apontando para a nota de referência. Os backlinks são encontrados pesquisando todos os corpos das notas pelo URI de link da nota.
  3. search-notes: Lista todas as notas que contêm uma determinada palavra-chave.
    • Entradas obrigatórias:
      • keyword: Palavra-chave para pesquisar.
    • Observação: Os resultados incluem corpos de notas truncados (200 caracteres). Use read-note para obter o conteúdo completo.
    • Suporta qualificadores de pesquisa avançados como book:, tag:, status:, title:, etc.
  4. list-notes: Lista todas as notas com condições especificadas.
    • Entradas obrigatórias:
      • bookId: O ID do caderno. Sempre começa com 'book:'.
    • Entradas opcionais:
      • tagIds: Um array de IDs de tags para filtrar. Cada um começa com 'tag:'.
      • keyword: Palavra-chave para filtrar notas.
      • sort: Campo de ordenação (updatedAt, createdAt ou title). Padrão: updatedAt.
      • descending: Inverte a ordem da saída. Padrão: true.
    • Observação: Os resultados incluem corpos de notas truncados (200 caracteres). Use read-note para obter o conteúdo completo.
  5. create-note: Cria uma nova nota no banco de dados.
    • Entradas obrigatórias:
      • bookId: O ID do caderno. Deve começar com 'book:' ou ser 'trash'.
      • title: O título da nota.
      • body: O conteúdo da nota em Markdown.
    • Entradas opcionais:
      • status: O status da nota (none, active, onHold, completed, dropped).
      • tags: Um array de IDs de tags para atribuir à nota. Cada um deve começar com 'tag:'.
  6. update-note: Atualiza uma nota existente no banco de dados. Apenas os campos fornecidos serão atualizados; campos omitidos permanecem inalterados.
    • Entradas obrigatórias:
      • _id: O ID da nota. Deve começar com 'note:'.
      • _rev: O ID de revisão (token MVCC do CouchDB).
    • Entradas opcionais:
      • bookId: O ID do caderno. Deve começar com 'book:' ou ser 'trash'.
      • title: O título da nota.
      • body: O conteúdo da nota em Markdown.
      • status: O status da nota (none, active, onHold, completed, dropped).
      • tags: Um array de IDs de tags para atribuir à nota. Cada um deve começar com 'tag:'.
  7. patch-note: Atualiza o corpo de uma nota existente realizando uma substituição exata de string. Mais eficiente que update-note para pequenas edições em notas grandes, pois economiza tokens. Você deve primeiro ler a nota com read-note para obter o corpo atual.
    • Entradas obrigatórias:
      • _id: O ID da nota. Deve começar com 'note:'.
      • _rev: O ID de revisão (token MVCC do CouchDB).
      • old_string: O texto exato a ser encontrado no corpo da nota. Deve corresponder exatamente a uma ocorrência. Inclua contexto suficiente ao redor para garantir uma correspondência única.
      • new_string: O texto para substituir old_string. Use uma string vazia para excluir o texto correspondente.
  8. list-notebooks: Recupera uma lista de todos os cadernos.
  9. read-book: Recupera um único caderno pelo seu ID.
    • Entradas obrigatórias:
      • bookId: O ID do caderno. Deve começar com 'book:'.
  10. create-book: Cria um novo caderno no banco de dados.
    • Entradas obrigatórias:
      • name: O nome do caderno.
    • Entradas opcionais:
      • parentBookId: O ID do caderno pai. Deve começar com 'book:'. Omita para criar o caderno no nível raiz.
  11. update-book: Atualiza um caderno existente no banco de dados. Apenas os campos fornecidos serão atualizados; campos omitidos permanecem inalterados, então você não precisa ler o caderno primeiro.
    • Entradas obrigatórias:
      • _id: O ID do caderno. Deve começar com 'book:'.
    • Entradas opcionais:
      • _rev: O ID de revisão (token MVCC do CouchDB). Apenas necessário como proteção de concorrência otimista — passe-o para fazer a atualização falhar em uma edição concorrente conflitante.
      • name: O nome do caderno.
      • parentBookId: O ID do caderno pai. Passe null para mover o caderno para o nível raiz.
  12. list-tags: Recupera uma lista de todas as tags.
  13. read-tag: Recupera uma única tag pelo seu ID.
    • Entradas obrigatórias:
      • tagId: O ID da tag. Deve começar com 'tag:'.
  14. create-tag: Cria uma nova tag no banco de dados.
    • Entradas obrigatórias:
      • name: O nome da tag.
    • Entradas opcionais:
      • color: O tipo de cor da tag (default, red, orange, yellow, olive, green, teal, blue, violet, purple, pink, brown, grey, black). Padrão: default.
  15. update-tag: Atualiza uma tag existente no banco de dados. Apenas os campos fornecidos serão atualizados; campos omitidos permanecem inalterados, então você não precisa ler a tag primeiro.
    • Entradas obrigatórias:
      • _id: O ID da tag. Deve começar com 'tag:'.
    • Entradas opcionais:
      • _rev: O ID de revisão (token MVCC do CouchDB). Apenas necessário como proteção de concorrência otimista — passe-o para fazer a atualização falhar em uma edição concorrente conflitante.
      • name: O nome da tag.
      • color: O tipo de cor da tag. Omita para manter a cor atual da tag.
  16. create-file: Cria um novo arquivo de anexo no banco de dados a partir de um arquivo de imagem local ou de dados de imagem em base64. Retorna o Markdown para incorporar o anexo no corpo de uma nota.
    • Entradas obrigatórias: exatamente uma de
      • filePath: Caminho absoluto para um arquivo de imagem local a ser anexado. Preferido — mantém os bytes da imagem fora da conversa.
      • data: Dados de imagem codificados em base64, sem o prefixo de URI data:.
    • Entradas opcionais:
      • name: O nome do arquivo. Padrão: o nome do arquivo de filePath, ou image.<ext> quando data é fornecido.
      • contentType: O tipo MIME (image/png, image/jpeg, image/jpg, image/svg+xml, image/gif, image/heic, image/heif). Inferido da extensão de filePath quando omitido, portanto é obrigatório com data.
      • publicIn: Um array de IDs de notas onde o anexo está incluído. Cada um deve começar com 'note:'.
    • Observação: Anexos são limitados a 10MB.
  17. read-file: Recupera um arquivo de anexo pelo seu ID. Retorna os metadados do arquivo e a própria imagem quando é PNG, JPEG ou GIF.
    • Entradas obrigatórias:
      • fileId: O ID do anexo. Deve começar com 'file:'.
    • Entradas opcionais:
      • outputPath: Caminho absoluto para gravar o anexo. Quando fornecido, o arquivo é salvo lá e seus bytes não são retornados inline. Necessário para obter anexos SVG, HEIC e HEIF, que não podem ser exibidos inline.
      • includeImage: Se deve retornar a imagem junto com os metadados. Padrão: true. Defina como false para buscar apenas os metadados de um anexo grande.

Depuração

Como os servidores MCP rodam via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente usar o MCP Inspector.

Você pode iniciar o MCP Inspector via npm com este comando:

npx @modelcontextprotocol/inspector "./dist/index.js"

Certifique-se de que as variáveis de ambiente estejam configuradas corretamente.

Ao iniciar, o Inspector exibirá uma URL que você pode acessar no seu navegador para começar a depurar.

Você também pode observar os logs do servidor com este comando:

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-inkdrop.log