reflect-mcp 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,132 @@
+# Reflect MCP Server
+
+Connect your [Reflect](https://reflect.app) notes to Claude Desktop.
+
+## Prerequisites
+
+Before installing, make sure you have:
+
+- **Reflect Desktop** - Must be installed (but does not need to be running)
+  - Download from [reflect.app](https://reflect.app/download)
+
+- **Claude Desktop** - Required to use MCP servers
+  - Download from [claude.ai](https://claude.com/download)
+
+- **Node.js** - Version 18 or higher recommended
+  - Download from [nodejs.org](https://nodejs.org)
+
+## Quick Start
+
+
+**1. Install the `reflect-mcp` package:**
+
+```bash
+npm install reflect-mcp
+```
+
+**2. Install the server:**
+
+```bash
+npx reflect-mcp install
+```
+
+**3. Add to Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "reflect": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
+    }
+  }
+}
+```
+
+**4. Restart Claude Desktop**
+
+That's it! First time you use a Reflect tool, your browser will open to authenticate.
+
+> **Note:** If you see auth errors, try restarting Claude Desktop one more time.
+
+
+## Usage Examples
+
+Once installed, you can ask Claude to read and write your notes:
+
+- "Read all my notes tagged #spanish and create a study guide note with my biggest gaps"
+
+- "Read my last 3 daily notes and create a weekly summary note tagged #reflection"
+
+- "Look at notes tagged #work. Create a 'Career Development Plan' note based on what I'm learning and struggling with"
+
+- "Read my 1:1 meeting notes with [[manager]] and create a performance review prep note "
+
+## Commands
+
+```bash
+reflect-mcp install [db-path]    # Install as auto-start service
+reflect-mcp uninstall            # Remove auto-start service
+reflect-mcp status               # Check service status
+reflect-mcp [db-path]            # Run server manually
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `db-path` | Path to Reflect SQLite database | `~/Library/Application Support/Reflect/File System/000/t/00/00000000` |
+| `--port <port>` | Server port | `3000` |
+
+## Examples
+
+```bash
+# Install with default settings
+npx reflect-mcp install
+
+# Install with custom database path
+npx reflect-mcp install ~/custom/path/to/reflect/db
+
+# Install with custom port
+npx reflect-mcp install --port 4000
+
+# Check if service is running
+npx reflect-mcp status
+
+# Remove auto-start
+npx reflect-mcp uninstall
+```
+
+## Tools Available
+
+- `get_graphs` - List all Reflect graphs
+- `get_backlinks` - Get backlinks for a note
+- `get_daily_notes` - Get recent daily notes
+- `get_daily_note_by_date` - Get daily note for specific date
+- `get_backlinked_notes` - Get notes with most backlinks
+- `get_tags` - Get all tags with usage counts
+- `get_notes_with_tag` - Get notes with a specific tag
+- `get_note` - Get a note by title
+- `create_note` - Create a new note
+
+## Troubleshooting
+
+**Server won't start**
+- Check if port 3000 is available: `lsof -i :3000`
+- Try a different port: `npx reflect-mcp install --port 4000`
+
+**OAuth not working**
+- Restart Claude Desktop after installation
+- Check server is running: `npx reflect-mcp status`
+- Try uninstalling and reinstalling: `npx reflect-mcp uninstall && npx reflect-mcp install`
+
+**Database not found**
+- Ensure Reflect Desktop is installed
+- Verify database path exists at default location
+- Try specifying custom path: `npx reflect-mcp install /path/to/db`
+
+## Demo:
+https://www.loom.com/share/455b1d3eb7184bdea1ae4e8d5904fc53
+## License
+
+MIT

package/dist/tools/index.js

@@ -11,7 +11,7 @@ export function registerTools(server, dbPath) {
     // Tool: Get all Reflect graphs
     server.addTool({
         name: "get_graphs",
-        description: "Get a list of all Reflect graphs accessible with the current access token",
+        description: "Get a list of all Reflect graphs.",
         parameters: z.object({}),
         execute: async (_args, { session }) => {
             if (!session) {
@@ -59,7 +59,7 @@ export function registerTools(server, dbPath) {
     // Tool: Get backlinks for a note from local Reflect SQLite database
     server.addTool({
         name: "get_backlinks",
-        description: "Get backlinks for a note from the local Reflect database. Returns notes that link to the specified note.",
+        description: "Get backlinks for a note from Reflect. Use  this tool to get more context about a note after calling the get_note tool.",
         parameters: z.object({
             subject: z.string().describe("The subject/title of the note to get backlinks for"),
             graphId: z.string().default("rapheal-brain").describe("The graph ID to search in"),
@@ -111,7 +111,7 @@ export function registerTools(server, dbPath) {
     // Tool: Get recent daily notes
     server.addTool({
         name: "get_daily_notes",
-        description: "Get the most recent daily notes from the local Reflect database",
+        description: "Get the most recent daily notes from Reflect.",
         parameters: z.object({
             limit: z.number().default(5).describe("Number of recent daily notes to return"),
             graphId: z.string().default("rapheal-brain").describe("The graph ID to search in"),
@@ -163,7 +163,7 @@ export function registerTools(server, dbPath) {
     // Tool: Get daily note by date
     server.addTool({
         name: "get_daily_note_by_date",
-        description: "Get the daily note for a specific date from the local Reflect database",
+        description: "Get the daily note for a specific date.",
         parameters: z.object({
             date: z.string().describe("The date in YYYY-MM-DD format"),
             graphId: z.string().default("rapheal-brain").describe("The graph ID to search in"),
@@ -225,7 +225,7 @@ export function registerTools(server, dbPath) {
     // Tool: Get notes with most backlinks
     server.addTool({
         name: "get_backlinked_notes",
-        description: "Get notes that have at least a minimum number of backlinks from the local Reflect database",
+        description: "Get notes that have at least a minimum number of backlinks from Reflect.",
         parameters: z.object({
             minBacklinks: z.number().default(5).describe("Minimum number of backlinks a note must have"),
             limit: z.number().default(10).describe("Maximum number of notes to return"),
@@ -278,7 +278,7 @@ export function registerTools(server, dbPath) {
     // Tool: Get all tags with usage counts
     server.addTool({
         name: "get_tags",
-        description: "Get all unique tags with their usage counts from the local Reflect database",
+        description: "Get all unique tags with their usage counts from Reflect.",
         parameters: z.object({
             graphId: z.string().default("rapheal-brain").describe("The graph ID to search in"),
             limit: z.number().default(50).describe("Maximum number of tags to return"),
@@ -334,7 +334,7 @@ export function registerTools(server, dbPath) {
     // Tool: Get notes with a specific tag
     server.addTool({
         name: "get_notes_with_tag",
-        description: "Get notes that have a specific tag from the local Reflect database",
+        description: "Get notes that have a specific tag from Reflect.",
         parameters: z.object({
             tag: z.string().describe("The tag to search for"),
             graphId: z.string().default("rapheal-brain").describe("The graph ID to search in"),
@@ -383,49 +383,116 @@ export function registerTools(server, dbPath) {
             }
         },
     });
-    // Tool: Get a note by title
+    // Tool: Get a note by title (exact match first, then fuzzy fallback)
     server.addTool({
         name: "get_note",
-        description: "Get a note by its title (subject) from the local Reflect database",
+        description: "Get a note by its title (subject) from Reflect.",
         parameters: z.object({
             title: z.string().describe("The title/subject of the note to retrieve"),
             graphId: z.string().default("rapheal-brain").describe("The graph ID to search in"),
         }),
         execute: async (args) => {
             const { title, graphId } = args;
+            const FUZZY_LIMIT = 3;
             try {
                 const dbFile = resolvedDbPath;
                 const db = new Database(dbFile, { readonly: true });
-                const stmt = db.prepare(`
+                // Try exact match first
+                const exactStmt = db.prepare(`
           SELECT id, subject, documentText, tags, editedAt, createdAt
           FROM notes 
           WHERE isDeleted = 0 AND graphId = ? AND subject = ?
         `);
-                const result = stmt.get(graphId, title);
+                const exactResult = exactStmt.get(graphId, title);
+                if (exactResult) {
+                    db.close();
+                    const note = {
+                        id: exactResult.id,
+                        subject: exactResult.subject,
+                        documentText: exactResult.documentText,
+                        tags: exactResult.tags ? JSON.parse(exactResult.tags) : [],
+                        editedAt: formatDate(exactResult.editedAt),
+                        createdAt: formatDate(exactResult.createdAt),
+                    };
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ title, graphId, note }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                // No exact match - try fuzzy search
+                const searchTerm = title.toLowerCase();
+                const fuzzyStmt = db.prepare(`
+          SELECT id, subject, documentText, tags, editedAt, createdAt,
+            CASE 
+              WHEN LOWER(subject) LIKE ? THEN 2
+              WHEN LOWER(subject) LIKE ? THEN 1
+              ELSE 0
+            END as relevance
+          FROM notes 
+          WHERE isDeleted = 0 
+            AND graphId = ? 
+            AND (LOWER(subject) LIKE ? OR LOWER(subject) LIKE ?)
+          ORDER BY relevance DESC, editedAt DESC
+          LIMIT ?
+        `);
+                const fuzzyResults = fuzzyStmt.all(`${searchTerm}%`, // starts with (score 2)
+                `%${searchTerm}%`, // contains (score 1)
+                graphId, `${searchTerm}%`, // WHERE starts with
+                `%${searchTerm}%`, // WHERE contains
+                FUZZY_LIMIT);
                 db.close();
-                if (!result) {
+                if (fuzzyResults.length === 0) {
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: JSON.stringify({ error: `Note '${title}' not found`, title, graphId }),
+                                text: JSON.stringify({
+                                    error: `No notes found matching '${title}'`,
+                                    query: title,
+                                    graphId
+                                }),
                             },
                         ],
                     };
                 }
-                const note = {
+                const notes = fuzzyResults.map((result) => ({
                     id: result.id,
                     subject: result.subject,
                     documentText: result.documentText,
                     tags: result.tags ? JSON.parse(result.tags) : [],
                     editedAt: formatDate(result.editedAt),
                     createdAt: formatDate(result.createdAt),
-                };
+                }));
+                // If only one fuzzy match, return it directly
+                if (notes.length === 1) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    query: title,
+                                    graphId,
+                                    note: notes[0],
+                                    matchType: "fuzzy"
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
                 return {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({ title, graphId, note }, null, 2),
+                            text: JSON.stringify({
+                                query: title,
+                                graphId,
+                                matchCount: notes.length,
+                                notes
+                            }, null, 2),
                         },
                     ],
                 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reflect-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "MCP server for Reflect Notes - connect your notes to Claude Desktop. Just run: npx reflect-mcp",
   "type": "module",
   "main": "dist/server.js",
@@ -15,7 +15,8 @@
     "build": "tsc",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "npm rebuild better-sqlite3 || true"
   },
   "keywords": [
     "mcp",
@@ -36,7 +37,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "better-sqlite3": "^11.0.0",
+    "better-sqlite3": "^11.10.0",
     "fastmcp": "^3.25.4",
     "zod": "^4.1.13"
   },