# 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