# MCP Notes Server

基于 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 的个人笔记管理服务，让 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 大模型理解自然语言指令，两步执行：先定位目标内容，再精确操作

## 快速开始

### 环境准备

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

### 配置

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

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

### 启动

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

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

### 客户端连接

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

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

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

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

或在代码中使用 fastmcp Client：

```python
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 通过网络调用：

```bash
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](https://github.com/jlowin/fastmcp) >= 3.4.0 — MCP 协议实现
- [OpenAI Python SDK](https://github.com/openai/openai-python) >= 2.0.0 — LLM 调用
- [python-dotenv](https://github.com/theskumar/python-dotenv) >= 1.0.0 — 环境变量管理

## 内网穿透（可选）

如需从公网访问，可自行搭建内网穿透。以 [frp](https://github.com/fatedier/frp) 为例：

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

```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：

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

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

## License

MIT