@pollychrome/joan-mcp 1.0.0

package/README.md

@@ -0,0 +1,385 @@
+# Joan MCP Server
+
+Model Context Protocol (MCP) server for the Joan productivity app. Enables AI assistants like Claude Code to interact with your projects, tasks, goals, milestones, and notes.
+
+## Features
+
+- **Read & Write Access**: Full CRUD operations for projects, tasks, goals, milestones, and notes
+- **Secure Authentication**: Login via browser with encrypted token storage
+- **Claude Code Integration**: Works seamlessly with Claude Code and other MCP clients
+- **Self-Describing**: Automatically provides usage instructions to AI assistants via MCP protocol
+- **Production API**: Connects directly to your Joan account data
+
+## Installation
+
+### Option 1: Global Install via npm link (Recommended for Development)
+
+```bash
+cd mcp-server
+npm install
+npm run build
+npm link
+
+# Now available globally:
+joan-mcp init
+```
+
+### Option 2: npm Install (After Publishing)
+
+```bash
+npm install -g @joan/mcp-server
+
+# Or run directly without installing:
+npx @joan/mcp-server init
+```
+
+### Option 3: From Source (Development)
+
+```bash
+cd mcp-server
+npm install
+npx tsx src/cli.ts init
+```
+
+## Quick Start (Recommended)
+
+Run the setup wizard to authenticate and configure Claude Code in one command:
+
+```bash
+# From source
+cd /path/to/Joan/mcp-server && npx tsx src/cli.ts init
+
+# Or after global install
+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)
+
+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"]
+    }
+  }
+}
+```
+
+Replace `/Users/YOUR_USERNAME/Joan` with the actual path to your Joan repository.
+
+### Option B: Per-Project Configuration
+
+Add Joan MCP to a specific project by creating/editing `.claude/settings.json` in that project's root:
+
+```json
+{
+  "mcpServers": {
+    "joan": {
+      "command": "npx",
+      "args": ["tsx", "/Users/YOUR_USERNAME/Joan/mcp-server/src/cli.ts", "serve"]
+    }
+  }
+}
+```
+
+### Verifying the Connection
+
+After configuring, restart Claude Code and verify Joan MCP is connected:
+
+1. Start Claude Code in your other project
+2. Ask: "Show me my Joan projects"
+3. If connected, you'll see your projects list
+
+### Example Workflows
+
+**While working on another project, you can:**
+
+```
+"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"
+
+"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
+- 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.
+
+### Troubleshooting Other-Project Setup
+
+**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)
+
+**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`:
+
+```json
+{
+  "mcpServers": {
+    "joan": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/Joan/mcp-server/src/cli.ts", "serve"]
+    }
+  }
+}
+```
+
+**After global install:**
+
+```json
+{
+  "mcpServers": {
+    "joan": {
+      "command": "joan-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+### 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"
+      }
+    }
+  }
+}
+```
+
+## CLI Commands
+
+| 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 |
+
+## Available Tools
+
+These tools allow AI assistants to modify data in Joan:
+
+### Task Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_task` | Create a new task in a project |
+| `update_task` | Update task title, description, status, priority, etc. |
+| `complete_task` | Mark a task as completed |
+| `delete_task` | Delete a task |
+
+### Project Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_project` | Create a new project |
+| `update_project` | Update project name, description, status |
+
+### Milestone Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_milestone` | Create a milestone in a project |
+| `update_milestone` | Update milestone details |
+| `delete_milestone` | Delete a milestone |
+| `link_tasks_to_milestone` | Link tasks to a milestone |
+| `unlink_task_from_milestone` | Remove task from milestone |
+
+### Goal Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_goal` | Create a new goal |
+| `update_goal` | Update goal title, status, progress |
+| `delete_goal` | Delete a goal |
+| `link_task_to_goal` | Link a task to track progress |
+| `unlink_task_from_goal` | Remove task from goal |
+
+### Note Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_note` | Create a new note |
+| `update_note` | Update note content and metadata |
+| `delete_note` | Delete a note |
+
+## Available Resources
+
+These resources provide read-only access to Joan data:
+
+| Resource URI | Description |
+|--------------|-------------|
+| `joan://projects` | List all projects |
+| `joan://projects/{id}` | Project details with stats |
+| `joan://projects/{id}/tasks` | Tasks in a project |
+| `joan://projects/{id}/milestones` | Project milestones |
+| `joan://projects/{id}/columns` | Kanban columns |
+| `joan://projects/{id}/analytics` | Project analytics |
+| `joan://tasks` | All user tasks |
+| `joan://tasks/{id}` | Task details |
+| `joan://goals` | All goals |
+| `joan://goals/{id}` | Goal with linked tasks |
+| `joan://goals/{id}/stats` | Goal statistics |
+| `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
+
+```bash
+cd mcp-server
+npm run dev
+```
+
+### Type Check
+
+```bash
+npm run typecheck
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `JOAN_AUTH_TOKEN` | JWT authentication token | (from login) |
+| `JOAN_API_URL` | API base URL | `https://joan-api.alexbbenson.workers.dev/api/v1` |
+
+## Security
+
+- Authentication tokens are encrypted at rest using AES-256-GCM
+- Tokens are stored in `~/.joan-mcp/credentials.json` with restricted permissions (600)
+- Tokens expire after 7 days
+- You can revoke MCP access from your Joan profile settings
+
+## Troubleshooting
+
+### "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
+
+### "Token expired"
+
+Tokens expire after 7 days. Simply run `joan-mcp login` again.
+
+### 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
+
+## License
+
+MIT

package/bin/joan-mcp

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// Entry point for joan-mcp CLI
+// This file is referenced in package.json "bin" field
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(__dirname, '..', 'dist', 'cli.js');
+
+import(cliPath).catch((err) => {
+  console.error('Failed to load Joan MCP CLI:', err.message);
+  console.error('Make sure to run "npm run build" first.');
+  process.exit(1);
+});

package/dist/auth.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Auth token management for Joan MCP server
+ * Handles storing, retrieving, and validating auth tokens
+ */
+/**
+ * Store auth token securely
+ */
+export declare function storeToken(token: string, email?: string, expiresAt?: Date): Promise<void>;
+/**
+ * Retrieve stored auth token
+ */
+export declare function getStoredToken(): Promise<{
+    token: string;
+    email?: string;
+    expiresAt?: Date;
+} | null>;
+/**
+ * Clear stored token
+ */
+export declare function clearToken(): Promise<void>;
+/**
+ * Get auth token from stored credentials or environment variable
+ */
+export declare function getAuthToken(): Promise<string>;
+/**
+ * Parse JWT to extract payload (without verification)
+ */
+export declare function parseJwt(token: string): {
+    sub?: string;
+    email?: string;
+    exp?: number;
+} | null;
+/**
+ * Check if token is expired based on JWT payload
+ */
+export declare function isTokenExpired(token: string): boolean;
+/**
+ * Start local HTTP server for OAuth callback
+ * Returns a promise that resolves with the token when received
+ */
+export declare function startCallbackServer(port: number): Promise<{
+    token: string;
+    email?: string;
+}>;
+/**
+ * Find an available port for the callback server
+ */
+export declare function findAvailablePort(startPort?: number): Promise<number>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8EH;;GAEG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,IAAI,GACf,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,GAAG,IAAI,CAAC,CA4BR;AAED;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAQhD;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAepD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW7F;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMrD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgF5F;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBjF"}