neemee-mcp

Neemee MCP 客户端库

一个用于连接 Neemee MCP 服务的 TypeScript 客户端库，使用官方 Model Context Protocol SDK。

概述

此库提供了一个便捷的接口，可通过 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 密钥。可通过 args 中的 --api-key 标志，或 NEEMEE_API_KEY 环境变量提供 API 密钥。

环境变量

• 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 文档