@ainote/mcp 1.1.1 → 1.2.0

package/README.md

@@ -11,6 +11,7 @@ A Model Context Protocol (MCP) server that connects AI assistants to your AI Not
 
 - [Access Methods](#access-methods)
 - [Features](#features)
+- [Authentication](#authentication)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
 - [Configuration](#configuration)
@@ -41,7 +42,7 @@ AI Note MCP server is available through three transport options to cover differe
 - **Best for**: Users wanting to expose AI Note tools to ChatGPT without deploying infrastructure
 
 ### 3. **Hosted HTTP Endpoint** - For Platform Integration
-- **URL**: `https://api.ainote.dev/mcp`
+- **URL**: `https://api.ainote.dev/api/mcp`
 - **Protocol**: JSON-RPC 2.0 over HTTP
 - **Usage**: Platform integrations (Kakao PlayMCP, etc.)
 - **Setup**: No installation required, direct API access
@@ -53,7 +54,10 @@ All transports expose the same tool catalog. Choose the option that matches your
 
 - 📝 **Task Management**: Create, update, delete, and list tasks directly from Claude Desktop
 - 📄 **Dev Docs**: Manage CLAUDE.md, Cursor rules, Windsurf rules, and dev documents centrally via MCP
-- 🗂️ **Dev Category Hierarchy**: Auto-organized under `dev/` with subcategories (claude, cursor, windsurf, copilot, docs)
+- 🗂️ **Dev Category Hierarchy**: Auto-organized under `dev/` with subcategories (claude, cursor, windsurf, copilot, docs, skills, agents, commands, hooks, mcp)
+- 🔄 **Claude Environment Sync**: Push/pull `~/.claude/` skills, agents, commands, hooks across machines (macOS/WSL/Linux)
+- 🔐 **End-to-End Encryption**: `mcp` category (mcpServers + API keys) auto-encrypted client-side with age; server never sees plaintext
+- 🪪 **OS Keychain Integration**: Per-machine age identity stored in macOS Keychain / libsecret / Credential Manager (file fallback supported)
 - 🏷️ **Category Support**: Organize tasks with categories
 - 🔍 **Advanced Filtering**: 18+ filter options including date ranges, location, overdue tasks
 - ⭐ **Priority Management**: Mark tasks as important
@@ -128,6 +132,69 @@ These tools also work inside Claude (no API key needed):
 | `login_and_get_key` | Login + get MCP key (existing account) |
 | `get_setup_guide` | Setup instructions |
 
+## Authentication
+
+The CLI supports browser-based login as a more secure alternative to manually pasting API keys into your MCP config. Tokens and the MCP key are stored in the OS keychain.
+
+### Quick start
+
+```bash
+ainote-mcp login                 # browser-based, recommended
+ainote-mcp whoami                # verify current login
+ainote-mcp logout                # revoke + clear keychain
+```
+
+### How it works
+
+`ainote-mcp login` runs an [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628) OAuth 2.0 Device Authorization Grant. The CLI generates a PKCE pair locally, opens your browser to sign in via the AI Note web app, and polls the backend until you approve. On success it stores an access token, a refresh token, and an MCP key in the OS keychain. The default MCP stdio mode automatically uses the stored MCP key — no `AINOTE_API_KEY` env var needed.
+
+### Storage locations
+
+| OS       | Location                                                                  |
+|----------|---------------------------------------------------------------------------|
+| macOS    | Keychain Access — service `@ainote/cli`                                   |
+| Linux    | libsecret (gnome-keyring / kwallet) — service `@ainote/cli`               |
+| Windows  | Credential Manager — target `@ainote/cli`                                 |
+| Fallback | `${XDG_CONFIG_HOME:-~/.config}/ainote/credentials.json` (mode `0600`)     |
+
+The fallback file is only used when no system keychain is available (e.g. headless servers without `libsecret`).
+
+### CLI flags
+
+- `--scope=mcp,read,write` — comma-separated scopes requested for the token (default: `mcp,read,write`)
+- `--no-browser` — print the verification URL instead of auto-opening a browser (use this on SSH/CI)
+
+### Environment overrides
+
+- `AINOTE_API_URL` — backend URL (default `https://ainote-5muq.onrender.com`)
+- `AINOTE_API_KEY` — pre-provisioned MCP key. When set, the login flow is bypassed entirely and this key is used as-is.
+
+### Headless / CI usage
+
+For SSH sessions, devcontainers, or CI runners that cannot open a browser, use `--no-browser`. The CLI will print a short user code and a verification URL; open the URL on any device (laptop, phone) signed in to your AI Note account, approve the request, then return to the terminal:
+
+```bash
+$ ainote-mcp login --no-browser
+Open this URL in any browser:
+  https://ainote.dev/oauth/cli/device?user_code=BCDF-GHJK
+Waiting for approval...
+✓ Logged in as you@example.com
+```
+
+After login, subsequent invocations (`ainote-mcp`, `ainote-mcp whoami`) work normally with no further interaction.
+
+### Troubleshooting
+
+| Symptom                                       | Fix                                                                                       |
+|-----------------------------------------------|-------------------------------------------------------------------------------------------|
+| `LOGIN_HINT` error on any subcommand          | Run `ainote-mcp login`                                                                    |
+| macOS Keychain prompt every run               | Open Keychain Access, find `@ainote/cli`, set access control to "Always allow" for `node` |
+| Browser does not open                         | Re-run with `--no-browser` and copy the URL manually                                      |
+| Persistent 401 after login                    | Tokens were revoked server-side. Run `ainote-mcp login` again                             |
+| `libsecret not available` on Linux            | Install `gnome-keyring` / `libsecret-1-0`, or rely on the file fallback (still encrypted at-rest by the OS) |
+
+See [`docs/architecture/CLI_AUTH.md`](../docs/architecture/CLI_AUTH.md) for the full protocol specification, sequence diagram, and security model.
+
 ## Prerequisites
 
 - Node.js >= 18.0.0
@@ -244,7 +311,7 @@ For platform integrations and services that prefer HTTP over stdio, AI Note prov
 
 ### Endpoint URL
 ```
-POST https://api.ainote.dev/mcp
+POST https://api.ainote.dev/api/mcp
 Content-Type: application/json
 ```
 
@@ -287,7 +354,7 @@ Authorization: Bearer YOUR_API_KEY
 This HTTP endpoint provides identical functionality to the stdio version, making AI Note MCP accessible to a broader range of platforms and integration scenarios.
 
 ### 4. **Streaming API** - For Large Data Operations
-- **URL**: `POST https://api.ainote.dev/mcp/stream`
+- **URL**: `POST https://api.ainote.dev/api/mcp/stream`
 - **Protocol**: Server-Sent Events (SSE)
 - **Usage**: Bulk operations, large task lists, real-time progress
 - **Best for**: Applications that need to handle large datasets or show progress indicators

package/index.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 /**
- * AI Note MCP Server - Claude Desktop Integration (stdio transport)
- * Also supports CLI subcommands: signup
+ * AI Note MCP Server — Claude Desktop integration (stdio transport).
+ *
+ * Also supports CLI subcommands:
+ *   signup   — interactive account creation
+ *   login    — device-authorization grant (RFC 8628)
+ *   logout   — revoke + clear local credentials
+ *   whoami   — show currently authenticated user
  */
 
 const subcommand = process.argv[2];
@@ -9,19 +14,39 @@ const subcommand = process.argv[2];
 if (subcommand === 'signup') {
   const { runSignup } = await import('./lib/cli/signup.js');
   await runSignup();
+} else if (subcommand === 'login') {
+  const { run } = await import('./lib/cli/login.js');
+  await run();
+} else if (subcommand === 'logout') {
+  const { run } = await import('./lib/cli/logout.js');
+  await run();
+} else if (subcommand === 'whoami') {
+  const { run } = await import('./lib/cli/whoami.js');
+  await run();
 } else {
   // Default: start MCP stdio server
   const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
   const { resolveAuthContext } = await import('./lib/auth/strategy-factory.js');
   const { createClaudeServer } = await import('./lib/core/server-factory.js');
+  const { getConfigAsync } = await import('./lib/core/config-manager.js');
+
+  // Hydrate AINOTE_API_KEY from the token store BEFORE auth context resolution
+  // so existing sync `authenticateWithMcpKey()` paths see the stored credential.
+  if (!process.env.AINOTE_API_KEY) {
+    try {
+      const cfg = await getConfigAsync();
+      if (cfg.api.key) {
+        process.env.AINOTE_API_KEY = cfg.api.key;
+      }
+    } catch { /* anonymous fallback handled below */ }
+  }
 
   const transport = new StdioServerTransport();
   const defaultAuthContext = resolveAuthContext('stdio');
 
   if (defaultAuthContext.type === 'anonymous') {
     console.error('[ainote-mcp] No AINOTE_API_KEY found. Starting in onboarding mode.');
-    console.error('[ainote-mcp] Use signup_and_get_key or login_and_get_key to get started.');
-    console.error('[ainote-mcp] Or run: npx @ainote/mcp signup');
+    console.error('[ainote-mcp] Run `npx @ainote/mcp login` (browser flow) or `npx @ainote/mcp signup`.');
   }
 
   const { server } = createClaudeServer({ defaultAuthContext });

package/lib/auth/device-flow.js

@@ -0,0 +1,274 @@
+/**
+ * RFC 8628 Device Authorization Grant — CLI client.
+ *
+ * Talks to the ainote backend endpoints:
+ *   POST /api/auth/cli/device/start
+ *   POST /api/auth/cli/device/poll
+ *   POST /api/auth/cli/device/cancel
+ *
+ * Per the plan, the server returns 200 + JSON body with a `status` field for
+ * polling state (authorization_pending, slow_down, access_denied, expired_token,
+ * invalid_grant) and a token payload (no `status`) on success. We never use
+ * HTTP error codes for polling state.
+ */
+import crypto from 'node:crypto';
+import axios from 'axios';
+
+export class DeviceFlowError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'DeviceFlowError';
+    this.code = code;
+  }
+}
+
+export class DeviceAccessDeniedError extends DeviceFlowError {
+  constructor(message = 'Authorization was denied by the user.') {
+    super(message, 'access_denied');
+    this.name = 'DeviceAccessDeniedError';
+  }
+}
+
+export class DeviceExpiredError extends DeviceFlowError {
+  constructor(message = 'Device code expired before authorization completed.') {
+    super(message, 'expired_token');
+    this.name = 'DeviceExpiredError';
+  }
+}
+
+export class DevicePkceError extends DeviceFlowError {
+  constructor(message = 'PKCE verification failed (invalid_grant).') {
+    super(message, 'invalid_grant');
+    this.name = 'DevicePkceError';
+  }
+}
+
+export class DeviceNetworkError extends DeviceFlowError {
+  constructor(message, cause) {
+    super(message, 'network_error');
+    this.name = 'DeviceNetworkError';
+    this.cause = cause;
+  }
+}
+
+function generatePkce() {
+  const verifier = crypto.randomBytes(32).toString('base64url');
+  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge };
+}
+
+function sleep(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+}
+
+/**
+ * Request a device + user code from the server.
+ *
+ * @param {Object} args
+ * @param {string} args.apiUrl - API base URL (no trailing slash).
+ * @param {string} args.clientName - Friendly client identifier (e.g. "ainote-mcp CLI").
+ * @param {string[]|string} [args.scopes] - Requested scopes.
+ * @returns {Promise<{device_code: string, user_code: string, verification_uri: string,
+ *   verification_uri_complete?: string, expires_in: number, interval: number,
+ *   code_verifier: string}>}
+ */
+export async function requestDeviceCode({ apiUrl, clientName, scopes }) {
+  const { verifier, challenge } = generatePkce();
+
+  const body = {
+    client_name: clientName,
+    scopes,
+    code_challenge: challenge,
+    code_challenge_method: 'S256'
+  };
+
+  let response;
+  try {
+    response = await axios.post(`${apiUrl}/api/auth/cli/device/start`, body, {
+      headers: { 'Content-Type': 'application/json' },
+      timeout: 30000
+    });
+  } catch (error) {
+    if (error.response) {
+      const data = error.response.data;
+      const msg = (data && (data.error_description || data.error || data.message)) ||
+        `Device authorization request failed (HTTP ${error.response.status}).`;
+      throw new DeviceFlowError(msg, 'start_failed');
+    }
+    throw new DeviceNetworkError(`Could not reach ${apiUrl}: ${error.message}`, error);
+  }
+
+  // The ainote backend wraps API responses in a standard envelope
+  // ({ success, status:'success', data: <payload>, meta }) — see render_success.
+  // RFC 8628 device endpoints live behind that envelope, so unwrap before reading.
+  const raw = response.data || {};
+  const data = (raw && typeof raw === 'object' && raw.data && typeof raw.data === 'object')
+    ? raw.data
+    : raw;
+
+  if (!data.device_code || !data.user_code || !data.verification_uri) {
+    throw new DeviceFlowError('Malformed response from device/start: missing required fields.', 'invalid_response');
+  }
+
+  return {
+    device_code: data.device_code,
+    user_code: data.user_code,
+    verification_uri: data.verification_uri,
+    verification_uri_complete: data.verification_uri_complete,
+    expires_in: Number(data.expires_in) || 900,
+    interval: Number(data.interval) || 5,
+    code_verifier: verifier
+  };
+}
+
+/**
+ * Poll the device/poll endpoint until terminal state.
+ *
+ * The server returns HTTP 200 with a body whose shape signals state:
+ *   - `{ error: 'authorization_pending' }`   → keep waiting
+ *   - `{ error: 'slow_down', interval?: n }` → bump interval by 5s and wait
+ *   - `{ error: 'access_denied' }`           → throw DeviceAccessDeniedError
+ *   - `{ error: 'expired_token' }`           → throw DeviceExpiredError
+ *   - `{ error: 'invalid_grant' }`           → throw DevicePkceError
+ *   - `{ access_token, ... }`                → success, resolve token bundle
+ *
+ * The ainote backend wraps these in `{ success, status:'success', data: <body>, meta }`,
+ * so we unwrap `response.data.data` when present.
+ *
+ * If the server ever does return non-2xx, we attempt to map the body shape
+ * the same way (RFC 8628 §3.5 permits 400 + error JSON, but our backend per
+ * the plan returns 200; we tolerate both).
+ *
+ * @param {Object} args
+ * @param {string} args.apiUrl
+ * @param {string} args.deviceCode
+ * @param {string} args.codeVerifier - PKCE verifier captured during start.
+ * @param {number} args.interval - Initial poll interval in seconds.
+ * @param {number} args.expiresIn - Total lifetime in seconds.
+ * @param {(info: {elapsed: number, interval: number}) => void} [args.onTick]
+ * @returns {Promise<{access_token: string, refresh_token?: string, mcp_key?: string,
+ *   expires_in?: number, user?: Object, scope?: string}>}
+ */
+export async function pollForToken({
+  apiUrl,
+  deviceCode,
+  codeVerifier,
+  interval,
+  expiresIn,
+  onTick
+}) {
+  let currentInterval = Math.max(1, Number(interval) || 5);
+  const totalBudget = Math.max(1, Number(expiresIn) || 900);
+  const startedAt = Date.now();
+
+  while (true) {
+    const elapsedBeforeWait = Math.floor((Date.now() - startedAt) / 1000);
+
+    if (elapsedBeforeWait >= totalBudget) {
+      throw new DeviceExpiredError();
+    }
+
+    if (typeof onTick === 'function') {
+      try {
+        onTick({ elapsed: elapsedBeforeWait, interval: currentInterval });
+      } catch { /* swallow UX callback errors */ }
+    }
+
+    await sleep(currentInterval);
+
+    const elapsedAfterWait = Math.floor((Date.now() - startedAt) / 1000);
+    if (elapsedAfterWait >= totalBudget) {
+      throw new DeviceExpiredError();
+    }
+
+    let body;
+    try {
+      const response = await axios.post(
+        `${apiUrl}/api/auth/cli/device/poll`,
+        { device_code: deviceCode, code_verifier: codeVerifier },
+        {
+          headers: { 'Content-Type': 'application/json' },
+          timeout: 30000,
+          // Per the plan the server returns 200 with status. Don't throw on
+          // 4xx so we can read the body uniformly.
+          validateStatus: (s) => s >= 200 && s < 500
+        }
+      );
+      const raw = response.data || {};
+      // Unwrap ainote API envelope ({ success, data: <payload>, meta }) if present.
+      body = (raw && typeof raw === 'object' && raw.data && typeof raw.data === 'object')
+        ? raw.data
+        : raw;
+    } catch (error) {
+      // Network/5xx — transient. Wait and retry rather than fail the whole flow.
+      // But if we're out of budget, give up.
+      if (Math.floor((Date.now() - startedAt) / 1000) >= totalBudget) {
+        throw new DeviceExpiredError();
+      }
+      continue;
+    }
+
+    // RFC 8628 §3.5 + ainote service: polling state lives in `error`, success has no `error`.
+    // Also accept legacy `status` field for forward-compat with any wrapper changes.
+    const pollState = body.error || body.status;
+
+    if (!pollState && body.access_token) {
+      return {
+        access_token: body.access_token,
+        refresh_token: body.refresh_token,
+        mcp_key: body.mcp_key,
+        expires_in: body.expires_in,
+        scope: body.scope,
+        user: body.user
+      };
+    }
+
+    switch (pollState) {
+      case 'authorization_pending':
+        continue;
+      case 'slow_down': {
+        const serverInterval = Number(body.interval);
+        if (Number.isFinite(serverInterval) && serverInterval > currentInterval) {
+          currentInterval = serverInterval;
+        } else {
+          currentInterval += 5;
+        }
+        continue;
+      }
+      case 'access_denied':
+        throw new DeviceAccessDeniedError(body.error_description);
+      case 'expired_token':
+        throw new DeviceExpiredError(body.error_description);
+      case 'invalid_grant':
+        throw new DevicePkceError(body.error_description);
+      default: {
+        const message = body.error_description ||
+          body.error ||
+          body.message ||
+          `Unexpected poll response: ${JSON.stringify(body).slice(0, 200)}`;
+        throw new DeviceFlowError(message, pollState || 'unknown');
+      }
+    }
+  }
+}
+
+/**
+ * Best-effort cancellation. Failures are swallowed — the server will GC
+ * the pending request via TTL anyway.
+ */
+export async function cancel({ apiUrl, deviceCode }) {
+  if (!deviceCode) return;
+  try {
+    await axios.post(
+      `${apiUrl}/api/auth/cli/device/cancel`,
+      { device_code: deviceCode },
+      {
+        headers: { 'Content-Type': 'application/json' },
+        timeout: 5000,
+        validateStatus: () => true
+      }
+    );
+  } catch {
+    // intentionally ignored
+  }
+}

package/lib/auth/mcp-key.js

@@ -1,10 +1,14 @@
 import { getConfig } from '../core/config.js';
 
+/**
+ * Synchronous variant: only consults env var. Kept for callers that cannot
+ * await (e.g. the stdio bootstrap path that hasn't loaded the async config).
+ */
 export function authenticateWithMcpKey() {
   const config = getConfig();
 
   if (!config.api.key) {
-    throw new Error('AINOTE_API_KEY is required to authenticate MCP requests');
+    throw new Error('AINOTE_API_KEY is required to authenticate MCP requests. Run `ainote-mcp login` or set AINOTE_API_KEY.');
   }
 
   return {
@@ -12,3 +16,25 @@ export function authenticateWithMcpKey() {
     apiKey: config.api.key
   };
 }
+
+/**
+ * Async variant: falls back to the local CLI token store (populated by
+ * `ainote-mcp login`) when no env var is set.
+ */
+export async function authenticateWithMcpKeyAsync() {
+  const envKey = process.env.AINOTE_API_KEY;
+  if (envKey) {
+    return { type: 'mcpKey', apiKey: envKey };
+  }
+
+  try {
+    const { getCredentials } = await import('./token-store.js');
+    const baseUrl = process.env.AINOTE_API_URL || 'https://ainote-5muq.onrender.com';
+    const creds = await getCredentials(baseUrl);
+    if (creds && creds.mcpKey) {
+      return { type: 'mcpKey', apiKey: creds.mcpKey };
+    }
+  } catch { /* fall through */ }
+
+  throw new Error('AINOTE_API_KEY is required to authenticate MCP requests. Run `ainote-mcp login` or set AINOTE_API_KEY.');
+}

package/lib/auth/refresh.js

@@ -0,0 +1,78 @@
+/**
+ * Access token rotation against the ainote backend.
+ *
+ * Endpoint: POST /api/auth/token/refresh
+ * Body:     { refresh_token: "rt_..." }
+ * Response: { access_token, refresh_token, expires_in }
+ *
+ * Concurrency: an in-process mutex (module-level Promise) ensures that
+ * parallel callers wait on a single in-flight refresh instead of issuing
+ * duplicate requests (which would otherwise burn through refresh-token
+ * rotation and invalidate the family).
+ */
+import axios from 'axios';
+
+let inFlight = null;
+
+export class RefreshError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.name = 'RefreshError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+async function performRefresh({ apiUrl, refreshToken }) {
+  let response;
+  try {
+    response = await axios.post(
+      `${apiUrl}/api/auth/token/refresh`,
+      { refresh_token: refreshToken },
+      {
+        headers: { 'Content-Type': 'application/json' },
+        timeout: 30000,
+        validateStatus: (s) => s >= 200 && s < 500
+      }
+    );
+  } catch (err) {
+    throw new RefreshError(`Refresh request failed: ${err.message}`);
+  }
+
+  if (response.status < 200 || response.status >= 300) {
+    const body = response.data || {};
+    const msg = body.error_description || body.error || body.message ||
+      `Refresh failed with HTTP ${response.status}`;
+    throw new RefreshError(msg, { status: response.status, body });
+  }
+
+  const body = response.data || {};
+  if (!body.access_token) {
+    throw new RefreshError('Refresh response missing access_token', { body });
+  }
+  return {
+    access_token: body.access_token,
+    refresh_token: body.refresh_token || refreshToken,
+    expires_in: Number(body.expires_in) || undefined
+  };
+}
+
+/**
+ * Rotate the access token. Concurrent callers share one in-flight request.
+ *
+ * @param {Object} args
+ * @param {string} args.apiUrl
+ * @param {string} args.refreshToken
+ * @returns {Promise<{access_token: string, refresh_token: string, expires_in?: number}>}
+ */
+export async function refreshAccessToken({ apiUrl, refreshToken }) {
+  if (!refreshToken) {
+    throw new RefreshError('No refresh token available — login required.');
+  }
+  if (inFlight) return inFlight;
+  inFlight = performRefresh({ apiUrl, refreshToken })
+    .finally(() => {
+      inFlight = null;
+    });
+  return inFlight;
+}