@pollychrome/joan-mcp 1.0.0 → 1.0.1

package/README.md

@@ -12,212 +12,111 @@ Model Context Protocol (MCP) server for the Joan productivity app. Enables AI as
 
 ## Installation
 
-### Option 1: Global Install via npm link (Recommended for Development)
+### Option 1: npx (Recommended - No Install Required)
 
 ```bash
-cd mcp-server
-npm install
-npm run build
-npm link
-
-# Now available globally:
-joan-mcp init
+npx @pollychrome/joan-mcp init
 ```
 
-### Option 2: npm Install (After Publishing)
+This single command will:
+1. Open your browser to authenticate with Joan
+2. Store credentials securely on your machine
+3. Configure Claude Code automatically
+
+### Option 2: Global Install
 
 ```bash
-npm install -g @joan/mcp-server
+npm install -g @pollychrome/joan-mcp
 
-# Or run directly without installing:
-npx @joan/mcp-server init
+# Then run:
+joan-mcp init
 ```
 
 ### Option 3: From Source (Development)
 
 ```bash
-cd mcp-server
+git clone https://github.com/pollychrome/joan-mcp.git
+cd joan-mcp
 npm install
-npx tsx src/cli.ts init
+npm run build
+npm link
+joan-mcp init
 ```
 
-## Quick Start (Recommended)
-
-Run the setup wizard to authenticate and configure Claude Code in one command:
+## Quick Start
 
 ```bash
-# From source
-cd /path/to/Joan/mcp-server && npx tsx src/cli.ts init
-
-# Or after global install
-joan-mcp init
+npx @pollychrome/joan-mcp init
 ```
 
-This will:
-1. Open your browser to authenticate with Joan
-2. Store the token encrypted in `~/.joan-mcp/credentials.json`
-3. Automatically configure Claude Code to use Joan MCP
-
-After setup, restart Claude Code and you're ready to go!
-
-## Using Joan MCP in Other Projects
-
-Once you've completed the initial setup above, you can use Joan MCP from **any project repository**. This lets you create tasks, track progress, and manage your work directly while coding on other projects.
-
-### Option A: Global Configuration (Recommended)
+After setup, **restart Claude Code** and you're ready to go!
 
-Add Joan MCP to your global Claude Code settings so it's available in all projects:
-
-**Location:** `~/.claude/settings.json`
-
-```json
-{
-  "mcpServers": {
-    "joan": {
-      "command": "npx",
-      "args": ["tsx", "/Users/YOUR_USERNAME/Joan/mcp-server/src/cli.ts", "serve"]
-    }
-  }
-}
-```
+## Using Joan MCP in Any Project
 
-Replace `/Users/YOUR_USERNAME/Joan` with the actual path to your Joan repository.
+Once you run `npx @pollychrome/joan-mcp init`, Joan is automatically configured globally. It works in **any project** without additional setup.
 
-### Option B: Per-Project Configuration
+### Example Prompts
 
-Add Joan MCP to a specific project by creating/editing `.claude/settings.json` in that project's root:
+While working on any codebase, you can say:
 
-```json
-{
-  "mcpServers": {
-    "joan": {
-      "command": "npx",
-      "args": ["tsx", "/Users/YOUR_USERNAME/Joan/mcp-server/src/cli.ts", "serve"]
-    }
-  }
-}
 ```
+"Create a task in Joan for the bug I just found"
 
-### Verifying the Connection
-
-After configuring, restart Claude Code and verify Joan MCP is connected:
+"Show me my Joan projects"
 
-1. Start Claude Code in your other project
-2. Ask: "Show me my Joan projects"
-3. If connected, you'll see your projects list
+"Add a note in Joan about this architecture decision"
 
-### Example Workflows
+"Mark my 'Review PR #42' task as completed"
 
-**While working on another project, you can:**
+"What tasks do I have in my Backend project?"
 
+"Create a milestone called 'v2.0 Release' in Joan"
 ```
-"Create a task in my Joan project for the bug I just found in this codebase"
 
-"Add a note in Joan about the architecture decisions I'm making here"
+### How It Works
 
-"What tasks do I have assigned in my Backend Refactor project?"
-
-"Mark my 'Review PR #42' task as completed in Joan"
-
-"Create a milestone in Joan called 'v2.0 Release' for my current sprint"
-```
-
-### How It Works (Self-Describing Server)
-
-Joan MCP uses the MCP protocol's `instructions` field to automatically describe itself to AI assistants. When Claude Code connects to the Joan MCP server, it receives:
-
-- A description of what Joan is
+Joan MCP is **self-describing** - it automatically tells Claude Code:
+- What Joan is and what it does
 - All available tools and their parameters
-- All available resources and their URIs
-- Usage guidelines and valid field values
-
-**This means you don't need to manually document Joan in your CLAUDE.md files** - the server tells Claude Code everything it needs to know during initialization.
+- All available resources and URIs
+- Valid field values (status, priority, etc.)
 
-### Troubleshooting Other-Project Setup
+No manual documentation needed in your CLAUDE.md files.
 
-**Joan MCP not appearing:**
-1. Ensure the path to Joan repository is absolute (starts with `/`)
-2. Verify Joan's mcp-server has dependencies installed: `cd /path/to/Joan/mcp-server && npm install`
-3. Restart Claude Code completely (not just the conversation)
+### Manual Configuration (Optional)
 
-**Authentication errors:**
-- Credentials are stored globally at `~/.joan-mcp/credentials.json`
-- Re-authenticate from any directory: `cd /path/to/Joan/mcp-server && npx tsx src/cli.ts login`
-
-## Manual Setup
-
-If you prefer to set up manually, follow these steps:
-
-### Step 1: Authenticate
-
-```bash
-# From source
-npx tsx src/cli.ts login
-
-# Or after global install
-joan-mcp login
-```
-
-### Step 2: Configure Claude Code
-
-Add the Joan MCP server to your Claude Code configuration:
-
-**For development (from source):**
-
-Add to `~/.config/claude-code/settings.json` or your project's `.claude/settings.json`:
+The `init` command configures this automatically, but if needed, add to `~/.claude/settings.json`:
 
 ```json
 {
   "mcpServers": {
     "joan": {
       "command": "npx",
-      "args": ["tsx", "/path/to/Joan/mcp-server/src/cli.ts", "serve"]
+      "args": ["@pollychrome/joan-mcp", "serve"]
     }
   }
 }
 ```
 
-**After global install:**
-
-```json
-{
-  "mcpServers": {
-    "joan": {
-      "command": "joan-mcp",
-      "args": ["serve"]
-    }
-  }
-}
-```
+### Troubleshooting
 
-### Alternative: Environment Variable
-
-Instead of using `joan-mcp login`, you can set the token directly:
-
-```json
-{
-  "mcpServers": {
-    "joan": {
-      "command": "joan-mcp",
-      "args": ["serve"],
-      "env": {
-        "JOAN_AUTH_TOKEN": "your-jwt-token-here"
-      }
-    }
-  }
-}
-```
+**Joan MCP not working:**
+1. Restart Claude Code completely
+2. Run `npx @pollychrome/joan-mcp status` to check auth
+3. Run `npx @pollychrome/joan-mcp login` to re-authenticate
 
 ## CLI Commands
 
+All commands can be run with `npx @pollychrome/joan-mcp <command>`:
+
 | Command | Description |
 |---------|-------------|
-| `joan-mcp init` | Full setup wizard (login + configure Claude Code) |
-| `joan-mcp login` | Authenticate with Joan (opens browser) |
-| `joan-mcp logout` | Clear stored credentials |
-| `joan-mcp status` | Show authentication status |
-| `joan-mcp serve` | Start the MCP server (default) |
-| `joan-mcp help` | Show help message |
+| `init` | Full setup wizard (login + configure Claude Code) |
+| `login` | Authenticate with Joan (opens browser) |
+| `logout` | Clear stored credentials |
+| `status` | Show authentication status |
+| `serve` | Start the MCP server (default) |
+| `help` | Show help message |
 
 ## Available Tools
 
@@ -287,46 +186,6 @@ These resources provide read-only access to Joan data:
 | `joan://notes` | All notes |
 | `joan://notes/{id}` | Note details |
 
-## Usage Examples
-
-Once configured, you can interact with Joan through Claude Code:
-
-### View Projects
-
-```
-"Show me all my projects in Joan"
-```
-
-### Create Tasks
-
-```
-"Create a task in my 'Website Redesign' project for implementing the new header component"
-```
-
-### Update Task Status
-
-```
-"Mark task ABC-123 as completed"
-```
-
-### Create Milestones
-
-```
-"Create a milestone called 'Beta Release' in my project with a target date of next Friday"
-```
-
-### Link Tasks to Milestones
-
-```
-"Link these 3 tasks to the Beta Release milestone"
-```
-
-### Check Progress
-
-```
-"What's the progress on my Q4 Goals?"
-```
-
 ## Development
 
 ### Run in Development Mode
@@ -366,19 +225,20 @@ npm run build
 
 ### "Authentication failed"
 
-1. Run `joan-mcp logout` to clear credentials
-2. Run `joan-mcp login` to re-authenticate
-3. Verify your Joan account is active
+```bash
+npx @pollychrome/joan-mcp logout
+npx @pollychrome/joan-mcp login
+```
 
 ### "Token expired"
 
-Tokens expire after 7 days. Simply run `joan-mcp login` again.
+Tokens expire after 7 days. Run `npx @pollychrome/joan-mcp login` to re-authenticate.
 
 ### MCP server not connecting
 
-1. Check that the path in your Claude Code config is correct
-2. Verify the server starts: `npx tsx src/cli.ts serve`
-3. Check for any error messages in the output
+1. Restart Claude Code completely
+2. Check status: `npx @pollychrome/joan-mcp status`
+3. Re-run setup: `npx @pollychrome/joan-mcp init`
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pollychrome/joan-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for Joan productivity app - enables AI assistants to manage projects, tasks, goals, milestones, and notes",
   "type": "module",
   "main": "dist/index.js",
@@ -27,12 +27,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pollychrome/Joan.git",
-    "directory": "mcp-server"
+    "url": "git+https://github.com/pollychrome/joan-mcp.git"
   },
-  "homepage": "https://github.com/pollychrome/Joan/tree/main/mcp-server#readme",
+  "homepage": "https://github.com/pollychrome/joan-mcp#readme",
   "bugs": {
-    "url": "https://github.com/pollychrome/Joan/issues"
+    "url": "https://github.com/pollychrome/joan-mcp/issues"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",