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