Neemee MCP

🚀 Neemee MCP Client Library

このライブラリは、公式のModel Context Protocol (MCP) SDKを使用して、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();

✨ 主な機能

• 公式のModel Context Protocol (MCP) SDKを使用してNeemee MCPサーバーに接続する。
• HTTPとSTDIOの両方のトランスポートモードをサポートする。
• 完全なTypeScriptサポートを提供する。

📦 インストール

npm install neemee-mcp

💻 使用例

基本的な使用法

上記のクイックスタートのコード例を参照してください。

高度な使用法

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

📚 ドキュメント

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 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ドキュメント