使用说明

便签MCP服务器

用于管理便签的MCP（模型上下文协议）服务器。该项目提供了一个MCP接口和一个功能齐全的REST API，用于创建、更新、删除、搜索和管理注释、标记和部分。它还提供了一个基于React的UI，用于与您的便签进行交互。

UI概述

Sticky Notes UI提供了一个现代、直观的界面来管理您的笔记：

左侧边栏：按对话、标签、颜色和日期过滤和组织笔记
主要内容：带有markdown渲染和实时更新的笔记网格视图
关于对话框：访问服务器配置信息（Web URL、WebSocket URL、数据库位置）
主题支持：在亮模式和暗模式之间切换
批量操作：为批量操作选择多个注释

特性

增强的WebSocket支持:
- 实时钞票同步
- 强健的重新连接策略
- 用于离线处理的消息队列
- 连接状态管理
服务器配置:
- 关于带有服务器详细信息的模态
- 动态端口分配
- 配置端点
主题系统:
- 支持亮/暗模式
- 主题持久性
- 动态主题切换
高级UI功能:
- 编辑器中的Markdown预览
- 批量操作（删除、着色、导出）
- 增强的过滤和排序
- 改进了分页
- 删除对话/标签中的最后一条注释时自动重置过滤器
MCP开发：实现MCP协议端点和工具处理程序（例如，创建注释、更新注释、删除注释、搜索注释、列出对话）。
REST API：支持通过Express对笔记、章节和标签进行完整的CRUD操作。
WebSocket支持：通过内置的WebSocket服务器提供可选的实时功能。
全文检索：可选SQLite FTS5，用于高效的笔记搜索。
标签管理：具有父子关系和改进的标签搜索功能的分层标签系统。
部门组织：将笔记分组到可自定义的部分。
颜色编码：支持颜色编码注释和批量颜色操作。
持久性：使用SQLite（通过better-splite3）进行本地存储。
UI集成：提供基于React的用户界面 /public 文件夹。
端口扫描：如果配置的端口正在使用中，则自动查找可用端口。
分页：客户端分页，每页可自定义项目。
对话管理：使用元数据（总笔记、创建日期、上次更新）增强对话跟踪。
Markdown支持：具有预览功能的笔记内容的完整markdown渲染。
高级过滤：按标签、对话和文本搜索进行组合过滤。
导出功能:
- 单张/多张纸币导出
- Markdown格式支持
- 自定义文件名选项

需求

Node.js（建议使用v16或更高版本）
npm（或pnpm）
SQLite（不需要额外安装，因为它使用better squelite3，它捆绑了SQLite）

安装和设置

克隆存储库

git clone https://your.repo.url/sticky-notes-server.git
cd sticky-notes-server

再进行
```
npm install
```
构建项目
```
npm run build
```
运行服务器
```
npm start
```

配置

服务器支持具有三个优先级（从高到低）的灵活配置系统：

环境变量
配置文件
默认值

环境变量

STICKY_NOTES_CONFIG：自定义配置文件位置的路径
DB_ROOT：数据库文件的根目录
DB_PATH：数据库文件名
DB_TIMEOUT：数据库操作超时（毫秒）
DB_VERBOSE：启用详细数据库日志记录（'true'/'false'）
WEB_UI_PORT：web UI的端口
WS_PORT：WebSocket服务器的端口
ENABLE_WEBSOCKET：启用/禁用WebSocket支持（“真”/“假”）
ENABLE_FTS：启用/禁用全文搜索（“真”/“假”）

配置文件

服务器在以下位置查找配置文件（按顺序）：

中指定的路径 STICKY_NOTES_CONFIG 环境变量
.sticky-notes.config.json 在当前工作目录中
.sticky-notes.config.json 在用户的主目录中
/etc/sticky-notes/config.json （仅限非Windows系统）

配置文件示例：

{
    "db": {
        "root": "C:/Users/username/Documents",
        "path": "sticky-notes.db",
        "timeout": 10000,
        "verbose": false
    },
    "server": {
        "webUiPort": 3088,
        "wsPort": 8089
    },
    "features": {
        "enableWebsocket": false,
        "enableFTS": true
    }
}

默认配置

如果没有提供配置，服务器将使用以下默认值：

{
    "db": {
        "root": "<user home directory>",
        "path": "sticky-notes.db",
        "timeout": 10000,
        "verbose": false (true in development)
    },
    "server": {
        "webUiPort": 3000,
        "wsPort": 8080
    },
    "features": {
        "enableWebsocket": true,
        "enableFTS": true
    }
}

港口装卸

如果配置的端口正在使用中，服务器将：

尝试查找下一个可用端口（扫描高达100个端口）
记录一条消息，指示实际使用的端口
在新端口上继续正常运行

例如，如果端口3000正在使用中，服务器可能会使用3001并记录：

Web UI running at http://localhost:3001 (original port 3000 was in use)

运行服务器

要启动便签MCP服务器，请运行：

npm start

这将：

使用标准I/O传输启动MCP服务器
启动为上的UI提供服务的Express web服务器 http://localhost:3000
初始化端口8080上的WebSocket服务器
使用所有必要的表和索引设置SQLite数据库

按 Ctrl+C 停止服务器。

MCP工具

服务器提供了几个MCP工具用于与笔记交互：

创建笔记

使用可选标记创建新注释。

{
  "name": "create-note",
  "arguments": {
    "title": "Meeting Notes",
    "content": "Discussed Q4 plans.",
    "conversationId": "conv123",
    "tags": ["meeting", "planning"],
    "color_hex": "#FFE999"
  }
}

必填字段：

title：字符串（1-100个字符，通常为对话名称）
content：字符串（支持markdown）
conversationId：String（对话的唯一标识符，由您提供）

可选字段：

tags：字符串数组
color_hex：字符串（十六进制颜色代码）。可用颜色：
- 黄色：“#FFE999”（默认）
- 绿色：“#A7F3D0”
- 蓝色：“#93C5FD”
- 红色：“#FCA5A5”
- 紫色：“#DDD6FE”
- 橙色：“#FFB17A”

示例响应： Note created with id 123

更新说明

更新现有笔记的内容。

{
  "name": "update-note",
  "arguments": {
    "id": "123",
    "content": "Updated meeting notes content"
  }
}

删除注释

删除特定注释。

{
  "name": "delete-note",
  "arguments": {
    "id": "123"
  }
}

搜索笔记

根据各种条件搜索笔记。支持按标签、对话和文本搜索进行组合过滤。

{
  "name": "search-notes",
  "arguments": {
    "query": "meeting",
    "tags": ["important"],
    "conversationId": "conv123"
  }
}

列出对话

返回包含元数据的系统中所有会话ID的列表。

{
  "name": "list-conversations",
  "arguments": {}
}

响应示例：

[
  {
    "conversationId": "conv123",
    "totalNotes": 5,
    "firstCreated": 1707753600,
    "lastUpdated": 1707840000
  },
  {
    "conversationId": "meeting-2024",
    "totalNotes": 3,
    "firstCreated": 1707667200,
    "lastUpdated": 1707753600
  }
]

REST API端点

服务器公开了几个REST端点：

注意端点

GET/api/注释
- 查询参数：
  - search：文本搜索查询
  - tags：标记名数组（服务器端处理重复数据消除）
  - conversation：对话ID
  - color：颜色十六进制代码
  - startDate：按创建日期筛选
  - page：页码（默认值：1）
  - limit：每页项目数（默认值：10）
  - sort：排序字段和方向（例如，“updated_at DESC”）
- 响应包括分页元数据：
```
{
  "notes": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}
```

截面端点

GET/api/部分
POST/api/部分
PUT/api/节/：id
DELETE/api/sections/：id
GET/api/sections/：id/notes

标记端点

GET/api/标签
GET/api/标签/层次结构
PATCH/api/tags/：id/party

对话端点

GET/api/对话

返回包含元数据的对话列表：

{
  "conversations": [
    {
      "conversationId": "conv123",
      "totalNotes": 5,
      "firstCreated": 1707753600,
      "lastUpdated": 1707840000
    }
  ]
}

与Claude Desktop集成

方法1：直接集成

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "stickyNotes": {
      "command": "node",
      "args": ["path/to/sticky-notes-server/build/index.js"],
      "env": {
        "DB_ROOT": "desired/db/location",
        "WEB_UI_PORT": "3000",
        "WS_PORT": "8080"
      }
    }
  }
}

方法2:NPX集成

如果作为NPX包发布（尚未实现）：

{
  "mcpServers": {
    "stickyNotes": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/sticky-notes-server"
      ],
      "env": {
        "DB_ROOT": "desired/db/location"
      }
    }
  }
}

发展

项目结构

sticky-notes-server/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts            // MCP server main entry point
    ├── public/             // React-based UI
    │   ├── index.html
    │   ├── app.js
    │   ├── components/     // React components
    │   │   ├── Note.js    // Note component with markdown support
    │   │   ├── PaginationControls.js
    │   │   └── Sidebar.js // Enhanced sidebar with conversations
    │   └── utils/
    │       └── markdown.ts // Markdown rendering utilities
    └── migrations/         // Database migrations

开发命令

从开发模式开始:
```
npm run dev
```
为生产而建:
```
npm run build
npm start
```

数据库模式

服务器使用以下主表：

notes：存储笔记内容和元数据
sections：管理笔记组织
tags：存储标记层次结构
note_tags：注释标记关系的连接表
notes_fts：全文搜索虚拟表

WebSocket实现

客户端集成

该应用程序包括一个用于WebSocket管理的自定义React挂钩：

const { connectionStatus, sendMessage, lastMessage } = useWebSocket({
    url: `ws://localhost:${wsPort}`,
    onMessage: handleMessage,
    reconnectAttempts: 5,
    reconnectInterval: 1000
});

消息类型

客户端消息:
- NOTE_CREATE：创建新笔记
- NOTE_UPDATE：更新现有注释
- NOTE_DELETE：删除注释
- SYNC_REQUEST：请求同步
服务器消息:
- NOTE_CREATED：广播新音符
- NOTE_UPDATED：广播更新
- NOTE_DELETED：广播删除
- SYNC_RESPONSE：同步数据
- ERROR：错误信息

重新连接策略

WebSocket实现包括一个复杂的重新连接策略：

指数退避
可配置的重试尝试
连接状态跟踪
断开连接期间的消息队列

主题系统

该应用程序包括一个全面的主题系统：

const ThemeProvider = ({ children }) => {
    const [theme, setTheme] = React.useState(() => {
        const savedTheme = localStorage.getItem('theme');
        return savedTheme || 
               (window.matchMedia('(prefers-color-scheme: dark)').matches 
                ? 'dark' : 'light');
    });
    // ... theme logic
};

主题功能

系统偏好检测
本地存储持久性
动态CSS类切换
平滑过渡
暗/亮模式切换

批量操作

该应用程序支持批量操作：

选择：多选笔记
行动:
- 删除多个笔记
- 更改多个音符的颜色
- 导出所选笔记
用户界面：专用批量操作工具栏

导出功能

增强的出口能力：

const exportOptions = {
    format: 'md',
    includeMetadata: true,
    includeToc: false,
    filename: 'custom_name.md'
};

导出功能

单张纸币出口
多张纸币导出
自定义文件名支持
Markdown格式
元数据包含选项

故障排除

常见问题和解决方案：

数据库位置问题
- 确保 DB_ROOT 环境变量设置正确
- 检查目标目录中的文件权限
端口冲突
- 验证端口3000和8080是否可用
- 使用 WEB_UI_PORT 和 WS_PORT 配置备用端口
性能问题
- 服务器使用SQLite优化，包括WAL模式
- 为常见查询自动创建索引
- 考虑对大型数据集进行定期数据库维护（VACUUM）

贡献

分叉存储库
创建要素分支
提交您的更改
推到分支
创建拉取请求

许可证

该项目根据 MIT许可证.

支持

对于问题、疑问或贡献：

检查问题章节
如果需要，创建新问题
加入我们的社区讨论

使用说明

便签MCP服务器

UI概述

特性

需求

安装和设置

配置

环境变量

配置文件

默认配置

港口装卸

运行服务器

MCP工具

创建笔记

更新说明

删除注释

搜索笔记

列出对话

REST API端点

注意端点

截面端点

标记端点

对话端点

与Claude Desktop集成

方法1：直接集成

方法2:NPX集成

发展

项目结构

开发命令

数据库模式

WebSocket实现

客户端集成

消息类型

重新连接策略

主题系统

主题功能

批量操作

导出功能

导出功能

故障排除

贡献

许可证

支持

相关 MCP

Obsidian笔记搜索服务

n8n工作流管理服务

Web漏洞扫描MCP服务器

知识库AI代理服务器

Neo N3 区块链 MCP 服务器

F5设备管理服务器