Prompt MCP Server for Amazon Q

A single-file Model Context Protocol (MCP) server for Amazon Q Developer CLI that manages prompt files (*.md) from local directories.

Features

• 🔄 Real-time File Monitoring: Automatically detects file changes and updates prompt list
• 📢 MCP Notifications: Sends notifications to Amazon Q CLI for automatic refresh
• 📁 Prompt Discovery: Lists all *.md files from configured directories
• 🏠 Default Directory: ~/.aws/amazonq/prompts (created automatically)
• 🎯 Custom Directories: Override with PROMPTS_PATH environment variable (PATH-like format)
• 🔧 Variable Substitution: Supports {variable} placeholders in prompts
• 🔍 Configurable Logging: Production-safe defaults with comprehensive debug mode
• 🌐 Cross-Platform: Works on Unix/Linux/macOS (Windows compatible)
• ⚡ Error Handling: Comprehensive error handling and logging
• 📦 No Dependencies: Pure Python 3.8+ implementation

Installation & Usage

Quick Start with uvx (Recommended)

# 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

Direct Usage

# 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

Amazon Q Integration

# 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

Configuration files:

• .amazonq/mcp.json - Uses local development path
• tests/.amazonq/mcp.json - Uses local built package
• tests/.amazonq/mcp-published.json - For published package (copy to mcp.json after publishing)

Building and Testing

# 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

Configuration

Environment Variables

• PROMPTS_PATH: Colon-separated list of directories (Unix) or semicolon-separated (Windows)
• Default: ~/.aws/amazonq/prompts

Workspace Configuration

The .amazonq/mcp.json file configures Amazon Q to use this server:

Development Configuration (Local)

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

Production Configuration (PyPI)

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

Environment Variables

PROMPTS_PATH

• Purpose: Specify custom directories to search for prompt files
• Format: Colon-separated list of directories (Unix/Linux/macOS) or semicolon-separated (Windows)
• Default: ~/.aws/amazonq/prompts
• Example:

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

MCP_LOG_LEVEL

• Purpose: Set the logging level for the MCP server
• Values: DEBUG, INFO, WARNING, ERROR, CRITICAL
• Default: WARNING (production level - only warnings and errors)
• Example:

  export MCP_LOG_LEVEL=INFO
  

MCP_DEBUG_LOGGING

• Purpose: Enable comprehensive debug logging with detailed request/response tracing
• Values: 1, true, yes, on (case-insensitive)
• Default: Disabled
• When enabled:
  • Forces INFO level logging regardless of MCP_LOG_LEVEL
  • Creates debug log file for easy monitoring
  • Logs all MCP requests and responses with full JSON details
  • Logs file monitoring activity and cache operations
  • Color-coded log messages with emojis for easy identification
• Example:

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

MCP_LOG_FILE

• Purpose: Set custom path for the debug log file
• Default: /tmp/mcp_server_debug.log
• Only used when: MCP_DEBUG_LOGGING is enabled
• Example:

  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
  

Debug Logging Usage

To enable debug logging for troubleshooting:

# 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

The debug logs will show:

• 📥 Raw requests received from Amazon Q CLI
• 🔵 Parsed incoming requests with details
• 🟢 Outgoing responses with full content
• 📤 Raw responses sent to Amazon Q CLI
• 📢 MCP notifications sent (e.g., prompts list changed)
• File monitoring activity and cache operations

Testing

The project includes comprehensive unit and functional tests:

Run All Tests

# 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

Individual Test Suites

# 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

Test Results

• Current Status: ✅ All 53 tests passing (100% success rate)
• Detailed Results: See tests/results/ directory for comprehensive reports
• Performance: Complete test suite runs in ~10.5 seconds

Test Coverage

• Unit Tests: 31 tests covering all server components
• Functional Tests: 14 end-to-end integration tests
• UVX Integration: 8 tests for package execution scenarios
• Total Coverage: 53 comprehensive tests

Creating Prompts

Simple Prompt

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

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

Parameterized Prompt

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

Usage Examples

List Available Prompts

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

Get a Prompt with 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

Requirements

• Python 3.6+
• No external dependencies
• Cross-platform support

Error Handling

The server includes comprehensive error handling:

• File permission validation
• File size limits (1MB max)
• Unicode encoding support (UTF-8 with latin-1 fallback)
• Directory access validation
• Graceful fallback to default directories
• Detailed logging to stderr

Testing

All core features have been tested:

• ✅ MCP protocol compliance (initialize, prompts/list, prompts/get)
• ✅ Prompt discovery and variable extraction
• ✅ PROMPTS_PATH environment variable support
• ✅ Cross-platform path handling
• ✅ Error handling and edge cases
• ✅ Amazon Q CLI integration

Project Structure

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

Architecture

This is a single-file implementation that:

1. Reads JSON-RPC requests from stdin
2. Scans configured directories for *.md files
3. Extracts variables using regex ({variable} pattern)
4. Substitutes variables in prompt content
5. Returns responses via stdout
6. Logs to stderr

Version History

For detailed version information, release notes, and changelog, see CHANGELOG.md.

---

For more information about the Model Context Protocol, see the MCP specification.