@sunub/obsidian-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,93 @@
+# Obsidian MCP Server
+
+`obsidian-mcp-server`는 [Model Context Protocol(MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)을 구현한 서버로, 로컬 Obsidian vault의 문서들을 AI 에이전트나 외부 애플리케이션에서 쉽게 탐색하고 관리할 수 있도록 강력한 도구 API를 제공합니다.
+
+Obsidian Vault를 이용해 AI가 활용 가능한 지식 베이스(Knowledge Base)로 확장하여 사용할 수 있게끔 하고 문서 검색, 요약, 정리와 같은 부가적인 작업을 자동화하여 사용자가 핵심적인 "글쓰기 활동"에만 집중할 수 있는 환경을 구축하고자 제작했습니다.
+
+## 핵심 아키텍처
+
+본 서버는 `VaultManager`와 `Indexer`를 중심으로 구축되어 대규모 Vault에서도 높은 성능과 메모리 효율성을 보장합니다.
+
+- **`Indexer` 기반 검색**: 서버 시작 시 가벼운 역 인덱스(Inverted Index)를 생성하여 키워드 검색 시 거의 즉각적인 결과를 반환합니다(O(1)). 전체 파일 내용을 메모리에 상주시키지 않아 메모리 사용량을 최소화합니다.
+- **`VaultManager`**: Vault 내의 모든 문서를 효율적으로 관리하며, 파일 시스템과 상호작용하여 문서의 생성, 수정, 삭제를 처리합니다.
+
+## 주요 기능
+
+- **고급 문서 탐색**: `vault` 도구를 통해 키워드 검색, 전체 목록 조회, 특정 문서 읽기, 통계 분석 등 다양한 탐색 기능을 제공합니다.
+- **AI 기반 속성 생성**: `generate_property` 도구는 문서 본문을 분석하여 `title`, `tags`, `summary` 등 적절한 frontmatter 속성을 자동으로 생성합니다.
+- **안전한 속성 업데이트**: `write_property` 도구를 사용하여 생성된 속성을 기존 frontmatter와 병합하여 파일에 안전하게 기록합니다.
+- **첨부 파일 자동 정리**: `organize_attachments` 도구는 문서와 연결된 첨부 파일(예: 이미지)을 자동으로 감지하여 문서 제목에 맞는 폴더로 이동시키고 링크를 업데이트합니다.
+- **통합 워크플로우**: `create_document_with_properties`와 같은 도구를 통해 문서 분석부터 속성 생성, 파일 업데이트까지의 전체 과정을 단일 명령으로 실행합니다.
+- **신뢰성 및 테스트**: `vitest`를 사용한 End-to-End 테스트와 GitHub Actions 기반의 CI/CD 파이프라인을 통해 서버의 안정성과 각 도구 API의 응답 스키마를 검증합니다.
+
+## 도구 API
+
+`obsidian-mcp-server`는 MCP 클라이언트를 통해 호출할 수 있는 다음과 같은 도구들을 제공합니다.
+
+### `vault`
+
+Vault 내 문서를 탐색하고 분석하는 핵심 도구입니다. `action` 파라미터를 통해 다양한 기능을 수행할 수 있습니다.
+
+- **`list_all`**: Vault 내 모든 문서의 목록과 메타데이터를 반환합니다.
+- **`search`**: 키워드를 기반으로 문서 제목, 내용, 태그를 검색합니다.
+- **`read`**: 특정 파일의 내용을 읽고 frontmatter와 본문을 반환합니다.
+- **`stats`**: Vault 내 모든 문서의 통계(단어, 글자 수 등)를 제공합니다.
+
+### `generate_property`
+
+문서 경로(`filePath`)를 입력받아 해당 문서의 내용을 분석하고, AI가 추천하는 frontmatter 속성을 생성하여 반환합니다.
+
+### `write_property`
+
+파일 경로(`filePath`)와 JSON 형식의 속성(`properties`)을 입력받아, 해당 파일의 frontmatter를 업데이트합니다.
+
+### `create_document_with_properties`
+
+문서 분석, 속성 생성, 파일 업데이트의 전 과정을 한 번에 처리하는 통합 도구입니다.
+
+### `organize_attachments`
+
+키워드로 문서를 찾아 해당 문서에 연결된 모든 첨부 파일을 `images/{문서 제목}` 폴더로 이동시키고, 문서 내의 링크를 자동으로 업데이트합니다.
+
+## 시작하기
+
+1.  **저장소 복제 및 의존성 설치**:
+
+    ```bash
+    git clone https://github.com/sunub/obsidian-mcp-server.git
+    cd obsidian-mcp-server
+    npm install
+    ```
+
+2.  **환경 변수 설정**:
+    프로젝트 루트에 `.env` 파일을 생성하고 Obsidian vault의 절대 경로를 지정합니다.
+
+    ```
+    VAULT_DIR_PATH=/path/to/your/obsidian/vault
+    ```
+
+3.  **프로젝트 빌드**:
+
+    ```bash
+    npm run build
+    ```
+
+4.  **서버 실행**:
+    ```bash
+    node build/index.js
+    ```
+    이제 MCP 클라이언트에서 서버에 연결하여 도구를 사용할 수 있습니다.
+
+## 개발
+
+### 테스트 실행
+
+`vitest`를 사용하여 End-to-End 테스트를 실행할 수 있습니다.
+
+```bash
+npm test
+```
+
+### CI/CD
+
+이 프로젝트는 GitHub Actions를 사용하여 CI/CD 파이프라인을 구축했습니다. `main` 브랜치에 push 또는 pull request가 발생하면 자동으로 빌드와 테스트가 수행됩니다.

package/build/index.js

@@ -0,0 +1,21 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import createMcpServer from "./server.js";
+export default function smitheryEntryPoint() {
+    const server = createMcpServer();
+    return server.server;
+}
+async function main() {
+    try {
+        const server = createMcpServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    catch (error) {
+        console.error("Failed to start MCP server:", error);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("main() 함수에서 치명적인 오류가 발생했습니다:", error);
+    process.exit(1);
+});

package/build/server.js

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import pkg from "../package.json" with { type: "json" };
+import tools from "./tools/index.js";
+export default function createMcpServer() {
+    const mcpServer = new McpServer({
+        version: pkg.version,
+        name: "obsidian-mcp-server",
+        title: "Obsidian MCP Server",
+    }, {
+        capabilities: {
+            logging: {},
+            tools: { listChanged: false },
+        },
+        instructions: `
+        This server provides access to Obsidian vault documents and related tools.
+        
+        Available tools:
+        - obsidian_content_getter: Search, read, and analyze vault documents
+        
+        Available resources:
+        - docs://{filename}: Read specific documents from the vault
+        
+        Environment requirements:
+        - VAULT_DIR_PATH: Path to your Obsidian vault directory
+      `,
+    });
+    for (const tool of Object.values(tools)) {
+        tool.register(mcpServer);
+    }
+    return mcpServer;
+}

package/build/tools/create_document_with_properties/index.js

@@ -0,0 +1,145 @@
+import { getGlobalVaultManager } from "../../utils/getVaultManager.js";
+import { getParsedVaultPath } from "../../utils/parseVaultPath.js";
+import { execute as writePropertyExecute } from "../write_property/index.js";
+import { createDocumentWithPropertiesParamsSchema, } from "./params.js";
+export const name = "create_document_with_properties";
+export const annotations = {
+    title: "Create Document with Properties",
+    openWorldHint: true,
+};
+export const description = `
+  Initiates an integrated workflow to read a document, guide an AI to generate properties, and then write those properties to a file.
+
+  This tool acts as a workflow manager for an AI agent. It reads the content of a specified document and returns a structured, multi-step plan. The AI agent must follow this plan by first calling the 'generate_obsidian_property' tool to get the document's content for analysis, and then, after generating the properties, calling the 'write_obsidian_property' tool to save them.
+
+  Use this tool to start the end-to-end process of enriching a document with AI-generated metadata.
+`;
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: annotations.title || name,
+        description: description,
+        inputSchema: createDocumentWithPropertiesParamsSchema.shape,
+        annotations: annotations,
+    }, execute);
+};
+export const execute = async (params) => {
+    const vaultDirPath = getParsedVaultPath();
+    if (!vaultDirPath) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "VAULT_DIR_PATH environment variable is not set",
+                        solution: "Set VAULT_DIR_PATH to your Obsidian vault directory",
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    let vaultManager = null;
+    try {
+        vaultManager = getGlobalVaultManager();
+    }
+    catch (e) {
+        return {
+            isError: true,
+            content: [
+                { type: "text", text: JSON.stringify({ error: e.message }) },
+            ],
+        };
+    }
+    try {
+        const targetPath = params.outputPath || params.sourcePath;
+        if (params.aiGeneratedProperties) {
+            const writeResult = await writePropertyExecute({
+                filePath: targetPath,
+                properties: params.aiGeneratedProperties,
+                quiet: params.quiet || false,
+            });
+            return writeResult;
+        }
+        const document = await vaultManager.getDocumentInfo(params.sourcePath);
+        if (document === null) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `Source document not found: ${params.sourcePath}`,
+                            suggestion: "Verify the file path and ensure the file exists. You can use the 'obsidian_vault' tool with the 'list_all' action to see all available files.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const instructionForAI = {
+            ai_prompt: "Your task is to analyze the provided text content and create a JSON object of document properties based on the requested schema. After creating the JSON object, you MUST call the 'create_document_with_properties' tool again, passing back the original parameters along with the new 'aiGeneratedProperties' parameter containing your generated JSON.",
+            purpose: "Analyze document content and return a structured JSON object of properties.",
+            content_to_analyze: {
+                source_path: params.sourcePath,
+                content_preview: document.content.substring(0, 2000) +
+                    (document.content.length > 2000 ? "..." : ""),
+            },
+            // AI가 다시 호출해야 할 다음 작업에 대한 명확한 명세
+            next_action_required: {
+                tool_to_call: name, // 바로 이 도구('create_document_with_properties')를 다시 호출
+                parameters_to_add: {
+                    sourcePath: params.sourcePath,
+                    outputPath: params.outputPath,
+                    overwrite: params.overwrite,
+                    quiet: params.quiet,
+                    aiGeneratedProperties: "<- Insert your generated JSON object here.",
+                },
+                example_of_next_call: {
+                    tool_name: name,
+                    parameters: {
+                        sourcePath: params.sourcePath,
+                        aiGeneratedProperties: {
+                            title: "Serverless 환경에서 I/O 처리 최적화 경험기",
+                            date: "2025-04-03",
+                            tags: ["serverless", "optimization"],
+                            summary: "Promise.all, Worker를 벤치마크하며 서버리스 환경에서의 I/O 처리 최적화 경험기를 공유합니다.",
+                            slug: "serverless-io-optimization",
+                            category: "code",
+                            completed: true,
+                        },
+                    },
+                },
+            },
+        };
+        return {
+            isError: false,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(instructionForAI, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: `Failed to create workflow instruction: ${error instanceof Error ? error.message : String(error)}`,
+                        params: params,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: createDocumentWithPropertiesParamsSchema.shape,
+    execute,
+    register,
+};

package/build/tools/create_document_with_properties/params.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { obsidianPropertyOutputSchema } from "../generate_property/params.js";
+// input properties
+const sourcePath = z
+    .string()
+    .describe('The path to the source markdown file to read and analyze (e.g., "draft/my-article.md")');
+const outputPath = z
+    .string()
+    .optional()
+    .describe("The path where the processed file with properties will be saved. If not provided, the source file will be updated in place.");
+const overwrite = z
+    .boolean()
+    .default(false)
+    .describe("If set to true, existing properties will be overwritten by the AI-generated content. Default: false.");
+const aiGeneratedProperties = obsidianPropertyOutputSchema
+    .optional()
+    .describe("AI-generated properties based on content analysis. If provided, these will be used instead of internal analysis.");
+const quiet = z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("If true, the final write operation will return a minimal success message.");
+// input schema
+export const createDocumentWithPropertiesParamsSchema = z
+    .object({
+    sourcePath: sourcePath,
+    outputPath: outputPath,
+    overwrite: overwrite.optional(),
+    aiGeneratedProperties: aiGeneratedProperties.optional(),
+    quiet: quiet,
+})
+    .describe("Parameters for creating or updating a document with automatically generated properties");

package/build/tools/generate_property/index.js

@@ -0,0 +1,124 @@
+import { getGlobalVaultManager } from "../../utils/getVaultManager.js";
+import { obsidianPropertyQueryParamsSchema, } from "./params.js";
+export const name = "generate_property";
+export const annotations = {
+    title: "Obsidian Property Writer",
+    openWorldHint: true,
+};
+export const description = `
+  Analyzes the content of a specified Obsidian Markdown file to automatically generate the most suitable properties (frontmatter) and updates the file directly.
+
+  Use Cases:
+  
+  - After Completing a Draft: Use when the body of the text is complete, and you want to generate all properties at once.
+  - Updating Information: Use when you want to update existing properties with more accurate information reflecting the latest content.
+  - Completing Missing Info: Use when you want to automatically add missing properties like tags or a summary to a document that only has a title.
+  
+  Parameters:
+  
+  filename: The name or path of the file to analyze and add properties to (e.g., "my-first-post.md").
+  overwrite: If set to true, existing properties will be overwritten by the AI-generated content. Default: false.
+  
+  Generated Properties:
+  
+  The AI analyzes the context of the content to generate the following properties:
+  
+  - aliases: An array of alternative names or synonyms based on the content.
+  - title: A title that best represents the core topic of the document.
+  - tags: An array of tags extracted from the core keywords of the content (e.g., [AI, Obsidian, productivity]).
+  - summary: A one to two-sentence summary of the entire document.
+  - slug: A hyphenated-string suitable for URLs, containing the core keywords from the content.
+  - date: The event date or creation date inferred from the content (in ISO 8601 format).
+  - completed: A boolean (true or false) indicating whether the content is considered a final version.
+  
+  Return Value:
+  
+  Upon success, returns a JSON object containing a success message that includes the modified filename.
+  { "status": "success", "message": "Successfully updated properties for my-first-post.md" }
+  
+  Requirements:
+  
+  The user's absolute path to the Obsidian vault must be correctly set in an environment variable.
+`;
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: annotations.title || name,
+        description: description,
+        inputSchema: obsidianPropertyQueryParamsSchema.shape,
+        annotations: annotations,
+    }, execute);
+};
+export const execute = async (params) => {
+    const response = { content: [], isError: false };
+    let vaultManager = null;
+    try {
+        vaultManager = getGlobalVaultManager();
+    }
+    catch (e) {
+        return {
+            isError: true,
+            content: [
+                { type: "text", text: JSON.stringify({ error: e.message }) },
+            ],
+        };
+    }
+    try {
+        const document = await vaultManager.getDocumentInfo(params.filename);
+        if (document === null) {
+            response.content.push({
+                type: "text",
+                text: JSON.stringify({
+                    error: `Document not found: ${params.filename}`,
+                    suggestion: "Use 'list_all' action to see available documents",
+                    searched_filename: params.filename,
+                }, null, 2),
+            });
+            return response;
+        }
+        const documentData = {
+            filename: params.filename,
+            content_preview: `${document.content.substring(0, 300).replace(/\s+/g, " ")}...`,
+            instructions: {
+                purpose: "Generate or update the document's frontmatter properties based on its content.",
+                usage: "Analyze the provided content_preview. If more detail is needed to generate accurate properties, you MUST first call the 'obsidian_vault' tool with the 'read' action to get the full document content.",
+                content_type: "markdown",
+                overwrite: params.overwrite || false,
+                output_format: "Return a JSON object with the following structure",
+                schema: {
+                    title: "string - Title representing the core topic",
+                    tags: "string[] - Array of relevant tags from content keywords",
+                    summary: "string - 1-2 sentence summary of the document",
+                    slug: "string - URL-friendly hyphenated identifier",
+                    date: "string - ISO 8601 date format",
+                    completed: "boolean - Whether content is finalized",
+                    aliases: "string[] - (Optional) Alternative names or synonyms",
+                    category: "string - (Optional) Document category",
+                },
+            },
+        };
+        response.content.push({
+            type: "text",
+            text: JSON.stringify(documentData, null, 2),
+        });
+    }
+    catch (error) {
+        response.isError = true;
+        response.content.push({
+            type: "text",
+            text: JSON.stringify({
+                error: error.message,
+                action: params,
+                solution: "Ensure the VAULT_DIR_PATH environment variable is set to your Obsidian vault directory and the filename is correct.",
+            }, null, 2),
+        });
+    }
+    return response;
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: obsidianPropertyQueryParamsSchema.shape,
+    execute,
+    register,
+};

package/build/tools/generate_property/params.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+// input properties
+const obsidianGenerateInputFilename = z
+    .string()
+    .describe('The name or path of the file to analyze and add properties to (e.g., "my-first-post.md")');
+const obsidianGenerateInputOverwrite = z
+    .boolean()
+    .default(true)
+    .describe("If set to true, existing properties will be overwritten by the AI-generated content. Default: false.");
+// input schema
+export const obsidianPropertyQueryParamsSchema = z
+    .object({
+    filename: obsidianGenerateInputFilename,
+    overwrite: obsidianGenerateInputOverwrite.optional(),
+})
+    .describe("Parameters for generating or updating Obsidian document properties");
+// output properties
+export const obsidianCssClassesProperty = z
+    .array(z.string())
+    .describe("List of CSS classes associated with the document");
+export const obsidianTagsProperty = z
+    .array(z.string())
+    .describe("List of tags associated with the document");
+export const obsidianTitleProperty = z
+    .string()
+    .describe("Title of the document");
+export const obsidianDateProperty = z
+    .string()
+    .describe("Creation date of the document in ISO 8601 format");
+export const obsidianSummaryProperty = z
+    .string()
+    .describe("Brief summary or abstract of the document");
+export const obsidianSlugProperty = z
+    .string()
+    .describe("URL-friendly identifier for the document");
+export const obsidianCategoryProperty = z
+    .string()
+    .describe("Category or classification of the document");
+export const obsidianCompletedProperty = z
+    .boolean()
+    .describe("Indicates whether a task or item is completed");
+// output schema
+export const obsidianPropertyOutputSchema = z
+    .object({
+    cssclasses: obsidianCssClassesProperty.optional(),
+    tags: obsidianTagsProperty.optional(),
+    title: obsidianTitleProperty.optional(),
+    date: obsidianDateProperty.optional(),
+    summary: obsidianSummaryProperty.optional(),
+    slug: obsidianSlugProperty.optional(),
+    category: obsidianCategoryProperty.optional(),
+    completed: obsidianCompletedProperty.optional(),
+})
+    .describe("Extracted properties from the Obsidian document content");

package/build/tools/index.js

@@ -0,0 +1,12 @@
+import CreateDocumentWithPropertyTool from "./create_document_with_properties/index.js";
+import GenerateObsidianVaultPropertiesTool from "./generate_property/index.js";
+import OrganizeAttachmentsTool from "./organize_attachments/index.js";
+import ObsidianVaultTool from "./vault/index.js";
+import WriteObsidianPropertyTool from "./write_property/index.js";
+export default {
+    ObsidianVaultTool,
+    GenerateObsidianVaultPropertiesTool,
+    WriteObsidianPropertyTool,
+    CreateDocumentWithPropertyTool,
+    OrganizeAttachmentsTool,
+};

package/build/tools/organize_attachments/index.js

@@ -0,0 +1,110 @@
+import { getGlobalVaultManager } from "../../utils/getVaultManager.js";
+import { getParsedVaultPath } from "../../utils/parseVaultPath.js";
+import { organizeAttachmentsParamsSchema, } from "./params.js";
+import { genreateOrganizationTasks } from "./utils.js";
+export const name = "organize_attachments";
+export const annotations = {
+    title: "Organize Attachments",
+    openWorldHint: true,
+};
+export const description = `
+  Scans a specified markdown file for linked images (or other attachments),
+  moves them to a dedicated folder named after the document's title,
+  and updates the links within the markdown file automatically.
+
+  Use Cases:
+  - When a post is finalized and you want to clean up all associated images into a neat folder.
+  - To automatically organize attachments for better vault management.
+
+  Example Workflow:
+  1. Specify 'my-awesome-post.md' as the fileName.
+  2. The tool finds the 'title' property in the frontmatter (e.g., "My Awesome Post").
+  3. It finds all image links like ![[my-image.png]].
+  4. It creates a folder at '{vault}/images/My Awesome Post/'.
+  5. It moves 'my-image.png' into that new folder.
+  6. It updates the link in the markdown file to ![[images/My Awesome Post/my-image.png]].
+`;
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: annotations.title || name,
+        description: description,
+        inputSchema: organizeAttachmentsParamsSchema.shape,
+        annotations: annotations,
+    }, execute);
+};
+export const execute = async (params) => {
+    const vaultDirPath = getParsedVaultPath();
+    if (!vaultDirPath) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: "VAULT_DIR_PATH is not set" }),
+                },
+            ],
+        };
+    }
+    let vaultManager = null;
+    try {
+        vaultManager = getGlobalVaultManager();
+    }
+    catch (e) {
+        return {
+            isError: true,
+            content: [
+                { type: "text", text: JSON.stringify({ error: e.message }) },
+            ],
+        };
+    }
+    try {
+        await vaultManager.initialize();
+        const documents = await vaultManager.searchDocuments(params.keyword);
+        if (documents.length === 0) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `No document found for keyword: ${params.keyword}`,
+                        }),
+                    },
+                ],
+            };
+        }
+        const organizationTasks = genreateOrganizationTasks(documents, vaultDirPath);
+        const results = await Promise.all(organizationTasks.map((task) => task()));
+        return {
+            isError: false,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        summary: `Processed ${documents.length} document(s).`,
+                        details: results,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: error.message }, null, 2),
+                },
+            ],
+        };
+    }
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: organizeAttachmentsParamsSchema.shape,
+    execute,
+    register,
+};