使用说明（Markdown 格式）

项目简介

Obsidian-TS-MCP 是一个基于 MCP 的后端服务器实现，旨在为 AI 客户端（如在 VS Code 中的 AI 助手、Claude Desktop 等）提供对 Obsidian Vault 的上下文信息和功能访问。服务器暴露 37 个工具，用于对笔记、模板、属性、任务、日记等进行创建、读取、修改、查询等操作，并通过 JSON-RPC 与客户端通信。

主要功能点

资源与数据访问：对 Obsidian Vault 的文件、目录、元数据（frontmatter）进行读取、写入、搜索与聚合统计。
工具注册与执行：提供一套完整的工具集合（37 个工具），客户端可通过 MCP 调用并获取结构化结果。
模板与提示支持：支持模板读取与渲染（支持日期、时间、标题等变量替换）。
会话与能力声明：服务器提供能力清单并可扩展，以应对多传输协议（如 stdio，后续可扩展）。
JSON-RPC 通信：通过 MCP 的标准请求/响应模式与客户端互操作，适配不同的前端客户端（如 VS Code、Claude 等）。
安全与可扩展：对输入进行校验，避免注入等风险；设计上便于增加新工具与扩展。

安装步骤

克隆仓库并进入项目目录
安装依赖并构建：
- npm install
- npm run build
设置 Obsidian Vault 环境
- 通过环境变量 OBSIDIAN_VAULT_PATH（Vault 的绝对路径）或其他实现中指定的路径定位 Vault（部署时请按实际路径设置）
启动 MCP 服务器
- 运行 dist/server.js（或通过 npm start 启动）
运行环境注意事项
- 确保 Obsidian 应用已开启并且 CLI 可用（视部署方式而定，当前实现以文件系统操作为核心，CLI 依赖在某些场景下被禁用）

服务器配置（客户端需要的最小配置示例）

注意：以下是 MCP 客户端需要的启动信息示例，用于描述服务器启动与连接方式。它不是服务器端代码，仅用于帮助 MCP 客户端正确连接到服务器。

{ "servers": { "obsidian": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/Obsidian-TS-MCP/dist/server.js"], "env": { "OBSIDIAN_VAULT": "My Vault" } // 注释：环境变量 OBSIDIAN_VAULT 指定默认 Vault 名称；若使用路径模式，请确保 Vault 路径通过 OBSIDIAN_VAULT_PATH 或等效机制设置 } } }

server name：obsidian（与 MCP 客户端对接时的服务器唯一标识）
command 与 args：以 node 调用 dist/server.js 的方式启动服务器
env 配置：OBSIDIAN_VAULT 指定默认 Vault 名称；如需指定文件系统路径，请设置 OBSIDIAN_VAULT_PATH（部署时按实际环境设定）

基本使用方法

客户端启动并连接：使用上述 JSON 配置在 MCP 客户端中启动服务器进程，确保服务器输出可被客户端读取
获取工具列表：请求工具集合，客户端可获取服务器暴露的 37 个工具及其输入规范
调用工具执行操作：通过 CallTool 请求调用指定工具，传入符合 Tool 输入模式的参数，服务器返回文本输出或错误信息
常见工作流示例
- 创建笔记、读取笔记、编辑 Frontmatter、搜索笔记、处理模板、查询底层数据等
- 使用 daily_note、project 系列工具进行日常记录与项目管理
注意事项
- 所有输入都经过模式校验，错误信息会以清晰文本返回
- 服务器对 Vault 拥有完全访问权限，请确保在受控环境中部署
- 服务器当前实现以 stdio 传输为主，后续可拓展至 SSE/WebSocket 等传输协定

基本参数与操作要点

配置环境变量 OBSIDIAN_VAULT 指定默认 Vault
触发工具时提供必要字段，如 create_note 需要 name、read_note 需要 file 或 path 等
支持的输出通常为文本块或 JSON，便于上层 AI 客户端对结果进行解析和呈现

部署与调试建议

在本地开发/测试阶段，使用 vitest 提供的 mock 测试覆盖关键工具与服务器行为
部署时确保 Node.js 版本为 18 及以上
对于生产，应加上认证与权限控制，限制对 Vault 的直接写入权限

Obsidian-TS-MCP