Agentic Tools

Fornece assistentes de IA com gerenciamento avançado de tarefas e capacidades de memória usando armazenamento local de arquivos JSON.

GitHub
88
Experimente este MCPPatrocinado

Documentação

Servidor MCP Agentic Tools

npm version npm downloads GitHub stars GitHub license Node.js Version

Um servidor abrangente do Model Context Protocol (MCP) que fornece aos assistentes de IA poderosos recursos de gerenciamento avançado de tarefas e memórias de agente com armazenamento específico por projeto.

🔗 Ecossistema

Este servidor MCP faz parte de um ecossistema completo de gerenciamento de tarefas e memórias:

  • 🖥️ Extensão do VS Code - Interface gráfica bonita para gerenciar tarefas e memórias diretamente no VS Code
  • ⚡ Servidor MCP (este repositório) - Ferramentas avançadas de agente de IA e API para gerenciamento inteligente de tarefas

💡 Dica Profissional: Use ambos juntos para a experiência de produtividade definitiva! A extensão do VS Code fornece uma interface visual enquanto o servidor MCP permite a integração com assistentes de IA com recursos avançados como análise de PRD, recomendações de tarefas e capacidades de pesquisa.

Recursos

🎯 Sistema Avançado de Gerenciamento de Tarefas com Hierarquia Ilimitada (v1.8.0)

  • Projetos: Organize o trabalho em projetos distintos com descrições
  • Modelo de Tarefa Unificado: Interface única de tarefas com suporte a profundidade de aninhamento ilimitada
  • Hierarquia Ilimitada: Tarefas → Subtarefas → Sub-subtarefas → aninhamento em profundidade infinita
  • Recursos Ricos em Todos os Níveis: Cada tarefa recebe prioridade, complexidade, dependências, tags e controle de tempo
  • Relacionamentos Pai-Filho: Organização flexível de hierarquia com o campo parentId
  • Controle de Nível: Cálculo automático do nível de hierarquia e indicadores visuais
  • Visualização em Árvore: Exibição abrangente de árvore hierárquica com profundidade ilimitada
  • Dependências Inteligentes: Gerenciamento de dependências de tarefas com validação em toda a hierarquia
  • Prioridade e Complexidade: Priorização em escala de 1 a 10 e estimativa de complexidade em todos os níveis
  • Controle de Status Aprimorado: fluxo de trabalho de status pendente, em andamento, bloqueado e concluído
  • Organização por Tags: Categorização e filtragem flexíveis
  • Controle de Tempo: Horas estimadas e reais para planejamento de projetos
  • Migração Automática: Atualização perfeita do modelo antigo de 3 níveis para profundidade ilimitada
  • Controle de Progresso: Monitore o status de conclusão em todos os níveis da hierarquia
  • Armazenamento Específico por Projeto: Cada diretório de trabalho possui dados de tarefas isolados
  • Rastreável por Git: Os dados de tarefas podem ser commitados junto com seu código

🧠 Sistema de Memórias de Agente

  • Memória Persistente: Armazene e recupere memórias de agente com títulos e conteúdo detalhado
  • Busca Inteligente: Busca de texto em múltiplos campos com pontuação de relevância em títulos, conteúdo e categorias
  • Classificação Inteligente: Algoritmo avançado de pontuação prioriza correspondências de título (60%), correspondências de conteúdo (30%) e bônus de categoria (20%)
  • Metadados Ricos: Sistema flexível de metadados para contexto aprimorado
  • Armazenamento JSON: Arquivos JSON individuais organizados por categoria, nomeados de acordo com os títulos das memórias
  • Específico por Projeto: Armazenamento de memórias isolado por diretório de trabalho

🔧 Ferramentas MCP Disponíveis

Gerenciamento de Projetos

  • list_projects - Visualizar todos os projetos em um diretório de trabalho
  • create_project - Criar um novo projeto em um diretório de trabalho
  • get_project - Obter informações detalhadas do projeto
  • update_project - Editar nome/descrição do projeto
  • delete_project - Excluir projeto e todos os dados associados

Gerenciamento de Tarefas (Hierarquia Ilimitada v1.8.0)

  • list_tasks - Visualizar tarefas em formato de árvore hierárquica com visualização de profundidade ilimitada
  • create_task - Criar tarefas em qualquer nível da hierarquia com parentId (suporta aninhamento ilimitado)
  • get_task - Obter informações detalhadas da tarefa, incluindo relacionamentos de hierarquia
  • update_task - Editar tarefas, metadados ou mover entre níveis de hierarquia com parentId
  • delete_task - Excluir tarefa e todas as subtarefas recursivamente
  • move_task - Ferramenta dedicada para mover tarefas dentro da estrutura de hierarquia
  • migrate_subtasks - Ferramenta de migração automática para converter subtarefas legadas no modelo unificado

Gerenciamento Avançado de Tarefas (Ferramentas de Agente de IA)

  • parse_prd - Analisar Documentos de Requisitos de Produto e gerar automaticamente tarefas estruturadas
  • get_next_task_recommendation - Obter recomendações inteligentes de tarefas com base em dependências, prioridades e complexidade
  • analyze_task_complexity - Analisar a complexidade das tarefas e sugerir a divisão de tarefas excessivamente complexas
  • infer_task_progress - Analisar a base de código para inferir o status de conclusão das tarefas a partir de evidências de implementação
  • research_task - Orientar agentes de IA a realizar pesquisas web abrangentes com integração de memória
  • generate_research_queries - Gerar consultas de pesquisa web inteligentes e direcionadas para pesquisa de tarefas

Gerenciamento de Subtarefas Legadas (Compatibilidade Retroativa)

  • list_subtasks - Visualizar subtarefas (compatibilidade legada, agora usa o modelo de Tarefa unificado)
  • create_subtask - Criar subtarefas (compatibilidade legada, cria tarefas com parentId)
  • get_subtask - Obter informações de tarefa (compatibilidade legada para subtarefas existentes)
  • update_subtask - Editar subtarefas (compatibilidade legada, usa operações de Tarefa unificadas)
  • delete_subtask - Excluir subtarefas (compatibilidade legada, exclui tarefas recursivamente)

Gerenciamento de Memórias de Agente

  • create_memory - Armazenar novas memórias com título e conteúdo detalhado
  • search_memories - Encontrar memórias usando busca inteligente em múltiplos campos com pontuação de relevância
  • get_memory - Obter informações detalhadas da memória
  • list_memories - Listar memórias com filtragem opcional
  • update_memory - Editar título, conteúdo, metadados ou categorização da memória
  • delete_memory - Excluir uma memória (requer confirmação)

Importante: Todas as ferramentas exigem um parâmetro workingDirectory para especificar onde os dados devem ser armazenados. Isso permite o gerenciamento de tarefas e memórias específico por projeto.

Instalação

Início Rápido

npx -y @pimzino/agentic-tools-mcp

Instalação Global

npm install -g @pimzino/agentic-tools-mcp

Uso

Modos de Armazenamento

O servidor MCP suporta dois modos de armazenamento:

📁 Modo Específico por Projeto (Padrão)

Os dados são armazenados em subdiretórios .agentic-tools-mcp/ dentro do diretório de trabalho de cada projeto.

npx -y @pimzino/agentic-tools-mcp

🌐 Modo de Diretório Global

Use o sinalizador --claude para armazenar todos os dados em um diretório global padronizado:

  • Windows: C:\Users\{username}\.agentic-tools-mcp\
  • macOS/Linux: ~/.agentic-tools-mcp/
npx -y @pimzino/agentic-tools-mcp --claude

Quando usar o sinalizador --claude:

  • Com o cliente Claude Desktop (uso não específico de projeto)
  • Quando você deseja um único espaço de trabalho global para todas as tarefas e memórias
  • Para assistentes de IA que trabalham em vários projetos

Nota: Ao usar o sinalizador --claude, o parâmetro workingDirectory em todas as ferramentas é ignorado e o diretório global é usado em seu lugar.

Com o Claude Desktop

Modo Específico por Projeto (Padrão)

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp"]
    }
  }
}

Modo de Diretório Global (Recomendado para Claude Desktop)

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp", "--claude"]
    }
  }
}

Nota: O servidor agora inclui recursos de gerenciamento de tarefas e memórias de agente.

Com o AugmentCode

Modo Específico por Projeto (Padrão)

  1. Abra o Painel de Configurações do Augment (ícone de engrenagem)
  2. Adicione o servidor MCP:
    • Nome: agentic-tools
    • Comando: npx -y @pimzino/agentic-tools-mcp
  3. Reinicie o VS Code

Modo de Diretório Global

  1. Abra o Painel de Configurações do Augment (ícone de engrenagem)
  2. Adicione o servidor MCP:
    • Nome: agentic-tools
    • Comando: npx -y @pimzino/agentic-tools-mcp --claude
  3. Reinicie o VS Code

Recursos Disponíveis: Gerenciamento de tarefas, memórias de agente e capacidades de busca baseada em texto.

Com a Extensão do VS Code (Recomendado)

Para a melhor experiência do usuário, instale a extensão Agentic Tools MCP Companion do VS Code:

  1. Clone o repositório da extensão complementar
  2. Abra-o no VS Code e pressione F5 para executar em modo de desenvolvimento
  3. Desfrute de uma bela interface gráfica para todo o gerenciamento de tarefas e memórias

Benefícios de usar ambos juntos:

  • 🎯 Gerenciamento Visual de Tarefas: Formulários ricos com prioridade, complexidade, status, tags e controle de tempo
  • 🎨 IU Aprimorada: Emojis de status, distintivos de prioridade e indicadores visuais
  • 🔄 Sincronização em Tempo Real: Alterações no VS Code instantaneamente disponíveis para assistentes de IA
  • 📁 Integração com Projetos: Integrado perfeitamente ao seu espaço de trabalho
  • 🤖 Colaboração com IA: Planejamento humano com execução de IA para produtividade ideal

Com Outros Clientes MCP

O servidor usa transporte STDIO e pode ser integrado a qualquer cliente compatível com MCP:

Modo Específico por Projeto

npx -y @pimzino/agentic-tools-mcp

Modo de Diretório Global

npx -y @pimzino/agentic-tools-mcp --claude

Modelos de Dados

Projeto

{
  id: string;           // Unique identifier
  name: string;         // Project name
  description: string;  // Project overview
  createdAt: string;    // ISO timestamp
  updatedAt: string;    // ISO timestamp
}

Tarefa (Modelo Unificado v1.8.0 - Hierarquia Ilimitada)

{
  id: string;                    // Unique identifier
  name: string;                  // Task name
  details: string;               // Enhanced description
  projectId: string;             // Parent project reference
  completed: boolean;            // Completion status
  createdAt: string;             // ISO timestamp
  updatedAt: string;             // ISO timestamp

  // Unlimited hierarchy fields (v1.8.0)
  parentId?: string;             // Parent task ID for unlimited nesting (NEW)
  level?: number;                // Computed hierarchy level (0, 1, 2, etc.) (NEW)

  // Enhanced metadata fields (from v1.7.0)
  dependsOn?: string[];          // Task dependencies (IDs of prerequisite tasks)
  priority?: number;             // Priority level (1-10, where 10 is highest)
  complexity?: number;           // Complexity estimate (1-10, where 10 is most complex)
  status?: string;               // Enhanced status: 'pending' | 'in-progress' | 'blocked' | 'done'
  tags?: string[];               // Tags for categorization and filtering
  estimatedHours?: number;       // Estimated time to complete (hours)
  actualHours?: number;          // Actual time spent (hours)
}

Subtarefa Legada (Obsoleta na v1.8.0)

A interface separada de Subtarefa foi substituída pelo modelo de Tarefa unificado. Subtarefas legadas são migradas automaticamente para tarefas com o campo parentId. Isso garante profundidade de hierarquia ilimitada, mantendo todos os recursos ricos em todos os níveis.

Memória

{
  id: string;                    // Unique identifier
  title: string;                 // Short title for file naming (max 50 characters)
  content: string;               // Detailed memory content/text (no limit)
  metadata: Record<string, any>; // Flexible metadata object
  createdAt: string;            // ISO timestamp
  updatedAt: string;            // ISO timestamp
  category?: string;            // Optional categorization
}

Fluxo de Trabalho de Exemplo

  1. Criar um Projeto

    Use create_project with:
- workingDirectory="/path/to/your/project"
- name="Website Redesign"
- description="Complete overhaul of company website"

  2. Adicionar Tarefas Aprimoradas

    Use create_task with:
- workingDirectory="/path/to/your/project"
- name="Design mockups"
- details="Create wireframes and high-fidelity designs"
- projectId="[project-id-from-step-1]"
- priority=8 (high priority)
- complexity=6 (above average complexity)
- status="pending"
- tags=["design", "ui", "mockups"]
- estimatedHours=16

  3. Dividir Tarefas

    Use create_subtask with:
- workingDirectory="/path/to/your/project"
- name="Create wireframes"
- details="Sketch basic layout structure"
- taskId="[task-id-from-step-2]"

  4. Acompanhar o Progresso

    Use update_task and update_subtask to mark items as completed
Use list_projects, list_tasks, and list_subtasks to view progress
(All with workingDirectory parameter)

Fluxo de Trabalho de Memórias de Agente

  1. Criar uma Memória

    Use create_memory with:
- workingDirectory="/path/to/your/project"
- title="User prefers concise technical responses"
- content="The user has explicitly stated they prefer concise responses with technical explanations. They value brevity but want detailed technical information when relevant."
- metadata={"source": "conversation", "confidence": 0.9}
- category="user_preferences"

  2. Buscar Memórias

    Use search_memories with:
- workingDirectory="/path/to/your/project"
- query="user preferences responses"
- limit=5
- threshold=0.3
- category="user_preferences"

  3. Listar e Gerenciar

    Use list_memories to view all memories
Use update_memory to modify existing memories (title, content, metadata, category)
Use delete_memory to remove outdated memories
(All with workingDirectory parameter)

📖 Início Rápido: Consulte docs/QUICK_START_MEMORIES.md para um guia passo a passo sobre memórias de agente.

Armazenamento de Dados

  • Específico por projeto: Cada diretório de trabalho possui seus próprios dados de tarefas e memórias isolados
  • Baseado em arquivos: Dados de tarefas armazenados em .agentic-tools-mcp/tasks/, dados de memórias em .agentic-tools-mcp/memories/
  • Rastreável por Git: Todos os dados podem ser commitados junto com o código do seu projeto
  • Persistente: Todos os dados persistem entre reinicializações do servidor
  • Atômico: Todas as operações são atômicas para evitar corrupção de dados
  • Armazenamento JSON: Armazenamento simples baseado em arquivos para organização eficiente de memórias
  • Amigável para backup: Armazenamento simples baseado em arquivos para fácil backup e migração

Estrutura de Armazenamento

your-project/
├── .agentic-tools-mcp/
│   ├── tasks/              # Task management data for this project
│   │   └── tasks.json      # Projects, tasks, and subtasks data
│   └── memories/           # JSON file storage for memories
│       ├── preferences/    # User preferences category
│       │   └── User_prefers_concise_technical_responses.json
│       ├── technical/      # Technical information category
│       │   └── React_TypeScript_project_with_strict_ESLint.json
│       └── context/        # Context information category
│           └── User_works_in_healthcare_needs_HIPAA_compliance.json
├── src/
├── package.json
└── README.md

Parâmetro de Diretório de Trabalho

Todas as ferramentas MCP exigem um parâmetro workingDirectory que especifica:

  • Onde armazenar a pasta .agentic-tools-mcp/ (no modo específico por projeto)
  • De qual projeto acessar os dados de tarefas e memórias
  • Permite que vários projetos tenham listas de tarefas e armazenamentos de memórias separados

Nota: Quando o servidor é iniciado com o sinalizador --claude, o parâmetro workingDirectory é ignorado e um diretório de usuário global é usado em seu lugar (~/.agentic-tools-mcp/ no macOS/Linux ou C:\Users\{username}\.agentic-tools-mcp\ no Windows).

Benefícios do Armazenamento Específico por Projeto

  • Integração com Git: Dados de tarefas e memórias podem ser commitados com seu código
  • Colaboração em Equipe: Compartilhe listas de tarefas e memórias de agente via controle de versão
  • Isolamento de Projetos: Cada projeto possui seu próprio sistema de gerenciamento de tarefas e memórias
  • Fluxo de Trabalho Multi-Projeto: Trabalhe em vários projetos simultaneamente com memórias isoladas
  • Backup e Migração: Armazenamento baseado em arquivos viaja com seu código
  • Busca de Texto: Busca simples de memórias baseada em conteúdo para recuperação inteligente de contexto
  • Continuidade do Agente: Memórias de agente persistentes entre sessões e implantações

Tratamento de Erros

  • Validação: Todas as entradas são validadas com mensagens de erro abrangentes
  • Validação de Diretório: Garante que o diretório de trabalho exista e seja acessível
  • Integridade Referencial: Previne tarefas/subtarefas órfãs com exclusões em cascata
  • Nomes Únicos: Impõe nomes únicos dentro do escopo (projeto/tarefa)
  • Confirmação: Operações destrutivas exigem confirmação explícita
  • Degradação Graciosa: Mensagens de erro detalhadas para solução de problemas
  • Erros de Armazenamento: Mensagens claras quando a inicialização do armazenamento falha

Desenvolvimento

Compilando a partir do Código Fonte

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

Estrutura do Projeto

src/
├── features/
│   ├── task-management/
│   │   ├── tools/           # MCP tool implementations
│   │   │   ├── projects/    # Project CRUD operations
│   │   │   ├── tasks/       # Task CRUD operations
│   │   │   └── subtasks/    # Subtask CRUD operations
│   │   ├── models/          # TypeScript interfaces
│   │   └── storage/         # Data persistence layer
│   └── agent-memories/
│       ├── tools/           # Memory MCP tool implementations
│       │   └── memories/    # Memory CRUD operations
│       ├── models/          # Memory TypeScript interfaces
│       └── storage/         # JSON file storage implementation
├── server.ts            # MCP server configuration
└── index.ts             # Entry point

Solução de Problemas

Problemas Comuns

"O diretório de trabalho não existe"

  • Certifique-se de que o caminho existe e é acessível
  • Use caminhos absolutos para confiabilidade
  • Verifique as permissões do diretório "A pesquisa de texto não retorna resultados" (Memórias do Agente)
  • Tente usar palavras-chave ou frases diferentes
  • Verifique se as memórias contêm os termos pesquisados
  • Confirme se o conteúdo da consulta corresponde ao conteúdo da memória

"Arquivos de memória não encontrados" (Memórias do Agente)

  • Garanta que o diretório de trabalho exista e seja gravável
  • Verifique se o diretório .agentic-tools-mcp/memories foi criado

Histórico de Versões

Consulte CHANGELOG.md para obter o histórico detalhado de versões e notas de lançamento.

Versão Atual: 1.8.0

  • 🚀 NOVO: Modelo de Tarefa Unificado: Interface de tarefa única com suporte a profundidade de aninhamento ilimitada
  • 🚀 NOVO: Hierarquia Ilimitada: Tarefas → Subtarefas → Sub-subtarefas → aninhamento em profundidade infinita
  • 🚀 NOVO: Migração Automática: Atualização perfeita do modelo de 3 níveis para profundidade ilimitada
  • 🚀 NOVO: Exibição de Árvore Aprimorada: Visualização hierárquica com indicadores de nível e profundidade ilimitada
  • 🚀 NOVO: Ferramentas de Hierarquia: move_task, migrate_subtasks para gerenciamento de profundidade ilimitada
  • ✅ Recursos Ricos em Todos os Níveis: Cada tarefa recebe prioridade, complexidade, dependências, tags e controle de tempo
  • ✅ Gerenciamento de Tarefas Aprimorado: Metadados ricos com dependências, prioridade, complexidade, status, tags e controle de tempo
  • ✅ Ferramentas Avançadas para Agentes de IA: Análise de PRD, recomendações de tarefas, análise de complexidade, inferência de progresso e orientação de pesquisa
  • ✅ Dependências Inteligentes de Tarefas: Validação de dependências e gerenciamento de fluxo de trabalho em toda a hierarquia
  • ✅ Sistema de Prioridade e Complexidade: Priorização em escala de 1 a 10 e estimativa de complexidade em todos os níveis
  • ✅ Fluxo de Trabalho de Status Aprimorado: Rastreamento de status pendente → em andamento → bloqueado → concluído
  • ✅ Organização Baseada em Tags: Sistema flexível de categorização e filtragem
  • ✅ Controle de Tempo: Horas estimadas e reais para planejamento de projetos
  • ✅ Integração de Pesquisa Híbrida: Pesquisa na web com cache de memória para agentes de IA
  • ✅ Sistema completo de gerenciamento de tarefas com organização hierárquica ilimitada
  • ✅ Memórias do agente com arquitetura de título/conteúdo e armazenamento em arquivos JSON
  • ✅ Pesquisa inteligente de múltiplos campos com pontuação de relevância
  • ✅ Armazenamento específico do projeto com ferramentas MCP abrangentes
  • ✅ Modo de diretório global com a flag --claude para Claude Desktop
  • ✅ Integração com o ecossistema de extensões do VS Code

Agradecimentos

Somos gratos à comunidade de código aberto e aos seguintes projetos que tornam este servidor MCP possível:

Tecnologias Principais

Desenvolvimento e Validação

  • Zod - Validação de esquema em TypeScript para tratamento robusto de entradas
  • ESLint - Qualidade e consistência de código
  • Prettier - Formatação de código

Armazenamento e Pesquisa de Arquivos

  • JSON - Formato de dados simples e legível para armazenamento de memórias
  • Pesquisa de Texto - Busca eficiente baseada em conteúdo nos arquivos de memória

Agradecimentos Especiais

  • Comunidade de Código Aberto - Por criar as ferramentas e bibliotecas que tornam este projeto possível

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar issues e pull requests.

Configuração de Desenvolvimento

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

Projetos Relacionados

🖥️ Extensão do VS Code

Agentic Tools MCP Companion - Uma bela extensão do VS Code que fornece uma interface gráfica para este servidor MCP.

Principais Recursos:

  • 🎯 Gerenciamento Visual de Tarefas: Interface gráfica rica com formulários aprimorados de metadados de tarefas
  • 📝 Formulários Aprimorados: Prioridade, complexidade, status, tags e controle de tempo
  • 🎨 Indicadores Visuais: Emojis de status, selos de prioridade e indicadores de complexidade
  • 📊 Tooltips Ricos: Informações completas da tarefa ao passar o mouse
  • 🔄 Sincronização em Tempo Real: Sincronização instantânea com os dados do servidor MCP
  • 📱 Design Responsivo: Formulários adaptáveis que funcionam em diferentes tamanhos de tela

Perfeito para:

  • Gerenciamento e planejamento visual de tarefas
  • Equipes que preferem interfaces gráficas
  • Gerentes de projeto que precisam de metadados ricos de tarefas
  • Qualquer pessoa que queira uma organização bonita de tarefas no VS Code

Suporte

Para problemas e dúvidas, use o rastreador de issues do GitHub.

Documentação

Obtendo Ajuda

  • 🐛 Reporte bugs via issues do GitHub
  • 💡 Solicite recursos via discussões do GitHub
  • 🖥️ Issues da Extensão do VS Code: Reporte issues específicos da extensão em agentic-tools-mcp-companion