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.