Security hardening: token validation, docs, release guide

README.md

@@ -2,14 +2,36 @@
 
 All things related to [Taskade](https://taskade.com/)'s MCP (Model Context Protocol) initiatives.
 
-- [Official MCP server](https://github.com/taskade/mcp/tree/main/packages/server) - Connect Taskade’s API to any MCP-compatible client like Claude or Cursor.
+- [Official MCP server](https://github.com/taskade/mcp/tree/main/packages/server) - Connect Taskade's API to any MCP-compatible client like Claude or Cursor.
 - [OpenAPI Codegen](https://github.com/taskade/mcp/tree/main/packages/openapi-codegen) - Generate MCP tools from any OpenAPI schema in minutes.
 
 ## ⚡ Taskade MCP Demo
 MCP-powered Taskade agent running inside Claude Desktop by Anthropic:
 
 ![Image](https://github.com/user-attachments/assets/0cee987b-b0d4-4d10-bb7f-da49a080d731)
 
+## 📖 Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Claude Desktop Setup](./docs/CLAUDE_DESKTOP_CONFIG.md) | Configure Claude Desktop with Taskade MCP |
+| [Cursor SSE Setup](./docs/CURSOR_SSE_CONFIG.md) | Configure Cursor with SSE transport |
+| [Security Policy](./SECURITY.md) | Token handling and security best practices |
+
+## 🔐 Security
+
+This project handles API tokens that provide access to your Taskade workspace. Please follow these security practices:
+
+| Practice | Requirement |
+|----------|-------------|
+| Token Storage | Environment variables only — never hardcode |
+| Version Control | `.env` files are gitignored — never commit tokens |
+| Transport | Use HTTPS for SSE/HTTP mode in production |
+| Rotation | Rotate tokens quarterly or after suspected exposure |
+
+Generate your Personal Access Token at [Taskade Settings](https://www.taskade.com/settings/password).
+
+For detailed security guidelines, see [SECURITY.md](./SECURITY.md).
 
 ## 🛠 Codegen for OpenAPI
 

SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Reporting a Vulnerability
+Do not disclose publicly. Use a private security channel.
+
+## Secrets Handling
+Never commit secrets. Use environment variables only.
+
+## Transport Security
+Prefer HTTPS/TLS for all network communication.
+
+## Rotation
+Rotate secrets immediately if compromised.

docs/CLAUDE_DESKTOP_CONFIG.md

@@ -0,0 +1,144 @@
+# Claude Desktop Integration Guide
+
+This guide explains how to configure Claude Desktop to use the Taskade MCP Server.
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| Claude Desktop | Latest version installed |
+| Taskade Account | Active account with API access |
+| Personal Access Token | Generated from Taskade settings |
+| Node.js | v20 or later (for local development) |
+
+## Generate Your Taskade API Token
+
+1. Navigate to [Taskade Settings](https://www.taskade.com/settings/password)
+2. Scroll to "Personal Access Tokens"
+3. Click "Generate New Token"
+4. Copy the token immediately (shown only once)
+5. Store securely — never commit to version control
+
+## Configuration Methods
+
+### Method 1: NPX (Recommended)
+
+Use the published npm package — no local installation required.
+
+**Config file location:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "taskade": {
+      "command": "npx",
+      "args": ["-y", "@taskade/mcp-server"],
+      "env": {
+        "TASKADE_API_KEY": "your_taskade_personal_access_token_here"
+      }
+    }
+  }
+}
+```
+
+### Method 2: Local Development
+
+For development or customization, run from a local clone.
+
+**Steps:**
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/taskade/mcp.git
+   cd mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+3. Build:
+   ```bash
+   pnpm run build
+   ```
+
+4. Configure Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "taskade": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp/packages/server/bin/cli.mjs"],
+      "env": {
+        "TASKADE_API_KEY": "your_taskade_personal_access_token_here"
+      }
+    }
+  }
+}
+```
+
+**Important:** Replace `/absolute/path/to/mcp` with the actual path to your cloned repository.
+
+## Verify Installation
+
+1. Restart Claude Desktop after saving configuration
+2. Open a new conversation
+3. Claude should now have access to Taskade tools
+4. Test with: "List my Taskade workspaces"
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `workspacesGet` | List all workspaces |
+| `workspaceFoldersGet` | List folders in a workspace |
+| `folderProjectsGet` | List projects in a folder |
+| `projectGet` | Get project details |
+| `projectTasksGet` | List tasks in a project |
+| `taskCreate` | Create a new task |
+| `taskComplete` | Mark a task complete |
+| `taskPut` | Update a task |
+
+See [constants.ts](../packages/server/src/constants.ts) for the complete list of 21 enabled tools.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "TASKADE_API_KEY not set" | Verify env variable in config |
+| Tools not appearing | Restart Claude Desktop |
+| Permission errors | Verify token has required scopes |
+| Connection timeout | Check network/firewall settings |
+
+### Debug Mode
+
+To see server logs, run manually in terminal:
+
+```bash
+TASKADE_API_KEY="your_token" npx -y @taskade/mcp-server
+```
+
+Or for local builds:
+
+```bash
+TASKADE_API_KEY="your_token" node /path/to/packages/server/bin/cli.mjs
+```
+
+## Security Notes
+
+- Never share your API token
+- Token is passed via environment variable, not stored in code
+- See [SECURITY.md](../SECURITY.md) for token rotation procedures
+- For production deployments, rotate tokens quarterly
+
+## Related Documentation
+
+- [Cursor SSE Configuration](./CURSOR_SSE_CONFIG.md)
+- [Security Policy](../SECURITY.md)
+- [Taskade API Documentation](https://developers.taskade.com)

docs/CURSOR_SSE_CONFIG.md

@@ -0,0 +1,170 @@
+# Cursor SSE Integration Guide
+
+This guide explains how to configure Cursor to use the Taskade MCP Server via SSE (Server-Sent Events).
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| Cursor | Latest version with MCP support |
+| Taskade Account | Active account with API access |
+| Personal Access Token | Generated from Taskade settings |
+| Node.js | v20 or later |
+
+## Generate Your Taskade API Token
+
+1. Navigate to [Taskade Settings](https://www.taskade.com/settings/password)
+2. Scroll to "Personal Access Tokens"
+3. Click "Generate New Token"
+4. Copy the token immediately (shown only once)
+5. Store securely — never commit to version control
+
+## Configuration Methods
+
+### Method 1: NPX with stdio (Simple)
+
+For basic integration without running a server.
+
+**Config file location:** `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "taskade": {
+      "command": "npx",
+      "args": ["-y", "@taskade/mcp-server"],
+      "env": {
+        "TASKADE_API_KEY": "your_taskade_personal_access_token_here"
+      }
+    }
+  }
+}
+```
+
+### Method 2: SSE/HTTP (Advanced)
+
+For clients that support SSE connections. Requires running a local server.
+
+**Step 1: Clone and build**
+
+```bash
+git clone https://github.com/taskade/mcp.git
+cd mcp
+pnpm install
+pnpm run build
+```
+
+**Step 2: Start the HTTP server**
+
+```bash
+cd packages/server
+pnpm run start:server
+```
+
+The server will start on port 3000.
+
+**Step 3: Configure Cursor**
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "taskade": {
+      "url": "http://localhost:3000/sse?access_token=your_taskade_personal_access_token_here"
+    }
+  }
+}
+```
+
+## Security Considerations
+
+⚠️ **IMPORTANT:** The SSE/HTTP mode passes your access token as a URL query parameter.
+
+| Risk | Mitigation |
+|------|------------|
+| Token in URL | Use HTTPS in production |
+| Token in logs | Configure server to not log URLs |
+| Token exposure | Only use on localhost or behind TLS |
+
+For production deployments, place the server behind a reverse proxy with HTTPS.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `workspacesGet` | List all workspaces |
+| `workspaceFoldersGet` | List folders in a workspace |
+| `folderProjectsGet` | List projects in a folder |
+| `projectGet` | Get project details |
+| `projectTasksGet` | List tasks in a project |
+| `taskCreate` | Create a new task |
+| `taskComplete` | Mark a task complete |
+| `taskPut` | Update a task |
+
+See [constants.ts](../packages/server/src/constants.ts) for the complete list of 21 enabled tools.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Connection refused | Verify server is running on port 3000 |
+| "Access token required" | Check token in URL query param |
+| Tools not appearing | Restart Cursor after config change |
+| CORS errors | Not applicable for SSE transport |
+
+### Verify Server is Running
+
+```bash
+curl -v "http://localhost:3000/sse?access_token=test"
+```
+
+Expected: SSE connection established (will hang waiting for events).
+
+### View Server Logs
+
+The server outputs to stderr. When starting with `pnpm run start:server`, you'll see:
+
+```
+⚠️  SECURITY WARNING: HTTP/SSE mode passes access tokens via query parameters.
+   For production use, ensure this server is behind HTTPS/TLS.
+   Tokens in HTTP URLs may be logged or intercepted.
+   See SECURITY.md for best practices.
+```
+
+This warning is expected and reminds you to use HTTPS in production.
+
+## Production Deployment
+
+For production use:
+
+1. Deploy behind HTTPS reverse proxy (nginx, Caddy, etc.)
+2. Use environment variables for token (not URL params)
+3. Implement rate limiting
+4. Enable access logging (without tokens)
+
+Example nginx configuration:
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name mcp.yourdomain.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location /sse {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_buffering off;
+        proxy_cache off;
+    }
+}
+```
+
+## Related Documentation
+
+- [Claude Desktop Configuration](./CLAUDE_DESKTOP_CONFIG.md)
+- [Security Policy](../SECURITY.md)
+- [Taskade API Documentation](https://developers.taskade.com)