Prompt MCP Server for Amazon Q

Un servidor MCP para la CLI de Amazon Q Developer que gestiona archivos de prompt locales.

Documentación

Prompt MCP Server para Amazon Q

Un servidor de Protocolo de Contexto de Modelo (MCP) de un solo archivo para Amazon Q Developer CLI que gestiona archivos de prompts (*.md) desde directorios locales.

Características

🔄 Monitoreo de Archivos en Tiempo Real: Detecta automáticamente cambios en archivos y actualiza la lista de prompts
📢 Notificaciones MCP: Envía notificaciones a Amazon Q CLI para actualización automática
📁 Descubrimiento de Prompts: Lista todos los archivos *.md desde directorios configurados
🏠 Directorio Predeterminado: ~/.aws/amazonq/prompts (creado automáticamente)
🎯 Directorios Personalizados: Anula con la variable de entorno PROMPTS_PATH (formato tipo PATH)
🔧 Sustitución de Variables: Soporta marcadores de posición {variable} en prompts
🔍 Registro Configurable: Valores predeterminados seguros para producción con modo de depuración completo
🌐 Multiplataforma: Funciona en Unix/Linux/macOS (compatible con Windows)
⚡ Manejo de Errores: Manejo integral de errores y registro
📦 Sin Dependencias: Implementación pura en Python 3.8+

Instalación y Uso

Inicio Rápido con uvx (Recomendado)

# Install and run directly (after publishing to PyPI)
uvx prompt-mcp-server

# Or install from local build
pyproject-build
uvx --from ./dist/prompt_mcp_server-2.0.3-py3-none-any.whl prompt-mcp-server

Uso Directo

# Run the server directly
python3 mcp_server/prompt_mcp_server.py

# With custom prompt directories
PROMPTS_PATH="./my-prompts:~/.aws/amazonq/prompts" python3 mcp_server/prompt_mcp_server.py

Integración con Amazon Q

# The workspace is configured to use uvx with the built package
q mcp list                    # Verify configuration (should show: prompt-server uvx)
q chat                        # Start Amazon Q CLI
/prompts                      # List available prompts
@debug_code                   # Use a prompt

Archivos de configuración:

.amazonq/mcp.json - Usa ruta de desarrollo local
tests/.amazonq/mcp.json - Usa paquete local compilado
tests/.amazonq/mcp-published.json - Para paquete publicado (copiar a mcp.json después de publicar)

Compilación y Pruebas

# Build package
pyproject-build

# Test with uvx
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize"}' | uvx --from ./dist/prompt_mcp_server-2.0.0-py3-none-any.whl prompt-mcp-server

Configuración

Variables de Entorno

PROMPTS_PATH: Lista de directorios separados por dos puntos (Unix) o punto y coma (Windows)
Predeterminado: ~/.aws/amazonq/prompts

Configuración del Espacio de Trabajo

El archivo .amazonq/mcp.json configura Amazon Q para usar este servidor:

Configuración de Desarrollo (Local)

{
  "mcpServers": {
    "prompt-server": {
      "command": "python3",
      "args": ["mcp_server/prompt_mcp_server.py"],
      "timeout": 10000
    }
  }
}

Configuración de Producción (PyPI)

{
  "mcpServers": {
    "prompt-server": {
      "command": "uvx",
      "args": ["prompt-mcp-server@latest"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Variables de Entorno

PROMPTS_PATH

Propósito: Especificar directorios personalizados para buscar archivos de prompts
Formato: Lista de directorios separados por dos puntos (Unix/Linux/macOS) o punto y coma (Windows)
Predeterminado: ~/.aws/amazonq/prompts

Ejemplo:

export PROMPTS_PATH="/path/to/prompts1:/path/to/prompts2"

MCP_LOG_LEVEL

Propósito: Establecer el nivel de registro para el servidor MCP
Valores: DEBUG, INFO, WARNING, ERROR, CRITICAL
Predeterminado: WARNING (nivel de producción - solo advertencias y errores)
Ejemplo:
```
export MCP_LOG_LEVEL=INFO
```

MCP_DEBUG_LOGGING

Propósito: Habilitar registro de depuración integral con seguimiento detallado de solicitudes/respuestas
Valores: 1, true, yes, on (sin distinción de mayúsculas/minúsculas)
Predeterminado: Deshabilitado
Cuando está habilitado:
- Fuerza el nivel de registro INFO independientemente de MCP_LOG_LEVEL
- Crea archivo de registro de depuración para monitoreo fácil
- Registra todas las solicitudes y respuestas MCP con detalles JSON completos
- Registra actividad de monitoreo de archivos y operaciones de caché
- Mensajes de registro con códigos de color y emojis para identificación fácil

Ejemplo:

export MCP_DEBUG_LOGGING=1
# Then monitor logs with:
tail -f /tmp/mcp_server_debug.log

MCP_LOG_FILE

Propósito: Establecer ruta personalizada para el archivo de registro de depuración
Predeterminado: /tmp/mcp_server_debug.log
Solo se usa cuando: MCP_DEBUG_LOGGING está habilitado

Ejemplo:

export MCP_DEBUG_LOGGING=1
export MCP_LOG_FILE=/path/to/custom/mcp_debug.log
# Then monitor logs with:
tail -f /path/to/custom/mcp_debug.log

Uso del Registro de Depuración

Para habilitar el registro de depuración para solución de problemas:

# Enable debug logging with default log file
export MCP_DEBUG_LOGGING=1

# Or enable with custom log file location
export MCP_DEBUG_LOGGING=1
export MCP_LOG_FILE=/path/to/custom/debug.log

# Start Amazon Q CLI
q chat

# In another terminal, monitor detailed logs
tail -f /tmp/mcp_server_debug.log
# Or if using custom log file:
tail -f /path/to/custom/debug.log

# Test file changes
echo "# Test" > ~/.aws/amazonq/prompts/test.md
rm ~/.aws/amazonq/prompts/test.md

Los registros de depuración mostrarán:

📥 Solicitudes sin procesar recibidas de Amazon Q CLI
🔵 Solicitudes entrantes analizadas con detalles
🟢 Respuestas salientes con contenido completo
📤 Respuestas sin procesar enviadas a Amazon Q CLI
📢 Notificaciones MCP enviadas (por ejemplo, lista de prompts cambiada)
Actividad de monitoreo de archivos y operaciones de caché

Pruebas

El proyecto incluye pruebas unitarias y funcionales integrales:

Ejecutar Todas las Pruebas

# Run both unit and functional tests
python3 tests/run_all_tests.py

# Run only unit tests
python3 tests/run_all_tests.py --unit-only

# Run only functional tests
python3 tests/run_all_tests.py --functional-only

Suites de Pruebas Individuales

# Unit tests (31 tests)
python3 tests/test_prompt_mcp_server.py

# Functional tests (14 tests)
python3 tests/test_functional.py

# UVX integration tests (8 tests)
python3 tests/test_uvx_integration.py

Resultados de Pruebas

Estado Actual: ✅ Las 53 pruebas pasan (tasa de éxito del 100%)
Resultados Detallados: Ver directorio tests/results/ para informes completos
Rendimiento: La suite de pruebas completa se ejecuta en ~10.5 segundos

Cobertura de Pruebas

Pruebas Unitarias: 31 pruebas que cubren todos los componentes del servidor
Pruebas Funcionales: 14 pruebas de integración de extremo a extremo
Integración UVX: 8 pruebas para escenarios de ejecución de paquetes
Cobertura Total: 53 pruebas integrales

Creación de Prompts

Prompt Simple

Crear ~/.aws/amazonq/prompts/debug_code.md:

# Debug Code Issues
Help me debug code by identifying issues and suggesting fixes.

Prompt Parametrizado

Crear ~/.aws/amazonq/prompts/create_function.md:

# Create {language} Function
Create a {language} function named {function_name} that {description}.

Requirements:
- Follow {language} best practices
- Include error handling
- Add comprehensive tests

Ejemplos de Uso

Listar Prompts Disponibles

echo '{"jsonrpc": "2.0", "id": 1, "method": "prompts/list"}' | python3 mcp_server/prompt_mcp_server.py

Obtener un Prompt con Variables

echo '{"jsonrpc": "2.0", "id": 2, "method": "prompts/get", "params": {"name": "create_function", "arguments": {"language": "Python", "function_name": "calculate", "description": "adds two numbers"}}}' | python3 mcp_server/prompt_mcp_server.py

Requisitos

Python 3.6+
Sin dependencias externas
Soporte multiplataforma

Manejo de Errores

El servidor incluye manejo integral de errores:

Validación de permisos de archivos
Límites de tamaño de archivos (máximo 1MB)
Soporte de codificación Unicode (UTF-8 con respaldo latin-1)
Validación de acceso a directorios
Respaldo elegante a directorios predeterminados
Registro detallado en stderr

Pruebas

Todas las características principales han sido probadas:

✅ Cumplimiento del protocolo MCP (initialize, prompts/list, prompts/get)
✅ Descubrimiento de prompts y extracción de variables
✅ Soporte de variable de entorno PROMPTS_PATH
✅ Manejo de rutas multiplataforma
✅ Manejo de errores y casos límite
✅ Integración con Amazon Q CLI

Estructura del Proyecto

mcp-prompts-local/
├── mcp_server/                    # Main package
│   ├── __init__.py               # Package initialization
│   └── prompt_mcp_server.py      # MCP server implementation
├── tools/                        # Development tools
│   ├── publish.py                # Automated publishing script
│   └── README.md                 # Tools documentation
├── tests/                        # Test suite
│   ├── test_prompt_mcp_server.py # Unit tests (31 tests)
│   ├── test_functional.py        # Functional tests (14 tests)
│   ├── test_uvx_integration.py   # UVX integration tests (8 tests)
│   ├── results/                  # Test execution results
│   │   ├── FULL_TEST_RESULTS.md  # Initial test results
│   │   ├── FINAL_TEST_RESULTS.md # Final test results (100% success)
│   │   └── README.md             # Test results documentation
│   └── .amazonq/                 # Test configurations
├── .amazonq/                     # Workspace configuration
│   └── mcp.json                  # Development MCP config
├── dist/                         # Built packages
├── pyproject.toml                # Package configuration
├── README.md                     # This file
└── LICENSE                       # MIT license

Arquitectura

Esta es una implementación de un solo archivo que:

Lee solicitudes JSON-RPC desde stdin
Escanea directorios configurados para archivos *.md
Extrae variables usando regex (patrón {variable})
Sustituye variables en el contenido del prompt
Devuelve respuestas a través de stdout
Registra en stderr

Historial de Versiones

Para información detallada de versiones, notas de lanzamiento y registro de cambios, ver CHANGELOG.md.

Para más información sobre el Protocolo de Contexto de Modelo, ver la especificación MCP.