Teckel IPFS MCP Toolkit
Faça upload, recupere, fixe e gerencie arquivos criptografados no IPFS por meio de uma API simples acessível como ferramentas MCP.
Documentação
ipfs-toolkit
Kit de ferramentas MCP para o Sistema de Arquivos Interplanetário (IPFS)
Como Usar os Kits de Ferramentas teckel
Primeiro, baixe e instale o aplicativo teckel.
Em seguida, gere uma chave de API usando o aplicativo teckel.
Faça o seguinte:
-
Navegue até a página Contas tocando no ícone de carteira no canto superior direito da tela inicial do aplicativo. Acesse o Gerenciador de Chaves de API para a Conta Ethereum criada ou importada tocando em "Gerenciar Chave de API" na página Contas.
-
Use a chave de API ao fazer chamadas para os endpoints. Todos os endpoints disponíveis estão acessíveis através do aplicativo teckel, incorporando a chave de API real para a Conta Ethereum fornecida.
-
Para fins ilustrativos, usaremos a seguinte chave fictícia d1e12345-c234-45a6-9b76-1234567891ff nos exemplos apresentados abaixo. Você substituiria sua chave de API real no lugar desta chave fictícia.
Em seguida, decida se você está usando os servidores MCP ou a API RESTful para acessar as ferramentas.
Usando os Servidores MCP
Configure seu cliente MCP de preferência
Seja qual for o cliente, a configuração é essencialmente a mesma. Ou seja, forneça ao cliente o endpoint do servidor MCP e as credenciais de acesso. Normalmente, isso vem na forma de um trecho de configuração JSON, usando sua chave de API como token "Bearer" na tag "Authorization". Por exemplo, aqui está a configuração precisa para uso com o aplicativo de desktop Cursor (navegue dentro do aplicativo Cursor para Configurações do Cursor -> Ferramentas e MCP -> + Novo servidor MCP e insira esses detalhes usando sua chave de API teckel real para substituir esta fictícia).
Configuração JSON do MCP (exemplo para uso com Cursor)
{
"mcpServers": {
"teckel-ipfs-toolkit": {
"url": "https://mcp-servers.bh.tkllabs.io:9780/ipfs-mcp",
"headers": {
"Authorization": "Bearer d1e12345-c234-45a6-9b76-1234567891ff"
}
}
}
}
NOTA: Esta configuração assume o protocolo HTTP (transmissível). Se o seu cliente exigir o protocolo SSE mais antigo (agora legado), substitua "ipfs-mcp" por "ipfs-sse".
Usando os Servidores de API RESTful
O benefício de usar os servidores MCP é que os LLMs conectados podem interpretar a linguagem natural nos prompts do usuário, preencher os parâmetros necessários para chamar as funções da API do kit de ferramentas e, em seguida, desmembrar a estrutura JSON retornada em linguagem natural para apresentação ao usuário. No entanto, se você deseja utilizar os kits de ferramentas teckel em um nível mais baixo (por exemplo, no seu próprio aplicativo), você pode chamar as funções diretamente usando os protocolos de API RESTful (POST). Você é então responsável por preencher os parâmetros de entrada e lidar com a saída JSON retornada. Todos os métodos chamados via serviços web RESTful devem ser "aguardados": não há disparar-e-esquecer (com polling futuro para conclusão de tarefas, etc).
Preços
Os preços (via créditos teckel comprados no aplicativo teckel) para uso dos serviços IPFS da teckel podem ser encontrados em https://teckel.io/pricing/
Limitação de Taxa
Todas as chamadas MCP/API estão sujeitas a limitação de taxa por chave de API. Os limites não são publicados, mas se uma determinada chave de API exceder o limite de taxa, um código de erro 429 será retornado na chamada em questão.
Erros
Se a chamada MCP/API falhar devido a erro do usuário resultando em um código de erro 4xx, o usuário será cobrado por uma Taxa de Chamada Base (veja https://teckel.io/ai-mcp-services/). Se a chamada de API falhar devido a erro do servidor resultando em um código de erro 5xx, o usuário não será cobrado. Se a chamada em questão fizer parte de uma cascata de chamadas aninhadas, as regras acima se aplicam à chamada "externa": Em outras palavras, se a chamada externa falhar com um código de erro 4xx, o usuário será cobrado por uma Taxa de Chamada Base (pela chamada externa com falha), e não haverá cobrança por nenhuma das chamadas em cascata (quer tenham sido bem-sucedidas ou não). Da mesma forma, se a chamada externa falhar com um código de erro 5xx, o usuário não será cobrado de forma alguma (mesmo que as chamadas em cascata sejam bem-sucedidas).
Criptografia
O IPFS é um serviço público e todo o conteúdo está, em princípio, disponível para qualquer pessoa. Portanto, se você considerar seu conteúdo privado, certifique-se de criptografá-lo antes de enviá-lo ao IPFS. A teckel facilita essa criptografia usando sua chave de API teckel para construir a chave de criptografia. No entanto, isso não fornece criptografia de ponta a ponta do seu conteúdo porque sua chave de API é conhecida pelos servidores teckel. Em vez disso, se você precisar de criptografia de ponta a ponta, na qual somente você (e não os servidores teckel, etc.) possa recuperar seu conteúdo, você deve primeiro criptografar seus arquivos offline usando seu próprio método escolhido, antes de enviá-los ao IPFS via teckel.
Moderação de conteúdo
Para fazer nossa parte na manutenção de uma internet limpa, a teckel pré-verifica todo o conteúdo enviado em busca de malware e conteúdo impróprio (conforme os termos da teckel). Qualquer conteúdo que falhe na pré-verificação é rejeitado. O endereço de carteira Ethereum associado à chave de API usada para a tentativa de envio pode ser colocado na lista negra a critério exclusivo da teckel.
Segurança da Chave de API
Caso você tenha preocupações de que sua chave de API foi comprometida (e outra pessoa possa estar consumindo seus créditos teckel usando sua chave), basta substituir a chave via Gerenciador de Chaves de API → Substituir chave de API no aplicativo teckel. A chave antiga será então desativada imediatamente. IMPORTANTE: se você alterar sua chave de API, qualquer conteúdo IPFS anteriormente criptografado via teckel não poderá mais ser recuperado, pois a chave de API é usada para criptografia. Antes de alterar sua chave de API, certifique-se de ter recuperado (e descriptografado) seus dados IPFS anteriores e armazenado as versões descriptografadas offline.
Aplicativo teckel
A funcionalidade do kit de ferramentas IPFS é totalmente compatível com a funcionalidade IPFS do aplicativo teckel. Isso significa que o conteúdo IPFS enviado através do aplicativo teckel pode ser acessado através do kit de ferramentas IPFS, e vice-versa.
Servidor MCP teckel — Referência da API IPFS
URL Base: https://mcp-servers.bh.tkllabs.io:9780
Autenticação
Todos os endpoints exigem um token Bearer no cabeçalho Authorization:
Authorization: Bearer YOUR_API_KEY
Índice de Endpoints
| Método | Caminho | Nome da Ferramenta MCP | Descrição |
|---|---|---|---|
| POST | /get_ipfs_content_for_apikey | list_ipfs_files | Listar arquivos IPFS da conta |
| POST | /remove_ipfs_files_from_account | remove_ipfs_files | Remover vários arquivos IPFS por busca de apelido |
| POST | /pin_ipfs_files_for_apikey | pin_ipfs_files | Fixar vários arquivos IPFS por busca de apelido |
| POST | /unpin_ipfs_files_for_apikey | unpin_ipfs_files | Desafixar vários arquivos IPFS por busca de apelido |
| POST | /pin_ipfs_cid_for_apikey | pin_ipfs_cid | Fixar um único arquivo IPFS por CID |
| POST | /remove_ipfs_cid_from_account | remove_ipfs_cid_from_account | Remover um único arquivo IPFS por CID |
| POST | /publish_ipfs_file_to_webserver | publish_ipfs_file_to_webserver | Publicar um arquivo IPFS no servidor web teckel |
| POST | /upload_sender_file_to_ipfs_for_apikey | upload_file_to_ipfs | Enviar um arquivo para o IPFS |
| POST | /upload_sender_base64_to_ipfs_for_apikey | upload_base64_file_to_ipfs | Enviar arquivo codificado em base64 para o IPFS |
| POST | /retrieve_ipfs_file_for_apikey | retrieve_ipfs_file | Recuperar um arquivo IPFS por CID |
Endpoints
POST /get_ipfs_content_for_apikey
Lista os arquivos IPFS da conta associada à chave de API, com filtragem opcional por apelido, status de fixação, estado de criptografia e tipo de conteúdo.
Ferramenta MCP: list_ipfs_files — Lista os arquivos IPFS (selecionados por apelido via search_string difusa) da conta correspondente à chave de API teckel usada na chamada.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
search_string | string | Não | "" | Busque esta string no apelido do arquivo. Deixe em branco para retornar todos. |
pinned_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas fixadas; 2 = apenas desafixadas |
encrypted_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas criptografadas; 2 = apenas não criptografadas |
content_type | string | Não | "" | Filtrar por tipo de conteúdo, ex.: image, audio, video. Deixe em branco para ignorar. |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/get_ipfs_content_for_apikey?search_string=my_video&pinned_state=0&encrypted_state=0&content_type=video" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /remove_ipfs_files_from_account
Desafixa e remove arquivos IPFS (selecionados por busca difusa de apelido) do nó IPFS teckel e do inventário da conta.
Nota: Isso apenas remove o conteúdo do nó e do inventário teckel. O conteúdo pode ainda existir na rede IPFS descentralizada.
Ferramenta MCP: remove_ipfs_files — Desafixa e remove os arquivos IPFS (selecionados por apelido via search_string difusa) do nó IPFS teckel e da conta da carteira, para a conta correspondente à chave de API teckel usada na chamada. Nota: isso apenas remove o conteúdo do nó e do inventário teckel. Ele pode ainda existir na rede descentralizada IPFS.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
search_string | string | Não | "" | Busque esta string no apelido do arquivo. Deixe em branco para corresponder a todos. |
pinned_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas fixadas; 2 = apenas desafixadas |
encrypted_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas criptografadas; 2 = apenas não criptografadas |
content_type | string | Não | "" | Filtrar por tipo de conteúdo, ex.: image, audio, video. Deixe em branco para ignorar. |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/remove_ipfs_files_from_account?search_string=old_test_files&pinned_state=0&encrypted_state=0" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /pin_ipfs_files_for_apikey
Fixa arquivos IPFS (selecionados por busca difusa de apelido) no nó IPFS teckel. A fixação impede a coleta automática de lixo do conteúdo.
Ferramenta MCP: pin_ipfs_files — Fixa os arquivos IPFS (selecionados por apelido via search_string difusa) no nó IPFS teckel para a conta correspondente à chave de API teckel usada na chamada. A fixação impede a exclusão automática do conteúdo do nó IPFS.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
search_string | string | Não | "" | Busque esta string no apelido do arquivo. Deixe em branco para corresponder a todos. |
pinned_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas fixadas; 2 = apenas desafixadas |
encrypted_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas criptografadas; 2 = apenas não criptografadas |
content_type | string | Não | "" | Filtrar por tipo de conteúdo, ex.: image, audio, video. Deixe em branco para ignorar. |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/pin_ipfs_files_for_apikey?search_string=important_files&pinned_state=2" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /unpin_ipfs_files_for_apikey
Desafixa arquivos IPFS (selecionados por busca difusa de apelido) do nó IPFS teckel. Arquivos desafixados são elegíveis para coleta automática de lixo.
Ferramenta MCP: unpin_ipfs_files — Desafixa os arquivos IPFS (selecionados por apelido via search_string difusa) do nó IPFS teckel para a conta correspondente à chave de API teckel usada na chamada. Desafixar permite a exclusão automática do conteúdo do nó IPFS.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
search_string | string | Não | "" | Busque esta string no apelido do arquivo. Deixe em branco para corresponder a todos. |
pinned_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas fixadas; 2 = apenas desafixadas |
encrypted_state | inteiro | Não | 0 | 0 = todas as entradas; 1 = apenas criptografadas; 2 = apenas não criptografadas |
content_type | string | Não | "" | Filtrar por tipo de conteúdo, ex.: image, audio, video. Deixe em branco para ignorar. |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/unpin_ipfs_files_for_apikey?search_string=old_drafts&pinned_state=1" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /pin_ipfs_cid_for_apikey
Fixa a entidade IPFS individual identificada por seu CID no nó IPFS teckel. A fixação impede a exclusão automática.
Ferramenta MCP: pin_ipfs_cid — Fixa a entidade individual identificada por seu CID IPFS no nó IPFS teckel para a conta correspondente à chave de API teckel usada na chamada. A fixação impede a exclusão automática do conteúdo do nó IPFS.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
cid | string | Não | "" | Identificador de conteúdo IPFS do arquivo a ser fixado (pin) |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/pin_ipfs_cid_for_apikey?cid=QmExampleCID123" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /remove_ipfs_cid_from_account
Remover o pin e excluir a entidade IPFS individual identificada pelo seu CID do nó IPFS teckel e do inventário da conta.
Nota: Isso remove apenas o conteúdo do nó e do inventário teckel. O conteúdo pode ainda existir na rede IPFS descentralizada.
Ferramenta MCP: remove_ipfs_cid_from_account — Remover o pin e excluir a entidade individual identificada pelo seu CID IPFS do nó IPFS teckel e da conta da carteira, para a conta correspondente à chave de API teckel usada na chamada. Nota: isso remove apenas o conteúdo do nó e do inventário teckel. Ele pode ainda existir na rede descentralizada IPFS.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
cid | string | Não | "" | Identificador de conteúdo IPFS do arquivo a ser removido |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/remove_ipfs_cid_from_account?cid=QmExampleCID123" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /publish_ipfs_file_to_webserver
Recuperar um arquivo IPFS por CID do nó teckel e publicá-lo no servidor web teckel, aplicando descriptografia se necessário. Retorna uma URL pública navegável.
Ferramenta MCP: publish_ipfs_file_to_webserver — Recuperar o arquivo IPFS, identificado pelo seu CID IPFS, do nó IPFS teckel, e publicá-lo no servidor web teckel, aplicando descriptografia se necessário, para a conta correspondente à chave de API teckel usada na chamada, retornando a URL navegável.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
cid | string | Não | "" | Identificador de conteúdo IPFS do arquivo a ser publicado |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/publish_ipfs_file_to_webserver?cid=QmExampleCID123" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /upload_sender_file_to_ipfs_for_apikey
Enviar um arquivo para o nó IPFS teckel para a conta associada à chave de API. O conteúdo é pré-verificado quanto à conformidade com os termos teckel antes de ser aceito.
Ferramenta MCP: upload_file_to_ipfs — Enviar o conteúdo do arquivo para o nó IPFS teckel para a conta correspondente à chave de API teckel usada na chamada. O conteúdo será pré-verificado quanto à compatibilidade com os termos teckel e será rejeitado se não estiver em conformidade.
Parâmetros
| Nome | Em | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|---|
file | corpo do formulário multipart | arquivo | Sim | — | Arquivo a ser enviado |
nicknameOnIPFS | consulta | string | Não | "" | Apelido para a listagem IPFS. Gerado automaticamente se estiver em branco. |
doEncryptOnIPFS | consulta | string | Não | "false" | Aplicar criptografia antes do envio. true ou false. |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/upload_sender_file_to_ipfs_for_apikey?nicknameOnIPFS=my_document&doEncryptOnIPFS=false" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@/path/to/your/file.pdf"
POST /upload_sender_base64_to_ipfs_for_apikey
Enviar dados de arquivo codificados em base64 para o nó IPFS teckel para a conta associada à chave de API. O conteúdo é pré-verificado quanto à conformidade com os termos teckel antes de ser aceito.
Ferramenta MCP: upload_base64_file_to_ipfs — Enviar o conteúdo do arquivo codificado em base64 para o nó IPFS teckel para a conta correspondente à chave de API teckel usada na chamada. O conteúdo será pré-verificado quanto à compatibilidade com os termos teckel e será rejeitado se não estiver em conformidade.
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
base64_data | string | Não | "" | Dados do arquivo codificados em base64 |
nicknameOnIPFS | string | Não | "" | Apelido para a listagem IPFS. Gerado automaticamente se estiver em branco. |
doEncryptOnIPFS | string | Não | "false" | Aplicar criptografia antes do envio. true ou false. |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/upload_sender_base64_to_ipfs_for_apikey?base64_data=SGVsbG8gV29ybGQ%3D&nicknameOnIPFS=my_file&doEncryptOnIPFS=false" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /retrieve_ipfs_file_for_apikey
Recuperar o conteúdo de um arquivo IPFS por CID do inventário da conta. Descriptografa automaticamente se o arquivo estiver criptografado. Apenas arquivos originalmente publicados no IPFS via teckel são suportados.
Ferramenta MCP: retrieve_ipfs_file — Recuperar o conteúdo do arquivo IPFS identificado pelo CID fornecido, do inventário da conta correspondente à chave de API teckel usada na chamada. Descriptografará automaticamente se estiver criptografado. Apenas arquivos originalmente publicados no IPFS via teckel são suportados, ou seja, não conteúdo IPFS genérico (de origem não teckel).
Parâmetros
| Nome | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
cid | string | Não | "" | Identificador de conteúdo IPFS do arquivo a ser recuperado |
curl -X POST "https://mcp-servers.bh.tkllabs.io:9780/retrieve_ipfs_file_for_apikey?cid=QmExampleCID123" \
-H "Authorization: Bearer YOUR_API_KEY"