db4app-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 db4app
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,134 @@
+# @db4app/mcp-server
+
+MCP server for db4.app - enables LLMs to interact with browser-based Postgres databases via Model Context Protocol.
+
+## Installation
+
+```bash
+npm install -g @db4app/mcp-server
+```
+
+Or use with `npx` (no installation needed):
+
+```bash
+npx @db4app/mcp-server
+```
+
+## Usage
+
+### With LM Studio
+
+1. Locate your `mcp.json` file:
+   - **macOS:** `~/Library/Application Support/LM Studio/mcp.json`
+   - **Windows:** `%APPDATA%\LM Studio\mcp.json`
+   - **Linux:** `~/.config/LM Studio/mcp.json`
+
+2. Add this to the `mcpServers` object in your `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "postgres-wasm": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@db4app/mcp-server"
+      ],
+      "env": {
+        "MCP_PROXY_HTTP_URL": "http://localhost:8787/query",
+        "LM_STUDIO_EMBEDDING_URL": "http://localhost:1234/v1/embeddings",
+        "LM_STUDIO_EMBEDDING_MODEL": "text-embedding-qwen3-embedding-4b",
+        "MCP_ALLOWED_TABLES": "rag_mcp.documents",
+        "MCP_PUBLIC_KEY": "YOUR_PUBLIC_KEY_HERE",
+        "MCP_USE_ENCRYPTION": "true"
+      }
+    }
+  }
+}
+```
+
+**Note**: Replace `YOUR_PUBLIC_KEY_HERE` with your actual public key from the Database page → Management tab → Encryption section.
+
+3. **Install an Embedding Model** (Required for RAG features):
+   - Open LM Studio → Search tab
+   - Search for embedding models (e.g., "bge", "e5", "text-embedding")
+   - Download and load an embedding-capable model
+   - Update `LM_STUDIO_EMBEDDING_MODEL` in your `mcp.json` with the exact model name
+   - Enable headless server mode in LM Studio
+
+4. Restart LM Studio to load the configuration.
+
+### With Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "postgres-wasm": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@db4app/mcp-server"
+      ],
+      "env": {
+        "MCP_PROXY_HTTP_URL": "http://localhost:8787/query",
+        "LM_STUDIO_EMBEDDING_URL": "http://localhost:1234/v1/embeddings",
+        "LM_STUDIO_EMBEDDING_MODEL": "text-embedding-qwen3-embedding-4b",
+        "MCP_ALLOWED_TABLES": "rag_mcp.documents",
+        "MCP_PUBLIC_KEY": "YOUR_PUBLIC_KEY_HERE",
+        "MCP_USE_ENCRYPTION": "true"
+      }
+    }
+  }
+}
+```
+
+**Note**: Replace `YOUR_PUBLIC_KEY_HERE` with your actual public key from the Database page → Management tab → Encryption section.
+
+## Configuration
+
+All configuration is done via environment variables:
+
+- `MCP_PROXY_HTTP_URL` - HTTP proxy endpoint (default: `http://localhost:8787/query`)
+- `LM_STUDIO_EMBEDDING_URL` - LM Studio embedding API endpoint (default: `http://localhost:1234/v1/embeddings`)
+- `LM_STUDIO_EMBEDDING_MODEL` - Optional model name for embeddings
+- `MCP_ALLOWED_TABLES` - **Required for recipes**: Comma-separated list of allowed tables (e.g., `"schema.table1,schema.table2"`). The proxy validates all SQL queries against this whitelist. If not set, the MCP server can access all tables (for direct use, not recommended for recipes).
+- `MCP_PUBLIC_KEY` - **Optional**: Base64-encoded public key for end-to-end encryption. If not provided, the MCP server will attempt to fetch it from the proxy's `/public-key` endpoint. Get your public key from the Database page → Management tab → Encryption section.
+- `MCP_USE_ENCRYPTION` - Enable end-to-end encryption (default: `true` if `MCP_PUBLIC_KEY` is set, otherwise `false`). When enabled, all SQL queries are encrypted with RSA-OAEP before being sent to the proxy, ensuring the proxy cannot decrypt them.
+
+## Available Tools
+
+- `query_database` - Execute SQL queries (respects `MCP_ALLOWED_TABLES` if set)
+- `list_tables` - List tables in the database (only shows whitelisted tables if `MCP_ALLOWED_TABLES` is set)
+- `remember` - Store information in memory with automatic embedding (requires `MCP_ALLOWED_TABLES` for recipe use)
+- `search_memory` - Search through stored memories using semantic similarity (requires `MCP_ALLOWED_TABLES` for recipe use)
+
+**Note**: When used with recipes, `MCP_ALLOWED_TABLES` must be set to restrict access to only the recipe's tables. The proxy server validates all queries against this whitelist.
+
+## End-to-End Encryption
+
+This MCP server supports end-to-end encryption of SQL queries using RSA-OAEP (2048-bit). When encryption is enabled:
+
+- SQL queries are encrypted in the MCP server using the browser's public key
+- The proxy server relays encrypted queries without being able to decrypt them
+- Only the browser (with the private key) can decrypt and execute queries
+- This ensures complete privacy: even the proxy cannot see your SQL queries
+
+To enable encryption:
+1. Get your public key from the Database page → Management tab → Encryption section
+2. Set `MCP_PUBLIC_KEY` to your public key (base64 string)
+3. Set `MCP_USE_ENCRYPTION` to `"true"`
+
+If `MCP_PUBLIC_KEY` is not provided, the MCP server will automatically fetch it from the proxy's `/public-key` endpoint.
+
+## Requirements
+
+- Node.js 18+
+- Postgres WASM proxy running (default: `http://localhost:8787/query`)
+- For RAG features: LM Studio with embedding-capable model loaded
+
+## License
+
+MIT
+