{"id":27999179,"url":"https://github.com/bsmi021/sticky-notes-server","last_synced_at":"2026-05-15T08:34:28.273Z","repository":{"id":277190392,"uuid":"930910701","full_name":"bsmi021/sticky-notes-server","owner":"bsmi021","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-18T19:01:50.000Z","size":738,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-14T04:28:41.204Z","etag":null,"topics":["cool-stuff","mcp","mcp-server","mcp-servers","modelcontextprotocol","sticky-notes"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bsmi021.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-11T12:17:33.000Z","updated_at":"2025-03-19T19:47:39.000Z","dependencies_parsed_at":"2025-02-12T16:45:19.840Z","dependency_job_id":"8637363c-b307-422e-9a34-a612a6e39c26","html_url":"https://github.com/bsmi021/sticky-notes-server","commit_stats":null,"previous_names":["bsmi021/sticky-notes-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bsmi021/sticky-notes-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fsticky-notes-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fsticky-notes-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fsticky-notes-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fsticky-notes-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bsmi021","download_url":"https://codeload.github.com/bsmi021/sticky-notes-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsmi021%2Fsticky-notes-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33059519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cool-stuff","mcp","mcp-server","mcp-servers","modelcontextprotocol","sticky-notes"],"created_at":"2025-05-08T22:56:51.015Z","updated_at":"2026-05-15T08:34:28.256Z","avatar_url":"https://github.com/bsmi021.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sticky Notes MCP Server\n\nA MCP (Model Context Protocol) server for managing sticky notes. This project provides both an MCP interface and a fully-featured REST API to create, update, delete, search, and manage notes, tags, and sections. It also serves a React-based UI for interacting with your sticky notes.\n\n## UI Overview\n\n![Sticky Notes UI](images/2025-02-18_13-53-38.png)\n\nThe Sticky Notes UI provides a modern, intuitive interface for managing your notes:\n\n- **Left Sidebar**: Filter and organize notes by conversations, tags, colors, and dates\n- **Main Content**: Grid view of notes with markdown rendering and real-time updates\n- **About Dialog**: Access server configuration information (Web URL, WebSocket URL, Database location)\n- **Theme Support**: Toggle between light and dark modes\n- **Bulk Actions**: Select multiple notes for batch operations\n\n---\n\n## Features\n\n- **Enhanced WebSocket Support**:\n  - Real-time note synchronization\n  - Robust reconnection strategy\n  - Message queuing for offline handling\n  - Connection status management\n- **Server Configuration**:\n  - About modal with server details\n  - Dynamic port assignment\n  - Configuration endpoint\n- **Theme System**:\n  - Light/dark mode support\n  - Theme persistence\n  - Dynamic theme switching\n- **Advanced UI Features**:\n  - Markdown preview in editor\n  - Bulk actions (delete, color, export)\n  - Enhanced filtering and sorting\n  - Improved pagination\n  - Automatic filter reset when deleting last note in a conversation/tag\n- **MCP Development**: Implements MCP protocol endpoints and tool handlers (e.g., create-note, update-note, delete-note, search-notes, list-conversations).\n- **REST API**: Supports full CRUD operations for notes, sections, and tags via Express.\n- **WebSocket Support**: Optional real-time capabilities through a built-in WebSocket server.\n- **Full-Text Search**: Optional SQLite FTS5 for efficient note searches.\n- **Tag Management**: Hierarchical tag system with parent-child relationships and improved tag search capabilities.\n- **Section Organization**: Group notes into customizable sections.\n- **Color Coding**: Support for color-coded notes and bulk color operations.\n- **Persistency**: Uses SQLite (via better-sqlite3) for local storage.\n- **UI Integration**: Serves a React-based user interface from the `/public` folder.\n- **Port Scanning**: Automatically finds available ports if configured ports are in use.\n- **Pagination**: Client-side pagination with customizable items per page.\n- **Conversations Management**: Enhanced conversation tracking with metadata (total notes, creation date, last update).\n- **Markdown Support**: Full markdown rendering for note content with preview capabilities.\n- **Advanced Filtering**: Combined filtering by tags, conversations, and text search.\n- **Export Capabilities**:\n  - Single/multiple note export\n  - Markdown format support\n  - Custom filename options\n\n---\n\n## Requirements\n\n- Node.js (v16 or later recommended)\n- npm (or pnpm)\n- SQLite (no additional installation required since it uses better-sqlite3, which bundles SQLite)\n\n---\n\n## Installation \u0026 Setup\n\n1. **Clone the Repository**\n\n   ```bash\n   git clone https://your.repo.url/sticky-notes-server.git\n   cd sticky-notes-server\n   ```\n\n2. **Install Dependencies**\n\n   ```bash\n   npm install\n   ```\n\n3. **Build the Project**\n\n   ```bash\n   npm run build\n   ```\n\n4. **Run the Server**\n\n   ```bash\n   npm start\n   ```\n\n---\n\n## Configuration\n\nThe server supports a flexible configuration system with three levels of precedence (highest to lowest):\n\n1. **Environment Variables**\n2. **Configuration File**\n3. **Default Values**\n\n### Environment Variables\n\n- `STICKY_NOTES_CONFIG`: Path to custom config file location\n- `DB_ROOT`: The root directory for the database file\n- `DB_PATH`: The database file name\n- `DB_TIMEOUT`: Database operation timeout in milliseconds\n- `DB_VERBOSE`: Enable verbose database logging ('true'/'false')\n- `WEB_UI_PORT`: Port for the web UI\n- `WS_PORT`: Port for WebSocket server\n- `ENABLE_WEBSOCKET`: Enable/disable WebSocket support ('true'/'false')\n- `ENABLE_FTS`: Enable/disable full-text search ('true'/'false')\n\n### Configuration File\n\nThe server looks for a configuration file in the following locations (in order):\n\n1. Path specified in `STICKY_NOTES_CONFIG` environment variable\n2. `.sticky-notes.config.json` in the current working directory\n3. `.sticky-notes.config.json` in the user's home directory\n4. `/etc/sticky-notes/config.json` (non-Windows systems only)\n\nExample configuration file:\n\n```json\n{\n    \"db\": {\n        \"root\": \"C:/Users/username/Documents\",\n        \"path\": \"sticky-notes.db\",\n        \"timeout\": 10000,\n        \"verbose\": false\n    },\n    \"server\": {\n        \"webUiPort\": 3088,\n        \"wsPort\": 8089\n    },\n    \"features\": {\n        \"enableWebsocket\": false,\n        \"enableFTS\": true\n    }\n}\n```\n\n### Default Configuration\n\nIf no configuration is provided, the server uses these defaults:\n\n```json\n{\n    \"db\": {\n        \"root\": \"\u003cuser home directory\u003e\",\n        \"path\": \"sticky-notes.db\",\n        \"timeout\": 10000,\n        \"verbose\": false (true in development)\n    },\n    \"server\": {\n        \"webUiPort\": 3000,\n        \"wsPort\": 8080\n    },\n    \"features\": {\n        \"enableWebsocket\": true,\n        \"enableFTS\": true\n    }\n}\n```\n\n### Port Handling\n\nIf a configured port is in use, the server will:\n\n1. Attempt to find the next available port (scanning up to 100 ports higher)\n2. Log a message indicating the actual port being used\n3. Continue normal operation on the new port\n\nFor example, if port 3000 is in use, the server might use 3001 and log:\n\n```bash\nWeb UI running at http://localhost:3001 (original port 3000 was in use)\n```\n\n---\n\n## Running the Server\n\nTo start the Sticky Notes MCP Server, run:\n\n```bash\nnpm start\n```\n\nThis will:\n\n- Start the MCP server using a standard I/O transport\n- Launch an Express web server serving the UI on [http://localhost:3000](http://localhost:3000)\n- Initialize the WebSocket server on port 8080\n- Set up the SQLite database with all necessary tables and indexes\n\nPress `Ctrl+C` to stop the server.\n\n---\n\n## MCP Tools\n\nThe server provides several MCP tools for interacting with notes:\n\n### create-note\n\nCreates a new note with optional tags.\n\n```json\n{\n  \"name\": \"create-note\",\n  \"arguments\": {\n    \"title\": \"Meeting Notes\",\n    \"content\": \"Discussed Q4 plans.\",\n    \"conversationId\": \"conv123\",\n    \"tags\": [\"meeting\", \"planning\"],\n    \"color_hex\": \"#FFE999\"\n  }\n}\n```\n\nRequired Fields:\n\n- `title`: String (1-100 chars, Generally the name of the conversation)\n- `content`: String (markdown supported)\n- `conversationId`: String (unique identifier for the conversation, you provide this)\n\nOptional Fields:\n\n- `tags`: Array of strings\n- `color_hex`: String (hex color code). Available colors:\n  - Yellow: \"#FFE999\" (default)\n  - Green: \"#A7F3D0\"\n  - Blue: \"#93C5FD\"\n  - Red: \"#FCA5A5\"\n  - Purple: \"#DDD6FE\"\n  - Orange: \"#FFB17A\"\n\nExample response: `Note created with id 123`\n\n### update-note\n\nUpdates an existing note's content.\n\n```json\n{\n  \"name\": \"update-note\",\n  \"arguments\": {\n    \"id\": \"123\",\n    \"content\": \"Updated meeting notes content\"\n  }\n}\n```\n\n### delete-note\n\nDeletes a specific note.\n\n```json\n{\n  \"name\": \"delete-note\",\n  \"arguments\": {\n    \"id\": \"123\"\n  }\n}\n```\n\n### search-notes\n\nSearches for notes based on various criteria. Supports combined filtering by tags, conversations, and text search.\n\n```json\n{\n  \"name\": \"search-notes\",\n  \"arguments\": {\n    \"query\": \"meeting\",\n    \"tags\": [\"important\"],\n    \"conversationId\": \"conv123\"\n  }\n}\n```\n\n### list-conversations\n\nReturns a list of all conversation IDs in the system with metadata.\n\n```json\n{\n  \"name\": \"list-conversations\",\n  \"arguments\": {}\n}\n```\n\nResponse example:\n\n```json\n[\n  {\n    \"conversationId\": \"conv123\",\n    \"totalNotes\": 5,\n    \"firstCreated\": 1707753600,\n    \"lastUpdated\": 1707840000\n  },\n  {\n    \"conversationId\": \"meeting-2024\",\n    \"totalNotes\": 3,\n    \"firstCreated\": 1707667200,\n    \"lastUpdated\": 1707753600\n  }\n]\n```\n\n---\n\n## REST API Endpoints\n\nThe server exposes several REST endpoints:\n\n### Notes Endpoints\n\n- **GET /api/notes**\n  - Query parameters:\n    - `search`: Text search query\n    - `tags`: Array of tag names (deduplication handled server-side)\n    - `conversation`: Conversation ID\n    - `color`: Color hex code\n    - `startDate`: Filter by creation date\n    - `page`: Page number (default: 1)\n    - `limit`: Items per page (default: 10)\n    - `sort`: Sort field and direction (e.g., \"updated_at DESC\")\n  - Response includes pagination metadata:\n\n    ```json\n    {\n      \"notes\": [...],\n      \"pagination\": {\n        \"total\": 100,\n        \"page\": 1,\n        \"limit\": 10,\n        \"totalPages\": 10\n      }\n    }\n    ```\n\n### Sections Endpoints\n\n- **GET /api/sections**\n- **POST /api/sections**\n- **PUT /api/sections/:id**\n- **DELETE /api/sections/:id**\n- **GET /api/sections/:id/notes**\n\n### Tags Endpoints\n\n- **GET /api/tags**\n- **GET /api/tags/hierarchy**\n- **PATCH /api/tags/:id/parent**\n\n### Conversations Endpoints\n\n- **GET /api/conversations**\n  - Returns list of conversations with metadata:\n\n    ```json\n    {\n      \"conversations\": [\n        {\n          \"conversationId\": \"conv123\",\n          \"totalNotes\": 5,\n          \"firstCreated\": 1707753600,\n          \"lastUpdated\": 1707840000\n        }\n      ]\n    }\n    ```\n\n---\n\n## Integration with Claude Desktop\n\n### Method 1: Direct Integration\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"stickyNotes\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/sticky-notes-server/build/index.js\"],\n      \"env\": {\n        \"DB_ROOT\": \"desired/db/location\",\n        \"WEB_UI_PORT\": \"3000\",\n        \"WS_PORT\": \"8080\"\n      }\n    }\n  }\n}\n```\n\n### Method 2: NPX Integration\n\nIf published as an NPX package (Not implemented yet):\n\n```json\n{\n  \"mcpServers\": {\n    \"stickyNotes\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/sticky-notes-server\"\n      ],\n      \"env\": {\n        \"DB_ROOT\": \"desired/db/location\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Development\n\n### Project Structure\n\n```bash\nsticky-notes-server/\n├── package.json\n├── tsconfig.json\n├── README.md\n└── src/\n    ├── index.ts            // MCP server main entry point\n    ├── public/             // React-based UI\n    │   ├── index.html\n    │   ├── app.js\n    │   ├── components/     // React components\n    │   │   ├── Note.js    // Note component with markdown support\n    │   │   ├── PaginationControls.js\n    │   │   └── Sidebar.js // Enhanced sidebar with conversations\n    │   └── utils/\n    │       └── markdown.ts // Markdown rendering utilities\n    └── migrations/         // Database migrations\n```\n\n### Development Commands\n\n- **Start in Development Mode**:\n\n  ```bash\n  npm run dev\n  ```\n\n- **Build for Production**:\n\n  ```bash\n  npm run build\n  npm start\n  ```\n\n### Database Schema\n\nThe server uses the following main tables:\n\n- `notes`: Stores note content and metadata\n- `sections`: Manages note organization\n- `tags`: Stores tag hierarchy\n- `note_tags`: Junction table for note-tag relationships\n- `notes_fts`: Full-text search virtual table\n\n---\n\n## WebSocket Implementation\n\n### Client-Side Integration\n\nThe application includes a custom React hook for WebSocket management:\n\n```typescript\nconst { connectionStatus, sendMessage, lastMessage } = useWebSocket({\n    url: `ws://localhost:${wsPort}`,\n    onMessage: handleMessage,\n    reconnectAttempts: 5,\n    reconnectInterval: 1000\n});\n```\n\n### Message Types\n\n1. **Client Messages**:\n   - `NOTE_CREATE`: Create new note\n   - `NOTE_UPDATE`: Update existing note\n   - `NOTE_DELETE`: Delete note\n   - `SYNC_REQUEST`: Request sync\n\n2. **Server Messages**:\n   - `NOTE_CREATED`: Broadcast new note\n   - `NOTE_UPDATED`: Broadcast update\n   - `NOTE_DELETED`: Broadcast deletion\n   - `SYNC_RESPONSE`: Sync data\n   - `ERROR`: Error information\n\n### Reconnection Strategy\n\nThe WebSocket implementation includes a sophisticated reconnection strategy:\n\n- Exponential backoff\n- Configurable retry attempts\n- Connection status tracking\n- Message queuing during disconnection\n\n## Theme System\n\nThe application includes a comprehensive theme system:\n\n```javascript\nconst ThemeProvider = ({ children }) =\u003e {\n    const [theme, setTheme] = React.useState(() =\u003e {\n        const savedTheme = localStorage.getItem('theme');\n        return savedTheme || \n               (window.matchMedia('(prefers-color-scheme: dark)').matches \n                ? 'dark' : 'light');\n    });\n    // ... theme logic\n};\n```\n\n### Theme Features\n\n- System preference detection\n- Local storage persistence\n- Dynamic CSS class switching\n- Smooth transitions\n- Dark/light mode toggle\n\n## Bulk Actions\n\nThe application supports bulk operations:\n\n- **Selection**: Multi-select notes\n- **Actions**:\n  - Delete multiple notes\n  - Change color for multiple notes\n  - Export selected notes\n- **UI**: Dedicated bulk actions toolbar\n\n## Export Functionality\n\nEnhanced export capabilities:\n\n```javascript\nconst exportOptions = {\n    format: 'md',\n    includeMetadata: true,\n    includeToc: false,\n    filename: 'custom_name.md'\n};\n```\n\n### Export Features\n\n- Single note export\n- Multiple note export\n- Custom filename support\n- Markdown formatting\n- Metadata inclusion options\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n1. **Database Location Issues**\n   - Ensure `DB_ROOT` environment variable is set correctly\n   - Check file permissions in the target directory\n\n2. **Port Conflicts**\n   - Verify ports 3000 and 8080 are available\n   - Use `WEB_UI_PORT` and `WS_PORT` to configure alternative ports\n\n3. **Performance Issues**\n   - The server uses SQLite optimizations including WAL mode\n   - Indexes are automatically created for common queries\n   - Consider regular database maintenance (VACUUM) for large datasets\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n## Support\n\nFor issues, questions, or contributions:\n\n1. Check the [Issues](https://github.com/your-repo/sticky-notes-server/issues) section\n2. Create a new issue if needed\n3. Join our community discussions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsmi021%2Fsticky-notes-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbsmi021%2Fsticky-notes-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsmi021%2Fsticky-notes-server/lists"}