Skip to content

Commit 809a98c

Browse files
neverinfamousneverinfamous
committed
Refine readmes
1 parent 0728e69 commit 809a98c

File tree

2 files changed

+245
-259
lines changed

2 files changed

+245
-259
lines changed

‎README.md‎

Lines changed: 145 additions & 173 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,145 @@
11
# SQLite MCP Server
22

3-
*Last Updated September 18, 2025 3:26 PM EST - v2.2.0*
3+
*Last Updated: September 18, 2025 5:11 PM EST – v2.2.0*
4+
5+
[![Docker Pulls](https://img.shields.io/docker/pulls/writenotenow/sqlite-mcp-server)](https://hub.docker.com/r/writenotenow/sqlite-mcp-server)
6+
![License](https://img.shields.io/badge/license-MIT-blue)
7+
![Version](https://img.shields.io/badge/version-v2.2.0-green)
8+
9+
## 🚀 Quick Try
10+
11+
Run instantly with Docker (creates a project-local database):
12+
13+
```bash
14+
docker run -i --rm \
15+
-v $(pwd):/workspace \
16+
writenotenow/sqlite-mcp-server:latest \
17+
--db-path /workspace/sqlite_mcp.db
18+
```
419

520
## Overview
621

7-
The SQLite MCP Server provides advanced database interaction and business intelligence capabilities featuring **Advanced Text Processing**, **Statistical Analysis Library**, **SpatiaLite Geospatial Analytics**, Enhanced Virtual Tables with Smart Type Inference, Vector Index Optimization with ANN search, Intelligent MCP Resources and Prompts, Semantic/Vector Search, Virtual Table Management, Advanced PRAGMA Operations, Backup/Restore operations, Full-Text Search (FTS5), enhanced JSONB support for improved JSON storage efficiency, transaction safety for all database operations, foreign key constraint enforcement, enhanced error handling, and detailed diagnostics.
22+
The SQLite MCP Server transforms SQLite into a powerful, AI-ready database engine. It extends standard relational operations with:
23+
24+
* **Advanced analytics** (statistics, business intelligence)
25+
* **Rich data operations** (text processing, JSONB, validation, caching)
26+
* **Specialized domains** (vector search, SpatiaLite geospatial analysis)
27+
* **AI-native capabilities** (intelligent MCP resources & guided prompts)
28+
29+
This makes it not just a database interface, but a **workflow-aware assistant** for developers and AI systems.
830

931
## Key Features
1032

11-
- **Advanced Text Processing**: Comprehensive text analysis toolkit with 8 specialized tools: PCRE regex extraction/replacement, fuzzy matching with Levenshtein distance, phonetic matching (Soundex/Metaphone), text similarity analysis (Cosine/Jaccard), normalization operations, pattern validation, advanced multi-method search, and comprehensive text validation
12-
- **Statistical Analysis Library**: Comprehensive statistical functions for data analysis including descriptive statistics, percentile analysis, and time series analysis
13-
- **JSONB Binary Storage**: Efficient binary JSON storage for improved performance and reduced storage requirements
14-
- **Transaction Safety**: All write operations automatically wrapped in transactions with proper rollback on errors
15-
- **Foreign Key Enforcement**: Automatic enforcement of foreign key constraints across all connections
16-
- **Advanced SQL Support**: Complex queries including window functions, subqueries, and advanced filtering
17-
- **Business Intelligence**: Integrated memo resource for capturing business insights during analysis
18-
- **Enhanced Error Handling**: Detailed diagnostics for JSON-related errors with specific suggestions for fixing issues
19-
- **Multi-Level Caching**: Hierarchical caching for optimal performance
20-
- **Pattern Recognition**: Automatic optimization of frequently executed queries
21-
- **JSON Validation**: Prevents invalid JSON from being stored in the database
22-
- **Comprehensive Schema Tools**: Enhanced tools for exploring and documenting database structure
23-
- **Database Administration Tools**: Complete suite of maintenance tools including VACUUM, ANALYZE, integrity checks, performance statistics, and index usage analysis
24-
- **Full-Text Search (FTS5)**: Comprehensive FTS5 implementation with table creation, index management, and enhanced search with BM25 ranking and snippets
25-
- **Backup/Restore Operations**: Enterprise-grade backup and restore capabilities with SQLite backup API, integrity verification, and safety confirmations
26-
- **Advanced PRAGMA Operations**: Comprehensive SQLite configuration management, performance optimization, and database introspection tools
27-
- **Virtual Table Management**: Complete virtual table lifecycle management for R-Tree spatial indexing, CSV file access, and sequence generation
28-
- **SpatiaLite Geospatial Analytics**: Enterprise-grade GIS capabilities with spatial indexing, geometric operations, and comprehensive spatial analysis
29-
- **Enhanced Virtual Tables**: Smart CSV/JSON import with automatic data type inference, nested object flattening, and schema analysis
30-
- **Semantic/Vector Search**: AI-native semantic search with embedding storage, cosine similarity, and hybrid keyword+semantic ranking
31-
- **Vector Index Optimization**: Approximate Nearest Neighbor (ANN) search with k-means clustering and spatial indexing for sub-linear O(log n) performance
32-
- **Intelligent MCP Resources**: Dynamic database meta-awareness with real-time schema, capabilities, statistics, search indexes, and performance insights
33-
- **Guided MCP Prompts**: Intelligent workflow automation with semantic query translation, table summarization, database optimization, and hybrid search recipes
34-
- **Advanced SQLite Engine**: Upgraded to SQLite 3.50.4 with significant performance enhancements
35-
36-
⚠️ Tool Count Consideration
37-
The SQLite MCP Server exposes 67 tools by default. MCP clients such as Cursor typically start warning users around 80 tools total, and stability issues can appear above ~100–120 tools depending on your setup. To keep your workspace responsive, you can disable any tools you don’t need directly in your MCP client settings. This makes it easy to slim down the server for your specific use case (e.g., only enabling query, JSON, or vector tools).
33+
* **Advanced Text Processing**: Comprehensive text analysis toolkit with 8 specialized tools: PCRE regex extraction/replacement, fuzzy matching with Levenshtein distance, phonetic matching (Soundex/Metaphone), text similarity analysis (Cosine/Jaccard), normalization operations, pattern validation, advanced multi-method search, and comprehensive text validation
34+
* **Statistical Analysis Library**: Comprehensive statistical functions for data analysis including descriptive statistics, percentile analysis, and time series analysis
35+
* **JSONB Binary Storage**: Efficient binary JSON storage for improved performance and reduced storage requirements
36+
* **Transaction Safety**: All write operations automatically wrapped in transactions with proper rollback on errors
37+
* **Foreign Key Enforcement**: Automatic enforcement of foreign key constraints across all connections
38+
* **Advanced SQL Support**: Complex queries including window functions, subqueries, and advanced filtering
39+
* **Business Intelligence**: Integrated memo resource for capturing business insights during analysis
40+
* **Enhanced Error Handling**: Detailed diagnostics for JSON-related errors with specific suggestions for fixing issues
41+
* **Multi-Level Caching**: Hierarchical caching for optimal performance
42+
* **Pattern Recognition**: Automatic optimization of frequently executed queries
43+
* **JSON Validation**: Prevents invalid JSON from being stored in the database
44+
* **WAL Mode Compatible**: Works alongside the existing Write-Ahead Logging (WAL) journal mode
45+
* **Comprehensive Schema Tools**: Enhanced tools for exploring and documenting database structure
46+
* **Database Administration Tools**: Complete suite of maintenance tools including VACUUM, ANALYZE, integrity checks, performance statistics, and index usage analysis
47+
* **Full-Text Search (FTS5)**: Comprehensive FTS5 implementation with table creation, index management, and enhanced search with BM25 ranking and snippets
48+
* **Backup/Restore Operations**: Enterprise-grade backup and restore capabilities with SQLite backup API, integrity verification, and safety confirmations
49+
* **Advanced PRAGMA Operations**: Comprehensive SQLite configuration management, performance optimization, and database introspection tools
50+
* **Virtual Table Management**: Complete virtual table lifecycle management for R-Tree spatial indexing, CSV file access, and sequence generation
51+
* **SpatiaLite Geospatial Analytics**: Enterprise-grade GIS capabilities with spatial indexing, geometric operations, and comprehensive spatial analysis
52+
* **Enhanced Virtual Tables**: Smart CSV/JSON import with automatic data type inference, nested object flattening, and schema analysis
53+
* **Semantic/Vector Search**: AI-native semantic search with embedding storage, cosine similarity, and hybrid keyword+semantic ranking
54+
* **Vector Index Optimization**: Approximate Nearest Neighbor (ANN) search with k-means clustering and spatial indexing for sub-linear O(log n) performance
55+
* **Intelligent MCP Resources**: Dynamic database meta-awareness with real-time schema, capabilities, statistics, search indexes, and performance insights
56+
* **Guided MCP Prompts**: Intelligent workflow automation with semantic query translation, table summarization, database optimization, and hybrid search recipes
57+
58+
**⚠️ Tool Count Consideration**
59+
The server exposes **67 tools** by default. MCP clients (e.g., Cursor) may warn around 80 tools and can become unstable past \~100–120. You can disable unneeded tools in client settings to slim down usage for your workflow.
3860

3961
## Attribution
4062

41-
This project is based on the original SQLite MCP Server from the [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers/tree/2025.4.24/src/sqlite) repository. We extend our sincere gratitude to the original developers and the Model Context Protocol team for creating the foundational server that made this enhanced version possible.
63+
This project is based on the original SQLite MCP Server from the [Model Context Protocol Servers](https://github.com/modelcontextprotocol/servers/tree/2025.4.24/src/sqlite) repository.
4264

43-
**Original Authors**: Model Context Protocol Team
44-
**Original Repository**: https://github.com/modelcontextprotocol/servers
65+
**Original Authors**: Model Context Protocol Team
66+
**Original Repository**: [https://github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers)
4567
**License**: MIT License
4668

47-
## Docker Hub Deployment
69+
## Getting Started
70+
71+
### Installation Requirements
72+
73+
* **Python 3.10+** – required runtime
74+
* **SQLite 3.45.0+** – with JSONB support (current: 3.50.2)
75+
* **MCP 1.14.0+** – Model Context Protocol library
76+
77+
**Optional (advanced users):**
4878

49-
The SQLite MCP Server is available on Docker Hub at `writenotenow/sqlite-mcp-server` with both `latest` and version-specific tags.
79+
* **Node.js 18+** – extra JSONB utilities (ESLint compliant)
80+
* **Visual Studio C++ Build Tools** – only for Node.js + better-sqlite3
81+
* ⚠️ Core server is Python-only and works without Node.js
5082

51-
### Available Docker Images
83+
### Known Minor Issues
84+
85+
* **JSON formatting**: Always use valid JSON with double quotes
86+
* **Complex queries**: Use parameter binding for advanced queries
87+
88+
### Quick Start (Python)
89+
90+
```bash
91+
# Auto-detect project root (default)
92+
python start_sqlite_mcp.py
93+
94+
# Create organized data directory
95+
python start_sqlite_mcp.py --create-data-dir
96+
97+
# Use specific database
98+
python start_sqlite_mcp.py --db-path /path/to/database.db
99+
100+
# In-memory (testing only)
101+
python start_sqlite_mcp.py --db-path :memory:
102+
```
103+
104+
### MCP Client Configuration
105+
106+
**Local Python:**
107+
108+
```json
109+
{
110+
"mcpServers": {
111+
"sqlite-mcp-server": {
112+
"command": "python",
113+
"args": [
114+
"/path/to/sqlite-mcp-server/start_sqlite_mcp.py",
115+
"--db-path", "/path/to/database.db"
116+
]
117+
}
118+
}
119+
}
120+
```
121+
122+
**Docker:**
123+
124+
```json
125+
{
126+
"mcpServers": {
127+
"sqlite-mcp-server": {
128+
"command": "docker",
129+
"args": [
130+
"run", "-i", "--rm",
131+
"-v", "/host/project:/workspace",
132+
"writenotenow/sqlite-mcp-server:latest",
133+
"--db-path", "/workspace/database.db"
134+
]
135+
}
136+
}
137+
}
138+
```
139+
140+
### Docker Hub Deployment
141+
142+
Available on Docker Hub at [`writenotenow/sqlite-mcp-server`](https://hub.docker.com/r/writenotenow/sqlite-mcp-server).
52143

53144
```bash
54145
# Pull latest version
@@ -525,6 +616,25 @@ read_query({
525616

526617
Note: The explicit `jsonb()` function should only be used in specific advanced cases or when required for parameter binding pattern. For direct SQL statements, standard JSON strings work efficiently.
527618

619+
### JSON Validation and JSONB Support
620+
621+
The SQLite MCP Server includes comprehensive JSON validation capabilities:
622+
623+
1. **Automatic JSON Field Validation**:
624+
- Validates formatting across all JSON fields in 32 columns
625+
- Ensures valid JSON structure during operations
626+
- Reports malformed JSON through notifications
627+
628+
2. **Validation Triggers**:
629+
- Automatically created SQLite triggers for INSERT/UPDATE operations
630+
- Prevents invalid JSON from being inserted or updated
631+
- Covers 16 tables with JSON/JSONB columns
632+
633+
3. **Repair Capabilities**:
634+
- Attempts to repair malformed JSON when found
635+
- Preserves as much data as possible during repairs
636+
- Records repair attempts in maintenance logs
637+
528638
### Transaction Safety
529639

530640
All write operations are now automatically wrapped in transactions with proper rollback on error:
@@ -764,134 +874,6 @@ If you encounter JSON-related errors:
764874
- **Existing databases** - Use `--db-path` to connect to any SQLite database
765875
- **`:memory:`** - Temporary database for testing (data not persisted)
766876

767-
### Quick Start Options
768-
769-
```bash
770-
# Use project root with auto-detection
771-
python start_sqlite_mcp.py
772-
773-
# Create data directory structure
774-
python start_sqlite_mcp.py --create-data-dir
775-
776-
# Use specific database file
777-
python start_sqlite_mcp.py --db-path /path/to/your/database.db
778-
779-
# Use in-memory database (testing)
780-
python start_sqlite_mcp.py --db-path :memory:
781-
```
782-
783-
### MCP Client Configuration
784-
785-
```json
786-
{
787-
"mcpServers": {
788-
"sqlite-local": {
789-
"command": "python",
790-
"args": [
791-
"/path/to/sqlite-mcp-server/start_sqlite_mcp.py",
792-
"--db-path", "/path/to/your/database.db"
793-
]
794-
}
795-
}
796-
}
797-
```
798-
799-
### Known Minor Issues (Non-Critical)
800-
- **JSON Formatting**: Standard JSON formatting resolves any escaping issues
801-
- **Complex Queries**: Advanced parameterized queries supported with proper parameter binding
802-
803-
## Installation Requirements
804-
805-
### Core Requirements (Required)
806-
- **Python 3.10+**: Programming language runtime
807-
- **SQLite 3.45.0+**: Core database engine with JSONB support (current system: 3.50.2)
808-
- **MCP 1.14.0+**: Model Context Protocol library
809-
810-
### Optional JavaScript Utilities (Advanced Users Only)
811-
- **Node.js 18+**: For optional JavaScript JSONB utilities (fully reconstructed and ESLint compliant)
812-
- **Visual Studio C++ Build Tools**: Required only if using JavaScript utilities with better-sqlite3
813-
- **Note**: The main MCP server is Python-based and works perfectly without any JavaScript dependencies
814-
815-
**For most users**: You only need Python requirements. The JavaScript utilities are optional helpers for advanced use cases.
816-
817-
### Quick Start Options
818-
819-
**Use existing database**:
820-
```bash
821-
python start_sqlite_mcp.py --db-path /path/to/your/database.db
822-
```
823-
824-
**Auto-detect project structure** (default):
825-
```bash
826-
python start_sqlite_mcp.py
827-
# Automatically finds project root and creates sqlite_mcp.db
828-
```
829-
830-
**Create organized data directory**:
831-
```bash
832-
python start_sqlite_mcp.py --create-data-dir
833-
# Creates ./data/sqlite_mcp.db in your project
834-
```
835-
836-
### MCP Client Configuration
837-
838-
**For Cursor/Claude Desktop**:
839-
```json
840-
{
841-
"mcpServers": {
842-
"sqlite-mcp-server": {
843-
"command": "python",
844-
"args": [
845-
"/path/to/sqlite-mcp-server/start_sqlite_mcp.py",
846-
"--db-path", "/path/to/your/database.db"
847-
]
848-
}
849-
}
850-
}
851-
```
852-
853-
**For Docker**:
854-
```json
855-
{
856-
"mcpServers": {
857-
"sqlite-mcp-server": {
858-
"command": "docker",
859-
"args": [
860-
"run", "-i", "--rm",
861-
"-v", "/host/project:/workspace",
862-
"ghcr.io/neverinfamous/sqlite-mcp-server:latest",
863-
"--db-path", "/workspace/database.db"
864-
]
865-
}
866-
}
867-
}
868-
```
869-
870-
## JSON Validation and JSONB Support
871-
872-
### JSON Validation System
873-
874-
The SQLite MCP Server includes comprehensive JSON validation capabilities:
875-
876-
1. **Automatic JSON Field Validation**:
877-
- Validates formatting across all JSON fields in 32 columns
878-
- Ensures valid JSON structure during operations
879-
- Reports malformed JSON through notifications
880-
881-
2. **Validation Triggers**:
882-
- Automatically created SQLite triggers for INSERT/UPDATE operations
883-
- Prevents invalid JSON from being inserted or updated
884-
- Covers 16 tables with JSON/JSONB columns
885-
886-
3. **Repair Capabilities**:
887-
- Attempts to repair malformed JSON when found
888-
- Preserves as much data as possible during repairs
889-
- Records repair attempts in maintenance logs
890-
891-
### JSONB Binary Storage Migration
892-
893-
The migration to JSONB is transparent to users - simply continue using standard JSON operations as shown in the examples.
894-
895877
## Virtual Table Management
896878

897879
The SQLite MCP Server provides comprehensive virtual table management capabilities, supporting multiple virtual table types for specialized data access patterns and performance optimization.
@@ -1694,16 +1676,6 @@ MCP Prompts provide intelligent workflow automation, acting as "recipes" that gu
16941676
**Consistency**: Standardized approaches to common database operations
16951677
**Efficiency**: Eliminates repetitive queries for metadata and schema information
16961678

1697-
## Planned Future Enhancements
1698-
1699-
#### **1. Advanced Data Connectors - LOW PRIORITY**
1700-
- **Planned**: Direct database connectors (PostgreSQL, MySQL, MongoDB)
1701-
- **Examples**: Cross-database queries, data synchronization
1702-
1703-
#### **2. Real-time Data Streaming - LOW PRIORITY**
1704-
- **Planned**: Live data ingestion from streaming sources
1705-
- **Examples**: Kafka, WebSocket, API polling integration
1706-
17071679
## Contributing
17081680

17091681
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to get started.

0 commit comments

Comments
 (0)