内容
# 小鸟 Obsidian MCP
一个本地优先的MCP服务器和Codex技能包，用于将日常工作上下文转换为路由Obsidian知识。
现代工作使得上下文分散在会议笔记、浏览器研究、电子邮件、聊天、任务系统和AI对话中。小鸟可以总结一天的工作，但保存在Gmail草稿中的每日总结并不是一个持久的知识库。Obsidian可以成为这样的知识库，但前提是信息被路由到正确的笔记中，而不是被堆积到一个巨大的原始日志中。
该项目连接了这些部分。它为一个Obsidian保险库提供了一个安全的本地MCP服务器和技能，用于导入小鸟的每日上下文，并在稍后搜索保险库作为“全局知识”。
预期的工作流程是：
```text
小鸟捕获并草拟每日上下文
-> Codex导入草稿
-> 已知项目/人员/任务/决策路由到Obsidian笔记
-> 未知项目进入路由审查
-> 稍后，Codex可以搜索Obsidian以获取项目记忆
```
目标不是保存原始活动转储。目标是保存有用的工作记忆，放在正确的位置：每日笔记、项目笔记、人员笔记、决策、任务和开放循环。
## 功能
- 将MCP客户端连接到一个配置的Obsidian保险库。
- 通过Codex技能从Gmail导入小鸟每日上下文草稿。
- 将已知项目和公司路由到配置的Obsidian笔记。
- 将未知项目发送到路由审查，而不是创建随机文件。
- 保留一个小型摄入账本以防止重复。
- 默认情况下，在路由后丢弃原始小鸟草稿正文。
- 添加一个反向查找技能，以便Codex可以搜索Obsidian作为“全局知识”。
## 工作原理
```text
小鸟Gmail草稿
-> Codex技能
-> 小鸟-obsidian-mcp
-> 路由Obsidian笔记
-> 成功写入后删除Gmail草稿
```
反向查找：
```text
用户询问“检查全局知识”
-> Codex技能
-> 通过MCP搜索/读取Obsidian
-> 用笔记来源回答
```
## 要求
- macOS、Linux或Windows，带有Node.js 20+
- 存储在本地文件系统上的Obsidian保险库
- 带有MCP支持的Codex
- 如果使用小鸟Gmail草稿工作流，则需要Gmail连接器访问权限
Obsidian不需要打开文件系统写入，但您应该使用现有的保险库路径。
`node_modules/`不是存储库的一部分。依赖项在`package.json`中声明，并使用`npm install`或`npm run setup:codex`本地安装。
## Codex快速入门
```bash
git clone <仓库网址>
cd 小鸟-obsidian-mcp
npm run setup:codex
```
设置脚本：
- 询问您的Obsidian保险库路径
- 安装依赖项
- 构建MCP服务器
- 从`config/routing.example.json`创建本地`config/routing.json`
- 在`~/.codex/config.toml`中注册MCP服务器
- 将包含的Codex技能安装到`~/.codex/skills`
在设置完成后重启Codex。
## 手动设置
安装和构建：
```bash
npm install
npm run build
```
使用以下配置您的MCP客户端：
```toml
[mcp_servers.littlebird_obsidian]
command = "node"
args = ["/绝对路径/小鸟-obsidian-mcp/dist/index.js"]
startup_timeout_sec = 30
[mcp_servers.littlebird_obsidian.env]
OBSIDIAN_VAULT_PATH = "/绝对路径/您的/Obsidian/保险库"
OBSIDIAN_WRITE_MODE = "create-append"
RAW_CAPTURE_RETENTION = "discard"
LITTLEBIRD_ROUTING_CONFIG_PATH = "/绝对路径/小鸟-obsidian-mcp/config/routing.json"
```
安装技能：
```bash
ln -s "/绝对路径/小鸟-obsidian-mcp/skills/littlebird-gmail-to-obsidian" "$HOME/.codex/skills/littlebird-gmail-to-obsidian"
ln -s "/绝对路径/小鸟-obsidian-mcp/skills/obsidian-global-knowledge" "$HOME/.codex/skills/obsidian-global-knowledge"
```
在更改MCP配置或安装技能后重启Codex。
## 配置路由
复制示例路由文件：
```bash
cp config/routing.example.json config/routing.json
```
编辑`config/routing.json`：
```json
{
"projectRoutes": [
{
"aliases": ["示例项目", "示例应用"],
"path": "Projects/示例项目.md"
},
{
"aliases": ["示例公司", "示例有限公司"],
"path": "Companies/示例公司.md"
}
],
"peopleRoutes": [
{
"aliases": ["示例人物"],
"path": "People/示例人物.md"
}
]
}
```
已知别名路由到配置的笔记。未知项目/公司项目被写入：
```text
00_Inbox/路由审查/
```
技能应该在删除源草稿之前询问这些未知项目属于哪里。
## 包含的技能
### 小鸟Gmail到Obsidian
提示：
```text
使用$littlebird-gmail-to-obsidian查找我的小鸟Gmail草稿并将其写入Obsidian。
```
行为：
- 在Gmail草稿中搜索小鸟每日上下文
- 最旧的优先处理所有匹配的草稿
- 通过MCP服务器写入路由知识
- 如果不存在Gmail草稿，则回退到旧的Obsidian分类笔记
- 仅在成功路由且无未解决的审查后删除Gmail草稿
### Obsidian全局知识
提示：
```text
使用$obsidian-global-knowledge检查我的全局目录以获取示例项目上下文。
```
行为：
- 搜索相关的Obsidian笔记
- 读取最高信号匹配
- 用简洁的综合答案
- 引用保险库相对笔记路径
## MCP工具
- `list_vault_folder`
- `search_notes`
- `read_note`
- `create_note`
- `append_to_note`
- `append_daily_note`
- `create_triage_entry`
- `ingest_littlebird_context`
- `process_littlebird_triage_note`
## 安全模型
服务器：
- 限制所有文件访问到一个配置的保险库路径
- 拒绝绝对工具输入路径
- 拒绝保险库外的路径遍历
- 不暴露一般删除或移动工具
- 永远不会用`create_note`覆盖现有笔记
- 默认情况下将原始小鸟草稿排除在保险库之外
- 保留一个小型摄入账本用于审计和重复检测
- 仅通过`process_littlebird_triage_note`删除过时的分类笔记
Gmail草稿删除由Codex技能处理，而不是MCP服务器。技能应该仅在摄入结果成功且不需要路由审查时删除草稿。
## 验证
临时保险库烟雾测试：
```bash
npm run smoke:cli
```
配置保险库MCP烟雾测试：
```bash
OBSIDIAN_VAULT_PATH="/绝对路径/您的/Obsidian/保险库" npm run smoke
```
测试：
```bash
npm run typecheck
npm test
```
## 本地文件和隐私
提交：
- `.env.example`
- `config/routing.example.json`
- `src/**`
- `skills/**`
- `docs/**`
不要提交：
- `.env`
- `config/routing.json`
- Obsidian保险库内容
- Gmail草稿ID
- 个人MCP客户端配置
- 生成的构建/测试输出
参见 [docs/env-and-local-files.md](docs/env-and-local-files.md) 和 [docs/permissions.md](docs/permissions.md)。
