Context Portal MCP (ConPort)

O que é o servidor Context Portal MCP (ConPort)?

O Context Portal (ConPort) é o banco de memória do seu projeto. É uma ferramenta que ajuda assistentes de IA a entender melhor seu projeto de software específico, armazenando informações importantes como decisões, tarefas e padrões arquiteturais de forma estruturada. Pense nele como a construção de uma base de conhecimento específica do projeto que a IA pode acessar facilmente e usar para fornecer respostas mais precisas e úteis.

O que ele faz:

• Mantém registro de decisões do projeto, progresso e designs de sistema.
• Armazena dados personalizados do projeto (como glossários ou especificações).
• Ajuda a IA a encontrar informações relevantes do projeto rapidamente (como uma busca inteligente).
• Permite que a IA use o contexto do projeto para respostas melhores (RAG).
• Mais eficiente para gerenciar, buscar e atualizar contexto em comparação com bancos de memória baseados em arquivos de texto simples.

O ConPort fornece uma maneira robusta e estruturada para assistentes de IA armazenarem, recuperarem e gerenciarem vários tipos de contexto de projeto. Ele efetivamente constrói um grafo de conhecimento específico do projeto, capturando entidades como decisões, progresso e arquitetura, junto com seus relacionamentos. Essa base de conhecimento estruturada, aprimorada por embeddings vetoriais para busca semântica, serve então como um backend poderoso para Geração Aumentada por Recuperação (RAG), permitindo que assistentes de IA acessem informações precisas e atualizadas para respostas mais conscientes do contexto e precisas.

Ele substitui sistemas antigos de gerenciamento de contexto baseados em arquivos, oferecendo um backend de banco de dados mais confiável e consultável (SQLite por workspace). O ConPort é projetado para ser um backend de contexto genérico, compatível com vários IDEs e interfaces de cliente que suportam MCP.

Os principais recursos incluem:

• Armazenamento de contexto estruturado usando SQLite (um banco de dados por workspace, criado automaticamente).
• Servidor MCP (context_portal_mcp) construído com Python/FastAPI.
• Um conjunto abrangente de ferramentas MCP definidas para interação (veja "Ferramentas ConPort Disponíveis" abaixo).
• Suporte a múltiplos workspaces via workspace_id.
• Modo de implantação principal: STDIO para integração estreita com IDE.
• Permite construir um grafo de conhecimento de projeto dinâmico com relacionamentos explícitos entre itens de contexto.
• Inclui armazenamento de dados vetoriais e recursos de busca semântica para potencializar RAG avançado.
• Serve como backend ideal para Geração Aumentada por Recuperação (RAG), fornecendo à IA memória de projeto precisa e consultável.
• Fornece contexto estruturado que assistentes de IA podem aproveitar para cache de prompt com provedores de LLM compatíveis.
• Gerencia a evolução do esquema do banco de dados usando migrações Alembic, garantindo atualizações contínuas e integridade dos dados.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte instalado:

• Python: Versão 3.8 ou superior é recomendada.
  • Baixar Python
  • Certifique-se de que o Python foi adicionado ao PATH do seu sistema durante a instalação (especialmente no Windows).
• uv: (Altamente Recomendado) Um gerenciador de pacotes e ambiente Python rápido. Usar uv simplifica significativamente a criação de ambientes virtuais e a instalação de dependências.
  • Instalar uv

Instalação e Configuração (Recomendado)

A maneira recomendada de instalar e executar o ConPort é usando uvx para executar o pacote diretamente do PyPI. Este método evita a necessidade de criar e gerenciar manualmente ambientes virtuais.

Configuração uvx (Recomendado para a maioria dos IDEs)

Nas configurações do seu cliente MCP (por exemplo, mcp_settings.json), use a seguinte configuração:

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--workspace_id",
        "${workspaceFolder}",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

• command: uvx gerencia o ambiente para você.
• args: Contém os argumentos para executar o servidor ConPort.
• ${workspaceFolder}: Esta variável do IDE é usada para fornecer automaticamente o caminho absoluto do workspace do projeto atual.
• --log-file: Opcional: Caminho para um arquivo onde os logs do servidor serão gravados. Se não for fornecido, os logs são direcionados para stderr (console). Útil para registro persistente e depuração do comportamento do servidor.
• --log-level: Opcional: Define o nível mínimo de registro para o servidor. As escolhas válidas são DEBUG, INFO, WARNING, ERROR, CRITICAL. O padrão é INFO. Defina como DEBUG para saída detalhada durante desenvolvimento ou solução de problemas.

Importante: Muitos IDEs não expandem ${workspaceFolder} ao iniciar servidores MCP. Use uma destas opções seguras:

1. Forneça um caminho absoluto para --workspace_id.
2. Omita --workspace_id na inicialização e dependa do workspace_id por chamada (recomendado se seu cliente o fornecer em cada chamada).

Configuração alternativa (sem --workspace_id na inicialização):

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from",
        "context-portal-mcp",
        "conport-mcp",
        "--mode",
        "stdio",
        "--log-file",
        "./logs/conport.log",
        "--log-level",
        "INFO"
      ]
    }
  }
}

Se você omitir --workspace_id, o servidor pulará a pré-inicialização e inicializará o banco de dados na primeira chamada de ferramenta usando o workspace_id fornecido nessa chamada.

Instalação para Desenvolvedores (do Repositório Git)

A maneira mais apropriada de desenvolver e testar o ConPort é executá-lo no seu IDE como um servidor MCP usando a configuração acima. Isso exercita o modo STDIO e o comportamento real do cliente.

Se você precisar executar com um checkout local e virtualenv, você pode configurar seu cliente MCP para iniciar o servidor de desenvolvimento via uv run e seu .venv/bin/python:

{
  "mcpServers": {
    "conport": {
      "command": "uv",
      "args": [
        "run",
        "--python",
        ".venv/bin/python",
        "--directory",
        "<path to context-portal repo> ",
        "conport-mcp",
        "--mode",
        "stdio",
        "--log-file",
        "./logs/conport-dev.log",
        "--log-level",
        "DEBUG"
      ],
      "disabled": false
    }
  }
}

Notas:

• Defina --directory para o caminho do seu repositório; isso usa seu checkout local e o interpretador do venv.
• Os logs vão para ./logs/conport-dev.log com verbosidade DEBUG.

Configuração do ambiente local

Configure para desenvolvimento ou contribuição via repositório Git.

1. Clone o repositório

   git clone https://github.com/GreatScottyMac/context-portal.git
   cd context-portal
   

2. Crie um ambiente virtual

   uv venv
   

   Ative-o usando a ativação padrão do seu shell (por exemplo, source .venv/bin/activate no macOS/Linux).

3. Instale as dependências

   uv pip install -r requirements.txt
   

4. Execute no seu IDE (recomendado) Configure as configurações MCP do seu IDE usando a "Configuração uvx" ou a configuração de desenvolvimento uv run mostrada acima. Este é o teste mais representativo do ConPort no modo STDIO.

5. Opcional: Ajuda da CLI

   uv run python src/context_portal_mcp/main.py --help
   

Notas:

• Para comportamento --workspace_id e manipulação de caminho do IDE, consulte as orientações na seção "Configuração uvx" acima. Muitos IDEs não expandem ${workspaceFolder}.

Para limpeza pré-atualização, incluindo limpeza do cache de bytecode Python, consulte o v0.2.4_UPDATE_GUIDE.md.

Uso com Agentes LLM (Instruções Personalizadas)

A eficácia do ConPort com agentes LLM é significativamente aprimorada ao fornecer instruções personalizadas específicas ou prompts de sistema para o LLM. Este repositório inclui arquivos de estratégia adaptados para diferentes ambientes:

• Para Roo Code:

  • roo_code_conport_strategy: Contém instruções detalhadas para LLMs que operam na extensão Roo Code do VS Code, orientando-os sobre como usar as ferramentas ConPort para gerenciamento de contexto.
  
  

• Para CLine:

  • cline_conport_strategy: Contém instruções detalhadas para LLMs que operam na extensão Cline do VS Code, orientando-os sobre como usar as ferramentas ConPort para gerenciamento de contexto.
  
  

• Para Windsurf Cascade:

  • cascade_conport_strategy: Orientação específica para LLMs integrados ao ambiente Windsurf Cascade. Importante: Ao iniciar uma sessão no Cascade, é necessário dizer explicitamente ao LLM:

  Initialize according to custom instructions
  

• Para Uso Geral/Independente de Plataforma:

  • generic_conport_strategy: Fornece um conjunto de instruções independente de plataforma para qualquer LLM compatível com MCP. Ele enfatiza o uso da operação get_conport_schema do ConPort para descobrir dinamicamente os nomes exatos das ferramentas ConPort e seus parâmetros, orientando o LLM sobre quando e por que realizar interações conceituais (como registrar uma decisão ou atualizar o contexto do produto) em vez de codificar detalhes específicos de invocação de ferramentas.
  
  

Como Usar Esses Arquivos de Estratégia:

1. Identifique o arquivo de estratégia relevante para o ambiente do seu agente LLM.
2. Copie o conteúdo inteiro desse arquivo.
3. Cole-o nas instruções personalizadas do seu LLM ou na área de prompt do sistema. O método varia conforme a plataforma LLM (configurações de extensão do IDE, interface web, configuração de API).

Essas instruções equipam o LLM com o conhecimento para:

• Inicializar e carregar contexto do ConPort.
• Atualizar o ConPort com novas informações (decisões, progresso, etc.).
• Gerenciar dados personalizados e relacionamentos.
• Entender a importância de workspace_id. Dica Importante para Iniciar Sessões: Para garantir que o agente LLM inicialize e carregue o contexto corretamente, especialmente em interfaces que podem nem sempre aderir estritamente às instruções personalizadas na primeira mensagem, é uma boa prática iniciar sua interação com uma diretiva clara como: Initialize according to custom instructions. Isso pode ajudar a solicitar que o agente execute sua sequência de inicialização do ConPort conforme definido em seu arquivo de estratégia.

Novo Conjunto de Estratégias: mem4sprint (O que há de novo)

O repositório inclui um novo conjunto de estratégias/documentação focado em planejamento de sprint e fluxos operacionais:

• conport-custom-instructions/mem4sprint.md — orientação concisa e padrões para usar categorias planas e prefixos FTS válidos.
• conport-custom-instructions/mem4sprint.schema_and_templates.md — meta esquema, iniciadores compactos, regras de consulta FTS e receitas mínimas de chamadas operacionais.

Destaques principais:

• Modelo de categoria plana (por exemplo, artifacts, rfc_doc, retrospective, ProjectGlossary, critical_settings).
• Apenas prefixos FTS5 válidos: category:, key:, value_text: para dados personalizados; summary:, rationale:, implementation_details:, tags: para decisões.
• Normalização de consultas na camada de handler; a camada de banco de dados permanece inalterada.

Resumo das notas de versão:

• Adicionada estratégia/documentação mem4sprint com categorias achatadas e regras FTS explícitas.
• Exemplos simplificados e receitas mínimas de chamadas operacionais incluídas.
• A documentação esclarece o tratamento do caminho do workspace do IDE para MCP.

Uso Inicial do ConPort em um Workspace

Quando você começa a usar o ConPort pela primeira vez em um workspace de projeto novo ou existente, o banco de dados ConPort (context_portal/context.db) será criado automaticamente pelo servidor se não existir. Para ajudar a inicializar o contexto inicial do projeto, especialmente o Contexto do Produto, considere o seguinte:

Usando um Arquivo projectBrief.md (Recomendado)

1. Crie projectBrief.md: No diretório raiz do workspace do seu projeto, crie um arquivo chamado projectBrief.md.
2. Adicione Conteúdo: Preencha este arquivo com uma visão geral de alto nível do seu projeto. Isso pode incluir:
   • O objetivo principal ou propósito do projeto.
   • Principais recursos ou componentes.
   • Público-alvo ou usuários.
   • Estilo arquitetural geral ou tecnologias-chave (se conhecidas).
   • Qualquer outra informação fundamental que defina o projeto.
3. Solicitação Automática de Importação: Quando um agente LLM usando um dos conjuntos de instruções personalizadas do ConPort fornecidos (por exemplo, roo_code_conport_strategy) inicializar no workspace, ele é projetado para:
   • Verificar a existência de projectBrief.md.
   • Se encontrado, ele lerá o arquivo e perguntará se você gostaria de importar seu conteúdo para o Contexto do Produto do ConPort.
   • Se você concordar, o conteúdo será adicionado ao ConPort, fornecendo uma linha de base imediata para o Contexto do Produto do projeto.

Inicialização Manual

Se projectBrief.md não for encontrado, ou se você optar por não importá-lo:

• O agente LLM (guiado por suas instruções personalizadas) normalmente informará que o Contexto do Produto do ConPort parece não inicializado.
• Ele pode se oferecer para ajudar você a definir o Contexto do Produto manualmente, possivelmente listando outros arquivos no seu workspace para reunir informações relevantes.

Ao fornecer contexto inicial, seja por meio de projectBrief.md ou entrada manual, você permite que o ConPort e o agente LLM conectado tenham uma compreensão fundamental melhor do seu projeto desde o início.

Detecção Automática de Workspace

O ConPort pode determinar automaticamente o workspace_id correto para que você não precise codificar um caminho absoluto na configuração do seu cliente MCP. Isso é especialmente útil para IDEs que não conseguem expandir ${workspaceFolder} ao iniciar servidores MCP.

A detecção está habilitada por padrão e pode ser controlada via flags de CLI:

Flags:

• --auto-detect-workspace (padrão: habilitado) Ativa a detecção automática.
• --no-auto-detect Desativa a detecção (um --workspace_id explícito ou workspace_id por ferramenta deve então ser fornecido).
• --workspace-search-start <path> Diretório inicial opcional para busca ascendente (padrão: diretório de trabalho atual).

Como funciona (multi-estratégia):

1. Indicadores Fortes (caminho rápido): Procura por raízes de projeto de alta confiança contendo qualquer um de: package.json, .git, pyproject.toml, Cargo.toml, go.mod, pom.xml.
2. Múltiplos Indicadores Gerais: Se ≥2 indicadores gerais (README, licença, arquivos de build, etc.) existirem em um diretório, ele é tratado como uma raiz.
3. Workspace ConPort Existente: A presença de um diretório context_portal/ indica um workspace válido.
4. Contexto de Ambiente MCP: Respeita variáveis de ambiente como VSCODE_WORKSPACE_FOLDER ou CONPORT_WORKSPACE quando definidas e válidas.
5. Fallback: Se nenhum indicador for encontrado, usa o diretório inicial de forma verbosa (com um aviso).

Ferramentas:

• get_workspace_detection_info (ferramenta MCP) expõe um dicionário de diagnóstico mostrando:
  • start_path
  • detected_workspace
  • detection_method (strong_indicators | multiple_indicators | existing_context_portal | fallback)
  • indicators_found
  • variáveis de ambiente relevantes

Melhores Práticas:

• Mantenha a detecção habilitada, a menos que você opere em cenários multi-raiz onde isolamento explícito por chamada seja necessário.
• Se uma IDE passar a string literal ${workspaceFolder}, o ConPort a ignorará e fará a detecção automática com segurança (registrado em WARNING).
• Para depurar raízes ambíguas (ex.: repositórios aninhados), execute a ferramenta de informações de detecção para confirmar qual diretório foi selecionado.

Exemplo de inicialização MCP (confiando totalmente na detecção automática):

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--log-level", "INFO"
      ]
    }
  }
}

Para desativar a detecção explicitamente (forçando apenas IDs fornecidos):

{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": [
        "--from", "context-portal-mcp",
        "conport-mcp",
        "--mode", "stdio",
        "--no-auto-detect",
        "--workspace_id", "/absolute/path/to/project"
      ]
    }
  }
}

Se você tiver um inicializador que começa dentro de um subdiretório profundo, forneça um caminho inicial mais alto:

conport-mcp --mode stdio --workspace-search-start ../../

Consulte UNIVERSAL_WORKSPACE_DETECTION.md para obter a justificativa completa, casos extremos e solução de problemas.

Ferramentas ConPort Disponíveis

O servidor ConPort expõe as seguintes ferramentas via MCP, permitindo interação com o grafo de conhecimento do projeto subjacente. Isso inclui ferramentas para busca semântica alimentada por armazenamento de dados vetoriais. Essas ferramentas facilitam o aspecto de Recuperação crucial para a Geração Aumentada (RAG) por agentes de IA. Todas as ferramentas exigem um argumento workspace_id (string, obrigatório) para especificar o workspace do projeto alvo.

Nota: Por conveniência, todos os parâmetros semelhantes a inteiros aceitam números ou strings apenas com dígitos (ex.: "10", " 3"). O servidor remove espaços em branco e converte esses valores para inteiros, preservando os limites de validação (ex.: ge=1). Crédito: @cipradu.

• Gerenciamento de Contexto do Produto:
  • get_product_context: Recupera os objetivos gerais, recursos e arquitetura do projeto.
  • update_product_context: Atualiza o contexto do produto. Aceita content completo (objeto) ou patch_content (objeto) para atualizações parciais (use __DELETE__ como valor no patch para remover uma chave).
• Gerenciamento de Contexto Ativo:
  • get_active_context: Recupera o foco de trabalho atual, mudanças recentes e problemas em aberto.
  • update_active_context: Atualiza o contexto ativo. Aceita content completo (objeto) ou patch_content (objeto) para atualizações parciais (use __DELETE__ como valor no patch para remover uma chave).
• Registro de Decisões:
  • log_decision: Registra uma decisão arquitetural ou de implementação.
    • Args: summary (str, obrigatório), rationale (str, opcional), implementation_details (str, opcional), tags (list[str], opcional).
  • get_decisions: Recupera decisões registradas.
    • Args: limit (int, opcional), tags_filter_include_all (list[str], opcional), tags_filter_include_any (list[str], opcional).
  • search_decisions_fts: Busca de texto completo nos campos de decisão (resumo, justificativa, detalhes, tags).
    • Args: query_term (str, obrigatório), limit (int, opcional).
  • delete_decision_by_id: Exclui uma decisão pelo seu ID.
    • Args: decision_id (int, obrigatório).
• Acompanhamento de Progresso:
  • log_progress: Registra uma entrada de progresso ou status de tarefa.
    • Args: status (str, obrigatório), description (str, obrigatório), parent_id (int, opcional), linked_item_type (str, opcional), linked_item_id (str, opcional).
  • get_progress: Recupera entradas de progresso.
    • Args: status_filter (str, opcional), parent_id_filter (int, opcional), limit (int, opcional).
  • update_progress: Atualiza uma entrada de progresso existente.
    • Args: progress_id (int, obrigatório), status (str, opcional), description (str, opcional), parent_id (int, opcional).
  • delete_progress_by_id: Exclui uma entrada de progresso pelo seu ID.
    • Args: progress_id (int, obrigatório).
• Gerenciamento de Padrões de Sistema:
  • log_system_pattern: Registra ou atualiza um padrão de sistema/codificação.
    • Args: name (str, obrigatório), description (str, opcional), tags (list[str], opcional).
  • get_system_patterns: Recupera padrões de sistema.
    • Args: tags_filter_include_all (list[str], opcional), tags_filter_include_any (list[str], opcional).
  • delete_system_pattern_by_id: Exclui um padrão de sistema pelo seu ID.
    • Args: pattern_id (int, obrigatório).
• Gerenciamento de Dados Personalizados:
  • log_custom_data: Armazena/atualiza uma entrada personalizada de chave-valor sob uma categoria. O valor é serializável em JSON.
    • Args: category (str, obrigatório), key (str, obrigatório), value (any, obrigatório).
  • get_custom_data: Recupera dados personalizados.
    • Args: category (str, opcional), key (str, opcional).
  • delete_custom_data: Exclui uma entrada específica de dados personalizados.
    • Args: category (str, obrigatório), key (str, obrigatório).
  • search_project_glossary_fts: Busca de texto completo na categoria de dados personalizados 'ProjectGlossary'.
    • Args: query_term (str, obrigatório), limit (int, opcional).
  • search_custom_data_value_fts: Busca de texto completo em todos os valores, categorias e chaves de dados personalizados.
    • Args: query_term (str, obrigatório), category_filter (str, opcional), limit (int, opcional).
• Vinculação de Contexto:
  • link_conport_items: Cria um link de relacionamento entre dois itens do ConPort, construindo explicitamente o grafo de conhecimento do projeto.
    • Args: source_item_type (str, obrigatório), source_item_id (str, obrigatório), target_item_type (str, obrigatório), target_item_id (str, obrigatório), relationship_type (str, obrigatório), description (str, opcional).
  • get_linked_items: Recupera itens vinculados a um item específico.
    • Args: item_type (str, obrigatório), item_id (str, obrigatório), relationship_type_filter (str, opcional), linked_item_type_filter (str, opcional), limit (int, opcional).
• Ferramentas de Histórico e Meta:
  • get_item_history: Recupera o histórico de versões do Contexto do Produto ou do Contexto Ativo.
    • Args: item_type ("product_context" | "active_context", obrigatório), version (int, opcional), before_timestamp (datetime, opcional), after_timestamp (datetime, opcional), limit (int, opcional).
  • get_recent_activity_summary: Fornece um resumo da atividade recente do ConPort.
    • Args: hours_ago (int, opcional), since_timestamp (datetime, opcional), limit_per_type (int, opcional, padrão: 5).
  • get_conport_schema: Recupera o esquema das ferramentas ConPort disponíveis e seus argumentos.
• Importação/Exportação:
  • export_conport_to_markdown: Exporta dados do ConPort para arquivos markdown.
    • Args: output_path (str, opcional, padrão: "./conport_export/").
  • import_markdown_to_conport: Importa dados de arquivos markdown para o ConPort.
    • Args: input_path (str, opcional, padrão: "./conport_export/").
• Operações em Lote:
  • batch_log_items: Registra vários itens do mesmo tipo (ex.: decisões, entradas de progresso) em uma única chamada.
    • Args: item_type (str, obrigatório - ex.: "decision", "progress_entry"), items (list[dict], obrigatório - lista de dicionários de modelos Pydantic para o tipo de item).

Leitura Adicional

Para uma compreensão mais aprofundada do design, arquitetura e padrões de uso avançado do ConPort, consulte:

• conport_mcp_deep_dive.md

Contribuindo

Consulte nosso guia CONTRIBUTING.md para detalhes sobre como contribuir com o projeto ConPort.

Licença

Este projeto é licenciado sob a licença Apache-2.0.

Agradecimentos

• Agradecimento especial a @cipradu pela valiosa sugestão de implementar a conversão de strings inteiras para argumentos numéricos, o que melhora a experiência do usuário ao interagir com o servidor MCP a partir de vários clientes.

Guia de Migração e Atualização de Banco de Dados

Para instruções detalhadas sobre como gerenciar seu arquivo context.db, especialmente ao atualizar o ConPort entre versões que incluem mudanças no esquema do banco de dados, consulte o dedicado v0.2.4_UPDATE_GUIDE.md. Este guia fornece etapas para migração manual de dados (exportação/importação), se necessário, e dicas de solução de problemas.