db4app Todo MCP Server

# db4app-todo-mcp-server MCP server for db4.app todo list app - enables LLMs to manage todos via Model Context Protocol using the Postgres TCP protocol. ## Installation ```bash npm install -g db4app-todo-mcp-server ``` Or use with `npx` (no installation needed): ```bash npx db4app-todo-mcp-server ``` ## Usage **Important**: This MCP server uses the **Postgres TCP protocol** to connect directly to your browser database, just like `psql` or other Postgres clients. It uses TLS encryption and password authentication. ### 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. **Get your Connection ID and Auth Token:** - Open the Database page in your browser - Your **Connection ID** is displayed in the Connection Info section - Your **Auth Token** is also shown in the Connection Info section (this is your password) 3. **Install the todo-mcp app** from the Community Apps page in db4.app 4. **Add this to the `mcpServers` object in your `mcp.json`:** ```json { "mcpServers": { "db4app-todo": { "command": "npx", "args": [ "-y", "db4app-todo-mcp-server@latest" ], "env": { "MCP_POSTGRES_URL": "postgres://postgres:YOUR_AUTH_TOKEN@YOUR_CONNECTION_ID.pg.db4.app", "MCP_SCHEMA": "todo_mcp" } } } } ``` **Important Notes:** - Replace `YOUR_AUTH_TOKEN` with your actual auth token from step 2 - Replace `YOUR_CONNECTION_ID` with your Connection ID from step 2 - The connection string format is: `postgres://postgres:AUTH_TOKEN@CONNECTION_ID.pg.db4.app` - Each browser tab has its own unique Connection ID and Auth Token - make sure you use the correct ones - **Postgres TCP Protocol**: The MCP server uses the standard Postgres wire protocol with TLS encryption, just like `psql` or DBeaver 5. **Restart LM Studio** to load the new MCP server configuration. ### With Claude Desktop 1. **Locate your Claude Desktop config:** - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - **Linux:** `~/.config/Claude/claude_desktop_config.json` 2. **Add the same configuration** as above to the `mcpServers` object. 3. **Restart Claude Desktop.** ## Available Tools ### `add_todo` Add a new todo item to the list. **Parameters:** - `title` (required): The title of the todo item - `description` (optional): Additional details - `category` (optional): Category name (e.g., "Work", "Personal", "Shopping") - `priority` (optional): Priority level (0=normal, 1=high, 2=urgent, default: 0) - `due_date` (optional): Due date in ISO format (e.g., "2024-12-31T23:59:59Z") **Example usage:** ``` "Add a todo to finish the project report by end of month, high priority, in the Work category" ``` ### `mark_as_done` Mark a todo item as completed. **Parameters:** - `todo_id` (required): The ID of the todo to mark as done **Example usage:** ``` "Mark todo #5 as done" "Complete the todo about finishing the report" ``` ### `list_todos` List all todos with optional filters. **Parameters:** - `show_completed` (optional): Show completed todos (default: true) - `category` (optional): Filter by category name - `priority` (optional): Filter by priority level (0, 1, or 2) **Example usage:** ``` "Show me all my pending todos" "List all high priority todos in the Work category" "What todos do I have due today?" ``` ### `remove_todo` Delete a todo item. **Parameters:** - `todo_id` (required): The ID of the todo to remove **Example usage:** ``` "Delete todo #3" "Remove the todo about buying groceries" ``` ## Environment Variables - `MCP_POSTGRES_URL`: Postgres connection URL (format: `postgres://postgres:AUTH_TOKEN@CONNECTION_ID.pg.db4.app`) - `MCP_SCHEMA`: Schema name for todo tables (default: `todo_mcp`) - `MCP_CONNECTION_ID`: Browser connection ID (alternative to full URL) - `MCP_AUTH_TOKEN`: Auth token for authentication (alternative to full URL) ## Troubleshooting ### Connection Issues - **Postgres TCP Protocol**: The MCP server uses the standard Postgres wire protocol with TLS encryption, just like `psql` or DBeaver - **Connection String Format**: `postgres://postgres:AUTH_TOKEN@CONNECTION_ID.pg.db4.app` - **Auth Token Required**: You must provide the auth token in the connection string (it's your password) - **TLS Encryption**: Connections are automatically encrypted using TLS (no additional configuration needed) ### Password Authentication Failed If you see `FATAL: Password authentication failed`: 1. **Get your Auth Token**: Open the Database page → Connection Info section 2. **Use the exact token**: Copy the token and use it in your connection string 3. **Token persistence**: The token is auto-generated and stored in your browser's localStorage 4. **Single error message**: You should see only ONE error message. If you see multiple errors, please report it as a bug. ### Schema Not Found If you see errors about the schema not existing: 1. **Install the app**: Make sure you've installed the "Todo List with MCP" app from the Community Apps page 2. **Check schema name**: Verify `MCP_SCHEMA` matches the schema name (default: `todo_mcp`) 3. **Verify installation**: Run `SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'todo_mcp';` to confirm the schema exists ## License MIT