Asesor Superior MCP (Aurai Advisor)

Un servicio MCP que permite a la IA local seguir consultando a modelos de lenguaje grandes (LLM) remotos cuando se enfrenta a problemas de programación complejos.

El repositorio actual corresponde a la versión "lista para uso a largo plazo", que ya ha completado estas capacidades clave:

• Consultas de múltiples turnos e informes de progreso

• Sincronización de archivos sync_context

• Carga automática de código/archivos de configuración convertidos a texto

• Aislamiento de sesiones (session_id)

• Persistencia del historial, bloqueo de archivos y escritura atómica

• Resumen automático del historial

• Recorte de la ventana de contexto

Novedades de esta actualización

Esta actualización principal se centra en:

• Corrección del problema donde el historial "resucitaba" tras ser borrado y reiniciado

• Adición de aislamiento de sesiones mediante session_id para evitar que el contexto se mezcle entre diferentes problemas

• Integración de configuraciones reales y funcionales como AURAI_TEMPERATURE, AURAI_MAX_ITERATIONS y AURAI_LOG_LEVEL

• Envío real de project_info y respuestas complementarias al asesor superior

• Adición de bloqueo de archivos de historial y escritura atómica para reducir el riesgo de corrupción del historial por concurrencia

• Adición de resumen automático del historial para evitar que las sesiones largas se vuelvan demasiado pesadas

• Adición de recorte de ventana de contexto; AURAI_CONTEXT_WINDOW ahora tiene efecto real

• sync_context ahora admite la conversión automática de archivos de texto (código/configuración) a formato enviable, sin necesidad de copiar manualmente a .txt

• Reescritura del README, la guía de instalación y el manual de usuario, colocando los pasos de instalación en una posición más destacada

Si es la primera vez que visitas este repositorio, los dos puntos más importantes son:

1. Lee primero la "Guía de instalación" a continuación

2. Los archivos de código ahora se pueden pasar directamente a sync_context

Casos de uso

Este MCP es adecuado para su uso en Claude Code o cualquier otro cliente MCP que admita el modo stdio.

Escenarios típicos:

• La IA local ya lo ha intentado, pero el problema sigue sin resolverse

• Necesidad de enviar errores, código, documentación y configuraciones al "asesor superior"

• Deseo de convertir una investigación compleja en un proceso de múltiples turnos: "Preguntar -> Ejecutar -> Informar -> Siguiente paso"

Resumen de funciones

• consult_aurai Herramienta de consulta principal. Envía problemas, fragmentos de código, contexto y soluciones intentadas para obtener el análisis y las sugerencias del asesor superior.

• sync_context Sincroniza el contexto de código y documentación. Ahora no solo admite .txt/.md, sino que convierte automáticamente archivos de texto como .py/.js/.ts/.json/.yaml/.toml/.ini en contenido de texto adecuado para el envío.

• report_progress Informa de los resultados de la ejecución al asesor superior para continuar con la siguiente iteración.

• get_status Consulta el estado de la sesión actual, el número de registros históricos y las rutas de los archivos de modelo e historial.

Guía de instalación

Para pasos de instalación más detallados, consulta:

• Guía de instalación de Claude Code

• Manual de usuario

A continuación, se presenta el flujo de instalación más común.

1. Preparar el entorno

# 需要 Python 3.10+
python --version

# 进入仓库目录
cd G:\codex\mcp-aurai-server

2. Crear entorno virtual e instalar dependencias

python -m venv venv
venv\Scripts\activate
pip install -e ".[all-dev]"

3. Registrar el MCP en Claude Code

claude mcp add --scope user --transport stdio aurai-advisor ^
  --env AURAI_API_KEY="your-api-key" ^
  --env AURAI_BASE_URL="https://api.example.com/v1" ^
  --env AURAI_MODEL="gpt-4o" ^
  -- "G:\codex\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

Nota:

• AURAI_BASE_URL debe ser una dirección de interfaz compatible con OpenAI

• La versión actual solo conserva el método custom, ya no se utiliza el antiguo AURAI_PROVIDER

• --scope user indica que estará disponible en todos los proyectos, lo cual es más conveniente

4. Verificar la instalación

claude mcp list
pytest

Resultado esperado:

• claude mcp list muestra aurai-advisor

• pytest pasa correctamente

Uso rápido

Escenario 1: Consultar un problema directamente

consult_aurai(
    problem_type="runtime_error",
    error_message="启动时报 KeyError: api_key",
    code_snippet="config = load_config()\napi_key = config['api_key']",
    context={
        "file_path": "src/config.py",
        "terminal_output": "Traceback ...",
    }
)

Escenario 2: Subir archivos de código primero y luego consultar

sync_context(
    operation="incremental",
    files=["src/main.py", "config/settings.json", "README.md"],
    project_info={
        "project_name": "My Project",
        "tech_stack": "Python + FastAPI"
    }
)

consult_aurai(
    problem_type="runtime_error",
    error_message="请结合已同步文件帮我排查启动失败"
)

Nota:

• Ya no es necesario copiar manualmente main.py a main.txt

• Los archivos de código de texto se convertirán automáticamente a texto para su envío

• Los archivos binarios serán omitidos

Escenario 3: Múltiples problemas en paralelo, usando aislamiento de sesión

consult_aurai(
    problem_type="runtime_error",
    error_message="问题 A",
    session_id="issue-a"
)

consult_aurai(
    problem_type="design_issue",
    error_message="问题 B",
    session_id="issue-b"
)

Esto evita que diferentes problemas se mezclen entre sí.

Reglas de carga de archivos para sync_context

Se enviarán directamente

• .md, .markdown, .mdx

• .txt

• Varios archivos de texto de código y configuración, por ejemplo:

  • .py .js .ts .tsx

  • .json .yaml .yml .toml

  • .ini .cfg .env

  • .java .go .rs .cpp .cs

Se convertirán automáticamente

• Archivos que no son .txt/.md pero cuyo contenido es texto

• Se generará automáticamente un nombre de envío .txt o .md

• Se incluirá la "ruta del archivo original" y el "nombre de envío convertido automáticamente" antes del contenido

Se omitirán

• Imágenes

• Archivos comprimidos

• Audio y video

• Archivos ejecutables

• Contenido claramente binario

Si un lote de archivos contiene tanto código como imágenes:

• El código se subirá normalmente

• Las imágenes se registrarán en skipped_files

• La sincronización completa seguirá siendo exitosa

Variables de entorno

Obligatorias

Opciones comunes

Comportamiento clave de la versión actual

1. Aislamiento de sesiones

• Cada session_id tiene su propio historial

• Si no se pasa ninguno, se utiliza default

• Las diferentes sesiones se guardan en archivos de historial distintos para evitar mezclas

2. Resumen del historial

• El historial antiguo se comprime automáticamente en un "resumen del historial"

• Se intenta conservar intactas las últimas rondas y el último sync_context

• Esto reduce el uso de contexto, dejando espacio para el problema actual

3. Recorte de la ventana de contexto

• Se prioriza la conservación de las instrucciones del sistema

• Se prioriza la conservación del último sync_context

• Se intenta conservar las rondas de historial más recientes

• Si es necesario, se reduce automáticamente la longitud de la salida actual para evitar exceder la ventana total

4. Archivos de historial más estables

• Se utilizan archivos de bloqueo al guardar el historial para evitar corrupciones por concurrencia

• La escritura se realiza mediante archivos temporales que luego se reemplazan, evitando archivos JSON incompletos

Pruebas

pytest

Los puntos clave cubiertos por la rama principal actual incluyen:

• Borrado y persistencia del historial

• Aislamiento de sesiones

• Carga automática con conversión de texto

• Bloqueo de historial y escritura atómica

• Resumen del historial

• Recorte de la ventana de contexto

Documentación

• Guía de instalación de Claude Code

• Manual de usuario

• Documentación de desarrollo

Preguntas frecuentes

¿Por qué el asesor superior no recibió el archivo de código que subí?

Las versiones antiguas requerían convertir manualmente a .txt. La versión actual ya admite la conversión automática de archivos de texto.

Si aún no lo recibe, verifica primero:

• Si la ruta del archivo existe

• Si el archivo es binario

• Los campos uploaded_files / skipped_files en la respuesta de sync_context

¿Por qué diferentes problemas se afectan entre sí?

Si deseas un aislamiento total, pasa un session_id diferente para cada problema.

¿Por qué el archivo de historial parece haberse acortado?

Es el resumen del historial trabajando. El historial antiguo se comprime en un acta; no se ha perdido, simplemente se ha convertido en un "acta de reunión" que ahorra más contexto.