MCP Notes Server

基于 MCP (Model Context Protocol) 的个人笔记管理服务，让 AI Agent 通过标准协议远程读写、搜索和编辑 Markdown 笔记。

功能

工具	说明
create_note	创建新笔记
append_note	追加内容（支持自动时间戳）
read_note	读取笔记（支持按行范围，返回 mtime 用于冲突检测）
delete_note	删除笔记
search_notes	跨文件关键词搜索，返回上下文
replace_in_note	精确文本替换（支持 mtime 校验）
list_notes	列出目录内容（支持递归）
smart_edit	自然语言指令编辑（调用 LLM 两步定位+操作）

特性

• Bearer Token 鉴权 — HTTP 模式下强制 Token 验证，stdio 模式自动跳过
• 路径安全 — 防止目录穿越，排除敏感目录（password、config 等）和指定文件
• 冲突检测 — 写操作支持 expected_mtime 校验，防止多 Agent 基于过期内容误操作；写操作返回新 mtime 供后续使用
• LLM 智能编辑 — smart_edit 通过 Kimi 大模型理解自然语言指令，两步执行：先定位目标内容，再精确操作

快速开始

环境准备

# Python 3.11+
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

配置

cp config/.env.example config/.env
# 编辑 config/.env，填入你的 API Key 和 Token

各字段说明见 config/.env.example。

启动

# stdio 模式（本地 Agent 直连，无需鉴权）
python mcp_server.py

# HTTP 模式（远程访问）
python mcp_server.py --transport http --port 8765

客户端连接

stdio 模式（推荐本地使用）：

Agent 客户端以子进程方式自动拉起 server，通过 stdin/stdout 管道通信，无需手动启动服务。

在 Claude Desktop、Cursor 等支持 MCP 的客户端中配置：

{
  "mcpServers": {
    "notes": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"]
    }
  }
}

或在代码中使用 fastmcp Client：

from fastmcp import Client

async with Client("mcp_server.py") as client:
    result = await client.call_tool("list_notes", {"directory": ""})
    print(result[0].text)

更多示例见 tests/test_client_stdio.py。

HTTP 模式（远程访问）：

需要先手动启动服务，Agent 通过网络调用：

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

安全机制

• 目录隔离：.venv、config、__pycache__、.git、password 目录不可访问
• 文件黑名单：work/账号密码相关数据.md 等敏感文件被明确排除
• 路径穿越防护：所有路径操作经过 resolve() 校验，禁止 .. 逃逸
• Token 鉴权：HTTP 模式必须携带 Authorization: Bearer <token>

冲突检测机制

Agent A: read_note("file.md")     → 返回 mtime: 1751529600.123
Agent A: replace_in_note(..., expected_mtime=1751529600.123) → ✅ 成功，返回新 mtime: 1751529605.456
Agent B: replace_in_note(..., expected_mtime=1751529600.123) → ⚠️ 被拦截，提示重新读取

依赖

• FastMCP >= 3.4.0 — MCP 协议实现
• OpenAI Python SDK >= 2.0.0 — LLM 调用
• python-dotenv >= 1.0.0 — 环境变量管理

内网穿透（可选）

如需从公网访问，可自行搭建内网穿透。以 frp 为例：

1. 下载 frpc 放到项目目录
2. 配置 frpc.toml：

serverAddr = "your-server-ip"
serverPort = 9000

[[proxies]]
name = "mcp-server"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8765
remotePort = 8765

3. 启动时加 --frpc 自动拉起 frpc：

python mcp_server.py --transport http --port 8765 --frpc

也可手动单独启动 frpc，不依赖本服务管理。

License

MIT