便签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": "",
"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许可证.
______________________________________________________________________
支持
对于问题、疑问或贡献：
- 检查 问题 章节
- 如果需要，创建新问题
- 加入我们的社区讨论