Capacities MCP Enhanced

Um servidor MCP aprimorado para a API 2.0 do Capacities com CRUD completo, edição precisa de blocos, suporte a Markdown, upload de arquivos e pooling de chaves de API.

GitHub
2

Documentação

Capacities MCP Enhanced — API 2.0 para Agentes de IA

O servidor MCP oficial é ruim, está na hora de criar um novo.

Construído para a nova Capacities API 2.0 com suporte nativo e preciso de CRUD em nível de bloco.

O Capacities MCP traz acesso rico de leitura e escrita à sua base de conhecimento por meio de um servidor amigável para agentes. Os agentes podem descobrir seus tipos de objetos, entender propriedades personalizadas, criar conteúdo refinado, fazer edições precisas, salvar recursos da web e trabalhar com Notas Diárias.

✨ Por que Capacities MCP Enhanced

  • ✍️ Criação de blocos estruturados e Markdown — combine fluxos de trabalho rápidos em Markdown com edição precisa de blocos nativos do Capacities em um único servidor.
  • 🧩 CRUD completo com Capacities API 2.0 — objetos, propriedades personalizadas, coleções, blocos, links da web, tarefas, tags e Notas Diárias.
  • 🤖 Projetado para agentes autônomos — descoberta de esquema em tempo real, respostas consistentes, ferramentas focadas e informações claras de recuperação.
  • 📤 Uploads de arquivos MCP amigáveis para agentes — suporte a uploads de múltiplos arquivos e arquivos grandes com relatórios de progresso MCP integrados, transferências em streaming, verificação de upload e rastreamento de trabalhos de longa duração.
  • 🔑 Pool de chaves de API — distribua solicitações entre várias chaves de API, melhore a taxa de transferência sob limites de taxa e forneça acesso resiliente à API para cargas de trabalho de alto volume.
  • 🔒 Operações de objetos seguras para concorrência — leituras do mesmo objeto podem ser executadas simultaneamente, enquanto gravações usam um bloqueio exclusivo e aguardam automaticamente leituras ativas ou outras gravações; objetos diferentes prosseguem simultaneamente.
  • 🎨 Conteúdo rico fiel — títulos, blocos aninhados, grades, alternadores, tarefas, links, referências a entidades, cores, código e matemática.
  • 📚 Habilidade de melhores práticas incluída — um guia completo de operação do agente está incluído, para que um modelo possa usar o servidor corretamente sem já conhecer o Capacities.

🚀 Início rápido

Requisitos

  • Node.js 20+ ou Bun 1.3+
  • Uma ou mais chaves de API pessoais da nova Capacities API com as permissões necessárias

Instalação

Configure seu cliente MCP para usar o servidor Capacities MCP:

Gere um token em Capacities → Configurações → Capacities API → Gerar novo token. Novos tokens de API começam com cap-api-.
Recomenda-se configurar pelo menos 3 tokens com o mesmo espaço e permissões para evitar erros de limite de taxa.

Claude Code

{
  "mcpServers": {
    "capacities": {
      "command": "npx",
      "args": ["--yes", "capacities-mcp-enhanced@latest"],
      "env": {
        "CAPACITIES_API_TOKEN": "cap-api-key-1,cap-api-key-2;cap-api-key-3"
      }
    }
  }
}

Hermes Agent

mcp_servers:
  capacities:
    command: "npx"
    args:
      - "--yes"
      - "capacities-mcp-enhanced@latest"
    env:
      CAPACITIES_API_TOKEN: "cap-api-key-1,cap-api-key-2;cap-api-key-3"
    supports_parallel_tool_calls: true

Instalar as habilidades incluídas (Opcional)

Ao instalar a habilidade de Melhores Práticas do Capacities MCP, seu agente pode aprender o fluxo de trabalho completo, esquemas de conteúdo rigorosos, padrões seguros de mutação, recuperação de limite de taxa e armadilhas comuns.

npx skills add nyrest/capacities-mcp-enhanced

🧰 O que os agentes podem fazer

CategoriaFerramentaO que faz
Descobrir e lerinspect_spaceDescubra estruturas, propriedades, rótulos e opções de gravação disponíveis.
Descobrir e lersearch_objectsEncontre objetos por título, opcionalmente dentro de estruturas selecionadas.
Descobrir e lerlist_objectsListe resumos de objetos paginados por cursor, por estrutura, tag ou coleção.
Descobrir e lerget_objectLeia um objeto completo como conteúdo estruturado ou Markdown.
Criar objetoscreate_objectCrie uma Página, Tarefa, Tag ou objeto personalizado com conteúdo estruturado.
Criar objetoscreate_object_markdownCrie um objeto a partir de um documento Markdown.
Criar objetoscreate_object_from_urlSalve um recurso da web com notas estruturadas.
Criar objetoscreate_object_from_url_markdownSalve um recurso da web com notas em Markdown.
Atualizar conteúdoupdate_objectAtualize títulos, propriedades tipadas e coleções.
Atualizar conteúdoappend_contentAdicione blocos estruturados a um objeto.
Atualizar conteúdoappend_content_markdownAdicione conteúdo Markdown a um objeto.
Atualizar conteúdoupdate_blockEdite com precisão um bloco existente.
Atualizar conteúdodelete_blockRemova um bloco e seu conteúdo aninhado.
Atualizar conteúdodelete_objectMova um objeto para a lixeira ou exclua-o permanentemente quando solicitado explicitamente.
Notas Diáriasappend_daily_noteAdicione blocos estruturados à Nota Diária de hoje ou de uma data específica.
Notas Diáriasappend_daily_note_markdownAdicione Markdown à Nota Diária de hoje ou de uma data específica.
Uploads de mídiaupload_filesTransmita um ou mais arquivos locais para objetos de mídia do Capacities com verificação de leitura de volta.
Uploads de mídiamanage_upload_jobInspecione, aguarde ou cancele um trabalho de upload em segundo plano em andamento.

search_objects é descoberta somente por título. Use list_objects quando você já souber uma estrutura, UUID de tag ou UUID de coleção e precisar de listagem de associação; siga nextCursor enquanto hasMore for verdadeiro, depois passe os IDs de objetos selecionados para get_object para obter o conteúdo completo.

upload_files aceita apenas caminhos de arquivo locais absolutos; caminhos relativos, diretórios e arquivos vazios são rejeitados. Trabalhos de upload em segundo plano existem apenas no processo MCP atual e retêm o status terminal por um tempo limitado.

Variáveis de ambiente e opções de configuração suportadas

ConfiguraçãoObrigatórioPadrãoDescrição
CAPACITIES_API_TOKENSim, a menos que cada chamada forneça apiToken—Uma chave de API ou um pool de chaves separado por vírgula/ponto e vírgula. As chaves devem pertencer ao mesmo espaço e usar as mesmas permissões.
CAPACITIES_MCP_READBACKNãotrueDefina como false para desativar a leitura de volta de mutação comum. A verificação de reversão permanece ativada. Valores aceitos: true, false.

A configuração por chamada é exposta por meio do argumento opcional apiToken em todas as ferramentas. Ele substitui CAPACITIES_API_TOKEN para essa chamada e aceita a mesma sintaxe de pool de chaves.

⚙️ Pool de chaves de API e limites de taxa

CAPACITIES_API_TOKEN e a opção apiToken por chamada aceitam múltiplas chaves de API separadas por , ou ;. As chaves são selecionadas com agendamento round-robin independentemente para cada endpoint, pulando chaves atualmente marcadas como limitadas por taxa.

Todas as chaves em um pool devem pertencer ao mesmo espaço e ter as mesmas permissões. Recomenda-se pelo menos 3 chaves; use instâncias separadas do servidor MCP para múltiplos espaços.

Em 429, o pool faz failover imediato para outra chave que não esteja limitada por taxa. O erro é retornado somente quando todas as chaves estão limitadas por taxa. Não há espera, backoff exponencial ou nova tentativa entre pools.

🚅 Concorrência e gravações seguras

Leituras para o mesmo objeto podem ser executadas simultaneamente. Uma mutação obtém um bloqueio exclusivo de objeto, então ela aguarda leituras ativas e outras gravações; leituras que chegam durante uma gravação também aguardam. Operações para objetos diferentes prosseguem simultaneamente. Isso protege o ciclo de vida completo de leitura → mutação → leitura de volta contra corridas de última gravação vence. O SDK do Capacities não expõe configuração de cancelamento/timeout de solicitação, então chamadas comuns apoiadas pelo SDK não usam uma corrida de timeout insegura no lado do cliente. O upload de mídia multiparte é o único caminho HTTP direto: ele mantém cancelamento nativo de AbortSignal, progresso explícito por parte, failover de pool de chaves e verificação independente de leitura de volta do SDK.

🛠️ Desenvolvimento

bun run lint
bun run typecheck
bun test
bun run build
bun run verify:tools

O gate final de lançamento local é:

npm run release:check
npm publish --dry-run --access public

npm publish --dry-run valida o pacote sem publicá-lo. A publicação real requer adicionalmente uma conta npm autenticada.

Testes de API ao vivo estão disponíveis por meio de bun run test:live quando um token de teste dedicado está configurado.

📚 Documentação