Neemee MCP

🚀 Neemee MCP客戶端庫

Neemee MCP客戶端庫是一個TypeScript庫，藉助官方的模型上下文協議（Model Context Protocol，MCP）SDK，可連接到Neemee MCP服務器。它為通過MCP與Neemee個人知識管理系統進行交互提供了便捷接口，支持HTTP和STDIO兩種傳輸模式，並且提供完整的TypeScript支持。

🚀 快速開始

HTTP模式（Web應用程序）

import { NeemeeClient } from 'neemee-mcp';

const client = new NeemeeClient({
  transport: 'http',
  baseUrl: 'https://neemee.app/mcp',
  apiKey: 'your-api-key'
});

await client.connect();

// 創建一個筆記
const result = await client.tools.createNote({
  content: 'My note content',
  title: 'My Note'
});

console.log(result);

await client.disconnect();

STDIO模式（直接進程通信）

import { NeemeeClient } from 'neemee-mcp';

const client = new NeemeeClient({
  transport: 'stdio'
});

await client.connect();

// 使用與HTTP模式相同的API
const notes = await client.resources.listNotes();
console.log(notes);

await client.disconnect();

✨ 主要特性

• 提供便捷接口，可通過模型上下文協議（MCP）與Neemee個人知識管理系統進行交互。
• 支持HTTP和STDIO兩種傳輸模式。
• 提供完整的TypeScript支持。

📦 安裝指南

npm install neemee-mcp

💻 使用示例

基礎用法

import { NeemeeClient } from 'neemee-mcp';

const client = new NeemeeClient({
  transport: 'http',
  baseUrl: 'https://neemee.app/mcp',
  apiKey: 'your-api-key'
});

await client.connect();

// 創建一個筆記
const result = await client.tools.createNote({
  content: 'My note content',
  title: 'My Note'
});

console.log(result);

await client.disconnect();

高級用法

import { NeemeeClient, AuthenticationError, ConnectionError } from 'neemee-mcp';

async function example() {
  const client = new NeemeeClient({
    transport: 'http',
    baseUrl: 'https://neemee.app/mcp',
    apiKey: process.env.NEEMEE_API_KEY
  });

  try {
    await client.connect();
    
    // 創建一個筆記
    const createResult = await client.tools.createNote({
      content: '# My First Note\n\nThis is some content.',
      title: 'First Note',
      frontmatter: {
        tags: ['example', 'test'],
        priority: 'high'
      }
    });
    
    console.log('Created note:', createResult);
    
    // 搜索筆記
    const searchResult = await client.tools.searchNotes({
      query: 'first',
      tags: 'example',
      limit: 10
    });
    
    console.log('Found notes:', searchResult);
    
    // 列出可用資源
    const resources = await client.listAvailableResources();
    console.log('Available resources:', resources);
    
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error('Authentication failed - check your API key');
    } else if (error instanceof ConnectionError) {
      console.error('Connection failed - check server URL and network');
    } else {
      console.error('Unexpected error:', error);
    }
  } finally {
    await client.disconnect();
  }
}

example().catch(console.error);

📚 詳細文檔

API參考

NeemeeClient

這是主要的客戶端類，可用於訪問工具和資源。

構造函數選項

interface NeemeeClientOptions {
  transport: 'http' | 'stdio';
  baseUrl?: string;        // 用於HTTP模式
  apiKey?: string;         // 用於身份驗證
  timeout?: number;        // 請求超時時間（毫秒）
}

方法

• connect(): Promise<void> - 連接到服務器
• disconnect(): Promise<void> - 斷開與服務器的連接
• listAvailableTools(): Promise<any> - 列出可用的MCP工具
• listAvailableResources(): Promise<any> - 列出可用的MCP資源

工具API

可通過client.tools訪問：

筆記操作

// 創建一個筆記
await client.tools.createNote({
  content: 'Note content',
  title: 'Optional title',
  url: 'Optional source URL',
  notebook: 'Optional notebook name',
  frontmatter: { /* Optional metadata */ }
});

// 更新一個筆記
await client.tools.updateNote({
  id: 'note-id',
  content: 'Updated content',
  title: 'Updated title'
});

// 刪除一個筆記
await client.tools.deleteNote('note-id', true);

// 搜索筆記
await client.tools.searchNotes({
  query: 'search terms',
  notebook: 'notebook-name',
  domain: 'example.com',
  tags: 'tag1,tag2',
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  limit: 50
});

筆記本操作

// 創建一個筆記本
await client.tools.createNotebook('Notebook Name', 'Optional description');

// 更新一個筆記本
await client.tools.updateNotebook('notebook-id', 'New Name', 'New description');

// 刪除一個筆記本
await client.tools.deleteNotebook('notebook-id', true);

// 搜索筆記本
await client.tools.searchNotebooks('search query', 20);

資源API

可通過client.resources訪問：

筆記操作

// 列出筆記並進行過濾
await client.resources.listNotes({
  page: 1,
  limit: 20,
  search: 'search terms',
  domain: 'example.com',
  notebook: 'notebook-name',
  tags: 'tag1,tag2',
  startDate: '2024-01-01',
  endDate: '2024-12-31'
});

// 獲取特定筆記
await client.resources.getNote('note-id');

筆記本操作

// 列出筆記本
await client.resources.listNotebooks({
  page: 1,
  limit: 20,
  search: 'search terms'
});

// 獲取特定筆記本
await client.resources.getNotebook('notebook-id');

系統信息

// 獲取使用統計信息
await client.resources.getStats();

// 檢查系統健康狀況
await client.resources.getHealth();

// 獲取最近活動
await client.resources.getRecentActivity();

錯誤處理

該庫針對不同的失敗場景提供了特定的錯誤類型：

import { 
  NeemeeClientError,
  AuthenticationError,
  ConnectionError,
  NotFoundError,
  ValidationError,
  ServerError
} from 'neemee-mcp';

try {
  await client.connect();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof ConnectionError) {
    console.error('Failed to connect to server');
  } else if (error instanceof NeemeeClientError) {
    console.error('Client error:', error.message);
  }
}

從v1.x遷移

重大變更

• 最低Node.js版本：現在需要Node.js 18.0.0及以上版本。
• 構造函數選項：格式已更改（請參閱快速開始示例）。
• 錯誤類型：錯誤層次結構已更新。
• 方法簽名：為了提高類型安全性，部分參數已優化。

遷移指南

舊的v1.x用法

// v1.x（已棄用）
const client = new LegacyNeemeeClient({
  useStdio: false,
  serverUrl: 'https://api.example.com',
  apiKey: 'key'
});

新的v2.x用法

// v2.x（推薦）
const client = new NeemeeClient({
  transport: 'http',
  baseUrl: 'https://api.example.com',
  apiKey: 'key'
});

舊版兼容性

為了實現臨時兼容性，可以使用LegacyNeemeeClient：

import { LegacyNeemeeClient } from 'neemee-mcp';

// 在遷移期間提供舊版API
const client = new LegacyNeemeeClient({
  useStdio: false,
  serverUrl: 'https://api.example.com',
  apiKey: 'key'
});

開發

從源代碼構建

git clone https://github.com/Paul-Bonneville-Labs/neemee-mcp.git
cd neemee-mcp
npm install
npm run build

運行測試

# 測試客戶端功能
npm run test:client

# 測試舊版兼容性
npm run test:legacy

# 使用模擬API服務器運行測試
npm run test:mock-api

可用腳本

• npm run build - 將TypeScript編譯到dist/目錄
• npm run dev - 運行開發服務器並支持熱重載
• npm run test:client - 測試新的客戶端API
• npm run test:legacy - 測試舊版兼容性
• npm run test:integration - 完整的集成測試

配置

Claude桌面配置

將此包用作STDIO傳輸的本地橋樑：

{
  "mcpServers": {
    "neemee-local": {
      "command": "npx",
      "args": ["-y", "neemee-mcp", "--api-key=your-api-key-here"],
      "env": {
        "NEEMEE_API_BASE_URL": "https://neemee.app/mcp"
      }
    }
  }
}

身份驗證：使用API密鑰進行身份驗證。您可以從Neemee設置中獲取API密鑰。API密鑰可以通過args中的--api-key標誌提供，也可以作為NEEMEE_API_KEY環境變量提供。

環境變量

• NEEMEE_API_KEY - 您的Neemee API密鑰（STDIO模式必需）
• NEEMEE_API_BASE_URL - Neemee API的基礎URL（默認為https://neemee.app/mcp）

身份驗證範圍

客戶端根據您的API密鑰支持不同的權限級別：

• read：訪問資源和搜索操作
• write：創建和更新操作（包括read權限）
• admin：刪除操作（包括write和read權限）

TypeScript支持

該庫使用TypeScript編寫，並提供完整的類型定義：

import type { 
  NeemeeClientOptions,
  CreateNoteParams,
  UpdateNoteParams,
  SearchNotesParams 
} from 'neemee-mcp';

const options: NeemeeClientOptions = {
  transport: 'http',
  baseUrl: 'https://api.example.com',
  apiKey: 'your-key'
};

const noteParams: CreateNoteParams = {
  content: 'Note content',
  title: 'Note title',
  frontmatter: {
    tags: ['typescript', 'example'],
    date: new Date().toISOString()
  }
};

📄 許可證

本項目採用MIT許可證。

支持

• GitHub問題：報告錯誤和請求功能
• 文檔：完整的API文檔