https://claude.ai/chat/4dea4e6a-4f62-44b0-8a96-f87167a17fef
https://claude.ai/public/artifacts/8f2db72a-f062-4d0c-b64c-e7f4018910d6

cloudflared tunnel --url http://localhost:3001

   - Email: `test@example.com`
   - Password: `password123`

# PocketBase Task MCP Server

A Model Context Protocol (MCP) server that integrates with PocketBase to manage tasks and projects. This server allows AI models (like Claude) to create tasks, list tasks with status filters, and browse projects.

**Now running over HTTP** - Easy to test locally and ready for deployment!

## Features

- **HTTP Transport**: Simple URL-based access, no complex configuration needed
- **Tool Chaining**: Automatically links tasks to projects by fetching IDs first
- **Project Management**: List all projects from the `projects` collection
- **Task Management**: Create tasks in the `task` collection with mandatory project relationships
- **Status Filtering**: List tasks and filter by 'Pending' or 'Completed' status
- **Environment Driven**: Securely managed via `.env` file for PocketBase authentication
- **Easy Testing**: Simple health check endpoint and MCP Inspector support

---

## ⚡ Quick Start

```bash
# 1. Install dependencies
npm install

# 2. Create .env file
echo "PB_AUTH_TOKEN=your_super_admin_token_here" > .env

# 3. Build the project
npm run build

# 4. Start the server
node dist/index.js
```

Your server is now running at `http://localhost:3000`!

Test it: Open `http://localhost:3000/health` in your browser.

---

## 🚀 Getting Started

### 1. Prerequisites
- [Node.js](https://nodejs.org/) (v18+)
- [PocketBase](https://pocketbase.io/) running locally at `http://127.0.0.1:8090`
- A PocketBase Super Admin token.

### 2. Installation
```bash
npm install
```

### 3. Configuration
Create a `.env` file in the project root:
```env
PB_AUTH_TOKEN=your_super_admin_token_here
```

---

## 🛠️ Development & Debugging

### Build the Project
Compile the TypeScript code into JavaScript:
```bash
npm run build
```

### Start the HTTP Server
Run the server locally:
```bash
node dist/index.js
```

The server will start on `http://localhost:3000` (or the port specified in your `.env` file).

You should see output like:
```
MCP server running on http://localhost:3000
Health check: http://localhost:3000/health
MCP endpoint: http://localhost:3000/mcp
```

### Test the Server
Visit the health check endpoint in your browser:
```
http://localhost:3000/health
```

You should see:
```json
{"status":"ok","message":"PMS MCP Server is running"}
```

### Optional Port Configuration
Add to your `.env` file to change the port:
```env
PORT=3000
PB_AUTH_TOKEN=your_super_admin_token_here
```

---

## 📖 Available Tools

- `list_projects`: Fetch all projects and their IDs.
- `create_task`: Create a new task (requires `task_title`, `eta`, `status`, and `project_id`).
- `list_tasks`: List all tasks with optional status filtering.

## 🧪 Testing the Tools

You can test the MCP server using the MCP Inspector or by connecting via the HTTP endpoint at `http://localhost:3000/mcp`.

### Using MCP Inspector
```bash
npx @modelcontextprotocol/inspector
```

Then connect to: `http://localhost:3000/mcp`

## 🌐 Why HTTP Over Stdio?

### Advantages:
- **No Configuration Files**: No need to edit `claude_desktop_config.json` or other complex configs
- **Easy Testing**: Simple URL access via browser or tools like Postman
- **Remote Ready**: Can be deployed to a server and accessed from anywhere
- **Multiple Clients**: Multiple applications can connect simultaneously
- **Better Debugging**: Easy to monitor requests and responses with standard HTTP tools

### Connecting from MCP Clients:
When using MCP-compatible clients, connect to:
```
http://localhost:3000/mcp
```

## 📝 Dependencies
- `@modelcontextprotocol/sdk`: Core MCP functionality
- `pocketbase`: PocketBase JS SDK
- `express`: HTTP server framework
- `cors`: Cross-Origin Resource Sharing middleware
- `zod`: Schema validation
- `dotenv`: Environment variable management