Prompt MCP Server for Amazon Q

An MCP server for the Amazon Q Developer CLI to manage local prompt files.

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

- 🔄 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.mdfiles from configured directories
- 🏠 Default Directory:~/.aws/amazonq/prompts(created automatically)
- 🎯 Custom Directories: Override withPROMPTS_PATHenvironment 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

# 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

# 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

# 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

- .amazonq/mcp.json- Uses local development path
- tests/.amazonq/mcp.json- Uses local built package
- tests/.amazonq/mcp-published.json- For published package (copy tomcp.jsonafter publishing)

# 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

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

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

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

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

- 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"

- 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

- Purpose: Enable comprehensive debug logging with detailed request/response tracing
- Values:1,true,yes,on(case-insensitive)
- Default: Disabled
- When enabled:

- ForcesINFOlevel logging regardless ofMCP_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

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

- Purpose: Set custom path for the debug log file
- Default:/tmp/mcp_server_debug.log
- Only used when:MCP_DEBUG_LOGGINGis 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

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

- 📥 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

The project includes comprehensive unit and functional 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

# 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

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

- 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

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

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

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

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

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

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

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

- ✅ 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

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

This is a single-file implementation that:
- Reads JSON-RPC requests from stdin
- Scans configured directories for*.mdfiles
- Extracts variables using regex ({variable}pattern)
- Substitutes variables in prompt content
- Returns responses via stdout
- Logs to stderr

For detailed version information, release notes, and changelog, seeCHANGELOG.md.

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

Make your AI agent speak every language on the planet, using Lingo.dev Localization Engine.