Neemee MCP Server

Neemee MCP客户端库

一个TypeScript客户端库，用于使用官方的模型上下文协议SDK连接到Neemee MCP服务器。

概述

该库提供了一个方便的界面，用于通过模型上下文协议（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 参考

Neemee客户端

提供对工具和资源访问的主客户端类。

构建器选项

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

方法

• connect(): Promise -连接到服务器
• disconnect(): Promise -断开与服务器的连接
• listAvailableTools(): Promise -列出可用的MCP工具
• listAvailableResources(): Promise -列出可用的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桌面配置

将此包用作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密钥可以通过 --api-key 旗在 args 或作为a NEEMEE_API_KEY 环境变量。

环境变量

• NEEMEE_API_KEY -您的Neemee API密钥（STDIO模式需要）
• NEEMEE_API_BASE_URL -Neemee API的基本URL（默认为https://neemee.app/mcp)

身份验证范围

客户端支持基于您的API密钥的不同权限级别：

• 读：获取资源和搜索操作
• 写：创建和更新操作（包括读取）
• 管理员：删除操作（包括写入和读取）

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

许可证

麻省理工学院

支持

• GitHub问题： 报告错误和请求功能
• 文档： API完整文档