mcp-postgresql-ops 3.3.1__tar.gz → 3.3.3__tar.gz

mcp_postgresql_ops-3.3.3/.env.example

@@ -0,0 +1,44 @@
+# Commons
+PYTHONPATH=/app/src
+
+# MCP Server Configuration
+# Transport 설정 : streamable-http 모드
+FASTMCP_TYPE=streamable-http
+FASTMCP_HOST=0.0.0.0
+FASTMCP_PORT=8000
+
+# 로깅 레벨 설정
+MCP_LOG_LEVEL=INFO
+
+# =============================================================================
+# Remote Authentication Settings (for streamable-http mode)
+# =============================================================================
+# Enable Bearer token authentication for streamable-http transport
+# Default: false (if not defined or empty, defaults to false)
+# Values: true/false, 1/0, yes/no, on/off (case insensitive)
+# WARNING: If REMOTE_AUTH_ENABLE=false, the server will accept requests without authentication!
+REMOTE_AUTH_ENABLE=false
+# Secret key for Bearer token authentication (required when REMOTE_AUTH_ENABLE=true)
+# Default: empty string (if not defined, authentication will be disabled even if REMOTE_AUTH_ENABLE=true)
+# Recommendation: Use strong, randomly generated secret keys (32+ characters)
+REMOTE_SECRET_KEY=my-test-secret-key-12345
+
+### PostgreSQL Configuration
+PGSQL_VERSION=16
+PGDATA=/data/db ### Don't change...
+POSTGRES_MAX_CONNECTIONS=200
+
+#### PostgreSQL Host Configuration:
+#--------------------------------------------
+POSTGRES_HOST=host.docker.internal
+POSTGRES_PORT=15432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=changeme!@34
+POSTGRES_DB=ecommerce
+#--------------------------------------------
+
+# Docker Env.
+DOCKER_EXTERNAL_PORT_OPENWEBUI=3003
+DOCKER_EXTERNAL_PORT_MCP_SERVER=18003
+DOCKER_EXTERNAL_PORT_MCPO_PROXY=8003
+DOCKER_INTERNAL_PORT_POSTGRESQL=5432

mcp_postgresql_ops-3.3.3/.github/CONTRIBUTING.md

@@ -0,0 +1,275 @@
+# Contributing to MCP PostgreSQL Operations
+
+🎉 Thank you for your interest in contributing to MCP PostgreSQL Operations! Whether you're fixing a bug, adding a new monitoring tool, or improving documentation, your contributions make this project better for everyone.
+
+## Getting Started
+
+### Prerequisites
+
+- PostgreSQL 12+ (for testing)
+- Python 3.12
+- UV package manager
+- Git
+
+### Development Setup
+
+1. **Fork and clone the repository:**
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/MCP-PostgreSQL-Ops.git
+   cd MCP-PostgreSQL-Ops
+   ```
+
+2. **Set up the development environment:**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your PostgreSQL connection details
+   ```
+
+3. **Start the test environment:**
+   ```bash
+   docker-compose up -d
+   ```
+
+4. **Test the setup:**
+   ```bash
+   ./scripts/run-mcp-inspector-local.sh
+   ```
+
+## Ways to Contribute
+
+### � Using Issue Templates
+
+When you click "New Issue" on GitHub, you'll see a template selection page with these options:
+- **🐛 Bug Report** - Report bugs with detailed PostgreSQL environment information
+- **💡 Feature Request** - Suggest new monitoring tools or improvements with PostgreSQL-specific requirements
+- **📚 Documentation** - Report documentation issues or suggest improvements
+- **❓ Question** - Ask general questions about setup, usage, or PostgreSQL compatibility
+
+You'll also find quick links to:
+- **🔒 Security Issues** - Report security vulnerabilities privately
+- **💬 GitHub Discussions** - Community discussions and advanced usage strategies
+- **📖 Documentation** - README with setup guides and examples
+- **🧪 MCP Inspector** - Local testing and debugging information
+- **🗂️ Tool Compatibility Matrix** - PostgreSQL version compatibility reference
+
+> **💡 Tip**: For security vulnerabilities related to database access or potential SQL injection, always use the Security Advisories feature instead of public issues.
+
+### �🐛 Bug Reports
+
+**Use the [Bug Report template](https://github.com/call518/MCP-PostgreSQL-Ops/issues/new?template=bug_report.md)** to report issues.
+
+The template will guide you to include:
+- PostgreSQL version and environment details
+- Steps to reproduce the issue
+- Expected vs actual behavior
+- Error messages or logs
+- MCP server configuration used
+
+### 💡 Feature Requests
+
+**Use the [Feature Request template](https://github.com/call518/MCP-PostgreSQL-Ops/issues/new?template=feature_request.md)** to suggest improvements.
+
+We welcome suggestions for:
+- New PostgreSQL monitoring tools
+- Additional database analysis features
+- Performance improvements
+- Documentation enhancements
+
+The template will help you provide:
+- The use case or problem you're trying to solve
+- Your proposed solution
+- PostgreSQL-specific requirements
+- Expected output format and usage examples
+
+### 🔧 Code Contributions
+
+#### Adding New MCP Tools
+
+The codebase is designed to be developer-friendly. To add a new monitoring tool:
+
+1. **Add your function to `src/mcp_postgresql_ops/mcp_main.py`:**
+   ```python
+   @mcp.tool()
+   def get_your_new_tool(
+       parameter1: str = "default_value",
+       parameter2: int = 10
+   ) -> list[dict]:
+       """
+       Brief description of what this tool does.
+       
+       Args:
+           parameter1: Description of parameter1
+           parameter2: Description of parameter2
+           
+       Returns:
+           List of dictionaries with monitoring data
+       """
+       # Your implementation here
+       pass
+   ```
+
+2. **Follow these patterns:**
+   - Use descriptive function names starting with `get_`
+   - Include comprehensive docstrings
+   - Handle PostgreSQL version compatibility
+   - Return structured data (list of dictionaries)
+   - Use read-only queries only
+
+3. **Test across PostgreSQL versions:**
+   - Test with PostgreSQL 12, 15, 16, 17 if possible
+   - Ensure graceful degradation for version-specific features
+   - Update the Tool Compatibility Matrix in README
+
+#### Code Style Guidelines
+
+- **Python**: Follow PEP 8 standards
+- **SQL**: Use uppercase for SQL keywords, lowercase for identifiers
+- **Comments**: Explain complex logic and PostgreSQL-specific behavior
+- **Error handling**: Provide meaningful error messages
+- **Version compatibility**: Always consider PostgreSQL version differences
+
+#### Testing Your Changes
+
+1. **Manual testing:**
+   ```bash
+   # Test with local development
+   python -m src.mcp_postgresql_ops.mcp_main --log-level DEBUG
+   
+   # Test with MCP Inspector
+   ./scripts/run-mcp-inspector-local.sh
+   ```
+
+2. **Version compatibility testing:**
+   - Test against different PostgreSQL versions
+   - Verify tool behavior with and without extensions
+   - Check error handling for unsupported features
+
+### 📚 Documentation
+
+**Use the [Documentation Issue template](https://github.com/call518/MCP-PostgreSQL-Ops/issues/new?template=documentation.md)** to report documentation problems.
+
+Help improve our documentation by:
+- Fixing typos or unclear explanations
+- Adding usage examples
+- Improving tool descriptions
+- Updating compatibility information
+
+## PostgreSQL-Specific Guidelines
+
+### Version Compatibility
+
+- **Support PostgreSQL 12-17**
+- Use version detection: `get_postgresql_version()`
+- Handle version-specific features gracefully
+- Update compatibility matrix when adding features
+
+### Query Guidelines
+
+- **Read-only operations only** - no data modification
+- Use system catalogs and statistics views
+- Handle missing extensions gracefully
+- Optimize for performance on production systems
+- Mask sensitive information in outputs
+
+### Extension Handling
+
+- Most tools should work without extensions
+- For `pg_stat_statements` dependent features, check availability first
+- Provide fallback behavior when extensions are missing
+- Document extension requirements clearly
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes:**
+   - Follow the coding guidelines
+   - Add or update tests if applicable
+   - Update documentation as needed
+
+3. **Test thoroughly:**
+   - Test with multiple PostgreSQL versions
+   - Verify backward compatibility
+   - Check error handling
+
+4. **Commit with clear messages:**
+   ```bash
+   git commit -m "Add tool for monitoring connection pooling
+   
+   - New get_connection_pool_stats function
+   - Compatible with PostgreSQL 12-17
+   - Handles missing pg_stat_statements gracefully"
+   ```
+
+5. **Push and create PR:**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+   Then create a Pull Request using our [PR template](https://github.com/call518/MCP-PostgreSQL-Ops/compare) which will guide you through the submission process.
+
+### Pull Request Guidelines
+
+Our **Pull Request template** will help you provide:
+- **Clear title and description**
+- **PostgreSQL compatibility information**
+- **Testing details and environment info**
+- **Documentation updates checklist**
+- **Security considerations**
+
+The template ensures all necessary information is included for efficient review.
+
+## Community Guidelines
+
+### Code of Conduct
+
+- Be respectful and inclusive
+- Welcome newcomers and questions
+- Focus on constructive feedback
+- Help others learn PostgreSQL monitoring concepts
+
+### Getting Help
+
+- **🐛 [Bug Reports](https://github.com/call518/MCP-PostgreSQL-Ops/issues/new?template=bug_report.md)**: For bugs and technical issues
+- **💡 [Feature Requests](https://github.com/call518/MCP-PostgreSQL-Ops/issues/new?template=feature_request.md)**: For new features and enhancements  
+- **📚 [Documentation Issues](https://github.com/call518/MCP-PostgreSQL-Ops/issues/new?template=documentation.md)**: For documentation problems
+- **❓ [Questions](https://github.com/call518/MCP-PostgreSQL-Ops/issues/new?template=question.md)**: For general questions and support
+- **💬 [Discussions](https://github.com/call518/MCP-PostgreSQL-Ops/discussions)**: For broader discussions and community interaction
+
+## Recognition
+
+Contributors are recognized in:
+- Project documentation
+- Release notes
+- Special thanks for significant contributions
+
+## PostgreSQL Expertise Levels
+
+Don't worry if you're not a PostgreSQL expert! Contributions are welcome at all levels:
+- **Beginners**: Documentation, testing, simple bug fixes
+- **Intermediate**: New monitoring tools, compatibility improvements
+- **Advanced**: Complex performance analysis features, version-specific optimizations
+
+## Development Tips
+
+### Understanding the Codebase
+
+- **`mcp_main.py`**: Main MCP server implementation
+- **`functions.py`**: Database utility functions
+- **`version_compat.py`**: PostgreSQL version compatibility helpers
+- **`scripts/`**: Development and testing utilities
+
+### PostgreSQL Testing Resources
+
+- Use the included test data (`scripts/create-test-data.sql`)
+- Test with different user permissions (superuser vs regular user)
+- Verify behavior on RDS/Aurora environments when possible
+
+---
+
+Thank you for contributing to MCP PostgreSQL Operations! Your efforts help make PostgreSQL monitoring more accessible to everyone. 🚀

mcp_postgresql_ops-3.3.3/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+buy_me_a_coffee: call518

mcp_postgresql_ops-3.3.3/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,83 @@
+---
+name: Bug Report
+about: Report a bug to help us improve MCP PostgreSQL Operations
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+<!-- A clear and concise description of what the bug is -->
+
+## Steps to Reproduce
+1. 
+2. 
+3. 
+4. 
+
+## Expected Behavior
+<!-- What you expected to happen -->
+
+## Actual Behavior
+<!-- What actually happened -->
+
+## Environment Details
+### PostgreSQL Environment
+- **PostgreSQL Version**: 
+- **Extensions Installed**: 
+  - [ ] pg_stat_statements
+  - [ ] pg_stat_monitor
+  - [ ] Other: ___
+- **Environment Type**: 
+  - [ ] Self-managed PostgreSQL
+  - [ ] Docker container
+  - [ ] AWS RDS
+  - [ ] AWS Aurora
+  - [ ] Google Cloud SQL
+  - [ ] Azure Database
+  - [ ] Other: ___
+- **User Permissions**: 
+  - [ ] Superuser
+  - [ ] Regular user with pg_read_all_stats
+  - [ ] Regular user without special permissions
+  - [ ] Other: ___
+
+### MCP Server Environment
+- **Installation Method**: 
+  - [ ] PyPI (uvx)
+  - [ ] Local source
+  - [ ] Docker
+- **Python Version**: 
+- **MCP Server Version**: 
+- **Client Used**: 
+  - [ ] Claude Desktop
+  - [ ] Open WebUI
+  - [ ] MCP Inspector
+  - [ ] Other: ___
+
+## Error Messages
+<!-- Include full error messages, stack traces, or logs -->
+```
+[Paste error messages here]
+```
+
+## Configuration
+<!-- Share relevant configuration (remove sensitive information) -->
+```json
+{
+  "env": {
+    "POSTGRES_HOST": "localhost",
+    "POSTGRES_PORT": "5432",
+    "POSTGRES_DB": "your_db"
+  }
+}
+```
+
+## Additional Context
+<!-- Add any other context about the problem here -->
+- Does this affect all tools or specific ones?
+- When did this start happening?
+- Any recent changes to your environment?
+
+## Screenshots
+<!-- If applicable, add screenshots to help explain your problem -->

mcp_postgresql_ops-3.3.3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,17 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔒 Security Issues
+    url: https://github.com/call518/MCP-PostgreSQL-Ops/security/advisories/new
+    about: Please report security vulnerabilities privately through GitHub Security Advisories
+  - name: 💬 GitHub Discussions
+    url: https://github.com/call518/MCP-PostgreSQL-Ops/discussions
+    about: Ask questions, share usage examples, and discuss PostgreSQL monitoring strategies with the community
+  - name: 📖 Documentation & Setup Guide
+    url: https://github.com/call518/MCP-PostgreSQL-Ops#readme
+    about: Check the README for installation instructions, compatibility matrix, and comprehensive usage examples
+  - name: 🧪 MCP Inspector Testing
+    url: https://github.com/call518/MCP-PostgreSQL-Ops#-quickstart-5-minutes
+    about: Use MCP Inspector for local testing and debugging of PostgreSQL monitoring tools
+  - name: 🗂️ Tool Compatibility Matrix
+    url: https://github.com/call518/MCP-PostgreSQL-Ops#tool-compatibility-matrix
+    about: Check PostgreSQL version compatibility and extension requirements for specific monitoring tools

mcp_postgresql_ops-3.3.3/.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,59 @@
+---
+name: Documentation Issue
+about: Report issues with documentation or suggest documentation improvements
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## Documentation Issue Type
+<!-- Mark the relevant option with an "x" -->
+- [ ] 📝 Typo or grammatical error
+- [ ] 📚 Missing documentation
+- [ ] 🔗 Broken or incorrect links
+- [ ] 🧩 Unclear or confusing explanation
+- [ ] 📋 Missing examples
+- [ ] 🔄 Outdated information
+- [ ] 🏗️ Structural improvement needed
+- [ ] 🌐 Translation issue
+
+## Location
+<!-- Where is the documentation issue located? -->
+- **File**: (e.g., README.md, CONTRIBUTING.md, etc.)
+- **Section**: (e.g., "Features", "Installation", etc.)
+- **Line numbers**: (if applicable)
+- **URL**: (if applicable)
+
+## Current Content
+<!-- Quote the current text that needs to be changed -->
+```
+[Current text here]
+```
+
+## Suggested Improvement
+<!-- Provide your suggestion for improvement -->
+```
+[Suggested text here]
+```
+
+## Additional Context
+<!-- Explain why this change would be helpful -->
+
+## Documentation Category
+<!-- What type of documentation is this about? -->
+- [ ] Installation/Setup
+- [ ] Configuration
+- [ ] Usage examples
+- [ ] Tool descriptions
+- [ ] PostgreSQL compatibility
+- [ ] Troubleshooting
+- [ ] Contributing guidelines
+- [ ] API/Tool reference
+- [ ] Architecture/Design
+- [ ] Other: ___
+
+## Priority
+- [ ] Critical - blocks users from using the tool
+- [ ] High - causes significant confusion
+- [ ] Medium - minor improvement
+- [ ] Low - cosmetic issue

mcp_postgresql_ops-3.3.3/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,77 @@
+---
+name: Feature Request
+about: Suggest a new monitoring tool or improvement for MCP PostgreSQL Operations
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+<!-- A clear and concise description of the feature you'd like to see -->
+
+## Use Case / Problem
+<!-- What problem would this feature solve? What's your use case? -->
+
+## Proposed Solution
+<!-- Describe the solution you'd like to see implemented -->
+
+## PostgreSQL Specific Requirements
+### Version Compatibility
+- [ ] Should work on PostgreSQL 12+
+- [ ] PostgreSQL version specific feature (specify versions): ___
+- [ ] Requires specific PostgreSQL extensions: ___
+
+### System Views/Tables Needed
+<!-- List the PostgreSQL system views or tables this feature would use -->
+- [ ] pg_stat_activity
+- [ ] pg_stat_statements
+- [ ] pg_stat_monitor  
+- [ ] information_schema.*
+- [ ] pg_stat_database
+- [ ] Other: ___
+
+### Extension Dependencies
+- [ ] No extensions required
+- [ ] Requires pg_stat_statements
+- [ ] Requires pg_stat_monitor
+- [ ] Requires other extensions: ___
+
+## Tool Category
+<!-- What type of monitoring tool would this be? -->
+- [ ] Performance monitoring
+- [ ] Query analysis
+- [ ] Schema/structure analysis
+- [ ] Maintenance operations (VACUUM, etc.)
+- [ ] Connection/session monitoring
+- [ ] Replication monitoring
+- [ ] Storage/capacity analysis
+- [ ] Security/permissions analysis
+- [ ] Other: ___
+
+## Expected Output Format
+<!-- Describe what kind of data this tool should return -->
+```
+Example of expected output structure
+```
+
+## Natural Language Queries
+<!-- Provide examples of how users would ask for this information -->
+- "Show me..."
+- "Analyze..."
+- "Find..."
+
+## Alternative Solutions
+<!-- Are there existing tools or workarounds you've considered? -->
+
+## Implementation Ideas
+<!-- If you have ideas about how this could be implemented, share them -->
+
+## Priority
+<!-- How important is this feature to you? -->
+- [ ] Critical - blocking current work
+- [ ] High - would significantly improve workflow
+- [ ] Medium - nice to have
+- [ ] Low - minor improvement
+
+## Additional Context
+<!-- Add any other context, screenshots, or examples about the feature request -->

mcp_postgresql_ops-3.3.3/.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,24 @@
+---
+name: Question
+about: Ask a question about using MCP PostgreSQL Operations
+title: '[QUESTION] '
+labels: question
+assignees: ''
+---
+
+## Question
+<!-- Ask your question clearly and concisely -->
+
+## Context
+<!-- Provide context about what you're trying to accomplish -->
+
+## Environment (if relevant)
+- **PostgreSQL Version**: 
+- **MCP Installation**: [ ] PyPI [ ] Local source [ ] Docker
+- **Client**: [ ] Claude Desktop [ ] Open WebUI [ ] Other: ___
+
+## What You've Tried
+<!-- Describe what you've already attempted -->
+
+## Additional Information
+<!-- Any other details that might help us answer your question -->