ru-mcp 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# rū
+
+Connect your Obsidian vault to Claude Desktop. Write `#tags` in your notes to seed context — then mention the same tag in Claude and it pulls in everything you've written about that topic automatically.
+
+---
+
+## What you need before starting
+
+- [Obsidian](https://obsidian.md) installed and open
+- The [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) installed and enabled in Obsidian
+- [Claude Desktop](https://claude.ai/download) installed
+- [Node.js](https://nodejs.org) (v18 or later)
+
+---
+
+## Install
+
+Open your terminal and run:
+
+```bash
+npx ru-mcp setup
+```
+
+The setup wizard will:
+1. Ask for your Obsidian API key (found in Obsidian → Settings → Community Plugins → Local REST API)
+2. Verify the connection to your vault
+3. Automatically add rū to your Claude Desktop config
+
+Then **fully quit and relaunch Claude Desktop** (Cmd+Q, not just close the window).
+
+---
+
+## Using rū in Claude Desktop
+
+1. Start a new conversation
+2. Click the **📎 paperclip icon** at the bottom of the input box
+3. Select **"Add from rū"** → choose **auto_context**
+4. That's it — from this point in the conversation, any `#tag` you write will automatically pull context from your vault before Claude responds
+
+**Example:** If you have notes tagged `#AIR` in Obsidian, just write:
+
+> What should I focus on this week? #AIR
+
+Claude will retrieve your `#AIR` context and factor it into the response.
+
+> **Note:** You'll need to add `auto_context` once per conversation. It doesn't persist across new chats.
+
+---
+
+## Finding your API key
+
+1. Open Obsidian
+2. Go to **Settings** (gear icon, bottom left)
+3. Scroll to **Community Plugins** → click **Local REST API**
+4. Your API key is shown in the box labeled "Your API Key must be passed in requests..."
+
+---
+
+## Troubleshooting
+
+**"Couldn't reach Obsidian at port 27124"**
+- Make sure Obsidian is open
+- Make sure the Local REST API plugin is enabled (Settings → Community Plugins → toggle it on)
+- If you see a different port in the plugin settings, run setup again and it will prompt you
+
+**rū doesn't appear in Claude Desktop**
+- Make sure you fully quit Claude Desktop (Cmd+Q) and relaunched it after setup
+- Check that the setup completed with a ✅ success message
+
+**"OBSIDIAN_API_KEY environment variable is not set"**
+- Your Claude Desktop config may be missing the env block — re-run `npx ru-mcp setup`
+
+---
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,258 @@
+import https from "node:https";
+import http from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const OBSIDIAN_PORT = process.env.OBSIDIAN_PORT ?? "27124";
+const OBSIDIAN_BASE_URL = `https://localhost:${OBSIDIAN_PORT}`;
+const API_KEY = process.env.OBSIDIAN_API_KEY ?? "";
+const CONTEXT_LENGTH = 300;
+if (!API_KEY) {
+    console.error("Error: OBSIDIAN_API_KEY environment variable is not set.\n" +
+        "Run `npx ru-mcp setup` to configure rū.");
+    process.exit(1);
+}
+// Reuse a single agent across requests; rejectUnauthorized:false bypasses
+// the self-signed certificate used by Obsidian Local REST API.
+const httpsAgent = new https.Agent({ rejectUnauthorized: false });
+// ── Noodle bridge ─────────────────────────────────────────────────────────────
+const NOODLE_SYNC_PORT = 27125;
+let noodleData = { folders: [], snippets: [] };
+// Tiny HTTP server — Noodle POSTs its full store here on every save
+const syncServer = http.createServer((req, res) => {
+    if (req.method === 'POST' && req.url === '/noodle/sync') {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk.toString(); });
+        req.on('end', () => {
+            try {
+                noodleData = JSON.parse(body);
+                res.writeHead(200).end('ok');
+            }
+            catch {
+                res.writeHead(400).end('bad json');
+            }
+        });
+    }
+    else {
+        res.writeHead(404).end();
+    }
+});
+syncServer.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+        console.error(`Warning: Noodle sync port ${NOODLE_SYNC_PORT} already in use — Noodle bridge disabled.`);
+    }
+    else {
+        console.error("Noodle sync server error:", err.message);
+    }
+});
+syncServer.listen(NOODLE_SYNC_PORT);
+// If a tag appears within the first 50 chars of a file it's a page-level tag
+// (first line) — fetch the whole file. Otherwise return the search snippet.
+const PAGE_TAG_THRESHOLD = 50;
+function fetchFullFile(filename) {
+    return new Promise((resolve, reject) => {
+        const encodedPath = filename.split("/").map(encodeURIComponent).join("/");
+        const req = https.request({
+            hostname: "localhost",
+            port: parseInt(OBSIDIAN_PORT, 10),
+            path: `/vault/${encodedPath}`,
+            method: "GET",
+            headers: { Authorization: `Bearer ${API_KEY}` },
+            agent: httpsAgent,
+        }, (res) => {
+            let data = "";
+            res.on("data", (chunk) => { data += chunk.toString(); });
+            res.on("end", () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`Failed to fetch ${filename}: status ${res.statusCode}`));
+                }
+                else {
+                    resolve(data);
+                }
+            });
+        });
+        req.on("error", reject);
+        req.end();
+    });
+}
+async function buildResultText(result) {
+    const isPageLevel = result.matches.some(m => m.match.start < PAGE_TAG_THRESHOLD);
+    if (isPageLevel) {
+        try {
+            const content = await fetchFullFile(result.filename);
+            return [
+                `File: ${result.filename} [full page]`,
+                "-".repeat(60),
+                content.trim(),
+                "",
+            ].join("\n");
+        }
+        catch {
+            // Fall back to snippets if full-file fetch fails
+        }
+    }
+    const lines = [
+        `File: ${result.filename}`,
+        "-".repeat(60),
+    ];
+    result.matches.forEach((m, i) => {
+        lines.push(`  Snippet ${i + 1}:`);
+        lines.push(`  ${m.context.trim()}`);
+        lines.push("");
+    });
+    return lines.join("\n");
+}
+async function queryObsidianTag(tag) {
+    const results = await new Promise((resolve, reject) => {
+        const encodedQuery = encodeURIComponent(`#${tag}`);
+        const path = `/search/simple/?query=${encodedQuery}&contextLength=${CONTEXT_LENGTH}`;
+        const req = https.request({
+            hostname: "localhost",
+            port: parseInt(OBSIDIAN_PORT, 10),
+            path,
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                "Content-Type": "application/json",
+                "Content-Length": "0",
+            },
+            agent: httpsAgent,
+        }, (res) => {
+            let data = "";
+            res.on("data", (chunk) => { data += chunk.toString(); });
+            res.on("end", () => {
+                if (res.statusCode !== 200) {
+                    reject(new Error(`Obsidian API returned status ${res.statusCode}: ${data}`));
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch (err) {
+                    reject(new Error(`Failed to parse Obsidian API response: ${err}`));
+                }
+            });
+        });
+        req.on("error", (err) => {
+            reject(new Error(`Request to Obsidian failed: ${err.message}`));
+        });
+        req.end();
+    });
+    if (results.length === 0)
+        return `No results found for tag #${tag}.`;
+    const parts = await Promise.all(results.map(buildResultText));
+    return `Found ${results.length} file(s) matching #${tag}:\n\n` + parts.join("\n");
+}
+const server = new Server({ name: "ru", version: "0.1.0" }, { capabilities: { tools: {}, prompts: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "get_context",
+            description: "Search your Obsidian vault for notes tagged with a given tag and return matching filenames and context snippets.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tag: {
+                        type: "string",
+                        description: 'The Obsidian tag to search for (without the # symbol). Example: "AIR" or "tasks".',
+                    },
+                },
+                required: ["tag"],
+            },
+        },
+        {
+            name: "get_noodle_context",
+            description: "Search Noodle projects for snippets in a folder matching a #tag. Returns all snippets stored in that project folder.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tag: {
+                        type: "string",
+                        description: 'Folder name without # (e.g. "InstrumentThinking").',
+                    },
+                },
+                required: ["tag"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = request.params.arguments;
+    if (request.params.name === "get_context") {
+        if (!args || typeof args.tag !== "string" || args.tag.trim() === "") {
+            throw new Error('Missing or invalid argument: "tag" must be a non-empty string.');
+        }
+        try {
+            const result = await queryObsidianTag(args.tag.trim());
+            return { content: [{ type: "text", text: result }] };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error querying Obsidian: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === "get_noodle_context") {
+        if (!args || typeof args.tag !== "string" || args.tag.trim() === "") {
+            throw new Error('Missing or invalid argument: "tag" must be a non-empty string.');
+        }
+        const tag = args.tag.trim().toLowerCase();
+        const folder = noodleData.folders.find(f => f.name.toLowerCase().includes(tag));
+        if (!folder) {
+            return { content: [{ type: "text", text: `No Noodle project matching #${args.tag.trim()} found.` }] };
+        }
+        const snippets = noodleData.snippets.filter(s => s.folderId === folder.id);
+        if (snippets.length === 0) {
+            return { content: [{ type: "text", text: `Project #${folder.name} exists but has no snippets.` }] };
+        }
+        const lines = [`Found ${snippets.length} snippet(s) in Noodle project #${folder.name}:\n`];
+        snippets.forEach((s, i) => {
+            lines.push(`Snippet ${i + 1}${s.url ? ` (source: ${s.url})` : ''}:`);
+            lines.push(`  "${s.text}"`);
+            if (s.note)
+                lines.push(`  Note: ${s.note}`);
+            lines.push('');
+        });
+        return { content: [{ type: "text", text: lines.join('\n') }] };
+    }
+    throw new Error(`Unknown tool: ${request.params.name}`);
+});
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: [
+        {
+            name: "auto_context",
+            description: "Instructs Claude to automatically call get_context for any #tag found in user messages before responding.",
+        },
+    ],
+}));
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "auto_context") {
+        throw new Error(`Unknown prompt: ${request.params.name}`);
+    }
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "Whenever my message contains one or more hashtags (e.g. #AIR, #InstrumentThinking), automatically call get_context (for Obsidian tags) AND get_noodle_context (for Noodle project folders) for each tag before composing your response. Incorporate the retrieved context into your answer without me needing to ask explicitly.",
+                },
+            },
+        ],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("rū MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/setup.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import https from "node:https";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+// ── Helpers ────────────────────────────────────────────────────────────────────
+function ask(rl, question) {
+    return new Promise((resolve) => rl.question(question, resolve));
+}
+function pingObsidian(apiKey, port) {
+    return new Promise((resolve) => {
+        const req = https.request({
+            hostname: "localhost",
+            port: parseInt(port, 10),
+            path: "/",
+            method: "GET",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            agent: new https.Agent({ rejectUnauthorized: false }),
+            timeout: 4000,
+        }, (res) => resolve(res.statusCode !== undefined && res.statusCode < 500));
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => { req.destroy(); resolve(false); });
+        req.end();
+    });
+}
+function claudeConfigPath() {
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA ?? "", "Claude", "claude_desktop_config.json");
+    }
+    return path.join(process.env.HOME ?? "", "Library", "Application Support", "Claude", "claude_desktop_config.json");
+}
+function serverEntryPath() {
+    // Resolve the dist/index.js path relative to this compiled file
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(__dirname, "index.js");
+}
+// ── Main ───────────────────────────────────────────────────────────────────────
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+console.log("\n🟣 rū setup\n");
+console.log("This will connect rū to your Obsidian vault and add it to Claude Desktop.\n");
+// Step 1 — API key
+console.log("Step 1 of 3 — Obsidian API key");
+console.log("Find it in Obsidian → Settings → Community Plugins → Local REST API\n");
+const apiKey = (await ask(rl, "Paste your API key: ")).trim();
+if (!apiKey) {
+    console.error("\n❌ No API key entered. Setup cancelled.");
+    rl.close();
+    process.exit(1);
+}
+// Step 2 — Verify connection
+console.log("\nStep 2 of 3 — Verifying connection...");
+const port = "27124";
+const connected = await pingObsidian(apiKey, port);
+if (!connected) {
+    console.error("\n❌ Couldn't reach Obsidian at port 27124.");
+    console.error("Make sure:");
+    console.error("  • Obsidian is open");
+    console.error("  • The Local REST API plugin is enabled");
+    console.error("  • If you changed the port, update OBSIDIAN_PORT in your Claude Desktop config manually\n");
+    rl.close();
+    process.exit(1);
+}
+console.log("✅ Connected to Obsidian successfully.\n");
+// Step 3 — Write Claude Desktop config
+console.log("Step 3 of 3 — Adding rū to Claude Desktop...");
+const configPath = claudeConfigPath();
+const serverPath = serverEntryPath();
+let config = {};
+if (fs.existsSync(configPath)) {
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch {
+        console.error(`\n❌ Could not read existing config at ${configPath}.`);
+        console.error("It may be malformed JSON. Please check the file and try again.\n");
+        rl.close();
+        process.exit(1);
+    }
+}
+// Merge — never overwrite other existing servers
+const existingServers = config.mcpServers ?? {};
+config.mcpServers = {
+    ...existingServers,
+    ru: {
+        command: "node",
+        args: [serverPath],
+        env: {
+            OBSIDIAN_API_KEY: apiKey,
+            OBSIDIAN_PORT: port,
+        },
+    },
+};
+fs.mkdirSync(path.dirname(configPath), { recursive: true });
+fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+console.log(`✅ rū added to Claude Desktop config.\n`);
+console.log("━".repeat(50));
+console.log("\n🎉 Setup complete!\n");
+console.log("Next steps:");
+console.log("  1. Fully quit Claude Desktop (Cmd+Q / right-click dock → Quit)");
+console.log("  2. Relaunch Claude Desktop");
+console.log("  3. Start a new conversation");
+console.log("  4. Click the 📎 paperclip icon → 'Add from rū' → select auto_context");
+console.log("  5. Now any #tag in your message will pull context from your vault automatically\n");
+rl.close();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "ru-mcp",
+  "version": "0.1.0",
+  "description": "rū — connect your Obsidian vault to Claude Desktop via #tags",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ru-mcp": "dist/setup.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "setup": "node dist/setup.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "obsidian",
+    "claude",
+    "context",
+    "tags"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0"
+  }
+}