neemee-mcp

Neemee MCP クライアントライブラリ

公式の Model Context Protocol SDK を使用して Neemee MCP サーバーに接続するための TypeScript クライアントライブラリです。

概要

このライブラリは、Model Context Protocol（MCP）を通じて Neemee のパーソナルナレッジ管理システムとやり取りするための便利なインターフェースを提供します。HTTP と STDIO の両方のトランスポートモードに対応し、TypeScript を全面的にサポートしています。

インストール

npm install neemee-mcp

クイックスタート

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();

// Create a note
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();

// Use same API as HTTP mode
const notes = await client.resources.listNotes();
console.log(notes);

await client.disconnect();

API リファレンス

NeemeeClient

ツールとリソースにアクセスするためのメインクライアントクラスです。

コンストラクターのオプション

interface NeemeeClientOptions {
  transport: 'http' | 'stdio';
  baseUrl?: string;        // For HTTP mode
  apiKey?: string;         // For authentication
  timeout?: number;        // Request timeout in milliseconds
}

メソッド

• connect(): Promise<void> - サーバーに接続します
• disconnect(): Promise<void> - サーバーとの接続を切断します
• listAvailableTools(): Promise<any> - 利用可能な MCP ツールを一覧表示します
• listAvailableResources(): Promise<any> - 利用可能な MCP リソースを一覧表示します

ツール API

client.tools からアクセスします。

ノート

// Create a note
await client.tools.createNote({
  content: 'Note content',
  title: 'Optional title',
  url: 'Optional source URL',
  notebook: 'Optional notebook name',
  frontmatter: { /* Optional metadata */ }
});

// Update a note
await client.tools.updateNote({
  id: 'note-id',
  content: 'Updated content',
  title: 'Updated title'
});

// Delete a note
await client.tools.deleteNote('note-id', true);

// Search notes
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
});

ノートブック

// Create a notebook
await client.tools.createNotebook('Notebook Name', 'Optional description');

// Update a notebook
await client.tools.updateNotebook('notebook-id', 'New Name', 'New description');

// Delete a notebook
await client.tools.deleteNotebook('notebook-id', true);

// Search notebooks
await client.tools.searchNotebooks('search query', 20);

リソース API

client.resources からアクセスします。

ノート

// List notes with filtering
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'
});

// Get a specific note
await client.resources.getNote('note-id');

ノートブック

// List notebooks
await client.resources.listNotebooks({
  page: 1,
  limit: 20,
  search: 'search terms'
});

// Get a specific notebook
await client.resources.getNotebook('notebook-id');

システム情報

// Get usage statistics
await client.resources.getStats();

// Check system health
await client.resources.getHealth();

// Get recent activity
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 (deprecated)
const client = new LegacyNeemeeClient({
  useStdio: false,
  serverUrl: 'https://api.example.com',
  apiKey: 'key'
});

v2.x での新しい使い方

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

レガシー互換性

一時的な互換性が必要な場合は、LegacyNeemeeClient を使用します。

import { LegacyNeemeeClient } from 'neemee-mcp';

// This provides the old API while you migrate
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

テストの実行

# Test client functionality
npm run test:client

# Test legacy compatibility
npm run test:legacy

# Run with mock API server
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 - 統合テストをすべて実行します

使用例

エラー処理を含む完全な例

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();
    
    // Create a note
    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);
    
    // Search for notes
    const searchResult = await client.tools.searchNotes({
      query: 'first',
      tags: 'example',
      limit: 10
    });
    
    console.log('Found notes:', searchResult);
    
    // List available resources
    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);

タグベースの検索

// Search notes with multiple tags
const taggedNotes = await client.tools.searchNotes({
  tags: 'work,important,urgent',
  notebook: 'Projects',
  limit: 25
});

// List notes with specific tags via resources
const resourceNotes = await client.resources.listNotes({
  tags: 'research,ai',
  domain: 'arxiv.org',
  limit: 50
});

設定

Claude Desktop の設定

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 Issues：バグの報告や機能のリクエスト
• ドキュメント：API ドキュメント全文