Prompt MCP Server for Amazon Q

Um servidor MCP para o Amazon Q Developer CLI gerenciar arquivos de prompt locais.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Prompt MCP Server for Amazon Q

Um servidor de Protocolo de Contexto de Modelo (MCP) de arquivo único para o Amazon Q Developer CLI que gerencia arquivos de prompt (*.md) de diretórios locais.

Recursos

  • 🔄 Monitoramento de Arquivos em Tempo Real: Detecta automaticamente alterações em arquivos e atualiza a lista de prompts
  • 📢 Notificações MCP: Envia notificações ao Amazon Q CLI para atualização automática
  • 📁 Descoberta de Prompts: Lista todos os arquivos *.md de diretórios configurados
  • 🏠 Diretório Padrão: ~/.aws/amazonq/prompts (criado automaticamente)
  • 🎯 Diretórios Personalizados: Substitua com a variável de ambiente PROMPTS_PATH (formato semelhante a PATH)
  • 🔧 Substituição de Variáveis: Suporta espaços reservados {variable} em prompts
  • 🔍 Registro Configurável: Padrões seguros para produção com modo de depuração abrangente
  • 🌐 Multiplataforma: Funciona em Unix/Linux/macOS (compatível com Windows)
  • ⚡ Tratamento de Erros: Tratamento abrangente de erros e registro
  • 📦 Sem Dependências: Implementação pura em Python 3.8+

Instalação e Uso

Início Rápido com 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 Direto

# 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

Integração com 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

Arquivos de configuração:

  • .amazonq/mcp.json - Usa caminho de desenvolvimento local
  • tests/.amazonq/mcp.json - Usa pacote local compilado
  • tests/.amazonq/mcp-published.json - Para pacote publicado (copie para mcp.json após a publicação)

Compilação e Testes

# 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

Configuração

Variáveis de Ambiente

  • PROMPTS_PATH: Lista de diretórios separados por dois-pontos (Unix) ou ponto-e-vírgula (Windows)
  • Padrão: ~/.aws/amazonq/prompts

Configuração do Workspace

O arquivo .amazonq/mcp.json configura o Amazon Q para usar este servidor:

Configuração de Desenvolvimento (Local)

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

Configuração de Produção (PyPI)

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

Variáveis de Ambiente

PROMPTS_PATH

  • Finalidade: Especificar diretórios personalizados para buscar arquivos de prompt
  • Formato: Lista de diretórios separados por dois-pontos (Unix/Linux/macOS) ou ponto-e-vírgula (Windows)
  • Padrão: ~/.aws/amazonq/prompts
  • Exemplo: 
    export PROMPTS_PATH="/path/to/prompts1:/path/to/prompts2"

MCP_LOG_LEVEL

  • Finalidade: Definir o nível de registro para o servidor MCP
  • Valores: DEBUG, INFO, WARNING, ERROR, CRITICAL
  • Padrão: WARNING (nível de produção - apenas avisos e erros)
  • Exemplo: 
    export MCP_LOG_LEVEL=INFO

MCP_DEBUG_LOGGING

  • Finalidade: Ativar registro de depuração abrangente com rastreamento detalhado de solicitações/respostas
  • Valores: 1, true, yes, on (sem diferenciar maiúsculas de minúsculas)
  • Padrão: Desativado
  • Quando ativado:
    • Força o nível de registro INFO independentemente de MCP_LOG_LEVEL
    • Cria arquivo de registro de depuração para monitoramento fácil
    • Registra todas as solicitações e respostas MCP com detalhes completos em JSON
    • Registra atividade de monitoramento de arquivos e operações de cache
    • Mensagens de registro codificadas por cores com emojis para fácil identificação
  • Exemplo: 
    export MCP_DEBUG_LOGGING=1
# Then monitor logs with:
tail -f /tmp/mcp_server_debug.log

MCP_LOG_FILE

  • Finalidade: Definir caminho personalizado para o arquivo de registro de depuração
  • Padrão: /tmp/mcp_server_debug.log
  • Usado apenas quando: MCP_DEBUG_LOGGING está ativado
  • Exemplo: 
    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 do Registro de Depuração

Para ativar o registro de depuração para solução 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

Os registros de depuração mostrarão:

  • 📥 Solicitações brutas recebidas do Amazon Q CLI
  • 🔵 Solicitações recebidas analisadas com detalhes
  • 🟢 Respostas enviadas com conteúdo completo
  • 📤 Respostas brutas enviadas ao Amazon Q CLI
  • 📢 Notificações MCP enviadas (por exemplo, lista de prompts alterada)
  • Atividade de monitoramento de arquivos e operações de cache

Testes

O projeto inclui testes unitários e funcionais abrangentes:

Executar Todos os Testes

# 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

Suítes de Testes Individuais

# 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 dos Testes

  • Status Atual: ✅ Todos os 53 testes passando (taxa de sucesso de 100%)
  • Resultados Detalhados: Consulte o diretório tests/results/ para relatórios abrangentes
  • Desempenho: Suíte de testes completa é executada em ~10,5 segundos

Cobertura de Testes

  • Testes Unitários: 31 testes cobrindo todos os componentes do servidor
  • Testes Funcionais: 14 testes de integração ponta a ponta
  • Integração UVX: 8 testes para cenários de execução de pacotes
  • Cobertura Total: 53 testes abrangentes

Criando Prompts

Prompt Simples

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

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

Prompt com Parâmetros

Crie ~/.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

Exemplos de Uso

Listar Prompts Disponíveis

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

Obter um Prompt com Variáveis

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+
  • Sem dependências externas
  • Suporte multiplataforma

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

  • Validação de permissões de arquivo
  • Limites de tamanho de arquivo (máximo de 1MB)
  • Suporte a codificação Unicode (UTF-8 com fallback para latin-1)
  • Validação de acesso a diretórios
  • Fallback gracioso para diretórios padrão
  • Registro detalhado em stderr

Testes

Todos os recursos principais foram testados:

  • ✅ Conformidade com o protocolo MCP (initialize, prompts/list, prompts/get)
  • ✅ Descoberta de prompts e extração de variáveis
  • ✅ Suporte à variável de ambiente PROMPTS_PATH
  • ✅ Tratamento de caminhos multiplataforma
  • ✅ Tratamento de erros e casos extremos
  • ✅ Integração com Amazon Q CLI

Estrutura do Projeto

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

Arquitetura

Esta é uma implementação de arquivo único que:

  1. Lê solicitações JSON-RPC de stdin
  2. Verifica diretórios configurados em busca de arquivos *.md
  3. Extrai variáveis usando regex (padrão {variable})
  4. Substitui variáveis no conteúdo do prompt
  5. Retorna respostas via stdout
  6. Registra em stderr

Histórico de Versões

Para informações detalhadas de versão, notas de lançamento e changelog, consulte CHANGELOG.md.

Para mais informações sobre o Protocolo de Contexto de Modelo, consulte a especificação MCP.