# FlowNoter 使用指南
## 简介
FlowNoter 是一个 MCP (Model Context Protocol) 服务器，可以将 AI 对话记录保存为格式化的 Markdown 笔记文件。
## 主要功能
1. **自动保存对话**: 将用户和 AI 助手的对话保存为 Markdown 格式
2. **智能清理**: 自动过滤掉思考过程、工具调用等内部信息，只保留最终回答
3. **时间戳**: 每个笔记都包含创建时间
4. **灵活配置**: 可以指定保存最近的 n 轮对话
5. **自动管理**: 自动创建和管理 `notes` 文件夹
## 安装
### 本地开发
```bash
# 克隆或下载项目
cd flownoter
# 安装依赖
npm install
# 构建项目
npm run build
```
### 使用 npx
如果发布到 npm，可以直接使用：
```bash
npx flownoter
```
## 配置 MCP 客户端
### Claude Desktop 配置
编辑 Claude Desktop 的配置文件，添加 FlowNoter 服务器：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
添加以下配置：
```json
{
"mcpServers": {
"flownoter": {
"command": "node",
"args": ["/path/to/flownoter/dist/index.js"]
}
}
}
```
或者使用 npx（如果已发布）：
```json
{
"mcpServers": {
"flownoter": {
"command": "npx",
"args": ["-y", "flownoter"]
}
}
}
```
## 工具说明
### save_conversation_note
保存对话记录为 Markdown 笔记。
#### 参数
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `messages` | Array | 是 | - | 对话消息数组 |
| `user_question` | String | 是 | - | 用户问题，用作笔记标题 |
| `num_messages` | Number | 否 | 全部 | 保存最近的 n 轮对话 |
#### 消息格式
```typescript
{
role: "user" | "assistant",
content: string
}
```
#### 示例调用
```json
{
"messages": [
{
"role": "user",
"content": "如何创建一个 MCP 服务器？"
},
{
"role": "assistant",
"content": "要创建 MCP 服务器，你需要..."
},
{
"role": "user",
"content": "能给我一个完整的例子吗？"
},
{
"role": "assistant",
"content": "当然可以！这里是一个完整的例子..."
}
],
"user_question": "创建 MCP 服务器教程",
"num_messages": 2
}
```
## 输出格式
笔记将保存在当前工作目录的 `notes` 文件夹中，格式如下：
```markdown
# [用户问题]
**Created:** [ISO 8601 时间戳]
---
## Question
[用户的问题]
## Answer
[AI 的回答（已清理）]
## Question
[第二个问题]
## Answer
[第二个回答]
```
## 文件命名规则
- 文件名基于用户问题的摘要
- 只保留字母、数字和中文字符
- 空格替换为下划线
- 限制长度为 50 字符
- 添加时间戳确保唯一性
示例：`创建MCP服务器教程_1696348800000.md`
## 自动清理内容
FlowNoter 会自动过滤以下内容：
- `<thinking>...</thinking>` - AI 的思考过程
- `<function_calls>...</function_calls>` - 函数调用记录
- `<function_results>...</function_results>` - 工具执行结果
- `<system_warning>...</system_warning>` - 系统警告信息
只保留最终的、给用户看的回答内容。
## 使用场景
1. **学习笔记**: 将与 AI 的技术讨论保存为学习资料
2. **项目文档**: 记录项目相关的问答和解决方案
3. **知识库**: 构建个人知识库和问题解答集
4. **回顾总结**: 方便回顾之前的对话内容
## 技术特性
- 使用 TypeScript 开发
- 基于 Model Context Protocol SDK
- 支持 stdio 传输协议
- 使用 Zod 进行参数验证
- 自动处理文件系统操作
## 开发
### 项目结构
```
flownoter/
├── src/
│ └── index.ts # 主服务器代码
├── dist/ # 编译输出
├── notes/ # 保存的笔记（运行时生成）
├── package.json
├── tsconfig.json
└── README.md
```
### 构建
```bash
npm run build
```
### 本地运行
```bash
npm start
```
## 故障排除
### 权限问题
确保 `dist/index.js` 文件有执行权限：
```bash
chmod +x dist/index.js
```
### notes 文件夹未创建
FlowNoter 会自动创建 `notes` 文件夹。如果遇到权限问题，请确保当前工作目录有写入权限。
### MCP 客户端连接问题
1. 检查配置文件路径是否正确
2. 确保已经运行 `npm run build`
3. 查看 MCP 客户端的日志输出
## 许可证
ISC
