algonotes_rag/docs/mcp/README.md

📡 MCP Server

状态：已完成 | 最后更新：2026-06-28

---

设计目标

1. 与 CLI 功能对等，提供标准化的工具接口供 AI 助手调用
2. 覆盖笔记管理、语义查询等核心场景
3. 支持 SSE 传输协议（HTTP），可接入 Claude Desktop / Claude Code / Cherry Studio 等 MCP 客户端

---

目录结构

src/mcp/
├── __init__.py      # 包标记
├── __main__.py      # python -m src.mcp 入口
├── server.py        # FastMCP 服务器配置和工具注册
└── tools.py         # 工具实现（包装现有函数）

---

命令总览

分类	工具	用途	详见
增	ingest	导入笔记	ingest.md
改	update	更新笔记内容	update.md
改	metadata	更新笔记元数据	metadata.md
删	delete	删除笔记	delete.md
查	show / list / search	查看/列出/搜索笔记	search.md
查	ask	RAG 问答	—
查	export	导出笔记（Obsidian）	export.md

---

启动方式

uv run algonotes mcp

默认监听 http://localhost:8000，启动后终端会显示：

Starting MCP server with SSE transport on http://0.0.0.0:8000

---

MCP 客户端配置

服务启动后，各客户端通过 HTTP URL 连接：

http://localhost:8000/sse

Cherry Studio

在 设置 → MCP 服务器 中添加：

{
  "algonotes": {
    "url": "http://localhost:8000/sse"
  }
}

Claude Desktop

{
  "mcpServers": {
    "algonotes": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Claude Code

claude mcp add --transport sse algonotes http://localhost:8000/sse

---

CLI vs MCP 对照

功能	CLI 命令	MCP 工具
导入笔记	algonotes ingest	ingest
更新内容	algonotes update content	update
更新元数据	algonotes update metadata	metadata
删除笔记	algonotes delete	delete
查看原文	algonotes query show	show
列出笔记	algonotes query list	list
语义搜索	algonotes query search	search
RAG 问答	algonotes query ask	ask
导出笔记	algonotes query export	export

---

设计原则

1. 零逻辑重复：所有工具函数仅调用 scripts/ 下的现有函数
2. 薄包装层：tools.py 负责参数转换和错误处理，不包含业务逻辑
3. JSON 格式统一：返回格式与 CLI --json 输出一致
4. 懒加载：store 单例在首次调用时初始化，避免启动时加载所有依赖

---

依赖关系

src/mcp/server.py
  └── src/mcp/tools.py
        ├── scripts/ingest.py (ingest_local, ingest_web)
        ├── scripts/update.py (update_note)
        ├── scripts/delete.py (delete_note)
        └── src/store/
              ├── file_store.py (get_file_store)
              ├── sql_store.py (get_sql_store)
              └── vector_store.py (get_vector_store)