Context Portal MCP (ConPort)

¿Qué es el servidor Context Portal MCP (ConPort)?

Context Portal (ConPort) es el banco de memoria de tu proyecto. Es una herramienta que ayuda a los asistentes de IA a comprender mejor tu proyecto de software específico almacenando información importante como decisiones, tareas y patrones arquitectónicos de manera estructurada. Piénsalo como la construcción de una base de conocimiento específica del proyecto a la que la IA puede acceder fácilmente y usar para brindarte respuestas más precisas y útiles.

Qué hace:

• Realiza un seguimiento de las decisiones del proyecto, el progreso y los diseños de sistemas.
• Almacena datos personalizados del proyecto (como glosarios o especificaciones).
• Ayuda a la IA a encontrar información relevante del proyecto rápidamente (como una búsqueda inteligente).
• Permite que la IA use el contexto del proyecto para mejores respuestas (RAG).
• Más eficiente para gestionar, buscar y actualizar contexto en comparación con los bancos de memoria basados en archivos de texto simples.

ConPort proporciona una forma robusta y estructurada para que los asistentes de IA almacenen, recuperen y gestionen varios tipos de contexto de proyecto. Efectivamente construye un grafo de conocimiento específico del proyecto, capturando entidades como decisiones, progreso y arquitectura, junto con sus relaciones. Esta base de conocimiento estructurada, mejorada con incrustaciones vectoriales para búsqueda semántica, sirve como un potente backend para Generación Aumentada por Recuperación (RAG), permitiendo a los asistentes de IA acceder a información precisa y actualizada para respuestas más conscientes del contexto y precisas.

Reemplaza los sistemas de gestión de contexto basados en archivos más antiguos al ofrecer un backend de base de datos más confiable y consultable (SQLite por espacio de trabajo). ConPort está diseñado para ser un backend de contexto genérico, compatible con varios IDEs e interfaces de cliente que soporten MCP.

Las características clave incluyen:

• Almacenamiento de contexto estructurado usando SQLite (una base de datos por espacio de trabajo, creada automáticamente).
• Servidor MCP (context_portal_mcp) construido con Python/FastAPI.
• Un conjunto completo de herramientas MCP definidas para la interacción (ver "Herramientas ConPort disponibles" a continuación).
• Soporte multi-espacio de trabajo mediante workspace_id.
• Modo de despliegue principal: STDIO para una integración estrecha con el IDE.
• Permite construir un grafo de conocimiento de proyecto dinámico con relaciones explícitas entre elementos de contexto.
• Incluye almacenamiento de datos vectoriales y capacidades de búsqueda semántica para potenciar RAG avanzado.
• Sirve como backend ideal para Generación Aumentada por Recuperación (RAG), proporcionando a la IA una memoria de proyecto precisa y consultable.
• Proporciona contexto estructurado que los asistentes de IA pueden aprovechar para caché de prompts con proveedores de LLM compatibles.
• Gestiona la evolución del esquema de la base de datos usando migraciones de Alembic, asegurando actualizaciones sin problemas e integridad de datos.

Requisitos previos

Antes de comenzar, asegúrate de tener instalado lo siguiente:

• Python: Se recomienda la versión 3.8 o superior.
  • Descargar Python
  • Asegúrate de que Python esté agregado al PATH de tu sistema durante la instalación (especialmente en Windows).
• uv: (Muy recomendado) Un gestor de entornos y paquetes de Python rápido. Usar uv simplifica significativamente la creación de entornos virtuales y la instalación de dependencias.
  • Instalar uv

Instalación y Configuración (Recomendado)

La forma recomendada de instalar y ejecutar ConPort es usando uvx para ejecutar el paquete directamente desde PyPI. Este método evita la necesidad de crear y gestionar entornos virtuales manualmente.

Configuración de uvx (Recomendado para la mayoría de los IDE)

En la configuración de tu cliente MCP (por ejemplo, mcp_settings.json), usa la siguiente configuración:

{
  "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 maneja el entorno por ti.
• args: Contiene los argumentos para ejecutar el servidor ConPort.
• ${workspaceFolder}: Esta variable del IDE se usa para proporcionar automáticamente la ruta absoluta del espacio de trabajo del proyecto actual.
• --log-file: Opcional: Ruta a un archivo donde se escribirán los registros del servidor. Si no se proporciona, los registros se dirigen a stderr (consola). Útil para registro persistente y depuración del comportamiento del servidor.
• --log-level: Opcional: Establece el nivel mínimo de registro para el servidor. Las opciones válidas son DEBUG, INFO, WARNING, ERROR, CRITICAL. El valor predeterminado es INFO. Establece DEBUG para salida detallada durante el desarrollo o la resolución de problemas.

Importante: Muchos IDE no expanden ${workspaceFolder} al lanzar servidores MCP. Usa una de estas opciones seguras:

1. Proporciona una ruta absoluta para --workspace_id.
2. Omite --workspace_id al inicio y confía en workspace_id por llamada (recomendado si tu cliente lo proporciona en cada llamada).

Configuración alternativa (sin --workspace_id al inicio):

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

Si omites --workspace_id, el servidor omitirá la pre-inicialización e inicializará la base de datos en la primera llamada a una herramienta usando el workspace_id proporcionado en esa llamada.

Instalación para Desarrolladores (desde el Repositorio Git)

La forma más adecuada de desarrollar y probar ConPort es ejecutarlo en tu IDE como servidor MCP usando la configuración anterior. Esto ejercita el modo STDIO y el comportamiento real del cliente.

Si necesitas ejecutar contra un checkout local y virtualenv, puedes configurar tu cliente MCP para lanzar el servidor de desarrollo mediante uv run y tu .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:

• Establece --directory a la ruta de tu repositorio; esto usa tu checkout local y el intérprete de venv.
• Los registros van a ./logs/conport-dev.log con verbosidad DEBUG.

Configuración del entorno local

Configuración para desarrollo o contribución a través del repositorio Git.

1. Clona el repositorio

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

2. Crea un entorno virtual

   uv venv
   

   Actívalo usando la activación estándar de tu shell (por ejemplo, source .venv/bin/activate en macOS/Linux).

3. Instala las dependencias

   uv pip install -r requirements.txt
   

4. Ejecuta en tu IDE (recomendado) Configura los ajustes MCP de tu IDE usando la "Configuración uvx" o la configuración de desarrollo uv run mostrada arriba. Esta es la prueba más representativa de ConPort en modo STDIO.

5. Opcional: ayuda de CLI

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

Notas:

• Para el comportamiento de --workspace_id y el manejo de rutas del IDE, consulta la guía en la sección "Configuración uvx" anterior. Muchos IDE no expanden ${workspaceFolder}.

Para la limpieza previa a la actualización, incluida la limpieza de la caché de bytecode de Python, consulta v0.2.4_UPDATE_GUIDE.md.

Uso con Agentes LLM (Instrucciones Personalizadas)

La efectividad de ConPort con agentes LLM se mejora significativamente al proporcionar instrucciones personalizadas específicas o prompts de sistema al LLM. Este repositorio incluye archivos de estrategia adaptados para diferentes entornos:

• Para Roo Code:

  • roo_code_conport_strategy: Contiene instrucciones detalladas para LLMs que operan dentro de la extensión Roo Code de VS Code, guiándolos sobre cómo usar las herramientas de ConPort para la gestión de contexto.
  
  

• Para CLine:

  • cline_conport_strategy: Contiene instrucciones detalladas para LLMs que operan dentro de la extensión Cline de VS Code, guiándolos sobre cómo usar las herramientas de ConPort para la gestión de contexto.
  
  

• Para Windsurf Cascade:

  • cascade_conport_strategy: Guía específica para LLMs integrados con el entorno Windsurf Cascade. Importante: Al iniciar una sesión en Cascade, es necesario decirle explícitamente al LLM:

  Initialize according to custom instructions
  

• Para uso general/independiente de la plataforma:

  • generic_conport_strategy: Proporciona un conjunto de instrucciones independiente de la plataforma para cualquier LLM compatible con MCP. Enfatiza el uso de la operación get_conport_schema de ConPort para descubrir dinámicamente los nombres exactos de las herramientas de ConPort y sus parámetros, guiando al LLM sobre cuándo y por qué realizar interacciones conceptuales (como registrar una decisión o actualizar el contexto del producto) en lugar de codificar detalles específicos de invocación de herramientas.
  
  

Cómo usar estos archivos de estrategia:

1. Identifica el archivo de estrategia relevante para el entorno de tu agente LLM.
2. Copia el contenido completo de ese archivo.
3. Pégalo en el área de instrucciones personalizadas o prompt de sistema de tu LLM. El método varía según la plataforma LLM (configuración de extensiones del IDE, interfaz web, configuración de API).

Estas instrucciones equipan al LLM con el conocimiento para:

• Inicializar y cargar contexto desde ConPort.
• Actualizar ConPort con nueva información (decisiones, progreso, etc.).
• Gestionar datos personalizados y relaciones.
• Comprender la importancia de workspace_id. Consejo importante para iniciar sesiones: Para asegurar que el agente LLM inicialice y cargue el contexto correctamente, especialmente en interfaces que no siempre se adhieren estrictamente a las instrucciones personalizadas en el primer mensaje, es una buena práctica comenzar tu interacción con una directiva clara como: Initialize according to custom instructions. Esto puede ayudar a incitar al agente a realizar su secuencia de inicialización de ConPort según lo definido en su archivo de estrategia.

Nuevo conjunto de estrategias: mem4sprint (Novedades)

El repositorio incluye un nuevo conjunto de estrategias/documentación centrado en la planificación de sprints y flujos operativos:

• conport-custom-instructions/mem4sprint.md — guía concisa y patrones para usar categorías planas y prefijos FTS válidos.
• conport-custom-instructions/mem4sprint.schema_and_templates.md — meta esquema, iniciadores compactos, reglas de consulta FTS y recetas de llamadas operativas mínimas.

Aspectos destacados:

• Modelo de categorías planas (por ejemplo, artifacts, rfc_doc, retrospective, ProjectGlossary, critical_settings).
• Solo prefijos FTS5 válidos: category:, key:, value_text: para datos personalizados; summary:, rationale:, implementation_details:, tags: para decisiones.
• Normalización de consultas en la capa de manejadores; la capa de base de datos permanece sin cambios.

Resumen de notas de versión:

• Se añadió la estrategia/documentación mem4sprint con categorías aplanadas y reglas FTS explícitas.
• Se simplificaron ejemplos e incluyeron recetas de llamadas operativas mínimas.
• La documentación aclara el manejo de rutas de espacio de trabajo del IDE para MCP.

Uso inicial de ConPort en un espacio de trabajo

Cuando comiences a usar ConPort por primera vez en un espacio de trabajo de proyecto nuevo o existente, la base de datos de ConPort (context_portal/context.db) será creada automáticamente por el servidor si no existe. Para ayudar a arrancar el contexto inicial del proyecto, especialmente el Contexto del Producto, considera lo siguiente:

Uso de un archivo projectBrief.md (Recomendado)

1. Crea projectBrief.md: En el directorio raíz de tu espacio de trabajo de proyecto, crea un archivo llamado projectBrief.md.
2. Añade contenido: Llena este archivo con una visión general de alto nivel de tu proyecto. Esto podría incluir:
   • El objetivo o propósito principal del proyecto.
   • Características o componentes clave.
   • Audiencia objetivo o usuarios.
   • Estilo arquitectónico general o tecnologías clave (si se conocen).
   • Cualquier otra información fundamental que defina el proyecto.
3. Solicitud automática de importación: Cuando un agente LLM que usa uno de los conjuntos de instrucciones personalizadas de ConPort proporcionados (por ejemplo, roo_code_conport_strategy) se inicializa en el espacio de trabajo, está diseñado para:
   • Verificar la existencia de projectBrief.md.
   • Si se encuentra, leerá el archivo y te preguntará si deseas importar su contenido al Contexto del Producto de ConPort.
   • Si aceptas, el contenido se agregará a ConPort, proporcionando una línea base inmediata para el Contexto del Producto del proyecto.

Inicialización manual

Si no se encuentra projectBrief.md, o si eliges no importarlo:

• El agente LLM (guiado por sus instrucciones personalizadas) normalmente le informará que el Contexto de Producto de ConPort parece no estar inicializado.
• Puede ofrecerle ayuda para definir el Contexto de Producto manualmente, posiblemente enumerando otros archivos en su espacio de trabajo para recopilar información relevante.

Al proporcionar contexto inicial, ya sea mediante projectBrief.md o entrada manual, permite que ConPort y el agente LLM conectado tengan una mejor comprensión fundamental de su proyecto desde el principio.

Detección Automática del Espacio de Trabajo

ConPort puede determinar automáticamente el workspace_id correcto para que no necesite codificar una ruta absoluta en la configuración de su cliente MCP. Esto es especialmente útil para IDEs que no logran expandir ${workspaceFolder} al iniciar servidores MCP.

La detección está habilitada por defecto y se puede controlar mediante banderas de CLI:

Banderas:

• --auto-detect-workspace (predeterminado: habilitado) Activa la detección automática.
• --no-auto-detect Desactiva la detección (entonces se debe proporcionar --workspace_id explícito o workspace_id por herramienta).
• --workspace-search-start <path> Directorio inicial opcional para la búsqueda ascendente (por defecto, el directorio de trabajo actual).

Cómo funciona (multi‑estrategia):

1. Indicadores Fuertes (ruta rápida): Busca raíces de proyecto de alta confianza que contengan cualquiera de: package.json, .git, pyproject.toml, Cargo.toml, go.mod, pom.xml.
2. Múltiples Indicadores Generales: Si existen ≥2 indicadores generales (README, licencia, archivos de compilación, etc.) en un directorio, se trata como una raíz.
3. Espacio de Trabajo ConPort Existente: La presencia de un directorio context_portal/ indica un espacio de trabajo válido.
4. Contexto del Entorno MCP: Respeta variables de entorno como VSCODE_WORKSPACE_FOLDER o CONPORT_WORKSPACE cuando están configuradas y son válidas.
5. Respaldo: Si no se encuentran indicadores, utiliza el directorio inicial de forma verbosa (con una advertencia).

Herramientas:

• get_workspace_detection_info (herramienta MCP) expone un diccionario de diagnóstico que muestra:
  • start_path
  • detected_workspace
  • detection_method (strong_indicators | multiple_indicators | existing_context_portal | fallback)
  • indicators_found
  • variables de entorno relevantes

Mejores Prácticas:

• Mantenga la detección habilitada a menos que opere en escenarios de múltiples raíces donde se requiera aislamiento explícito por llamada.
• Si un IDE pasa la cadena literal ${workspaceFolder}, ConPort la ignorará y realizará la detección automática de forma segura (registrado en WARNING).
• Para depurar raíces ambiguas (p. ej., repositorios anidados), ejecute la herramienta de información de detección para confirmar qué directorio fue seleccionado.

Ejemplo de lanzamiento MCP (confiando completamente en la detección automática):

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

Para desactivar la detección explícitamente (forzando solo los IDs proporcionados):

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

Si tiene un lanzador que se inicia dentro de un subdirectorio profundo, proporcione una ruta de inicio más alta:

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

Consulte UNIVERSAL_WORKSPACE_DETECTION.md para conocer la justificación completa, los casos límite y la resolución de problemas.

Herramientas Disponibles de ConPort

El servidor ConPort expone las siguientes herramientas a través de MCP, permitiendo la interacción con el grafo de conocimiento del proyecto subyacente. Esto incluye herramientas para búsqueda semántica impulsada por almacenamiento de datos vectoriales. Estas herramientas facilitan el aspecto de Recuperación crucial para la Generación Aumentada (RAG) por parte de agentes de IA. Todas las herramientas requieren un argumento workspace_id (cadena, obligatorio) para especificar el espacio de trabajo del proyecto de destino.

Nota: Por conveniencia, todos los parámetros similares a enteros aceptan números o cadenas de solo dígitos (p. ej., "10", " 3"). El servidor recorta los espacios en blanco y los convierte a enteros mientras preserva los límites de validación (p. ej., ge=1). Crédito: @cipradu.

• Gestión del Contexto de Producto:
  • get_product_context: Recupera los objetivos generales, las características y la arquitectura del proyecto.
  • update_product_context: Actualiza el contexto de producto. Acepta content completo (objeto) o patch_content (objeto) para actualizaciones parciales (use __DELETE__ como valor en el parche para eliminar una clave).
• Gestión del Contexto Activo:
  • get_active_context: Recupera el enfoque de trabajo actual, los cambios recientes y los problemas abiertos.
  • update_active_context: Actualiza el contexto activo. Acepta content completo (objeto) o patch_content (objeto) para actualizaciones parciales (use __DELETE__ como valor en el parche para eliminar una clave).
• Registro de Decisiones:
  • log_decision: Registra una decisión arquitectónica o de implementación.
    • Args: summary (str, req), rationale (str, opt), implementation_details (str, opt), tags (list[str], opt).
  • get_decisions: Recupera las decisiones registradas.
    • Args: limit (int, opt), tags_filter_include_all (list[str], opt), tags_filter_include_any (list[str], opt).
  • search_decisions_fts: Búsqueda de texto completo en los campos de decisión (resumen, justificación, detalles, etiquetas).
    • Args: query_term (str, req), limit (int, opt).
  • delete_decision_by_id: Elimina una decisión por su ID.
    • Args: decision_id (int, req).
• Seguimiento de Progreso:
  • log_progress: Registra una entrada de progreso o estado de tarea.
    • Args: status (str, req), description (str, req), parent_id (int, opt), linked_item_type (str, opt), linked_item_id (str, opt).
  • get_progress: Recupera las entradas de progreso.
    • Args: status_filter (str, opt), parent_id_filter (int, opt), limit (int, opt).
  • update_progress: Actualiza una entrada de progreso existente.
    • Args: progress_id (int, req), status (str, opt), description (str, opt), parent_id (int, opt).
  • delete_progress_by_id: Elimina una entrada de progreso por su ID.
    • Args: progress_id (int, req).
• Gestión de Patrones del Sistema:
  • log_system_pattern: Registra o actualiza un patrón de sistema/codificación.
    • Args: name (str, req), description (str, opt), tags (list[str], opt).
  • get_system_patterns: Recupera los patrones del sistema.
    • Args: tags_filter_include_all (list[str], opt), tags_filter_include_any (list[str], opt).
  • delete_system_pattern_by_id: Elimina un patrón del sistema por su ID.
    • Args: pattern_id (int, req).
• Gestión de Datos Personalizados:
  • log_custom_data: Almacena/actualiza una entrada personalizada de clave-valor bajo una categoría. El valor es serializable en JSON.
    • Args: category (str, req), key (str, req), value (any, req).
  • get_custom_data: Recupera datos personalizados.
    • Args: category (str, opt), key (str, opt).
  • delete_custom_data: Elimina una entrada específica de datos personalizados.
    • Args: category (str, req), key (str, req).
  • search_project_glossary_fts: Búsqueda de texto completo dentro de la categoría de datos personalizados 'ProjectGlossary'.
    • Args: query_term (str, req), limit (int, opt).
  • search_custom_data_value_fts: Búsqueda de texto completo en todos los valores, categorías y claves de datos personalizados.
    • Args: query_term (str, req), category_filter (str, opt), limit (int, opt).
• Vinculación de Contexto:
  • link_conport_items: Crea un enlace de relación entre dos elementos de ConPort, construyendo explícitamente el grafo de conocimiento del proyecto.
    • Args: source_item_type (str, req), source_item_id (str, req), target_item_type (str, req), target_item_id (str, req), relationship_type (str, req), description (str, opt).
  • get_linked_items: Recupera los elementos vinculados a un elemento específico.
    • Args: item_type (str, req), item_id (str, req), relationship_type_filter (str, opt), linked_item_type_filter (str, opt), limit (int, opt).
• Herramientas de Historial y Meta:
  • get_item_history: Recupera el historial de versiones del Contexto de Producto o Activo.
    • Args: item_type ("product_context" | "active_context", req), version (int, opt), before_timestamp (datetime, opt), after_timestamp (datetime, opt), limit (int, opt).
  • get_recent_activity_summary: Proporciona un resumen de la actividad reciente de ConPort.
    • Args: hours_ago (int, opt), since_timestamp (datetime, opt), limit_per_type (int, opt, default: 5).
  • get_conport_schema: Recupera el esquema de las herramientas ConPort disponibles y sus argumentos.
• Importación/Exportación:
  • export_conport_to_markdown: Exporta los datos de ConPort a archivos markdown.
    • Args: output_path (str, opt, default: "./conport_export/").
  • import_markdown_to_conport: Importa datos de archivos markdown a ConPort.
    • Args: input_path (str, opt, default: "./conport_export/").
• Operaciones por Lote:
  • batch_log_items: Registra múltiples elementos del mismo tipo (p. ej., decisiones, entradas de progreso) en una sola llamada.
    • Args: item_type (str, req - p. ej., "decision", "progress_entry"), items (list[dict], req - lista de dicts del modelo Pydantic para el tipo de elemento).

Lectura Adicional

Para una comprensión más profunda del diseño, la arquitectura y los patrones de uso avanzado de ConPort, consulte:

• conport_mcp_deep_dive.md

Contribuciones

Consulte nuestra guía CONTRIBUTING.md para obtener detalles sobre cómo contribuir al proyecto ConPort.

Licencia

Este proyecto está licenciado bajo la licencia Apache-2.0.

Agradecimientos

• Un agradecimiento especial a @cipradu por la valiosa sugerencia de implementar la coerción de cadenas a enteros para argumentos numéricos, lo que mejora la experiencia del usuario al interactuar con el servidor MCP desde varios clientes.

Guía de Migración y Actualización de Base de Datos

Para obtener instrucciones detalladas sobre cómo gestionar su archivo context.db, especialmente al actualizar ConPort entre versiones que incluyen cambios en el esquema de la base de datos, consulte la guía dedicada v0.2.4_UPDATE_GUIDE.md. Esta guía proporciona pasos para la migración manual de datos (exportación/importación) si es necesario, y consejos para la resolución de problemas.