vscarpenter · vscarpenter · Oct 26, 2025 · Oct 26, 2025
@@ -55,3 +55,16 @@ sonar-project.properties
 worker/.wrangler
 worker/.dev.vars
 worker/wrangler.toml.local
+
+# Sensitive configuration files (prevent credential leaks)
+**/claude-config.json
+!**/claude-config.example.json
+packages/mcp-server/test-*.sh
+!packages/mcp-server/test-manual.sh
+!packages/mcp-server/test-setup.sh
+!packages/mcp-server/test-env-vars.js
+packages/mcp-server/debug-*.sh
+!packages/mcp-server/debug-*.example.sh
+worker/cf-dev-config.json
+*SETUP_GUIDE.md
+gitleaks-report.json
@@ -0,0 +1,55 @@
+# Source files (we only need dist/)
+src/
+tsconfig.json
+*.ts
+!*.d.ts
+
+# Documentation (keep only README.md and LICENSE)
+TESTING.md
+TESTING_V0.2.md
+QUICKSTART.md
+DECRYPTION.md
+DEPLOYMENT_COMPLETE.md
+README-SECURITY.md
+
+# Test scripts and configs (SECURITY: May contain hardcoded credentials)
+*.sh
+test-*.js
+test-*.json
+check-*.sh
+debug-*.sh
+claude-config*.json
+!*.example
+
+# Environment files
+.env
+.env.*
+.env.example
+
+# Development files
+node_modules/
+.DS_Store
+*.log
+npm-debug.log*
+.npmrc
+
+# Test files
+__tests__/
+*.test.js
+*.spec.js
+test/
+tests/
+
+# Build artifacts
+*.tsbuildinfo
+
+# Git files
+.git/
+.gitignore
+.gitattributes
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vinny Carpenter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -1,7 +1,37 @@
 # GSD Task Manager MCP Server
 
+[![npm version](https://badge.fury.io/js/gsd-mcp-server.svg)](https://www.npmjs.com/package/gsd-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Model Context Protocol (MCP) server for GSD Task Manager. Provides read-only access to your synced tasks through Claude Desktop and other MCP-compatible AI assistants.
 
+## Quick Start
+
+```bash
+# Install via npx (no installation needed!)
+npx gsd-mcp-server
+```
+
+Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gsd-tasks": {
+      "command": "npx",
+      "args": ["-y", "gsd-mcp-server"],
+      "env": {
+        "GSD_API_URL": "https://gsd.vinny.dev",
+        "GSD_AUTH_TOKEN": "your-jwt-token-here",
+        "GSD_ENCRYPTION_PASSPHRASE": "your-passphrase-here"
+      }
+    }
+  }
+}
+```
+
+See [Installation](#installation) section below for detailed setup instructions.
+
 ## Features
 
 **Metadata Access** (v0.1.0)
@@ -31,21 +61,24 @@ Model Context Protocol (MCP) server for GSD Task Manager. Provides read-only acc
 
 ## Installation
 
-### 1. Install Dependencies
+**Two installation options:**
 
-From the `packages/mcp-server` directory:
+### Option A: Use Published Package (Recommended)
 
-```bash
-npm install
-```
+No installation needed! Use `npx` to run the package directly from npm.
 
-### 2. Build the Server
+### Option B: Build from Source
 
-```bash
-npm run build
-```
+For development or if you want to modify the code:
+
+1. Clone the repository
+2. Navigate to `packages/mcp-server`
+3. Install dependencies: `npm install`
+4. Build the server: `npm run build`
 
-### 3. Get Your Auth Token
+## Setup
+
+### 1. Get Your Auth Token
 
 You'll need a JWT token from your GSD sync setup. Two options:
 
@@ -60,13 +93,33 @@ You'll need a JWT token from your GSD sync setup. Two options:
 2. Intercept the callback response
 3. Extract the `token` field from the JSON response
 
-### 4. Configure Claude Desktop
+### 2. Configure Claude Desktop
 
 Add the MCP server to your Claude Desktop config:
 
 **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
+**Using published package (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "gsd-tasks": {
+      "command": "npx",
+      "args": ["-y", "gsd-mcp-server"],
+      "env": {
+        "GSD_API_URL": "https://gsd.vinny.dev",
+        "GSD_AUTH_TOKEN": "your-jwt-token-here",
+        "GSD_ENCRYPTION_PASSPHRASE": "your-passphrase-here"
+      }
+    }
+  }
+}
+```
+
+**Using local build (for development):**
+
 ```json
 {
   "mcpServers": {
@@ -76,7 +129,7 @@ Add the MCP server to your Claude Desktop config:
         "/absolute/path/to/gsd-taskmanager/packages/mcp-server/dist/index.js"
       ],
       "env": {
-        "GSD_API_URL": "https://gsd-sync-worker-production.vscarpenter.workers.dev",
+        "GSD_API_URL": "https://gsd.vinny.dev",
         "GSD_AUTH_TOKEN": "your-jwt-token-here",
         "GSD_ENCRYPTION_PASSPHRASE": "your-passphrase-here"
       }
@@ -85,15 +138,16 @@ Add the MCP server to your Claude Desktop config:
 }
 ```
 
-**Important Notes**:
-- Replace `/absolute/path/to/gsd-taskmanager` with your actual project path
-- Use your Worker API URL (development, staging, or production)
-- Token will expire - you'll need to update it periodically (every 7 days)
+**Configuration Notes**:
+- Replace `your-jwt-token-here` with your actual token from Step 1
+- Replace `your-passphrase-here` with your sync encryption passphrase
+- `GSD_API_URL`: Use `https://gsd.vinny.dev` for production (or your custom Worker URL)
+- Token expires every 7 days - you'll need to update it periodically
 - **Optional**: Add `GSD_ENCRYPTION_PASSPHRASE` to enable decrypted task access (v0.2.0)
   - Without it: Only metadata tools work (sync status, devices, stats)
   - With it: Full task content access (list, search, read tasks)
 
-### 5. Restart Claude Desktop
+### 3. Restart Claude Desktop
 
 Close and reopen Claude Desktop to load the MCP server.
 
@@ -285,9 +339,11 @@ Search tasks by text query across titles, descriptions, tags, and subtasks. **Re
 - Try accessing the URL in your browser: `{GSD_API_URL}/health`
 
 ### "Cannot find module" error
-- Run `npm run build` to compile TypeScript
-- Check that the path in Claude config is absolute and correct
-- Verify that `dist/index.js` exists after building
+- **If using npx**: Ensure you have internet connection (npx needs to download the package)
+- **If using local build**:
+  - Run `npm run build` to compile TypeScript
+  - Check that the path in Claude config is absolute and correct
+  - Verify that `dist/index.js` exists after building
 
 ### "Encryption passphrase not provided" (v0.2.0)
 - This error appears when using decryption tools without the passphrase
@@ -320,13 +376,23 @@ npm run build
 
 **Testing Locally** (without Claude Desktop):
 ```bash
-export GSD_API_URL="https://sync.gsd.vinny.dev"
+export GSD_API_URL="https://gsd.vinny.dev"
 export GSD_AUTH_TOKEN="your-jwt-token"
+export GSD_ENCRYPTION_PASSPHRASE="your-passphrase"
 npm start
 ```
 
 Then send MCP protocol JSON over stdin (advanced).
 
+**Publishing to npm**:
+```bash
+# Update version (patch/minor/major)
+npm version patch
+
+# Publish (requires 2FA code)
+npm publish --access public --otp=YOUR_CODE
+```
+
 ## Future Enhancements
 
 **Write Operations** (v0.3.0)

@@ -1,25 +1,46 @@
 {
-  "name": "@gsd/mcp-server",
-  "version": "0.2.0",
+  "name": "gsd-mcp-server",
+  "version": "0.2.1",
   "description": "MCP server for GSD Task Manager - decrypted read-only access to synced tasks",
   "type": "module",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
     "gsd-mcp-server": "dist/index.js"
   },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/index.js"
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "mcp",
+    "model-context-protocol",
     "task-manager",
     "productivity",
-    "claude"
+    "claude",
+    "claude-desktop",
+    "eisenhower-matrix",
+    "encryption",
+    "privacy"
   ],
   "author": "Vinny Carpenter",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vscarpenter/gsd-taskmanager.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/vscarpenter/gsd-taskmanager#readme",
+  "bugs": {
+    "url": "https://github.com/vscarpenter/gsd-taskmanager/issues"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "zod": "^3.24.1"