reflect-mcp 1.0.0

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Reflect MCP Server - CLI Entry Point
+ *
+ * Run with: npx reflect-mcp <db-path>
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Reflect MCP Server - CLI Entry Point
+ *
+ * Run with: npx reflect-mcp <db-path>
+ */
+import { startReflectMCPServer } from "./server.js";
+import { DEFAULT_DB_PATH } from "./utils.js";
+const REFLECT_CLIENT_ID = "55798f25d5a24efb95e4174fff3d219e";
+// Parse command line arguments
+function parseArgs() {
+    const args = process.argv.slice(2);
+    let dbPath = DEFAULT_DB_PATH;
+    let port = 3000;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--port" && args[i + 1]) {
+            port = parseInt(args[++i]);
+        }
+        else if (args[i] === "--help" || args[i] === "-h") {
+            console.log(`
+Usage: reflect-mcp [db-path] [options]
+
+Arguments:
+  db-path           Path to Reflect SQLite database
+                    (default: ${DEFAULT_DB_PATH})
+
+Options:
+  --port <port>     Port to run server on (default: 3000)
+  --help, -h        Show this help message
+
+Examples:
+  npx reflect-mcp
+  npx reflect-mcp ~/Library/Application\\ Support/Reflect/File\\ System/000/t/00/00000000
+  npx reflect-mcp /path/to/reflect/db --port 4000
+`);
+            process.exit(0);
+        }
+        else if (!args[i].startsWith("--")) {
+            // Positional argument = db path
+            dbPath = args[i];
+        }
+    }
+    return { dbPath, port };
+}
+const { dbPath, port: PORT } = parseArgs();
+startReflectMCPServer({
+    clientId: REFLECT_CLIENT_ID,
+    port: PORT,
+    dbPath,
+}).then(() => {
+    console.log(`Reflect MCP Server running on http://localhost:${PORT}`);
+    console.log(`Database: ${dbPath}`);
+}).catch((err) => {
+    console.error("Failed to start server:", err);
+    process.exit(1);
+});

package/dist/pkcehandler.d.ts

@@ -0,0 +1,87 @@
+/**
+ * PKCE OAuth Proxy (No Client Secret Required)
+ *
+ * This module provides a custom OAuth proxy that uses PKCE for authentication
+ * without requiring a client secret, suitable for public clients.
+ */
+export interface TokenData {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: Date;
+}
+export interface PKCEOAuthProxyConfig {
+    baseUrl: string;
+    clientId: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    scopes: string[];
+    redirectPath?: string;
+    tokenStoragePath?: string;
+}
+export declare class PKCEOAuthProxy {
+    private config;
+    private transactions;
+    private tokens;
+    private cleanupInterval;
+    constructor(options: PKCEOAuthProxyConfig);
+    private loadTokensFromDisk;
+    private saveTokensToDisk;
+    private generatePKCE;
+    private generateId;
+    getAuthorizationServerMetadata(): {
+        issuer: string;
+        authorizationEndpoint: string;
+        tokenEndpoint: string;
+        registrationEndpoint: string;
+        responseTypesSupported: string[];
+        grantTypesSupported: string[];
+        codeChallengeMethodsSupported: string[];
+        scopesSupported: string[];
+    };
+    authorize(params: {
+        client_id: string;
+        redirect_uri: string;
+        response_type: string;
+        state?: string;
+        scope?: string;
+        code_challenge?: string;
+        code_challenge_method?: string;
+    }): Promise<Response>;
+    handleCallback(request: Request): Promise<Response>;
+    exchangeAuthorizationCode(params: {
+        grant_type: string;
+        code: string;
+        client_id: string;
+        redirect_uri: string;
+        code_verifier?: string;
+        client_secret?: string;
+    }): Promise<{
+        access_token: string;
+        token_type: string;
+        expires_in: number;
+        refresh_token?: string;
+        scope?: string;
+    }>;
+    exchangeRefreshToken(params: {
+        grant_type: string;
+        refresh_token: string;
+        client_id: string;
+        client_secret?: string;
+    }): Promise<{
+        access_token: string;
+        token_type: string;
+        expires_in: number;
+        refresh_token?: string;
+    }>;
+    registerClient(request: {
+        redirect_uris?: string[];
+        client_name?: string;
+    }): Promise<{
+        client_id: string;
+        client_name?: string;
+        redirect_uris?: string[];
+    }>;
+    loadUpstreamTokens(proxyToken: string): TokenData | null;
+    private startCleanup;
+    destroy(): void;
+}

package/dist/pkcehandler.js

@@ -0,0 +1,312 @@
+/**
+ * PKCE OAuth Proxy (No Client Secret Required)
+ *
+ * This module provides a custom OAuth proxy that uses PKCE for authentication
+ * without requiring a client secret, suitable for public clients.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { OAuthProxyError } from "fastmcp/auth";
+// ============================================================================
+// PKCEOAuthProxy Class
+// ============================================================================
+export class PKCEOAuthProxy {
+    config;
+    // In-memory storage for transactions (short-lived, don't need persistence)
+    transactions = new Map();
+    // Token storage - persisted to disk
+    tokens = new Map();
+    cleanupInterval = null;
+    constructor(options) {
+        this.config = {
+            baseUrl: options.baseUrl,
+            clientId: options.clientId,
+            authorizationEndpoint: options.authorizationEndpoint,
+            tokenEndpoint: options.tokenEndpoint,
+            redirectPath: options.redirectPath || "/oauth/callback",
+            scopes: options.scopes,
+            tokenStoragePath: options.tokenStoragePath || path.join(os.homedir(), ".reflect-mcp-tokens.json"),
+        };
+        this.loadTokensFromDisk();
+        this.startCleanup();
+    }
+    // Load tokens from disk on startup
+    loadTokensFromDisk() {
+        try {
+            if (fs.existsSync(this.config.tokenStoragePath)) {
+                const data = fs.readFileSync(this.config.tokenStoragePath, "utf-8");
+                const stored = JSON.parse(data);
+                for (const [key, value] of Object.entries(stored)) {
+                    const expiresAt = new Date(value.expiresAt);
+                    // Only load non-expired tokens
+                    if (expiresAt > new Date()) {
+                        this.tokens.set(key, {
+                            accessToken: value.accessToken,
+                            refreshToken: value.refreshToken,
+                            expiresAt,
+                        });
+                    }
+                }
+                console.log(`[PKCEProxy] Loaded ${this.tokens.size} tokens from disk`);
+            }
+        }
+        catch (error) {
+            console.warn("[PKCEProxy] Failed to load tokens from disk:", error);
+        }
+    }
+    // Save tokens to disk
+    saveTokensToDisk() {
+        try {
+            const toStore = {};
+            for (const [key, value] of this.tokens) {
+                toStore[key] = {
+                    accessToken: value.accessToken,
+                    refreshToken: value.refreshToken,
+                    expiresAt: value.expiresAt.toISOString(),
+                };
+            }
+            fs.writeFileSync(this.config.tokenStoragePath, JSON.stringify(toStore, null, 2));
+        }
+        catch (error) {
+            console.error("[PKCEProxy] Failed to save tokens to disk:", error);
+        }
+    }
+    // Generate PKCE code verifier and challenge
+    generatePKCE() {
+        // Generate a random code verifier (43-128 characters)
+        const verifier = crypto.randomBytes(32).toString("base64url");
+        // Create code challenge: BASE64URL(SHA256(code_verifier))
+        const challenge = crypto
+            .createHash("sha256")
+            .update(verifier)
+            .digest("base64url");
+        return { verifier, challenge };
+    }
+    generateId() {
+        return crypto.randomBytes(16).toString("hex");
+    }
+    // Get authorization server metadata for MCP clients
+    getAuthorizationServerMetadata() {
+        return {
+            issuer: this.config.baseUrl,
+            authorizationEndpoint: `${this.config.baseUrl}/oauth/authorize`,
+            tokenEndpoint: `${this.config.baseUrl}/oauth/token`,
+            registrationEndpoint: `${this.config.baseUrl}/oauth/register`,
+            responseTypesSupported: ["code"],
+            grantTypesSupported: ["authorization_code", "refresh_token"],
+            codeChallengeMethodsSupported: ["S256"],
+            scopesSupported: this.config.scopes,
+        };
+    }
+    // Handle /oauth/authorize - redirect to upstream with PKCE
+    async authorize(params) {
+        console.log("[PKCEProxy] Authorize called with params:", params);
+        if (params.response_type !== "code") {
+            return new Response(JSON.stringify({ error: "unsupported_response_type" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        // Generate our own PKCE for upstream
+        const pkce = this.generatePKCE();
+        const transactionId = this.generateId();
+        // Store transaction
+        const transaction = {
+            codeVerifier: pkce.verifier,
+            codeChallenge: pkce.challenge,
+            clientCallbackUrl: params.redirect_uri,
+            clientId: params.client_id,
+            clientState: params.state || this.generateId(),
+            scope: params.scope ? params.scope.split(" ") : this.config.scopes,
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() + 600 * 1000), // 10 minutes
+        };
+        this.transactions.set(transactionId, transaction);
+        console.log("[PKCEProxy] Created transaction:", transactionId);
+        // Build upstream authorization URL
+        const authUrl = new URL(this.config.authorizationEndpoint);
+        authUrl.searchParams.set("client_id", this.config.clientId);
+        authUrl.searchParams.set("redirect_uri", `${this.config.baseUrl}${this.config.redirectPath}`);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("scope", transaction.scope.join(","));
+        authUrl.searchParams.set("state", transactionId); // Use transaction ID as state
+        authUrl.searchParams.set("code_challenge", pkce.challenge);
+        authUrl.searchParams.set("code_challenge_method", "S256");
+        console.log("[PKCEProxy] Redirecting to:", authUrl.toString());
+        return new Response(null, {
+            status: 302,
+            headers: { Location: authUrl.toString() },
+        });
+    }
+    // Handle /oauth/callback - exchange code for tokens
+    // FastMCP passes a Request object, so we need to extract params from URL
+    async handleCallback(request) {
+        const url = new URL(request.url);
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        console.log("[PKCEProxy] Callback received with state:", state, "code:", code ? "present" : "missing");
+        if (!state) {
+            console.error("[PKCEProxy] Missing state parameter");
+            return new Response(JSON.stringify({ error: "missing_state" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        if (!code) {
+            console.error("[PKCEProxy] Missing code parameter");
+            return new Response(JSON.stringify({ error: "missing_code" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const transaction = this.transactions.get(state);
+        if (!transaction) {
+            console.error("[PKCEProxy] Transaction not found for state:", state);
+            console.error("[PKCEProxy] Available transactions:", Array.from(this.transactions.keys()));
+            return new Response(JSON.stringify({ error: "invalid_state" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        if (transaction.expiresAt < new Date()) {
+            this.transactions.delete(state);
+            return new Response(JSON.stringify({ error: "transaction_expired" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        // Exchange code for tokens with upstream (NO client_secret!)
+        console.log("[PKCEProxy] Exchanging code for tokens...");
+        const tokenResponse = await fetch(this.config.tokenEndpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code: code,
+                client_id: this.config.clientId,
+                redirect_uri: `${this.config.baseUrl}${this.config.redirectPath}`,
+                code_verifier: transaction.codeVerifier, // PKCE verifier, no secret!
+            }),
+        });
+        if (!tokenResponse.ok) {
+            const error = await tokenResponse.text();
+            console.error("[PKCEProxy] Token exchange failed:", error);
+            return new Response(JSON.stringify({ error: "token_exchange_failed", details: error }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        const tokens = await tokenResponse.json();
+        console.log("[PKCEProxy] Got tokens, expires_in:", tokens.expires_in);
+        // Generate a proxy token to give to the client
+        const proxyToken = this.generateId();
+        this.tokens.set(proxyToken, {
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expiresAt: new Date(Date.now() + (tokens.expires_in || 3600) * 1000),
+        });
+        this.saveTokensToDisk(); // Persist to disk
+        // Redirect back to client with our proxy token
+        const clientRedirect = new URL(transaction.clientCallbackUrl);
+        clientRedirect.searchParams.set("code", proxyToken);
+        clientRedirect.searchParams.set("state", transaction.clientState);
+        // Clean up transaction
+        this.transactions.delete(state);
+        console.log("[PKCEProxy] Redirecting to client:", clientRedirect.toString());
+        return new Response(null, {
+            status: 302,
+            headers: { Location: clientRedirect.toString() },
+        });
+    }
+    // Handle /oauth/token - exchange proxy code for access token
+    // FastMCP expects a TokenResponse object, not a Response
+    async exchangeAuthorizationCode(params) {
+        console.log("[PKCEProxy] exchangeAuthorizationCode called with code:", params.code?.slice(0, 8) + "...");
+        if (!params.code) {
+            throw new OAuthProxyError("invalid_request", "Missing authorization code", 400);
+        }
+        const tokenData = this.tokens.get(params.code);
+        if (!tokenData) {
+            console.error("[PKCEProxy] Token not found for code:", params.code);
+            console.error("[PKCEProxy] Available tokens:", Array.from(this.tokens.keys()).map(k => k.slice(0, 8) + "..."));
+            throw new OAuthProxyError("invalid_grant", "Invalid or expired authorization code", 400);
+        }
+        // Remove the code (single use)
+        this.tokens.delete(params.code);
+        // Generate a new access token for the client
+        const accessToken = this.generateId();
+        this.tokens.set(accessToken, tokenData);
+        this.saveTokensToDisk(); // Persist to disk
+        const expiresIn = Math.floor((tokenData.expiresAt.getTime() - Date.now()) / 1000);
+        console.log("[PKCEProxy] Issuing access token, expires in:", expiresIn, "seconds");
+        return {
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: expiresIn > 0 ? expiresIn : 3600,
+            // Note: Not returning refresh_token since Reflect doesn't support refresh_token grant
+            // This tells the MCP client to re-authenticate via OAuth when the token expires
+        };
+    }
+    // Handle refresh token exchange
+    // Note: Reflect's API doesn't support standard refresh_token grant
+    // We throw an OAuthProxyError to trigger re-authentication via OAuth flow
+    async exchangeRefreshToken(params) {
+        console.log("[PKCEProxy] exchangeRefreshToken called - Reflect doesn't support refresh_token grant");
+        console.log("[PKCEProxy] Triggering re-authentication via OAuth flow...");
+        // Reflect's token endpoint only accepts authorization_code grant, not refresh_token
+        // Throw OAuthProxyError so FastMCP handles it properly and triggers re-auth
+        throw new OAuthProxyError("invalid_grant", "Refresh tokens are not supported. Please re-authenticate.", 400);
+    }
+    // Handle /oauth/register (Dynamic Client Registration)
+    async registerClient(request) {
+        // For public clients, we just acknowledge the registration
+        // The actual client_id is configured server-side
+        return {
+            client_id: this.generateId(),
+            client_name: request.client_name,
+            redirect_uris: request.redirect_uris,
+        };
+    }
+    // Load upstream tokens for a given proxy token
+    loadUpstreamTokens(proxyToken) {
+        const data = this.tokens.get(proxyToken);
+        if (!data)
+            return null;
+        if (data.expiresAt < new Date()) {
+            this.tokens.delete(proxyToken);
+            this.saveTokensToDisk();
+            return null;
+        }
+        return data;
+    }
+    // Cleanup expired transactions and tokens
+    startCleanup() {
+        this.cleanupInterval = setInterval(() => {
+            const now = new Date();
+            let tokensChanged = false;
+            for (const [id, tx] of this.transactions) {
+                if (tx.expiresAt < now)
+                    this.transactions.delete(id);
+            }
+            for (const [id, token] of this.tokens) {
+                if (token.expiresAt < now) {
+                    this.tokens.delete(id);
+                    tokensChanged = true;
+                }
+            }
+            if (tokensChanged) {
+                this.saveTokensToDisk();
+            }
+        }, 60000); // Every minute
+    }
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        // Save tokens before shutdown
+        this.saveTokensToDisk();
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reflect MCP Server Factory
+ *
+ * Creates and configures the FastMCP server with PKCE OAuth
+ */
+export interface ServerConfig {
+    clientId: string;
+    port?: number;
+    dbPath?: string;
+}
+export declare function startReflectMCPServer(config: ServerConfig): Promise<void>;
+export { PKCEOAuthProxy } from "./pkcehandler.js";
+export * from "./utils.js";

package/dist/server.js

@@ -0,0 +1,73 @@
+/**
+ * Reflect MCP Server Factory
+ *
+ * Creates and configures the FastMCP server with PKCE OAuth
+ */
+import { FastMCP } from "fastmcp";
+import { PKCEOAuthProxy } from "./pkcehandler.js";
+import { registerTools } from "./tools/index.js";
+export async function startReflectMCPServer(config) {
+    const port = config.port || 3000;
+    const baseUrl = `http://localhost:${port}`;
+    // Create PKCE OAuth Proxy (no client_secret required!)
+    const pkceProxy = new PKCEOAuthProxy({
+        baseUrl,
+        clientId: config.clientId,
+        authorizationEndpoint: "https://reflect.app/oauth",
+        tokenEndpoint: "https://reflect.app/api/oauth/token",
+        scopes: ["read:graph", "write:graph"],
+    });
+    // Get auth server metadata
+    const authServerMetadata = pkceProxy.getAuthorizationServerMetadata();
+    // Create FastMCP server
+    const server = new FastMCP({
+        name: "Reflect MCP Server",
+        oauth: {
+            authorizationServer: authServerMetadata,
+            enabled: true,
+            protectedResource: {
+                resource: baseUrl,
+                authorizationServers: [authServerMetadata.issuer],
+                scopesSupported: ["read:graph", "write:graph"],
+            },
+            proxy: pkceProxy,
+        },
+        authenticate: async (request) => {
+            const authHeader = request.headers.authorization;
+            if (!authHeader?.startsWith("Bearer ")) {
+                return undefined;
+            }
+            const token = authHeader.slice(7);
+            try {
+                const tokenData = pkceProxy.loadUpstreamTokens(token);
+                if (!tokenData) {
+                    return undefined;
+                }
+                const expiresIn = Math.floor((tokenData.expiresAt.getTime() - Date.now()) / 1000);
+                return {
+                    accessToken: tokenData.accessToken,
+                    refreshToken: tokenData.refreshToken,
+                    expiresIn,
+                };
+            }
+            catch (error) {
+                console.error("[Auth] Error:", error);
+                return undefined;
+            }
+        },
+        version: "1.0.0",
+    });
+    // Register all tools
+    registerTools(server, config.dbPath);
+    // Start server
+    await server.start({
+        httpStream: {
+            port,
+            stateless: true,
+        },
+        transportType: "httpStream",
+    });
+}
+// Also export for programmatic use
+export { PKCEOAuthProxy } from "./pkcehandler.js";
+export * from "./utils.js";

package/dist/tools/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reflect MCP Tools
+ *
+ * All tools for interacting with Reflect notes
+ */
+import { FastMCP } from "fastmcp";
+export declare function registerTools(server: FastMCP, dbPath?: string): void;

package/dist/tools/index.js

@@ -0,0 +1,545 @@
+/**
+ * Reflect MCP Tools
+ *
+ * All tools for interacting with Reflect notes
+ */
+import { z } from "zod";
+import Database from "better-sqlite3";
+import { DEFAULT_DB_PATH, expandPath, stripHtml, formatDate, getDateForTimezone } from "../utils.js";
+export function registerTools(server, dbPath) {
+    const resolvedDbPath = expandPath(dbPath || DEFAULT_DB_PATH);
+    // Tool: Get all Reflect graphs
+    server.addTool({
+        name: "get_graphs",
+        description: "Get a list of all Reflect graphs accessible with the current access token",
+        parameters: z.object({}),
+        execute: async (_args, { session }) => {
+            if (!session) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: "Not authenticated. Please complete OAuth flow first." }),
+                        },
+                    ],
+                };
+            }
+            const { accessToken } = session;
+            try {
+                const response = await fetch("https://reflect.app/api/graphs", {
+                    headers: {
+                        Authorization: `Bearer ${accessToken}`,
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                const data = await response.json();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(data, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // 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.",
+        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"),
+            limit: z.number().default(10).describe("Maximum number of backlinks to return"),
+        }),
+        execute: async (args) => {
+            const { subject, graphId, limit } = args;
+            try {
+                const dbFile = resolvedDbPath;
+                const db = new Database(dbFile, { readonly: true });
+                const stmt = db.prepare(`
+          SELECT bl.contextHtml, bl.label, bl.updatedAt, source.subject AS from_subject
+          FROM noteBacklinks bl
+          JOIN notes target ON bl.toNoteId = target.id
+          JOIN notes source ON bl.fromNoteId = source.id
+          WHERE target.subject = ? AND target.graphId = ?
+          ORDER BY bl.updatedAt DESC
+          LIMIT ?
+        `);
+                const results = stmt.all(subject, graphId, limit);
+                db.close();
+                const backlinks = results.map((row) => ({
+                    fromSubject: row.from_subject,
+                    label: row.label,
+                    contextText: stripHtml(row.contextHtml),
+                    updatedAt: formatDate(row.updatedAt),
+                }));
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ subject, graphId, backlinks }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // Tool: Get recent daily notes
+    server.addTool({
+        name: "get_daily_notes",
+        description: "Get the most recent daily notes from the local Reflect database",
+        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"),
+        }),
+        execute: async (args) => {
+            const { limit, graphId } = args;
+            try {
+                const dbFile = resolvedDbPath;
+                const db = new Database(dbFile, { readonly: true });
+                const stmt = db.prepare(`
+          SELECT id, subject, documentText, editedAt, tags, dailyDate, graphId
+          FROM notes 
+          WHERE isDaily = 1 AND isDeleted = 0 AND LENGTH(documentText) > 0 AND graphId = ?
+          ORDER BY dailyDate DESC
+          LIMIT ?
+        `);
+                const rows = stmt.all(graphId, limit);
+                db.close();
+                const dailyNotes = rows.map((row) => ({
+                    id: row.id,
+                    subject: row.subject,
+                    documentText: row.documentText?.slice(0, 500) || "",
+                    editedAt: formatDate(row.editedAt),
+                    tags: row.tags ? JSON.parse(row.tags) : [],
+                    dailyDate: formatDate(row.dailyDate),
+                    graphId: row.graphId,
+                }));
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ graphId, count: dailyNotes.length, dailyNotes }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // 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",
+        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"),
+        }),
+        execute: async (args) => {
+            const { date, graphId } = args;
+            try {
+                const dbFile = resolvedDbPath;
+                const db = new Database(dbFile, { readonly: true });
+                const dateObj = new Date(date + "T00:00:00");
+                const dateMs = dateObj.getTime();
+                const stmt = db.prepare(`
+          SELECT id, subject, documentText, editedAt, tags, dailyDate, graphId
+          FROM notes 
+          WHERE isDaily = 1 AND isDeleted = 0 AND graphId = ? AND dailyDate = ?
+        `);
+                const result = stmt.get(graphId, dateMs);
+                db.close();
+                if (!result) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ error: `No daily note found for ${date}`, date, graphId }),
+                            },
+                        ],
+                    };
+                }
+                const dailyNote = {
+                    id: result.id,
+                    subject: result.subject,
+                    documentText: result.documentText,
+                    editedAt: formatDate(result.editedAt),
+                    tags: result.tags ? JSON.parse(result.tags) : [],
+                    dailyDate: formatDate(result.dailyDate),
+                    graphId: result.graphId,
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ date, graphId, dailyNote }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // 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",
+        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"),
+            graphId: z.string().default("rapheal-brain").describe("The graph ID to search in"),
+        }),
+        execute: async (args) => {
+            const { minBacklinks, limit, graphId } = args;
+            try {
+                const dbFile = resolvedDbPath;
+                const db = new Database(dbFile, { readonly: true });
+                const stmt = db.prepare(`
+          SELECT n.id, n.subject, COUNT(bl.id) as backlink_count, n.documentText
+          FROM notes n
+          JOIN noteBacklinks bl ON bl.toNoteId = n.id
+          WHERE n.isDeleted = 0 AND n.subject != 'Audio Memos' AND n.subject != 'Links' AND n.graphId = ?
+          GROUP BY n.id
+          HAVING COUNT(bl.id) >= ?
+          ORDER BY backlink_count DESC
+          LIMIT ?
+        `);
+                const results = stmt.all(graphId, minBacklinks, limit);
+                db.close();
+                const notes = results.map((row) => ({
+                    id: row.id,
+                    subject: row.subject,
+                    backlinkCount: row.backlink_count,
+                    documentText: row.documentText?.slice(0, 200) || "",
+                }));
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ graphId, minBacklinks, count: notes.length, notes }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // 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",
+        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"),
+        }),
+        execute: async (args) => {
+            const { graphId, limit } = args;
+            try {
+                const dbFile = resolvedDbPath;
+                const db = new Database(dbFile, { readonly: true });
+                const stmt = db.prepare(`
+          SELECT tags FROM notes 
+          WHERE isDeleted = 0 AND graphId = ? AND tags IS NOT NULL AND tags != '[]'
+        `);
+                const rows = stmt.all(graphId);
+                db.close();
+                const tagCounts = {};
+                for (const row of rows) {
+                    try {
+                        const tags = JSON.parse(row.tags);
+                        for (const tag of tags) {
+                            tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                const sortedTags = Object.entries(tagCounts)
+                    .map(([tag, count]) => ({ tag, count }))
+                    .sort((a, b) => b.count - a.count)
+                    .slice(0, limit);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ graphId, totalTags: Object.keys(tagCounts).length, tags: sortedTags }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // 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",
+        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"),
+            limit: z.number().default(20).describe("Maximum number of notes to return"),
+        }),
+        execute: async (args) => {
+            const { tag, graphId, limit } = args;
+            try {
+                const dbFile = resolvedDbPath;
+                const db = new Database(dbFile, { readonly: true });
+                const stmt = db.prepare(`
+          SELECT id, subject, tags, editedAt, LENGTH(documentText) as docLen, documentText
+          FROM notes 
+          WHERE isDeleted = 0 AND graphId = ? AND tags LIKE ?
+          ORDER BY editedAt DESC
+          LIMIT ?
+        `);
+                const results = stmt.all(graphId, `%"${tag}"%`, limit);
+                db.close();
+                const notes = results.map((row) => ({
+                    id: row.id,
+                    subject: row.subject,
+                    tags: row.tags ? JSON.parse(row.tags) : [],
+                    editedAt: formatDate(row.editedAt),
+                    documentLength: row.docLen,
+                    documentText: row.documentText?.slice(0, 300) || "",
+                }));
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ tag, graphId, count: notes.length, notes }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // Tool: Get a note by title
+    server.addTool({
+        name: "get_note",
+        description: "Get a note by its title (subject) from the local Reflect database",
+        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;
+            try {
+                const dbFile = resolvedDbPath;
+                const db = new Database(dbFile, { readonly: true });
+                const stmt = db.prepare(`
+          SELECT id, subject, documentText, tags, editedAt, createdAt
+          FROM notes 
+          WHERE isDeleted = 0 AND graphId = ? AND subject = ?
+        `);
+                const result = stmt.get(graphId, title);
+                db.close();
+                if (!result) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ error: `Note '${title}' not found`, title, graphId }),
+                            },
+                        ],
+                    };
+                }
+                const note = {
+                    id: result.id,
+                    subject: result.subject,
+                    documentText: result.documentText,
+                    tags: result.tags ? JSON.parse(result.tags) : [],
+                    editedAt: formatDate(result.editedAt),
+                    createdAt: formatDate(result.createdAt),
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ title, graphId, note }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+    // Tool: Create a new note in Reflect via API
+    server.addTool({
+        name: "create_note",
+        description: "Create a new note in Reflect. Must add the tasks field if there are any actionable items to add. Pass in the user's timezone to ensure the note is created with the correct date. Check what tags the user has already created, and determine which tag to use for this content, or create a new tag if no tags fit the content.",
+        parameters: z.object({
+            subject: z.string().describe("The title/subject of the note. Example: 'Meeting Summary - Project Planning'"),
+            content: z.string().describe("The markdown content for the note. This is the main body of the note."),
+            graph_id: z.string().describe("The unique identifier of the Reflect graph where the note should be created."),
+            timezone: z.string().describe("The user's timezone in IANA format. Example: 'America/New_York', 'Europe/London', 'Asia/Tokyo'. Used to determine the correct date for the daily note backlink."),
+            tag: z.string().describe("The tag to add to the note. Example: 'personal'"),
+            tasks: z.array(z.string()).optional().describe("A list of tasks to add to the note. Must add this field if there are any actionable items. Example: ['Review PR', 'Schedule meeting']"),
+        }),
+        execute: async (args, { session }) => {
+            if (!session) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: "Not authenticated. Please complete OAuth flow first." }),
+                        },
+                    ],
+                };
+            }
+            const { accessToken } = session;
+            const { subject, content, graph_id, timezone, tag, tasks } = args;
+            const todayDate = getDateForTimezone(timezone);
+            const contentParts = [];
+            contentParts.push(`#ai-generated\n`);
+            contentParts.push(`- [[${tag}]]\n`);
+            const contentLines = content.split('\n');
+            const indentedContent = contentLines.map(line => `  ${line}`).join('\n');
+            contentParts.push(indentedContent);
+            if (tasks && tasks.length > 0) {
+                contentParts.push('');
+                contentParts.push('  ## Tasks');
+                const formattedTasks = tasks.map(task => `  - + ${task}`).join('\n');
+                contentParts.push(formattedTasks);
+            }
+            const fullContent = contentParts.join('\n');
+            try {
+                const response = await fetch(`https://reflect.app/api/graphs/${graph_id}/notes`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${accessToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        subject: subject,
+                        content_markdown: fullContent,
+                        pinned: false,
+                    }),
+                });
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    throw new Error(`HTTP error! status: ${response.status}, body: ${errorText}`);
+                }
+                const data = await response.json();
+                const dailyNoteResponse = await fetch(`https://reflect.app/api/graphs/${graph_id}/daily-notes`, {
+                    method: "PUT",
+                    headers: {
+                        Authorization: `Bearer ${accessToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        date: todayDate,
+                        text: `[[${subject}]]`,
+                        transform_type: "list-append",
+                        list_name: `[[${tag}]]`,
+                    }),
+                });
+                if (!dailyNoteResponse.ok) {
+                    const errorText = await dailyNoteResponse.text();
+                    console.error(`Failed to append to daily notes: ${dailyNoteResponse.status}, ${errorText}`);
+                }
+                const message = `Note "${subject}" created with tag [[${tag}]]${tasks?.length ? ` and ${tasks.length} task(s)` : ''} and linked in daily notes`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                note: data,
+                                message: message
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ error: String(e) }),
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}

package/dist/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility functions for the Reflect MCP Server
+ */
+export declare const DEFAULT_DB_PATH = "~/Library/Application Support/Reflect/File System/000/t/00/00000000";
+/**
+ * Expands ~ to the user's home directory
+ */
+export declare function expandPath(filePath: string): string;
+/**
+ * Strips HTML tags from a string, converting <br> to newlines
+ */
+export declare function stripHtml(html: string | null): string;
+/**
+ * Formats a timestamp in milliseconds to an ISO date string
+ */
+export declare function formatDate(timestampMs: number): string;
+/**
+ * Gets today's date in YYYY-MM-DD format for a specific timezone
+ */
+export declare function getDateForTimezone(timezone: string): string;

package/dist/utils.js

@@ -0,0 +1,46 @@
+/**
+ * Utility functions for the Reflect MCP Server
+ */
+import * as path from "path";
+import * as os from "os";
+// Reflect local database path
+export const DEFAULT_DB_PATH = "~/Library/Application Support/Reflect/File System/000/t/00/00000000";
+/**
+ * Expands ~ to the user's home directory
+ */
+export function expandPath(filePath) {
+    if (filePath.startsWith("~")) {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return filePath;
+}
+/**
+ * Strips HTML tags from a string, converting <br> to newlines
+ */
+export function stripHtml(html) {
+    if (!html)
+        return "";
+    let text = html.replace(/<br\s*\/?>/gi, "\n");
+    text = text.replace(/<[^>]+>/g, "");
+    text = text.replace(/\n\s*\n/g, "\n\n");
+    return text.trim();
+}
+/**
+ * Formats a timestamp in milliseconds to an ISO date string
+ */
+export function formatDate(timestampMs) {
+    return new Date(timestampMs).toISOString();
+}
+/**
+ * Gets today's date in YYYY-MM-DD format for a specific timezone
+ */
+export function getDateForTimezone(timezone) {
+    const now = new Date();
+    const formatter = new Intl.DateTimeFormat('en-CA', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    });
+    return formatter.format(now);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "reflect-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Reflect Notes - connect your notes to Claude Desktop. Just run: npx reflect-mcp",
+  "type": "module",
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "bin": {
+    "reflect-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "reflect",
+    "claude",
+    "ai",
+    "notes",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "fastmcp": "^3.25.4",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}