obsidian-vault-mcp 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# Obsidian Vault MCP
+
+专为 Obsidian Vault 设计的 MCP 服务器，提供知识库专用工具。
+
+## 安装
+
+```bash
+npm install -g obsidian-vault-mcp
+# 或
+npx obsidian-vault-mcp --vault /path/to/vault
+```
+
+## 使用
+
+```bash
+obsidian-vault-mcp --vault /path/to/your/vault
+```
+
+## 提供的工具
+
+| 工具 | 功能 |
+|-----|------|
+| `search_notes` | 按标题、内容、标签搜索笔记 |
+| `get_note_metadata` | 获取笔记的 frontmatter 和元数据 |
+| `get_backlinks` | 获取指向某笔记的所有反向链接 |
+| `list_by_tag` | 按标签列出所有笔记 |
+| `get_vault_structure` | 获取 vault 目录结构 |
+| `get_recent_notes` | 获取最近修改的笔记 |
+| `create_note` | 创建带 frontmatter 的新笔记 |
+
+## 在 Claude Code ACP 中配置
+
+在 Obsidian ACP 插件设置中添加 MCP 服务器：
+
+```json
+{
+  "id": "vault",
+  "name": "Obsidian Vault",
+  "type": "stdio",
+  "command": "npx",
+  "args": ["obsidian-vault-mcp", "--vault", "{VAULT_PATH}"],
+  "enabled": true
+}
+```
+
+## 工具详情
+
+### search_notes
+
+搜索笔记，支持按标题、内容、标签搜索。
+
+```json
+{
+  "query": "搜索关键词",
+  "searchIn": "all",  // title | content | tags | all
+  "limit": 20
+}
+```
+
+### get_note_metadata
+
+获取笔记的完整元数据。
+
+```json
+{
+  "path": "folder/note.md"
+}
+```
+
+返回：
+```json
+{
+  "path": "folder/note.md",
+  "frontmatter": { "title": "...", "tags": ["..."] },
+  "tags": ["tag1", "tag2"],
+  "links": ["other-note", "another"],
+  "modified": "2025-01-01T00:00:00Z",
+  "created": "2024-12-01T00:00:00Z",
+  "size": 1234
+}
+```
+
+### get_backlinks
+
+获取所有链接到指定笔记的笔记。
+
+```json
+{
+  "path": "folder/note.md"
+}
+```
+
+### list_by_tag
+
+获取包含特定标签的所有笔记。
+
+```json
+{
+  "tag": "project"  // 不需要 #
+}
+```
+
+### get_vault_structure
+
+获取 vault 的目录结构。
+
+```json
+{
+  "depth": 2  // 遍历深度
+}
+```
+
+### get_recent_notes
+
+获取最近修改的笔记。
+
+```json
+{
+  "limit": 10,
+  "days": 7
+}
+```
+
+### create_note
+
+创建新笔记。
+
+```json
+{
+  "path": "folder/new-note.md",
+  "content": "# New Note\n\nContent here...",
+  "frontmatter": {
+    "title": "New Note",
+    "tags": ["new", "example"]
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Obsidian Vault MCP Server
+ *
+ * 提供 Obsidian Vault 专用的 MCP 工具
+ * 使用 Orama (BM25) 进行全文搜索
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+/**
+ * Obsidian Vault MCP Server
+ *
+ * 提供 Obsidian Vault 专用的 MCP 工具
+ * 使用 Orama (BM25) 进行全文搜索
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { create, insert, search } from '@orama/orama';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// 解析命令行参数
+const args = process.argv.slice(2);
+let vaultPath = process.cwd();
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--vault' && args[i + 1]) {
+        vaultPath = args[i + 1];
+        i++;
+    }
+}
+// Orama 搜索索引
+let searchIndex;
+// 确保 vault 路径存在
+async function validateVaultPath() {
+    try {
+        const stat = await fs.stat(vaultPath);
+        if (!stat.isDirectory()) {
+            console.error(`Error: ${vaultPath} is not a directory`);
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(`Error: ${vaultPath} does not exist`);
+        process.exit(1);
+    }
+}
+// 构建搜索索引
+async function buildSearchIndex() {
+    console.error('Building search index...');
+    const startTime = Date.now();
+    searchIndex = await create({
+        schema: {
+            path: 'string',
+            title: 'string',
+            content: 'string',
+            tags: 'string',
+        },
+    });
+    let count = 0;
+    async function indexDir(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory() && !entry.name.startsWith('.')) {
+                await indexDir(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                try {
+                    const content = await fs.readFile(fullPath, 'utf-8');
+                    const relativePath = path.relative(vaultPath, fullPath);
+                    const title = path.basename(entry.name, '.md');
+                    // 提取标签
+                    const tagMatches = content.match(/#[\w\u4e00-\u9fa5/-]+/g) || [];
+                    const tags = tagMatches.join(' ');
+                    await insert(searchIndex, {
+                        path: relativePath,
+                        title,
+                        content,
+                        tags,
+                    });
+                    count++;
+                }
+                catch {
+                    // 忽略读取错误
+                }
+            }
+        }
+    }
+    await indexDir(vaultPath);
+    const elapsed = Date.now() - startTime;
+    console.error(`Indexed ${count} notes in ${elapsed}ms`);
+}
+// 工具定义
+const TOOLS = [
+    {
+        name: 'search_notes',
+        description: 'Search notes using BM25 algorithm (supports fuzzy matching)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query (supports Chinese)' },
+                limit: { type: 'number', default: 20, description: 'Max results' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'get_note_metadata',
+        description: 'Get frontmatter and metadata of a note',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Note path relative to vault' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'get_backlinks',
+        description: 'Get all notes that link to the specified note',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Note path relative to vault' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'list_by_tag',
+        description: 'List all notes with a specific tag',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tag: { type: 'string', description: 'Tag to search for (without #)' },
+            },
+            required: ['tag'],
+        },
+    },
+    {
+        name: 'get_vault_structure',
+        description: 'Get the folder structure of the vault',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                depth: { type: 'number', default: 2, description: 'Max depth to traverse' },
+            },
+        },
+    },
+    {
+        name: 'get_recent_notes',
+        description: 'Get recently modified notes',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', default: 10, description: 'Max results' },
+                days: { type: 'number', default: 7, description: 'Days to look back' },
+            },
+        },
+    },
+    {
+        name: 'create_note',
+        description: 'Create a new note with optional frontmatter',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Note path relative to vault' },
+                content: { type: 'string', description: 'Note content (markdown)' },
+                frontmatter: {
+                    type: 'object',
+                    description: 'YAML frontmatter as key-value pairs',
+                },
+            },
+            required: ['path', 'content'],
+        },
+    },
+    {
+        name: 'rebuild_index',
+        description: 'Rebuild the search index (use after adding/modifying notes)',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+];
+// 工具实现 - 使用 Orama BM25 搜索
+async function searchNotes(query, limit = 20) {
+    const results = await search(searchIndex, {
+        term: query,
+        limit,
+        boost: {
+            title: 2, // 标题权重更高
+            tags: 1.5, // 标签次之
+            content: 1, // 内容权重正常
+        },
+    });
+    return results.hits.map(hit => ({
+        path: hit.document.path,
+        title: hit.document.title,
+        score: hit.score,
+    }));
+}
+async function getNoteMetadata(notePath) {
+    const fullPath = path.join(vaultPath, notePath);
+    const content = await fs.readFile(fullPath, 'utf-8');
+    const stat = await fs.stat(fullPath);
+    // 解析 frontmatter
+    let frontmatter = {};
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (fmMatch) {
+        const fmContent = fmMatch[1];
+        for (const line of fmContent.split('\n')) {
+            const colonIndex = line.indexOf(':');
+            if (colonIndex > 0) {
+                const key = line.slice(0, colonIndex).trim();
+                const value = line.slice(colonIndex + 1).trim();
+                frontmatter[key] = value;
+            }
+        }
+    }
+    // 提取标签
+    const tags = (content.match(/#[\w\u4e00-\u9fa5/-]+/g) || [])
+        .map(t => t.slice(1));
+    // 提取链接
+    const links = (content.match(/\[\[([^\]]+)\]\]/g) || [])
+        .map(l => l.slice(2, -2).split('|')[0]);
+    return {
+        path: notePath,
+        frontmatter,
+        tags: [...new Set(tags)],
+        links: [...new Set(links)],
+        modified: stat.mtime.toISOString(),
+        created: stat.birthtime.toISOString(),
+        size: stat.size,
+    };
+}
+async function getBacklinks(notePath) {
+    const backlinks = [];
+    const noteBasename = path.basename(notePath, '.md');
+    async function searchDir(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = path.relative(vaultPath, fullPath);
+            if (entry.isDirectory() && !entry.name.startsWith('.')) {
+                await searchDir(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md') && relativePath !== notePath) {
+                try {
+                    const content = await fs.readFile(fullPath, 'utf-8');
+                    if (content.includes(`[[${noteBasename}]]`) ||
+                        content.includes(`[[${notePath}]]`) ||
+                        content.includes(`[[${noteBasename}|`)) {
+                        backlinks.push(relativePath);
+                    }
+                }
+                catch {
+                    // 忽略
+                }
+            }
+        }
+    }
+    await searchDir(vaultPath);
+    return backlinks;
+}
+async function listByTag(tag) {
+    // 使用 Orama 搜索标签
+    const searchTag = tag.startsWith('#') ? tag.slice(1) : tag;
+    const results = await search(searchIndex, {
+        term: searchTag,
+        properties: ['tags'],
+        limit: 100,
+    });
+    return results.hits.map(hit => hit.document.path);
+}
+async function getVaultStructure(maxDepth = 2) {
+    async function buildTree(dir, currentDepth) {
+        if (currentDepth > maxDepth) {
+            return { type: 'folder', truncated: true };
+        }
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const children = {};
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.isDirectory()) {
+                children[entry.name] = await buildTree(path.join(dir, entry.name), currentDepth + 1);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                children[entry.name] = { type: 'note' };
+            }
+        }
+        return { type: 'folder', children };
+    }
+    return buildTree(vaultPath, 0);
+}
+async function getRecentNotes(limit = 10, days = 7) {
+    const results = [];
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+    async function searchDir(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory() && !entry.name.startsWith('.')) {
+                await searchDir(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                try {
+                    const stat = await fs.stat(fullPath);
+                    if (stat.mtime >= cutoff) {
+                        results.push({
+                            path: path.relative(vaultPath, fullPath),
+                            modified: stat.mtime,
+                        });
+                    }
+                }
+                catch {
+                    // 忽略
+                }
+            }
+        }
+    }
+    await searchDir(vaultPath);
+    return results
+        .sort((a, b) => b.modified.getTime() - a.modified.getTime())
+        .slice(0, limit)
+        .map(r => ({ path: r.path, modified: r.modified.toISOString() }));
+}
+async function createNote(notePath, content, frontmatter) {
+    const fullPath = path.join(vaultPath, notePath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    let finalContent = content;
+    if (frontmatter && Object.keys(frontmatter).length > 0) {
+        const fmLines = Object.entries(frontmatter)
+            .map(([k, v]) => `${k}: ${JSON.stringify(v)}`);
+        finalContent = `---\n${fmLines.join('\n')}\n---\n\n${content}`;
+    }
+    await fs.writeFile(fullPath, finalContent, 'utf-8');
+    // 更新索引
+    const title = path.basename(notePath, '.md');
+    const tagMatches = finalContent.match(/#[\w\u4e00-\u9fa5/-]+/g) || [];
+    await insert(searchIndex, {
+        path: notePath,
+        title,
+        content: finalContent,
+        tags: tagMatches.join(' '),
+    });
+    return `Created: ${notePath}`;
+}
+// 创建 MCP 服务器
+async function main() {
+    await validateVaultPath();
+    await buildSearchIndex();
+    const server = new Server({ name: 'obsidian-vault-mcp', version: '0.2.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case 'search_notes':
+                    result = await searchNotes(args?.query, args?.limit);
+                    break;
+                case 'get_note_metadata':
+                    result = await getNoteMetadata(args?.path);
+                    break;
+                case 'get_backlinks':
+                    result = await getBacklinks(args?.path);
+                    break;
+                case 'list_by_tag':
+                    result = await listByTag(args?.tag);
+                    break;
+                case 'get_vault_structure':
+                    result = await getVaultStructure(args?.depth);
+                    break;
+                case 'get_recent_notes':
+                    result = await getRecentNotes(args?.limit, args?.days);
+                    break;
+                case 'create_note':
+                    result = await createNote(args?.path, args?.content, args?.frontmatter);
+                    break;
+                case 'rebuild_index':
+                    await buildSearchIndex();
+                    result = 'Index rebuilt successfully';
+                    break;
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error: ${error.message}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Obsidian Vault MCP Server v0.2.0 (BM25)`);
+    console.error(`Vault: ${vaultPath}`);
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "obsidian-vault-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Obsidian vault with BM25 search, backlinks, tags, and more",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "obsidian-vault-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "obsidian",
+    "vault",
+    "ai",
+    "claude",
+    "bm25",
+    "search"
+  ],
+  "author": "chyax",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@orama/orama": "^3.1.18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}