mcp-dbutils 0.2.4__tar.gz → 0.2.8__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcp_dbutils-0.2.8/.coveragerc +17 -0
- mcp_dbutils-0.2.8/.github/workflows/test.yml +77 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/.gitignore +3 -0
- mcp_dbutils-0.2.8/CHANGELOG.md +158 -0
- mcp_dbutils-0.2.8/Dockerfile +17 -0
- mcp_dbutils-0.2.4/README.md → mcp_dbutils-0.2.8/PKG-INFO +50 -5
- mcp_dbutils-0.2.4/PKG-INFO → mcp_dbutils-0.2.8/README.md +28 -19
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/README_CN.md +15 -5
- mcp_dbutils-0.2.8/pyproject.toml +38 -0
- mcp_dbutils-0.2.8/smithery.yaml +21 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/base.py +68 -15
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/postgres/handler.py +12 -12
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/sqlite/handler.py +19 -8
- mcp_dbutils-0.2.8/src/mcp_dbutils/stats.py +85 -0
- mcp_dbutils-0.2.8/tests/conftest.py +123 -0
- mcp_dbutils-0.2.8/tests/integration/test_monitoring.py +78 -0
- mcp_dbutils-0.2.8/tests/integration/test_postgres.py +83 -0
- mcp_dbutils-0.2.8/tests/integration/test_prompts.py +41 -0
- mcp_dbutils-0.2.8/tests/integration/test_sqlite.py +84 -0
- mcp_dbutils-0.2.8/tests/unit/test_stats.py +93 -0
- mcp_dbutils-0.2.4/CHANGELOG.md +0 -79
- mcp_dbutils-0.2.4/pyproject.toml +0 -23
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/.github/workflows/publish.yml +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/LICENSE +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/config.yaml.example +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/__init__.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/config.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/log.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/postgres/__init__.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/postgres/config.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/postgres/server.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/sqlite/__init__.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/sqlite/config.py +0 -0
- {mcp_dbutils-0.2.4 → mcp_dbutils-0.2.8}/src/mcp_dbutils/sqlite/server.py +0 -0
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
[run]
|
|
2
|
+
source = src/mcp_dbutils
|
|
3
|
+
omit =
|
|
4
|
+
tests/*
|
|
5
|
+
**/__init__.py
|
|
6
|
+
|
|
7
|
+
[report]
|
|
8
|
+
exclude_lines =
|
|
9
|
+
pragma: no cover
|
|
10
|
+
def __repr__
|
|
11
|
+
raise NotImplementedError
|
|
12
|
+
if __name__ == .__main__.:
|
|
13
|
+
pass
|
|
14
|
+
raise ImportError
|
|
15
|
+
|
|
16
|
+
[html]
|
|
17
|
+
directory = coverage_html
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
name: Tests
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [ main ]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [ main ]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
|
|
13
|
+
services:
|
|
14
|
+
postgres:
|
|
15
|
+
image: postgres:15-alpine
|
|
16
|
+
env:
|
|
17
|
+
POSTGRES_PASSWORD: postgres
|
|
18
|
+
ports:
|
|
19
|
+
- 5432:5432
|
|
20
|
+
options: >-
|
|
21
|
+
--health-cmd pg_isready
|
|
22
|
+
--health-interval 10s
|
|
23
|
+
--health-timeout 5s
|
|
24
|
+
--health-retries 5
|
|
25
|
+
|
|
26
|
+
steps:
|
|
27
|
+
- uses: actions/checkout@v4
|
|
28
|
+
|
|
29
|
+
- name: Install uv
|
|
30
|
+
uses: astral-sh/setup-uv@v4
|
|
31
|
+
|
|
32
|
+
- name: Set up Python
|
|
33
|
+
run: uv python install
|
|
34
|
+
|
|
35
|
+
- name: Create and activate venv
|
|
36
|
+
run: |
|
|
37
|
+
uv venv
|
|
38
|
+
. .venv/bin/activate
|
|
39
|
+
|
|
40
|
+
- name: Install dependencies
|
|
41
|
+
run: uv pip install -e ".[test]"
|
|
42
|
+
|
|
43
|
+
- name: Run tests with coverage
|
|
44
|
+
id: tests
|
|
45
|
+
run: |
|
|
46
|
+
uv run pytest \
|
|
47
|
+
-v \
|
|
48
|
+
--cov=src/mcp_dbutils \
|
|
49
|
+
--cov-report=html \
|
|
50
|
+
--cov-report=term-missing \
|
|
51
|
+
--cov-report=json:coverage.json \
|
|
52
|
+
tests/
|
|
53
|
+
|
|
54
|
+
- name: Calculate coverage percentage
|
|
55
|
+
id: calc_coverage
|
|
56
|
+
run: |
|
|
57
|
+
COVERAGE=$(jq -r '.totals.percent_covered' coverage.json)
|
|
58
|
+
echo "Coverage: $COVERAGE"
|
|
59
|
+
echo "percentage=${COVERAGE%.*}" >> $GITHUB_OUTPUT
|
|
60
|
+
if (( $(echo "$COVERAGE >= 90" | bc -l) )); then
|
|
61
|
+
echo "color=green" >> $GITHUB_OUTPUT
|
|
62
|
+
elif (( $(echo "$COVERAGE >= 80" | bc -l) )); then
|
|
63
|
+
echo "color=yellow" >> $GITHUB_OUTPUT
|
|
64
|
+
else
|
|
65
|
+
echo "color=red" >> $GITHUB_OUTPUT
|
|
66
|
+
fi
|
|
67
|
+
|
|
68
|
+
- name: Create Coverage Badge
|
|
69
|
+
uses: schneegans/dynamic-badges-action@v1.7.0
|
|
70
|
+
with:
|
|
71
|
+
auth: ${{ secrets.GIST_SECRET }}
|
|
72
|
+
gistID: bdd0a63ec2a816539ff8c136ceb41e48
|
|
73
|
+
filename: coverage.json
|
|
74
|
+
label: "coverage"
|
|
75
|
+
message: "${{ steps.calc_coverage.outputs.percentage }}%"
|
|
76
|
+
color: "${{ steps.calc_coverage.outputs.color }}"
|
|
77
|
+
namedLogo: python
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## [0.2.11] - 2025-02-15
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- Added basic prompts support
|
|
9
|
+
- Implemented empty prompts/list handler
|
|
10
|
+
- Added prompts capability configuration
|
|
11
|
+
- Added integration tests for prompts
|
|
12
|
+
|
|
13
|
+
## [0.2.10] - 2025-02-15
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
- Resource monitoring system
|
|
17
|
+
- Added ResourceStats for resource usage tracking
|
|
18
|
+
- Implemented connection lifecycle monitoring
|
|
19
|
+
- Added error pattern analysis
|
|
20
|
+
- Added memory usage estimation
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
- Enhanced database handlers
|
|
24
|
+
- Improved error tracking and reporting
|
|
25
|
+
- Added resource cleanup logging
|
|
26
|
+
- Standardized monitoring output format
|
|
27
|
+
- Implemented template method pattern for queries
|
|
28
|
+
|
|
29
|
+
### Fixed
|
|
30
|
+
- Unified resource monitoring across all database types
|
|
31
|
+
- Added proper cleanup for monitoring resources
|
|
32
|
+
|
|
33
|
+
## [0.2.9] - 2025-02-15
|
|
34
|
+
|
|
35
|
+
### Changed
|
|
36
|
+
- Optimized database type handling
|
|
37
|
+
- Removed redundant type detection based on path/dbname
|
|
38
|
+
- Now using explicit 'type' field from configuration
|
|
39
|
+
- Added custom exception classes for better error handling
|
|
40
|
+
- Enhanced logging for handler lifecycle
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
- New exception hierarchy for better error handling
|
|
44
|
+
- DatabaseError as base exception
|
|
45
|
+
- ConfigurationError for configuration issues
|
|
46
|
+
- ConnectionError for connection problems
|
|
47
|
+
- Improved debug logging
|
|
48
|
+
- Added handler creation logs
|
|
49
|
+
- Added cleanup operation logs
|
|
50
|
+
- Enhanced error messages with more context
|
|
51
|
+
|
|
52
|
+
## [0.2.8] - 2025-02-15
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
- Improved test configuration and stability
|
|
56
|
+
- Removed custom event_loop fixture in favor of pytest-asyncio's default
|
|
57
|
+
- Configured asyncio_mode to strict for better async test behavior
|
|
58
|
+
- Set asyncio_default_fixture_loop_scope to function level
|
|
59
|
+
- Fixed all pytest-asyncio deprecation warnings
|
|
60
|
+
|
|
61
|
+
## [0.2.7] - 2025-02-15
|
|
62
|
+
|
|
63
|
+
### Added
|
|
64
|
+
- Added GitHub Actions workflow for automated testing
|
|
65
|
+
- Added PostgreSQL service in CI environment
|
|
66
|
+
- Added detailed test reporting with coverage in CI
|
|
67
|
+
- Added coverage badge to README using dynamic-badges-action
|
|
68
|
+
|
|
69
|
+
## [0.2.6] - 2025-02-12
|
|
70
|
+
|
|
71
|
+
### Added
|
|
72
|
+
- Added test coverage reporting with pytest-cov
|
|
73
|
+
- Added coverage configuration and HTML report generation
|
|
74
|
+
- Added test coverage tracking for all source code
|
|
75
|
+
|
|
76
|
+
## [0.2.5] - 2025-02-12
|
|
77
|
+
|
|
78
|
+
### Added
|
|
79
|
+
- Comprehensive automated tests for both PostgreSQL and SQLite handlers
|
|
80
|
+
- Integration tests for database operations
|
|
81
|
+
- Unit tests for configuration
|
|
82
|
+
- Test fixtures and Docker-based test environments
|
|
83
|
+
|
|
84
|
+
## [0.2.4] - 2025-02-09
|
|
85
|
+
|
|
86
|
+
### Changed
|
|
87
|
+
- Unified server configuration name to "dbutils"
|
|
88
|
+
- Improved documentation formatting and readability
|
|
89
|
+
- Added architecture diagrams
|
|
90
|
+
- Added contribution guidelines
|
|
91
|
+
- Enhanced installation instructions with environment variables
|
|
92
|
+
- Added acknowledgments section
|
|
93
|
+
|
|
94
|
+
## [0.2.3] - 2025-02-09
|
|
95
|
+
|
|
96
|
+
### Added
|
|
97
|
+
- Added comprehensive installation guides for uvx, pip, and Docker
|
|
98
|
+
- Added GitHub Actions workflow for automated PyPI releases
|
|
99
|
+
- Added both English and Chinese documentation
|
|
100
|
+
- Added project badges and repository information
|
|
101
|
+
|
|
102
|
+
### Changed
|
|
103
|
+
- Internationalized all code messages and docstrings
|
|
104
|
+
- Updated Python version requirement to 3.10+
|
|
105
|
+
- Improved documentation structure and examples
|
|
106
|
+
- Unified project naming to mcp-dbutils across all references
|
|
107
|
+
|
|
108
|
+
## [0.2.2] - 2025-02-09
|
|
109
|
+
|
|
110
|
+
### Added
|
|
111
|
+
- Added explicit database type declaration in configs
|
|
112
|
+
- Improved database type awareness in query results
|
|
113
|
+
- Standardized field naming across different database types
|
|
114
|
+
|
|
115
|
+
### Changed
|
|
116
|
+
- Unified response format for normal results and error messages
|
|
117
|
+
- Enhanced error reporting with database-specific details
|
|
118
|
+
|
|
119
|
+
## [0.2.1] - 2025-02-09
|
|
120
|
+
|
|
121
|
+
### Added
|
|
122
|
+
- SQLite database support with basic CRUD operations
|
|
123
|
+
- Password protection for SQLite databases
|
|
124
|
+
- Table schema inspection for SQLite
|
|
125
|
+
- URI connection string support for SQLite
|
|
126
|
+
|
|
127
|
+
### Fixed
|
|
128
|
+
- Automatic database type detection from config
|
|
129
|
+
- Connection handling improvements
|
|
130
|
+
|
|
131
|
+
## [0.2.0] - 2025-02-09
|
|
132
|
+
|
|
133
|
+
### Changed
|
|
134
|
+
- Renamed project from mcp-postgres to mcp-dbutils
|
|
135
|
+
- Restructured project for multi-database support
|
|
136
|
+
- Added base classes for database handling
|
|
137
|
+
- Improved configuration management
|
|
138
|
+
- Enhanced error handling and logging
|
|
139
|
+
|
|
140
|
+
## [0.1.1] - 2025-02-08
|
|
141
|
+
|
|
142
|
+
### Added
|
|
143
|
+
- Enhanced PostgreSQL error logging with error codes
|
|
144
|
+
- Improved error details with pgcode and pgerror
|
|
145
|
+
- Better error differentiation between PostgreSQL-specific and general errors
|
|
146
|
+
|
|
147
|
+
### Changed
|
|
148
|
+
- Maintained backwards compatibility while improving error flow
|
|
149
|
+
|
|
150
|
+
## [0.1.0] - 2025-02-08
|
|
151
|
+
|
|
152
|
+
### Added
|
|
153
|
+
- Initial PostgreSQL implementation
|
|
154
|
+
- YAML configuration for multiple databases
|
|
155
|
+
- Connection pool management
|
|
156
|
+
- Table structure querying
|
|
157
|
+
- Read-only SQL query execution
|
|
158
|
+
- Basic error handling and logging
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
|
|
2
|
+
# Use a base Python image
|
|
3
|
+
FROM python:3.10-slim AS base
|
|
4
|
+
|
|
5
|
+
# Set the working directory in the container
|
|
6
|
+
WORKDIR /app
|
|
7
|
+
|
|
8
|
+
# Copy the project file
|
|
9
|
+
COPY pyproject.toml README.md src /app/
|
|
10
|
+
|
|
11
|
+
# Install dependencies and the package
|
|
12
|
+
RUN pip install hatchling && \
|
|
13
|
+
hatchling build && \
|
|
14
|
+
pip install dist/*.whl
|
|
15
|
+
|
|
16
|
+
# Set the entry point to run the server
|
|
17
|
+
ENTRYPOINT ["mcp-dbutils", "--config", "/app/config.yaml"]
|
|
@@ -1,9 +1,33 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-dbutils
|
|
3
|
+
Version: 0.2.8
|
|
4
|
+
Summary: MCP Database Utilities Service
|
|
5
|
+
Author: Dong Hao
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Requires-Dist: mcp>=1.2.1
|
|
10
|
+
Requires-Dist: psycopg2-binary>=2.9.10
|
|
11
|
+
Requires-Dist: python-dotenv>=1.0.1
|
|
12
|
+
Requires-Dist: pyyaml>=6.0.2
|
|
13
|
+
Provides-Extra: test
|
|
14
|
+
Requires-Dist: aiosqlite>=0.19.0; extra == 'test'
|
|
15
|
+
Requires-Dist: docker>=7.0.0; extra == 'test'
|
|
16
|
+
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
|
|
17
|
+
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
|
|
18
|
+
Requires-Dist: pytest-docker>=2.0.0; extra == 'test'
|
|
19
|
+
Requires-Dist: pytest>=7.0.0; extra == 'test'
|
|
20
|
+
Requires-Dist: testcontainers>=3.7.0; extra == 'test'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
1
23
|
# MCP Database Utilities
|
|
2
24
|
|
|
3
25
|
|
|
4
26
|
|
|
27
|
+
[](https://github.com/donghao1393/mcp-dbutils/actions)
|
|
5
28
|
|
|
6
29
|
|
|
30
|
+
[](https://smithery.ai/server/@donghao1393/mcp-dbutils)
|
|
7
31
|
|
|
8
32
|
[中文文档](README_CN.md)
|
|
9
33
|
|
|
@@ -21,6 +45,13 @@ MCP Database Utilities is a unified database access service that supports multip
|
|
|
21
45
|
## Installation and Configuration
|
|
22
46
|
|
|
23
47
|
### Installation Methods
|
|
48
|
+
#### Installing via Smithery
|
|
49
|
+
|
|
50
|
+
To install Database Utilities for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@donghao1393/mcp-dbutils):
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude
|
|
54
|
+
```
|
|
24
55
|
|
|
25
56
|
#### Using uvx (Recommended)
|
|
26
57
|
No installation required, run directly using `uvx`:
|
|
@@ -72,6 +103,7 @@ Add to Claude configuration:
|
|
|
72
103
|
```bash
|
|
73
104
|
docker run -i --rm \
|
|
74
105
|
-v /path/to/config.yaml:/app/config.yaml \
|
|
106
|
+
-v /path/to/sqlite.db:/app/sqlite.db \ # Optional: for SQLite database
|
|
75
107
|
-e MCP_DEBUG=1 \ # Optional: Enable debug mode
|
|
76
108
|
mcp/dbutils --config /app/config.yaml
|
|
77
109
|
```
|
|
@@ -87,6 +119,8 @@ Add to Claude configuration:
|
|
|
87
119
|
"--rm",
|
|
88
120
|
"-v",
|
|
89
121
|
"/path/to/config.yaml:/app/config.yaml",
|
|
122
|
+
"-v",
|
|
123
|
+
"/path/to/sqlite.db:/app/sqlite.db", // Optional: for SQLite database
|
|
90
124
|
"mcp/dbutils",
|
|
91
125
|
"--config",
|
|
92
126
|
"/app/config.yaml"
|
|
@@ -98,6 +132,12 @@ Add to Claude configuration:
|
|
|
98
132
|
}
|
|
99
133
|
```
|
|
100
134
|
|
|
135
|
+
> **Note for Docker database connections:**
|
|
136
|
+
> - For SQLite: Mount your database file using `-v /path/to/sqlite.db:/app/sqlite.db`
|
|
137
|
+
> - For PostgreSQL running on host:
|
|
138
|
+
> - On Mac/Windows: Use `host.docker.internal` as host in config
|
|
139
|
+
> - On Linux: Use `172.17.0.1` (docker0 IP) or run with `--network="host"`
|
|
140
|
+
|
|
101
141
|
### Requirements
|
|
102
142
|
- Python 3.10+
|
|
103
143
|
- PostgreSQL (optional)
|
|
@@ -108,20 +148,21 @@ The project requires a YAML configuration file, specified via the `--config` par
|
|
|
108
148
|
|
|
109
149
|
```yaml
|
|
110
150
|
databases:
|
|
111
|
-
# PostgreSQL example
|
|
151
|
+
# PostgreSQL example (when using Docker)
|
|
112
152
|
my_postgres:
|
|
113
153
|
type: postgres
|
|
114
154
|
dbname: test_db
|
|
115
155
|
user: postgres
|
|
116
156
|
password: secret
|
|
117
|
-
host:
|
|
157
|
+
host: host.docker.internal # For Mac/Windows
|
|
158
|
+
# host: 172.17.0.1 # For Linux (docker0 IP)
|
|
118
159
|
port: 5432
|
|
119
160
|
|
|
120
|
-
# SQLite example
|
|
161
|
+
# SQLite example (when using Docker)
|
|
121
162
|
my_sqlite:
|
|
122
163
|
type: sqlite
|
|
123
|
-
path: /
|
|
124
|
-
password: optional_password
|
|
164
|
+
path: /app/sqlite.db # Mapped path inside container
|
|
165
|
+
password: optional_password # optional
|
|
125
166
|
```
|
|
126
167
|
|
|
127
168
|
### Debug Mode
|
|
@@ -269,3 +310,7 @@ For detailed guidelines, see [CONTRIBUTING.md](.github/CONTRIBUTING.md)
|
|
|
269
310
|
* [5ire](https://5ire.app/)
|
|
270
311
|
* [Cline](https://cline.bot)
|
|
271
312
|
- [Model Context Protocol](https://modelcontextprotocol.io/) for comprehensive interfaces
|
|
313
|
+
|
|
314
|
+
## Star History
|
|
315
|
+
|
|
316
|
+
[](https://star-history.com/#donghao1393/mcp-dbutils&Date)
|
|
@@ -1,23 +1,11 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: mcp-dbutils
|
|
3
|
-
Version: 0.2.4
|
|
4
|
-
Summary: MCP Database Utilities Service
|
|
5
|
-
Author: Dong Hao
|
|
6
|
-
License-Expression: MIT
|
|
7
|
-
License-File: LICENSE
|
|
8
|
-
Requires-Python: >=3.10
|
|
9
|
-
Requires-Dist: mcp>=1.2.1
|
|
10
|
-
Requires-Dist: psycopg2-binary>=2.9.10
|
|
11
|
-
Requires-Dist: python-dotenv>=1.0.1
|
|
12
|
-
Requires-Dist: pyyaml>=6.0.2
|
|
13
|
-
Description-Content-Type: text/markdown
|
|
14
|
-
|
|
15
1
|
# MCP Database Utilities
|
|
16
2
|
|
|
17
3
|
|
|
18
4
|
|
|
5
|
+
[](https://github.com/donghao1393/mcp-dbutils/actions)
|
|
19
6
|
|
|
20
7
|
|
|
8
|
+
[](https://smithery.ai/server/@donghao1393/mcp-dbutils)
|
|
21
9
|
|
|
22
10
|
[中文文档](README_CN.md)
|
|
23
11
|
|
|
@@ -35,6 +23,13 @@ MCP Database Utilities is a unified database access service that supports multip
|
|
|
35
23
|
## Installation and Configuration
|
|
36
24
|
|
|
37
25
|
### Installation Methods
|
|
26
|
+
#### Installing via Smithery
|
|
27
|
+
|
|
28
|
+
To install Database Utilities for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@donghao1393/mcp-dbutils):
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude
|
|
32
|
+
```
|
|
38
33
|
|
|
39
34
|
#### Using uvx (Recommended)
|
|
40
35
|
No installation required, run directly using `uvx`:
|
|
@@ -86,6 +81,7 @@ Add to Claude configuration:
|
|
|
86
81
|
```bash
|
|
87
82
|
docker run -i --rm \
|
|
88
83
|
-v /path/to/config.yaml:/app/config.yaml \
|
|
84
|
+
-v /path/to/sqlite.db:/app/sqlite.db \ # Optional: for SQLite database
|
|
89
85
|
-e MCP_DEBUG=1 \ # Optional: Enable debug mode
|
|
90
86
|
mcp/dbutils --config /app/config.yaml
|
|
91
87
|
```
|
|
@@ -101,6 +97,8 @@ Add to Claude configuration:
|
|
|
101
97
|
"--rm",
|
|
102
98
|
"-v",
|
|
103
99
|
"/path/to/config.yaml:/app/config.yaml",
|
|
100
|
+
"-v",
|
|
101
|
+
"/path/to/sqlite.db:/app/sqlite.db", // Optional: for SQLite database
|
|
104
102
|
"mcp/dbutils",
|
|
105
103
|
"--config",
|
|
106
104
|
"/app/config.yaml"
|
|
@@ -112,6 +110,12 @@ Add to Claude configuration:
|
|
|
112
110
|
}
|
|
113
111
|
```
|
|
114
112
|
|
|
113
|
+
> **Note for Docker database connections:**
|
|
114
|
+
> - For SQLite: Mount your database file using `-v /path/to/sqlite.db:/app/sqlite.db`
|
|
115
|
+
> - For PostgreSQL running on host:
|
|
116
|
+
> - On Mac/Windows: Use `host.docker.internal` as host in config
|
|
117
|
+
> - On Linux: Use `172.17.0.1` (docker0 IP) or run with `--network="host"`
|
|
118
|
+
|
|
115
119
|
### Requirements
|
|
116
120
|
- Python 3.10+
|
|
117
121
|
- PostgreSQL (optional)
|
|
@@ -122,20 +126,21 @@ The project requires a YAML configuration file, specified via the `--config` par
|
|
|
122
126
|
|
|
123
127
|
```yaml
|
|
124
128
|
databases:
|
|
125
|
-
# PostgreSQL example
|
|
129
|
+
# PostgreSQL example (when using Docker)
|
|
126
130
|
my_postgres:
|
|
127
131
|
type: postgres
|
|
128
132
|
dbname: test_db
|
|
129
133
|
user: postgres
|
|
130
134
|
password: secret
|
|
131
|
-
host:
|
|
135
|
+
host: host.docker.internal # For Mac/Windows
|
|
136
|
+
# host: 172.17.0.1 # For Linux (docker0 IP)
|
|
132
137
|
port: 5432
|
|
133
138
|
|
|
134
|
-
# SQLite example
|
|
139
|
+
# SQLite example (when using Docker)
|
|
135
140
|
my_sqlite:
|
|
136
141
|
type: sqlite
|
|
137
|
-
path: /
|
|
138
|
-
password: optional_password
|
|
142
|
+
path: /app/sqlite.db # Mapped path inside container
|
|
143
|
+
password: optional_password # optional
|
|
139
144
|
```
|
|
140
145
|
|
|
141
146
|
### Debug Mode
|
|
@@ -283,3 +288,7 @@ For detailed guidelines, see [CONTRIBUTING.md](.github/CONTRIBUTING.md)
|
|
|
283
288
|
* [5ire](https://5ire.app/)
|
|
284
289
|
* [Cline](https://cline.bot)
|
|
285
290
|
- [Model Context Protocol](https://modelcontextprotocol.io/) for comprehensive interfaces
|
|
291
|
+
|
|
292
|
+
## Star History
|
|
293
|
+
|
|
294
|
+
[](https://star-history.com/#donghao1393/mcp-dbutils&Date)
|
|
@@ -65,6 +65,7 @@ pip install mcp-dbutils
|
|
|
65
65
|
```bash
|
|
66
66
|
docker run -i --rm \
|
|
67
67
|
-v /path/to/config.yaml:/app/config.yaml \
|
|
68
|
+
-v /path/to/sqlite.db:/app/sqlite.db \ # 可选：用于SQLite数据库
|
|
68
69
|
-e MCP_DEBUG=1 \ # 可选：启用调试模式
|
|
69
70
|
mcp/dbutils --config /app/config.yaml
|
|
70
71
|
```
|
|
@@ -80,6 +81,8 @@ docker run -i --rm \
|
|
|
80
81
|
"--rm",
|
|
81
82
|
"-v",
|
|
82
83
|
"/path/to/config.yaml:/app/config.yaml",
|
|
84
|
+
"-v",
|
|
85
|
+
"/path/to/sqlite.db:/app/sqlite.db", // 可选：用于SQLite数据库
|
|
83
86
|
"mcp/dbutils",
|
|
84
87
|
"--config",
|
|
85
88
|
"/app/config.yaml"
|
|
@@ -91,6 +94,12 @@ docker run -i --rm \
|
|
|
91
94
|
}
|
|
92
95
|
```
|
|
93
96
|
|
|
97
|
+
> **Docker数据库连接说明：**
|
|
98
|
+
> - SQLite数据库：使用 `-v /path/to/sqlite.db:/app/sqlite.db` 映射数据库文件
|
|
99
|
+
> - 主机上运行的PostgreSQL：
|
|
100
|
+
> - Mac/Windows：配置中使用 `host.docker.internal`
|
|
101
|
+
> - Linux：使用 `172.17.0.1`（docker0网络IP）或使用 `--network="host"` 运行
|
|
102
|
+
|
|
94
103
|
### 环境要求
|
|
95
104
|
- Python 3.10+
|
|
96
105
|
- PostgreSQL (可选)
|
|
@@ -101,20 +110,21 @@ docker run -i --rm \
|
|
|
101
110
|
|
|
102
111
|
```yaml
|
|
103
112
|
databases:
|
|
104
|
-
# PostgreSQL
|
|
113
|
+
# PostgreSQL配置示例（使用Docker）
|
|
105
114
|
my_postgres:
|
|
106
115
|
type: postgres
|
|
107
116
|
dbname: test_db
|
|
108
117
|
user: postgres
|
|
109
118
|
password: secret
|
|
110
|
-
host:
|
|
119
|
+
host: host.docker.internal # Mac/Windows系统使用
|
|
120
|
+
# host: 172.17.0.1 # Linux系统使用（docker0网络IP）
|
|
111
121
|
port: 5432
|
|
112
122
|
|
|
113
|
-
# SQLite
|
|
123
|
+
# SQLite配置示例（使用Docker）
|
|
114
124
|
my_sqlite:
|
|
115
125
|
type: sqlite
|
|
116
|
-
path: /
|
|
117
|
-
password: optional_password
|
|
126
|
+
path: /app/sqlite.db # 容器内的映射路径
|
|
127
|
+
password: optional_password # 可选
|
|
118
128
|
```
|
|
119
129
|
|
|
120
130
|
### 调试模式
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "mcp-dbutils"
|
|
3
|
+
version = "0.2.8"
|
|
4
|
+
description = "MCP Database Utilities Service"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
authors = [
|
|
8
|
+
{name = "Dong Hao"}
|
|
9
|
+
]
|
|
10
|
+
dependencies = [
|
|
11
|
+
"mcp>=1.2.1",
|
|
12
|
+
"psycopg2-binary>=2.9.10",
|
|
13
|
+
"python-dotenv>=1.0.1",
|
|
14
|
+
"pyyaml>=6.0.2",
|
|
15
|
+
]
|
|
16
|
+
requires-python = ">=3.10"
|
|
17
|
+
|
|
18
|
+
[build-system]
|
|
19
|
+
requires = ["hatchling"]
|
|
20
|
+
build-backend = "hatchling.build"
|
|
21
|
+
|
|
22
|
+
[project.scripts]
|
|
23
|
+
mcp-dbutils = "mcp_dbutils:main"
|
|
24
|
+
|
|
25
|
+
[project.optional-dependencies]
|
|
26
|
+
test = [
|
|
27
|
+
"pytest>=7.0.0",
|
|
28
|
+
"pytest-asyncio>=0.23.0",
|
|
29
|
+
"pytest-docker>=2.0.0",
|
|
30
|
+
"docker>=7.0.0",
|
|
31
|
+
"aiosqlite>=0.19.0",
|
|
32
|
+
"testcontainers>=3.7.0",
|
|
33
|
+
"pytest-cov>=4.1.0"
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
[tool.pytest.ini_options]
|
|
37
|
+
asyncio_mode = "strict"
|
|
38
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
|
|
2
|
+
|
|
3
|
+
startCommand:
|
|
4
|
+
type: stdio
|
|
5
|
+
configSchema:
|
|
6
|
+
# JSON Schema defining the configuration options for the MCP.
|
|
7
|
+
type: object
|
|
8
|
+
required:
|
|
9
|
+
- configPath
|
|
10
|
+
properties:
|
|
11
|
+
configPath:
|
|
12
|
+
type: string
|
|
13
|
+
description: The path to the YAML configuration file for database settings.
|
|
14
|
+
debugMode:
|
|
15
|
+
type: boolean
|
|
16
|
+
default: false
|
|
17
|
+
description: "Optional: Enable debug mode for detailed logging."
|
|
18
|
+
commandFunction:
|
|
19
|
+
# A function that produces the CLI command to start the MCP on stdio.
|
|
20
|
+
|-
|
|
21
|
+
(config) => ({ command: 'docker', args: ['run', '-i', '--rm', '-v', `${config.configPath}:/app/config.yaml`, 'mcp/dbutils', '--config', '/app/config.yaml'], env: { MCP_DEBUG: config.debugMode ? '1' : '0' } })
|