@ainote/mcp 1.0.1 → 1.0.3

package/README-ko.md

@@ -103,16 +103,48 @@ Claude Desktop을 AI Note 작업 관리 시스템에 연결하는 MCP(Model Cont
 
 ## 설치
 
-### 설치
+### 옵션 1: npm에서 설치 (권장)
 
-소스코드로부터 설치
+```bash
+npm install -g @ainote/mcp
+```
+
+### 옵션 2: 소스코드로부터 설치
+
+```bash
+git clone https://github.com/ainote-dev/ainote-mcp.git
+cd ainote-mcp-server
+npm install
+```
+
+## 업데이트
+
+### npm에서 업데이트 (권장)
+
+npm을 통해 설치한 경우 최신 버전으로 업데이트:
+
+```bash
+npm update -g @ainote/mcp
+```
+
+특정 버전을 설치하려면:
+
+```bash
+npm install -g @ainote/mcp@1.0.2
+```
+
+### 소스코드에서 업데이트
+
+소스코드로 설치한 경우:
 
 ```bash
-git clone https://github.com/your-username/ainote-mcp-server.git
 cd ainote-mcp-server
+git pull origin main
 npm install
 ```
 
+업데이트 후에는 **Claude Desktop을 재시작**하여 새 버전을 로드하세요.
+
 ## 설정
 
 ### 1. 환경 변수 설정

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,6 +23,32 @@ 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
@@ -30,7 +60,7 @@ A Model Context Protocol (MCP) server that connects Claude Desktop to your AI No
 
 ## 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
@@ -51,6 +81,34 @@ cd ainote-mcp-server
 npm install
 ```
 
+## Update
+
+### Update from npm (Recommended)
+
+To update to the latest version when installed via npm:
+
+```bash
+npm update -g @ainote/mcp
+```
+
+Or to install a specific version:
+
+```bash
+npm install -g @ainote/mcp@1.0.2
+```
+
+### Update from source
+
+If you installed from source:
+
+```bash
+cd ainote-mcp-server
+git pull origin main
+npm install
+```
+
+After updating, **restart Claude Desktop** to load the new version.
+
 ## Configuration
 
 To connect the MCP server with Claude Desktop, follow these steps.
@@ -111,6 +169,81 @@ 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.
+
+### 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

package/index.js

@@ -1,229 +1,25 @@
 #!/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://ainote-5muq.onrender.com';
-
-// Create axios instance with default config
-const api = axios.create({
-  baseURL: API_URL,
-  headers: {
-    'Authorization': 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;
+/**
+ * AI Note MCP Server - Claude Desktop Integration (stdio transport)
+ */
 
-  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)
-            }
-          ]
-        };
-      }
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { resolveAuthContext } from './lib/auth/strategy-factory.js';
+import { createClaudeServer } from './lib/core/server-factory.js';
 
-      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)
-            }
-          ]
-        };
-      }
+const transport = new StdioServerTransport();
 
-      case 'delete_task': {
-        const response = await api.delete(`/api/mcp/tasks/${args.id}`);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(response.data, null, 2)
-            }
-          ]
-        };
-      }
+let defaultAuthContext;
 
-      case 'list_categories': {
-        const response = await api.get('/api/mcp/categories');
-        return {
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(response.data, null, 2)
-            }
-          ]
-        };
-      }
+try {
+  defaultAuthContext = resolveAuthContext('stdio');
+} catch (error) {
+  console.error(`[ainote-mcp] Authentication error: ${error.message}`);
+  process.exitCode = 1;
+  throw error;
+}
 
-      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
-    };
-  }
-});
+const { server } = createClaudeServer({ defaultAuthContext });
 
-// Start the server
-const transport = new StdioServerTransport();
 await server.connect(transport);
-
-console.error('AI Note MCP proxy server started');
+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,18 @@
+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') {
+    return authenticateWithMcpKey();
+  }
+
+  const features = getFeatureFlags();
+
+  if (transportType === 'sse' && features.oauthAuth) {
+    return authenticateWithOAuth(headers);
+  }
+
+  // Default fallback to MCP key to maintain backward compatibility.
+  return authenticateWithMcpKey();
+}

package/lib/core/api-client.js

@@ -0,0 +1 @@
+export * from '../utils/api-client.js';

package/lib/core/config-manager.js

@@ -0,0 +1,67 @@
+const DEFAULT_API_URL = 'https://ainote-5muq.onrender.com';
+const DEFAULT_HTTP_PORT = 3030;
+
+const parseBoolean = (value, fallback) => {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = `${value}`.trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+};
+
+const parseNumber = (value, fallback) => {
+  if (value === undefined) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+const parseList = (value) => {
+  if (!value) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return value
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+};
+
+export function getConfig() {
+  const features = {
+    chatgptSupport: parseBoolean(process.env.AINOTE_ENABLE_CHATGPT_SUPPORT, true),
+    oauthAuth: parseBoolean(process.env.AINOTE_ENABLE_OAUTH_AUTH, false),
+    sseTransport: parseBoolean(process.env.AINOTE_ENABLE_SSE_TRANSPORT, true)
+  };
+
+  return {
+    api: {
+      key: process.env.AINOTE_API_KEY,
+      url: process.env.AINOTE_API_URL || DEFAULT_API_URL
+    },
+    http: {
+      port: parseNumber(process.env.AINOTE_MCP_HTTP_PORT, DEFAULT_HTTP_PORT),
+      endpoint: process.env.AINOTE_MCP_HTTP_ENDPOINT || '/sse',
+      messageEndpoint: process.env.AINOTE_MCP_HTTP_MESSAGES_ENDPOINT || '/messages',
+      allowedOrigins: parseList(process.env.AINOTE_MCP_ALLOWED_ORIGINS),
+      allowedHosts: parseList(process.env.AINOTE_MCP_ALLOWED_HOSTS)
+    },
+    features
+  };
+}
+
+export function getFeatureFlags() {
+  return getConfig().features;
+}

package/lib/core/config.js

@@ -0,0 +1 @@
+export * from './config-manager.js';

package/lib/core/mcp-server.js

@@ -0,0 +1,2 @@
+// Deprecated: use server-factory instead.
+export { createClaudeServer, createChatGptServer, createServerForProfile } from './server-factory.js';

package/lib/core/server-factory.js

@@ -0,0 +1,77 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ToolRegistry } from './tool-registry.js';
+import { getConfig } from './config-manager.js';
+import { createApiClient } from '../utils/api-client.js';
+import { getSharedTools } from '../tools/shared-tools.js';
+import { getChatGptTools } from '../tools/chatgpt-tools.js';
+import { toErrorContent } from '../tools/internal/formatters.js';
+
+function buildServerInfo(profile) {
+  return {
+    name: `ainote-mcp-${profile}`,
+    version: '1.1.0'
+  };
+}
+
+function registerTools(registry, { includeChatGpt }) {
+  registry.registerMany(getSharedTools());
+
+  if (includeChatGpt) {
+    registry.registerMany(getChatGptTools());
+  }
+}
+
+function createServer({ profile, defaultAuthContext } = {}) {
+  const config = getConfig();
+  const includeChatGpt = profile === 'chatgpt' && config.features.chatgptSupport;
+  const registry = new ToolRegistry();
+
+  registerTools(registry, { includeChatGpt });
+
+  const server = new Server(buildServerInfo(profile), {
+    capabilities: {
+      tools: {}
+    }
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: registry.listDefinitions()
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    try {
+      const { name, arguments: args } = request.params;
+      console.error(`[MCP] Calling tool: ${name}`, JSON.stringify(args));
+
+      const authContext = extra?.authInfo ?? defaultAuthContext;
+      const apiClient = createApiClient(authContext);
+
+      const result = await registry.execute(name, args, {
+        apiClient,
+        request,
+        extra
+      });
+
+      console.error(`[MCP] Tool ${name} completed successfully`);
+      return result;
+    } catch (error) {
+      console.error(`[MCP] Tool error:`, error);
+      return toErrorContent(error);
+    }
+  });
+
+  return { server, registry };
+}
+
+export function createClaudeServer(options = {}) {
+  return createServer({ profile: 'claude', ...options });
+}
+
+export function createChatGptServer(options = {}) {
+  return createServer({ profile: 'chatgpt', ...options });
+}
+
+export function createServerForProfile(profile, options = {}) {
+  return createServer({ profile, ...options });
+}

package/lib/core/tool-registry.js

@@ -0,0 +1,31 @@
+export class ToolRegistry {
+  constructor() {
+    this.tools = new Map();
+  }
+
+  register(tool) {
+    if (!tool?.definition?.name) {
+      throw new Error('Invalid tool registration: missing tool name');
+    }
+
+    this.tools.set(tool.definition.name, tool);
+  }
+
+  registerMany(tools = []) {
+    tools.forEach((tool) => this.register(tool));
+  }
+
+  listDefinitions() {
+    return Array.from(this.tools.values()).map((tool) => tool.definition);
+  }
+
+  async execute(name, args, context) {
+    const tool = this.tools.get(name);
+
+    if (!tool) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return tool.handler(args ?? {}, context ?? {});
+  }
+}

package/lib/tools/chatgpt-tools.js

@@ -0,0 +1,93 @@
+import { toSuccessContent } from './internal/formatters.js';
+
+const MAX_RESULTS = 20;
+
+function searchDefinition() {
+  return {
+    name: 'search',
+    description: 'Search tasks and categories in AI Note',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query for tasks content, categories, or due dates'
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of search results (default: 20)'
+        }
+      },
+      required: ['query']
+    }
+  };
+}
+
+function fetchDefinition() {
+  return {
+    name: 'fetch',
+    description: 'Fetch detailed information about a specific task',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Task ID to fetch detailed information'
+        }
+      },
+      required: ['id']
+    }
+  };
+}
+
+export function getChatGptTools() {
+  return [
+    {
+      definition: searchDefinition(),
+      handler: async (args, { apiClient }) => {
+        const limit = typeof args.limit === 'number' ? Math.min(args.limit, MAX_RESULTS) : MAX_RESULTS;
+        const response = await apiClient.get('/api/mcp/tasks', {
+          params: {
+            search: args.query,
+            limit
+          }
+        });
+
+        const results = Array.isArray(response.data?.tasks)
+          ? response.data.tasks.map((task) => ({
+              id: task.id,
+              title: task.content,
+              due_date: task.due_date,
+              is_important: task.is_important,
+              url: task.url ?? `https://app.ainote.dev/tasks/${task.id}`,
+              category: task.category
+            }))
+          : response.data;
+
+        return toSuccessContent({
+          results,
+          meta: {
+            source: 'ai-note',
+            query: args.query,
+            limit
+          }
+        });
+      }
+    },
+    {
+      definition: fetchDefinition(),
+      handler: async (args, { apiClient }) => {
+        const response = await apiClient.get(`/api/mcp/tasks/${args.id}`);
+        const task = response.data?.task ?? response.data;
+
+        return toSuccessContent({
+          task,
+          meta: {
+            source: 'ai-note',
+            fetched_at: new Date().toISOString()
+          }
+        });
+      }
+    }
+  ];
+}

package/lib/tools/index.js

@@ -0,0 +1,3 @@
+export { getSharedTools } from './shared-tools.js';
+export { getChatGptTools } from './chatgpt-tools.js';
+export { toSuccessContent, toErrorContent } from './internal/formatters.js';

package/lib/tools/internal/formatters.js

@@ -0,0 +1,37 @@
+export function toSuccessContent(payload, options = {}) {
+  const { pretty = true } = options;
+  const text = pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text
+      }
+    ]
+  };
+}
+
+export function toErrorContent(error) {
+  const message = error?.message ?? String(error);
+  const details = error?.response?.data;
+  const textParts = [`Error: ${message}`];
+
+  if (details) {
+    try {
+      textParts.push(JSON.stringify(details, null, 2));
+    } catch (stringifyError) {
+      textParts.push(String(details));
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: textParts.join('\n')
+      }
+    ],
+    isError: true
+  };
+}

package/lib/tools/shared-tools.js

@@ -0,0 +1,152 @@
+import { toSuccessContent } from './internal/formatters.js';
+
+function listTasksDefinition() {
+  return {
+    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'
+        }
+      }
+    }
+  };
+}
+
+function createTaskDefinition() {
+  return {
+    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']
+    }
+  };
+}
+
+function updateTaskDefinition() {
+  return {
+    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']
+    }
+  };
+}
+
+function deleteTaskDefinition() {
+  return {
+    name: 'delete_task',
+    description: 'Delete a task (soft delete)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Task ID to delete'
+        }
+      },
+      required: ['id']
+    }
+  };
+}
+
+function listCategoriesDefinition() {
+  return {
+    name: 'list_categories',
+    description: 'List all categories',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  };
+}
+
+export function getSharedTools() {
+  return [
+    {
+      definition: listTasksDefinition(),
+      handler: async (args, { apiClient }) => {
+        const result = await apiClient.callTool('list_tasks', args);
+        return result;  // Return full result with { content: [...] }
+      }
+    },
+    {
+      definition: createTaskDefinition(),
+      handler: async (args, { apiClient }) => {
+        const result = await apiClient.callTool('create_task', args);
+        return result;  // Return full result with { content: [...] }
+      }
+    },
+    {
+      definition: updateTaskDefinition(),
+      handler: async (args, { apiClient }) => {
+        const result = await apiClient.callTool('update_task', args);
+        return result;  // Return full result with { content: [...] }
+      }
+    },
+    {
+      definition: deleteTaskDefinition(),
+      handler: async (args, { apiClient }) => {
+        const result = await apiClient.callTool('delete_task', args);
+        return result;  // Return full result with { content: [...] }
+      }
+    },
+    {
+      definition: listCategoriesDefinition(),
+      handler: async (_args, { apiClient }) => {
+        const result = await apiClient.callTool('list_categories', {});
+        return result;  // Return full result with { content: [...] }
+      }
+    }
+  ];
+}

package/lib/utils/api-client.js

@@ -0,0 +1,74 @@
+import axios from 'axios';
+import { getConfig } from '../core/config-manager.js';
+
+function buildHeaders(authContext, config) {
+  const headers = {
+    'Content-Type': 'application/json'
+  };
+
+  const contextType = authContext?.type ?? 'mcpKey';
+
+  if (contextType === 'oauth') {
+    const bearerToken = authContext?.token;
+    if (!bearerToken) {
+      throw new Error('OAuth authentication requires a bearer token');
+    }
+    headers.Authorization = `Bearer ${bearerToken}`;
+  } else {
+    const apiKey = authContext?.apiKey ?? config.api.key;
+    if (!apiKey) {
+      throw new Error('AINOTE_API_KEY environment variable is required for MCP authentication');
+    }
+    headers.Authorization = `McpKey ${apiKey}`;
+  }
+
+  return headers;
+}
+
+let requestIdCounter = 1;
+
+/**
+ * JSON-RPC 2.0 요청 생성 헬퍼
+ */
+function createJsonRpcRequest(method, params = {}) {
+  return {
+    jsonrpc: '2.0',
+    id: requestIdCounter++,
+    method,
+    params
+  };
+}
+
+/**
+ * JSON-RPC 2.0 tools/call 요청 생성
+ */
+function createToolCallRequest(toolName, arguments_) {
+  return createJsonRpcRequest('tools/call', {
+    name: toolName,
+    arguments: arguments_
+  });
+}
+
+export function createApiClient(authContext) {
+  const config = getConfig();
+  const headers = buildHeaders(authContext, config);
+
+  const axiosInstance = axios.create({
+    baseURL: config.api.url,
+    headers
+  });
+
+  // JSON-RPC helper 메서드 추가
+  axiosInstance.callTool = async (toolName, arguments_) => {
+    const rpcRequest = createToolCallRequest(toolName, arguments_);
+    const response = await axiosInstance.post('/api/mcp', rpcRequest);
+
+    if (response.data.error) {
+      throw new Error(`JSON-RPC Error [${response.data.error.code}]: ${response.data.error.message}`);
+    }
+
+    return response.data.result;
+  };
+
+  return axiosInstance;
+}

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@ainote/mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "MCP server for AI Note - Connect Claude Desktop to your AI Note tasks",
   "main": "index.js",
   "type": "module",
   "bin": {
-    "ainote-mcp": "./index.js"
+    "ainote-mcp": "./index.js",
+    "ainote-mcp-http": "./server.js"
   },
   "scripts": {
     "start": "node index.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "start:http": "node server.js",
+    "test": "NODE_ENV=test NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:watch": "NODE_ENV=test NODE_OPTIONS=--experimental-vm-modules jest --watch",
+    "test:coverage": "NODE_ENV=test NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "test:verbose": "NODE_ENV=test NODE_OPTIONS=--experimental-vm-modules jest --verbose"
   },
   "keywords": [
     "mcp",
@@ -37,14 +42,44 @@
   },
   "homepage": "https://github.com/ainote-dev/ainote-mcp#readme",
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "axios": "^1.6.0"
+    "axios": "^1.6.0",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "morgan": "^1.10.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "axios-mock-adapter": "^1.22.0",
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "transform": {},
+    "testEnvironment": "node",
+    "collectCoverageFrom": [
+      "index.js",
+      "server.js",
+      "lib/**/*.js",
+      "!node_modules/**"
+    ],
+    "coverageDirectory": "coverage",
+    "coverageReporters": [
+      "text",
+      "lcov",
+      "html"
+    ],
+    "testMatch": [
+      "**/__tests__/**/*.test.js",
+      "**/?(*.)+(spec|test).js"
+    ]
   },
   "files": [
     "index.js",
+    "server.js",
+    "lib",
     "README.md",
     "README-ko.md",
     "LICENSE"

package/server.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import express from 'express';
+import cors from 'cors';
+import morgan from 'morgan';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { createChatGptServer } from './lib/core/server-factory.js';
+import { getConfig } from './lib/core/config-manager.js';
+import { resolveAuthContext } from './lib/auth/strategy-factory.js';
+
+const config = getConfig();
+
+if (!config.features.sseTransport) {
+  console.error('[ainote-mcp] SSE transport is disabled. Set AINOTE_ENABLE_SSE_TRANSPORT=true to enable.');
+  process.exit(1);
+}
+
+const app = express();
+const sessions = new Map();
+
+const corsOptions = {
+  origin: config.http.allowedOrigins.length > 0 ? config.http.allowedOrigins : true,
+  credentials: true
+};
+
+app.use(cors(corsOptions));
+app.use(express.json({ limit: '4mb' }));
+app.use(morgan(':method :url :status :response-time ms - :res[content-length]'));
+
+app.get('/health', (_req, res) => {
+  res.json({
+    status: 'ok',
+    transport: 'sse',
+    timestamp: Date.now()
+  });
+});
+
+app.get(config.http.endpoint, async (req, res) => {
+  try {
+    const { server } = createChatGptServer();
+    const transport = new SSEServerTransport(config.http.messageEndpoint, res, {
+      enableDnsRebindingProtection: config.http.allowedHosts.length > 0 || config.http.allowedOrigins.length > 0,
+      allowedHosts: config.http.allowedHosts.length > 0 ? config.http.allowedHosts : undefined,
+      allowedOrigins: config.http.allowedOrigins.length > 0 ? config.http.allowedOrigins : undefined
+    });
+
+    sessions.set(transport.sessionId, { transport, server });
+
+    transport.onclose = async () => {
+      sessions.delete(transport.sessionId);
+      try {
+        await server.close();
+      } catch (closeError) {
+        console.error(`[ainote-mcp] Error while closing server: ${closeError.message}`);
+      }
+    };
+
+    transport.onerror = (error) => {
+      console.error(`[ainote-mcp] SSE transport error: ${error.message}`);
+    };
+
+    await server.connect(transport);
+  } catch (error) {
+    console.error(`[ainote-mcp] Failed to establish SSE connection: ${error.message}`);
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Failed to establish SSE connection' });
+    }
+  }
+});
+
+app.post(config.http.messageEndpoint, async (req, res) => {
+  const sessionId = req.query.sessionId;
+
+  if (!sessionId) {
+    return res.status(400).json({ error: 'Missing sessionId query parameter' });
+  }
+
+  const session = sessions.get(sessionId);
+
+  if (!session) {
+    return res.status(404).json({ error: `No transport found for sessionId ${sessionId}` });
+  }
+
+  try {
+    const authContext = resolveAuthContext('sse', req.headers);
+    req.auth = authContext;
+  } catch (error) {
+    return res.status(401).json({ error: error.message });
+  }
+
+  try {
+    await session.transport.handlePostMessage(req, res, req.body);
+  } catch (error) {
+    console.error(`[ainote-mcp] Failed to handle POST message: ${error.message}`);
+    if (!res.headersSent) {
+      res.status(500).json({ error: 'Failed to handle message' });
+    }
+  }
+});
+
+const port = config.http.port;
+app.listen(port, () => {
+  console.error(`AI Note MCP HTTP/SSE server listening on port ${port}`);
+});