shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

neemee-mcp

Neemee MCP客户端库是一个TypeScript库，用于通过Model Context Protocol（MCP）与Neemee个人知识管理系统进行交互。它支持HTTP和STDIO两种传输模式，提供了创建、更新、搜索笔记和笔记本等工具API，以及获取系统信息和资源列表的资源API，并包含完整的TypeScript类型支持和错误处理机制。

article

README

🚀 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许可证。

支持

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端