@ainote/mcp 1.0.2 → 1.1.0

package/README.md

@@ -3,15 +3,19 @@
 [![npm version](https://badge.fury.io/js/%40ainote%2Fmcp-server.svg)](https://badge.fury.io/js/%40ainote%2Fmcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Model Context Protocol (MCP) server that connects Claude Desktop to your AI Note task management system. This server allows Claude to directly interact with your AI Note tasks, enabling task creation, updates, and management through natural language conversations.
+A Model Context Protocol (MCP) server that connects AI assistants to your AI Note task management system. This package enables direct interaction with your AI Note tasks through natural language conversations in Claude Desktop and other MCP-compatible platforms.
+
+> 📚 **[Complete Project Guide](../docs/PROJECT_GUIDE.md)** - 전체 프로젝트 가이드 및 아키텍처 정보
 
 ## Table of Contents
 
+- [Access Methods](#access-methods)
 - [Features](#features)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Usage](#usage)
+- [HTTP Endpoint](#http-endpoint)
 - [Available Tools](#available-tools)
 - [API Reference](#api-reference)
 - [Development](#development)
@@ -19,20 +23,115 @@ A Model Context Protocol (MCP) server that connects Claude Desktop to your AI No
 - [Contributing](#contributing)
 - [License](#license)
 
+## Access Methods
+
+AI Note MCP server is available through three transport options to cover different integration scenarios:
+
+### 1. **stdio Mode (This Package)** - For Personal Use
+- **Installation**: `npm install -g @ainote/mcp`
+- **Usage**: Claude Desktop and other stdio-based MCP clients
+- **Setup**: Local installation with API key configuration
+- **Best for**: Individual users connecting their personal AI Note account to Claude Desktop
+
+### 2. **Local SSE Bridge (ChatGPT / MCP Apps)**
+- **Command**: `ainote-mcp-http`
+- **Protocol**: Server-Sent Events (SSE) + JSON-RPC over HTTP POST
+- **Usage**: ChatGPT Model Context Protocol connectors, other SSE-capable MCP clients
+- **Setup**: Run locally alongside your browser; supports API key or (optional) OAuth bearer tokens
+- **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`
+- **Protocol**: JSON-RPC 2.0 over HTTP
+- **Usage**: Platform integrations (Kakao PlayMCP, etc.)
+- **Setup**: No installation required, direct API access
+- **Best for**: Third-party platforms and services integrating AI Note functionality
+
+All transports expose the same tool catalog. Choose the option that matches your hosting model and client capabilities.
+
 ## Features
 
 - 📝 **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)
 - 🏷️ **Category Support**: Organize tasks with categories
-- 🔍 **Advanced Search**: Search tasks by content, status, and more
+- 🔍 **Advanced Filtering**: 18+ filter options including date ranges, location, overdue tasks
 - ⭐ **Priority Management**: Mark tasks as important
-- 📅 **Due Date Support**: Set and manage task due dates
-- 🔒 **Secure API Integration**: Uses API key authentication for secure access
+- 📅 **Smart Due Dates**: Human-readable format with relative time (e.g., `'26.1.25 14:30 - 오늘`)
+- 🔒 **Dual Authentication**: Support for both User API Key (24-char) and MCP Key (64-char)
+- 📊 **Usage Tracking**: Automatic API usage statistics per MCP key
+- 🌊 **Streaming API**: Real-time streaming for bulk operations and large datasets
+- 🤖 **Bot Integration**: Telegram bot support via Clawdbot + mcporter
+
+## Quick Start (No Account Needed)
+
+You can start using AI Note MCP **without an existing account**. The MCP server includes onboarding tools that let you sign up and get an API key directly from Claude:
+
+### 1. Add to your MCP config (no API key yet)
+
+```json
+{
+  "mcpServers": {
+    "ainote": {
+      "command": "npx",
+      "args": ["-y", "@ainote/mcp"]
+    }
+  }
+}
+```
+
+### 2. Restart Claude Desktop
+
+### 3. Ask Claude to sign you up
+
+> "Sign me up for AI Note with email user@example.com and password mypassword123"
+
+Claude will call the `signup_and_get_key` tool and return your MCP API key.
+
+### 4. Add the API key to your config
+
+```json
+{
+  "mcpServers": {
+    "ainote": {
+      "command": "npx",
+      "args": ["-y", "@ainote/mcp"],
+      "env": {
+        "AINOTE_API_KEY": "<your-key-from-step-3>"
+      }
+    }
+  }
+}
+```
+
+### 5. Restart Claude Desktop again
+
+Now all tools (tasks, dev docs, etc.) are available.
+
+### CLI Signup
+
+You can also sign up directly from the terminal:
+
+```bash
+npx @ainote/mcp signup
+```
+
+This will interactively ask for email, password, and name, then return your MCP API key.
+
+### Onboarding MCP Tools
+
+These tools also work inside Claude (no API key needed):
+
+| Tool | Description |
+|------|-------------|
+| `signup_and_get_key` | Create account + get MCP key |
+| `login_and_get_key` | Login + get MCP key (existing account) |
+| `get_setup_guide` | Setup instructions |
 
 ## Prerequisites
 
-- Node.js >= 16.0.0
+- Node.js >= 18.0.0
 - npm or yarn
-- AI Note API access (API key required)
 - Claude Desktop with MCP support enabled
 
 ## Installation
@@ -139,16 +238,148 @@ You: "Mark task ID 123 as completed"
 Claude: I'll mark that task as completed...
 ```
 
+## HTTP Endpoint
+
+For platform integrations and services that prefer HTTP over stdio, AI Note provides a direct HTTP endpoint:
+
+### Endpoint URL
+```
+POST https://api.ainote.dev/mcp
+Content-Type: application/json
+```
+
+### Authentication
+```http
+Authorization: Bearer YOUR_API_KEY
+```
+
+### Request Format (JSON-RPC 2.0)
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "tools/list",
+  "id": 1
+}
+```
+
+### Response Format
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    "tools": [...]
+  },
+  "id": 1
+}
+```
+
+### Supported Methods
+- `ping` - Health check
+- `capabilities` - Server capabilities
+- `tools/list` - List available tools
+- `tools/call` - Execute a specific tool
+
+### Platform Integration Examples
+- **Kakao PlayMCP**: Use the HTTP endpoint for seamless integration
+- **Custom Applications**: Build your own MCP client using the HTTP API
+- **Enterprise Solutions**: Direct server-to-server communication
+
+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`
+- **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
+
+#### Streaming Methods
+| Method | Description |
+|--------|-------------|
+| `tasks/list` | Stream task list with filters |
+| `tasks/create` | Create single task with progress |
+| `tasks/analyze` | Get task statistics and insights |
+| `tasks/bulk_update` | Update multiple tasks with progress |
+| `tasks/bulk_create` | Create up to 1000 tasks at once |
+
+#### Streaming Events
+```
+event: progress
+data: {"status": "starting", "total": 100}
+
+event: data
+data: {"type": "task", "data": {...}}
+
+event: result
+data: {"status": "success", "count": 100}
+```
+
+### 5. **Telegram Bot Integration** - Via Clawdbot
+- **Setup Guide**: [CLAWDBOT_SETUP.md](./CLAWDBOT_SETUP.md)
+- **Tool**: mcporter for MCP server bridging
+- **Usage**: Natural language task management in Telegram
+
+```bash
+# Quick setup
+npm install -g mcporter
+mcporter call ainote.list_tasks
+```
+
+### Local Development Bridge (`ainote-mcp-http`)
+
+Run the bundled HTTP/SSE bridge when you need a local endpoint for ChatGPT or other MCP clients that speak SSE:
+
+```bash
+ainote-mcp-http
+```
+
+By default the server listens on `http://localhost:3030` and exposes two endpoints:
+
+- `GET /sse` – establishes the SSE stream and returns the `sessionId`
+- `POST /messages?sessionId=...` – receives JSON-RPC payloads from the client
+- `GET /health` – simple health probe for monitoring
+
+#### Configuration
+
+Environment variable | Description | Default
+---|---|---
+`AINOTE_API_KEY` | API key used for MCP key authentication | **required**
+`AINOTE_API_URL` | Target AI Note API base URL | `https://ainote-5muq.onrender.com`
+`AINOTE_MCP_HTTP_PORT` | Local port for the SSE server | `3030`
+`AINOTE_MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed browser origins | _any_
+`AINOTE_MCP_ALLOWED_HOSTS` | Comma-separated list of allowed `Host` headers | _any_
+`AINOTE_ENABLE_OAUTH_AUTH` | Set to `true` to allow Bearer tokens (OAuth) | `false`
+
+When OAuth is enabled the server expects `Authorization: Bearer ...` headers from the client and forwards them to the AI Note API.
+
 ## Available Tools
 
 ### list_tasks
 
-List tasks from AI Note with filtering options.
+List tasks from AI Note with advanced filtering options.
 
-**Parameters:**
+**Basic Parameters:**
 - `status` (optional): Filter by status - "pending" or "completed"
 - `limit` (optional): Maximum number of tasks (default: 25, max: 500)
 - `search` (optional): Search keyword in task content
+- `is_important` (optional): Filter important tasks only
+
+**Location & Category:**
+- `location` (optional): Filter by location (partial match, e.g., "여의도")
+- `category_id` (optional): Filter by category UUID
+
+**Date Range Filters:**
+- `due_date_start` / `due_date_end`: Filter by due date range
+- `completed_date_start` / `completed_date_end`: Filter by completion date
+- `created_date_start` / `created_date_end`: Filter by creation date
+
+**Special Filters:**
+- `overdue` (optional): Filter overdue incomplete tasks
+- `due_today` (optional): Filter tasks due today
+- `has_notification` (optional): Filter by notification status
+
+**Sorting:**
+- `sort_by` (optional): Sort field - "due_date", "created_at", "completed_at", "updated_at", "is_important"
+- `sort_order` (optional): Sort direction - "asc" or "desc"
 
 ### create_task
 
@@ -183,6 +414,80 @@ List all available categories.
 
 **Parameters:** None
 
+---
+
+### Dev Doc Tools (v1.1.0+)
+
+Manage AI coding tool configuration files and dev documents centrally. All docs are organized under the `dev/` category hierarchy.
+
+#### list_dev_docs
+
+List dev documents with optional filtering.
+
+**Parameters:**
+- `category` (optional): Subcategory filter (claude, cursor, windsurf, copilot, docs)
+- `search` (optional): Search keyword in document title
+- `content_type` (optional): Filter by type - "markdown", "json", "yaml", "text"
+
+#### get_dev_doc
+
+Get a single dev document by title or id.
+
+**Parameters:**
+- `title` or `id` (one required): Document identifier
+- `category` (optional): Subcategory to disambiguate title
+- `include_versions` (optional): Include version history
+
+#### create_dev_doc
+
+Create a new dev document under `dev/` category.
+
+**Parameters:**
+- `title` (required): Document title (e.g., "project-a-claude.md")
+- `content` (required): Document content
+- `category` (optional): Subcategory (default: "docs")
+- `content_type` (optional): Auto-detected from title extension
+
+#### update_dev_doc
+
+Update a dev document with replace, append, or prepend modes.
+
+**Parameters:**
+- `title` or `id` (one required): Document identifier
+- `content` (required): New content
+- `mode` (optional): "replace" (default), "append", or "prepend"
+
+#### delete_dev_doc
+
+Soft delete a dev document.
+
+**Parameters:**
+- `title` or `id` (one required): Document identifier
+
+#### list_dev_categories
+
+List all subcategories under `dev/` with document counts.
+
+**Parameters:** None
+
+#### Example: Store CLAUDE.md in ainote
+
+```
+You: "Save this project's CLAUDE.md content to ainote"
+Claude: I'll create a dev doc in the claude category...
+→ create_dev_doc(title: "myproject-claude.md", content: "...", category: "claude")
+
+You: "Update my cursor rules in ainote"
+Claude: I'll update the cursor rules doc...
+→ update_dev_doc(title: "api-rules.mdc", category: "cursor", content: "...")
+
+You: "Show me all my dev docs"
+Claude: I'll list all documents under dev/...
+→ list_dev_docs()
+```
+
+---
+
 ## API Reference
 
 The MCP server communicates with the AI Note API using the following endpoints:

package/index.js

@@ -1,229 +1,31 @@
 #!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import axios from 'axios';
-
-const API_KEY = process.env.AINOTE_API_KEY;
-const API_URL = process.env.AINOTE_API_URL || 'https://api.ainote.dev';
-
-// Create axios instance with default config
-const api = axios.create({
-  baseURL: API_URL,
-  headers: {
-    'Authorization': `McpKey ${API_KEY}`,
-    'Content-Type': 'application/json'
-  }
-});
-
-// Create MCP server
-const server = new Server(
-  {
-    name: 'ainote-mcp',
-    version: '1.0.0',
-  },
-  {
-    capabilities: {
-      tools: {},
-    },
-  }
-);
-
-// Define available tools
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: 'list_tasks',
-        description: 'List tasks from AI Note',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            status: {
-              type: 'string',
-              enum: ['pending', 'completed'],
-              description: 'Filter by task status'
-            },
-            limit: {
-              type: 'number',
-              description: 'Maximum number of tasks to return (default: 25, max: 500)'
-            },
-            search: {
-              type: 'string',
-              description: 'Search keyword in task content'
-            }
-          }
-        }
-      },
-      {
-        name: 'create_task',
-        description: 'Create a new task in AI Note',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            content: {
-              type: 'string',
-              description: 'Task content'
-            },
-            is_important: {
-              type: 'boolean',
-              description: 'Mark task as important'
-            },
-            due_date: {
-              type: 'string',
-              description: 'Due date in ISO format'
-            },
-            category_id: {
-              type: 'string',
-              description: 'Category ID'
-            }
-          },
-          required: ['content']
-        }
-      },
-      {
-        name: 'update_task',
-        description: 'Update an existing task',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            id: {
-              type: 'string',
-              description: 'Task ID'
-            },
-            content: {
-              type: 'string',
-              description: 'New task content'
-            },
-            is_important: {
-              type: 'boolean',
-              description: 'Update important status'
-            },
-            completed_at: {
-              type: 'string',
-              description: 'Mark as completed (ISO format) or null to uncomplete'
-            }
-          },
-          required: ['id']
-        }
-      },
-      {
-        name: 'delete_task',
-        description: 'Delete a task (soft delete)',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            id: {
-              type: 'string',
-              description: 'Task ID to delete'
-            }
-          },
-          required: ['id']
-        }
-      },
-      {
-        name: 'list_categories',
-        description: 'List all categories',
-        inputSchema: {
-          type: 'object',
-          properties: {}
-        }
-      }
-    ]
-  };
-});
-
-// Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  try {
-    switch (name) {
-      case 'list_tasks': {
-        const response = await api.get('/api/mcp/tasks', {
-          params: args
-        });
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(response.data, null, 2)
-            }
-          ]
-        };
-      }
-
-      case 'create_task': {
-        const response = await api.post('/api/mcp/tasks', {
-          task: args
-        });
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(response.data, null, 2)
-            }
-          ]
-        };
-      }
-
-      case 'update_task': {
-        const { id, ...updateData } = args;
-        const response = await api.put(`/api/mcp/tasks/${id}`, {
-          task: updateData
-        });
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(response.data, null, 2)
-            }
-          ]
-        };
-      }
-
-      case 'delete_task': {
-        const response = await api.delete(`/api/mcp/tasks/${args.id}`);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(response.data, null, 2)
-            }
-          ]
-        };
-      }
-
-      case 'list_categories': {
-        const response = await api.get('/api/mcp/categories');
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(response.data, null, 2)
-            }
-          ]
-        };
-      }
-
-      default:
-        throw new Error(`Unknown tool: ${name}`);
-    }
-  } catch (error) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error: ${error.message}\n${error.response?.data ? JSON.stringify(error.response.data, null, 2) : ''}`
-        }
-      ],
-      isError: true
-    };
+/**
+ * AI Note MCP Server - Claude Desktop Integration (stdio transport)
+ * Also supports CLI subcommands: signup
+ */
+
+const subcommand = process.argv[2];
+
+if (subcommand === 'signup') {
+  const { runSignup } = await import('./lib/cli/signup.js');
+  await runSignup();
+} 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 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');
   }
-});
 
-// Start the server
-const transport = new StdioServerTransport();
-await server.connect(transport);
+  const { server } = createClaudeServer({ defaultAuthContext });
 
-console.error('AI Note MCP proxy server started');
+  await server.connect(transport);
+  console.error('AI Note MCP stdio server started (Claude Desktop compatible)');
+}

package/lib/auth/mcp-key.js

@@ -0,0 +1,14 @@
+import { getConfig } from '../core/config.js';
+
+export function authenticateWithMcpKey() {
+  const config = getConfig();
+
+  if (!config.api.key) {
+    throw new Error('AINOTE_API_KEY is required to authenticate MCP requests');
+  }
+
+  return {
+    type: 'mcpKey',
+    apiKey: config.api.key
+  };
+}

package/lib/auth/oauth.js

@@ -0,0 +1,18 @@
+export function authenticateWithOAuth(headers = {}) {
+  const authHeader = headers['authorization'] || headers['Authorization'];
+
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    throw new Error('Missing or invalid Bearer token for OAuth authentication');
+  }
+
+  const token = authHeader.substring('Bearer '.length).trim();
+
+  if (!token) {
+    throw new Error('Bearer token is empty');
+  }
+
+  return {
+    type: 'oauth',
+    token
+  };
+}

package/lib/auth/strategy-factory.js

@@ -0,0 +1,31 @@
+import { authenticateWithMcpKey } from './mcp-key.js';
+import { authenticateWithOAuth } from './oauth.js';
+import { getFeatureFlags } from '../core/config.js';
+
+export function resolveAuthContext(transportType, headers = {}) {
+  if (transportType === 'stdio') {
+    try {
+      return authenticateWithMcpKey();
+    } catch {
+      // No API key configured — allow anonymous mode for onboarding tools
+      return { type: 'anonymous' };
+    }
+  }
+
+  const features = getFeatureFlags();
+
+  if (transportType === 'sse' && features.oauthAuth) {
+    try {
+      return authenticateWithOAuth(headers);
+    } catch {
+      // Fall through to MCP key or anonymous
+    }
+  }
+
+  // Default fallback to MCP key, then anonymous for onboarding
+  try {
+    return authenticateWithMcpKey();
+  } catch {
+    return { type: 'anonymous' };
+  }
+}