mcp-sqlite-memory-bank 1.2.3__tar.gz → 1.3.0__tar.gz

{mcp_sqlite_memory_bank-1.2.3/src/mcp_sqlite_memory_bank.egg-info → mcp_sqlite_memory_bank-1.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mcp_sqlite_memory_bank
-Version: 1.2.3
-Summary: A dynamic, agent/LLM-friendly SQLite memory bank for MCP servers.
+Version: 1.3.0
+Summary: A dynamic, agent/LLM-friendly SQLite memory bank for MCP servers with semantic search capabilities.
 Author-email: Robert Meisner <robert@catchit.pl>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/robertmeisner/mcp_sqlite_memory_bank
@@ -45,6 +45,60 @@ This project provides a robust, discoverable API for creating, exploring, and ma
 
 ---
 
+## Quick Start
+
+Get started with SQLite Memory Bank in your IDE in under 2 minutes:
+
+### 1. Install and Run
+```bash
+# Install uvx if you don't have it
+pip install uvx
+
+# Run SQLite Memory Bank
+uvx mcp-sqlite-memory-bank
+```
+
+### 2. Configure Your IDE
+
+**VS Code / Cursor:** Add to `.vscode/mcp.json`:
+```jsonc
+{
+  "servers": {
+    "SQLite_Memory": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--refresh", "mcp-sqlite-memory-bank"],
+      "env": {
+        "DB_PATH": "${workspaceFolder}/.vscode/project_memory.sqlite"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop:** Add to `claude_desktop_config.json`:
+```jsonc
+{
+  "mcpServers": {
+    "sqlite_memory": {
+      "command": "uvx",
+      "args": ["mcp-sqlite-memory-bank"],
+      "env": {
+        "DB_PATH": "/path/to/your/memory.db"
+      }
+    }
+  }
+}
+```
+
+### 3. Test It
+Restart your IDE and try asking your AI assistant:
+> "Create a table called 'notes' with columns 'id' (integer, primary key) and 'content' (text). Then add a note saying 'Hello SQLite Memory Bank!'"
+
+✅ You should see the AI using the SQLite Memory Bank tools to create the table and add the note!
+
+---
+
 ## Features
 
 - **Dynamic Table Management:** Create, list, describe, rename, and drop tables at runtime
@@ -86,6 +140,22 @@ Each tool validates inputs and returns consistent response formats with success/
 
 ---
 
+## Transport Modes
+
+### Stdio Mode (Default)
+- **Use case**: MCP clients (VS Code, Claude Desktop, etc.)
+- **Protocol**: JSON-RPC over stdin/stdout
+- **Command**: `uvx mcp-sqlite-memory-bank`
+- **Benefits**: Direct integration with AI assistants and IDEs
+
+### HTTP Mode (Development)
+- **Use case**: Development, testing, web APIs
+- **Protocol**: HTTP REST API
+- **Command**: `python -m mcp_sqlite_memory_bank.server main --port 8000`
+- **Benefits**: Web browser access, curl testing, API integration
+
+---
+
 ## Installation & Transport Options
 
 **Requirements:**
@@ -111,134 +181,133 @@ python -m pip install --user pipx
 pipx run mcp_sqlite_memory_bank
 ```
 
-### Option 4: Run via UVX
+### Option 4: Run via UVX (Recommended for MCP clients)
 ```bash
-# Install UVX if you don't have it
-curl -fsSL https://uvx.zip/install.sh | bash
-
-# Run directly without installation
-uvx run mcp_sqlite_memory_bank
+# Run directly with latest version (recommended)
+uvx mcp-sqlite-memory-bank
 
-# Or, specify a version
-uvx run mcp_sqlite_memory_bank@latest
+# Force refresh to get latest updates
+uvx --refresh mcp-sqlite-memory-bank
 ```
 
-### Option 5: Docker (Containerized) # Coming soon - not yet implemented
-```bash
-# Pull the image
-docker pull robertmeisner/mcp_sqlite_memory_bank:latest
-
-# Run with stdio transport (for Claude Desktop)
-docker run -i --rm \
-  --mount type=bind,src=/path/to/data/dir,dst=/data \
-  robertmeisner/mcp_sqlite_memory_bank:latest stdio
-
-# Run with HTTP transport (for API access) 
-docker run -p 8000:8000 --rm \
-  --mount type=bind,src=/path/to/data/dir,dst=/data \
-  robertmeisner/mcp_sqlite_memory_bank:latest http
-```
+---
 
 ### Transport Options
 
-SQLite Memory Bank currently supports:
+SQLite Memory Bank currently supports **stdio transport** for MCP clients:
 
-- **stdio** (default): For direct integration with Claude Desktop and other MCP clients
-
-Planned transport options (not yet implemented):
-- **http**: For web access and API usage
-- **streamable-http**: For the latest MCP specification
+**Stdio Transport (Default - for MCP clients like VS Code, Claude Desktop):**
+```bash
+uvx mcp-sqlite-memory-bank
+```
 
-Run with the default transport:
+**HTTP Transport (Development/Testing only):**
 ```bash
-python -m mcp_sqlite_memory_bank.server
+python -m mcp_sqlite_memory_bank.server main --host 127.0.0.1 --port 8000
 ```
 
 ---
 
 ## Setup and Configuration
 
-You can configure the database path and other options via environment variables or a `.env` file in your project root.
+### Database Location
+
+**Default Behavior (v1.2.5+):**
+- **User-specific database**: `~/.mcp_sqlite_memory/memory.db`
+- **Isolated per user**: Each user gets their own database
+- **Persistent across projects**: Data is preserved between sessions
+
+**Custom Database Paths:**
+You can configure a custom database location via the `DB_PATH` environment variable:
+
+- **Project-specific**: `DB_PATH=./project_memory.db`
+- **Shared team database**: `DB_PATH=/shared/team_memory.db`
+- **Temporary database**: `DB_PATH=/tmp/session_memory.db`
 
 **Environment Variables:**
-- `DB_PATH`: Path to the SQLite database file (default: `./test.db`)
-- Any other options supported by the server (see API docs)
+- `DB_PATH`: Path to the SQLite database file (default: `~/.mcp_sqlite_memory/memory.db`)
 
 **Example `.env`:**
 ```env
-DB_PATH=./test.db
+# Use project-specific database
+DB_PATH=./project_memory.db
+
+# Or use a specific location
+DB_PATH=/path/to/my/memory.db
 ```
 
+**Migration Note:**
+If you were using v1.2.4 or earlier, your data was stored in `./test.db` in the current working directory. To migrate your data:
+
+1. Locate your old `test.db` file
+2. Copy it to the new default location: `~/.mcp_sqlite_memory/memory.db`
+3. Or set `DB_PATH` to point to your existing database
+
 ---
 
 ## Integration with Editors & Agent Platforms
 
 ### VS Code Integration
 
-#### Quick Install
-[Install with Python Module in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=sqlite-memory&config=%7B%22command%22%3A%22python%22%2C%22args%22%3A%5B%22-m%22%2C%22mcp_sqlite_memory_bank%22%5D%7D)
-
-[Install with Docker in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=sqlite-memory&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fdata%22%2C%22robertmeisner%2Fmcp_sqlite_memory_bank%3Alatest%22%5D%7D)
-
 #### Manual Configuration
 
-Add or update `.vscode/mcp.json` in your project root:
+**Option 1: Use Default User Database (Recommended)**
 ```jsonc
 {
   "servers": {
     "SQLite_Memory": {
       "type": "stdio",
-      "command": "python",
-      "args": ["-m", "mcp_sqlite_memory_bank.server"],
-      "env": {
-        "DB_PATH": "${workspaceFolder}/data/memory.db"
-      }
+      "command": "uvx",
+      "args": ["--refresh", "mcp-sqlite-memory-bank"]
     }
   }
 }
 ```
 
-## FastMCP Integration (Planned)
-
-```bash
-# Coming soon - not yet implemented
-fastmcp install mcp_sqlite_memory_bank/server.py --name "SQLite Memory Bank"
+**Option 2: Project-Specific Database**
+```jsonc
+{
+  "servers": {
+    "SQLite_Memory": {
+      "type": "stdio",
+      "command": "uvx", 
+      "args": ["--refresh", "mcp-sqlite-memory-bank"],
+      "env": {
+        "DB_PATH": "${workspaceFolder}/.mcp_memory.db"
+      }
+    }
+  }
+}
 ```
 
-### Claude Desktop Integration
-
-Add to your `claude_desktop_config.json`:
-
+**Option 3: Custom Database Location**
 ```jsonc
 {
-  "mcpServers": {
-    "sqlite_memory": {
-      "command": "python",
-      "args": ["-m", "mcp_sqlite_memory_bank.server"],
+  "servers": {
+    "SQLite_Memory": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--refresh", "mcp-sqlite-memory-bank"],
       "env": {
-        "DB_PATH": "/path/to/your/memory.db"
+        "DB_PATH": "/path/to/your/custom/memory.db"
       }
     }
   }
 }
 ```
 
-#### Docker Option for Claude Desktop
+### Claude Desktop Integration
+
+Add to your `claude_desktop_config.json`:
 
 ```jsonc
 {
   "mcpServers": {
     "sqlite_memory": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "--mount", "type=bind,src=/path/to/data/dir,dst=/data",
-        "robertmeisner/mcp_sqlite_memory_bank:latest"
-      ],
+      "command": "uvx",
+      "args": ["mcp-sqlite-memory-bank"],
       "env": {
-        "DB_PATH": "/data/memory.db"
+        "DB_PATH": "/path/to/your/memory.db"
       }
     }
   }
@@ -252,36 +321,28 @@ Add to your `claude_desktop_config.json`:
 
 ## Running the Server
 
-### Transport Options
+### MCP Stdio Mode (Recommended)
 
-SQLite Memory Bank currently supports stdio transport only:
+For use with VS Code, Claude Desktop, and other MCP clients:
 
-**Stdio Transport (Default - for Claude Desktop):**
 ```bash
-python -m mcp_sqlite_memory_bank.server
-```
+# Run with uvx (automatically gets latest version)
+uvx mcp-sqlite-memory-bank
 
-**HTTP Transport (REST API - Planned):**
-```bash
-# Coming soon - not yet implemented
-python -m mcp_sqlite_memory_bank.server http --port 8000
+# Force refresh to latest version
+uvx --refresh mcp-sqlite-memory-bank
 ```
 
-**Streamable HTTP Transport (Latest MCP Spec - Planned):**
-```bash
-# Coming soon - not yet implemented
-python -m mcp_sqlite_memory_bank.server streamable-http --port 8000
-```
+### Development/Testing Modes
 
-**With the example runner:**
+**HTTP Server Mode (for development and testing):**
 ```bash
-python examples/run_server.py
+python -m mcp_sqlite_memory_bank.server main --port 8000
 ```
 
-**With FastMCP (Planned):**
+**Direct Python Module:**
 ```bash
-# Coming soon - not yet implemented
-fastmcp install mcp_sqlite_memory_bank/server.py --name "SQLite Memory Bank"
+python -m mcp_sqlite_memory_bank.server
 ```
 
 ---
@@ -403,6 +464,43 @@ For a complete agent memory implementation example, see [examples/agent_memory_e
 
 ---
 
+## Troubleshooting
+
+### Common MCP Connection Issues
+
+**Server not starting / Connection timeout:**
+```bash
+# Force refresh uvx cache and try again
+uvx --refresh mcp-sqlite-memory-bank
+
+# Check if the command works directly
+uvx mcp-sqlite-memory-bank --help
+```
+
+**VS Code: "Server exited before responding to initialize request":**
+1. Check the MCP configuration in `.vscode/mcp.json`
+2. Ensure `uvx` is installed and in your PATH
+3. Try restarting VS Code or running "MCP: Restart Server" from Command Palette
+
+**Tools not appearing in IDE:**
+1. Verify the server is running: `uvx mcp-sqlite-memory-bank` should start without errors
+2. Check that `"type": "stdio"` is set in your MCP configuration
+3. Restart your IDE or reload MCP configuration
+
+**Database permission errors:**
+- Ensure the directory for `DB_PATH` exists and is writable
+- Check file permissions on the SQLite database file
+- Use absolute paths in `DB_PATH` to avoid path resolution issues
+
+**Package not found / outdated version:**
+```bash
+# Clear uvx cache completely
+uvx cache remove mcp-sqlite-memory-bank
+uvx mcp-sqlite-memory-bank
+```
+
+---
+
 
 ## Running Tests