🤖 Misonote MCP Client

AI 原生的文档管理系统 - 通过 MCP 协议将 Misonote Markdown 与 Cursor 编辑器深度集成，让 AI 成为您的智能文档助手

🌟 核心特性

• 🤖 AI 原生设计 - 专为 AI 编辑器优化的文档管理体验
• 📝 智能文档操作 - 创建、编辑、搜索文档，一切通过自然语言完成
• 🧠 记忆系统 - AI 记住您的习惯、偏好和项目经验
• 🔍 智能搜索 - 全文搜索，相关性排序，智能摘要
• 🔗 即时分享 - 自动生成在线访问链接
• ⚡ 即插即用 - 支持 Smithery.ai 一键安装

📋 功能详情

功能模块	描述	支持的操作
📝 文档管理	完整的文档生命周期管理	创建、读取、更新、删除、列表
🔍 智能搜索	全文搜索与智能排序	内容搜索、标题搜索、路径搜索
🧠 记忆系统	AI 个性化记忆存储	习惯、偏好、复盘、洞察
🔗 链接生成	自动生成分享链接	在线访问、即时分享
🛠️ 服务器管理	服务器状态与能力查询	健康检查、能力查询

🧠 记忆系统详解

记忆类型	用途	示例
habits	工作习惯记录	"我习惯使用 TypeScript 而不是 JavaScript"
preferences	技术偏好	"我偏好使用 Tailwind CSS 进行样式设计"
retrospectives	项目复盘	"这次重构学到了组件设计的重要性"
insights	学习洞察	"发现使用 React Query 能大幅简化状态管理"

依赖项目: 需要配合 misonote-markdown 文档服务器使用

🚀 快速开始

📦 安装方式

🌟 方式一：Smithery.ai（推荐）

一键安装，零配置！

1. 访问 Smithery.ai
2. 配置
3. 测试
4. 点击 "Install" 按钮
5. 自动配置完成，立即可用

📦 方式二：NPM 全局安装

npm install -g misonote-mcp

🛠️ 方式三：源码安装

git clone https://github.com/leeguooooo/misonote-mcp-client.git
cd misonote-mcp-client
npm install

⚙️ Cursor 配置

🌟 Smithery.ai 用户

无需配置！ 安装后自动生效。

📦 NPM 全局安装用户

在 Cursor 设置中添加：

{
  "mcpServers": {
    "misonote": {
      "command": "misonote-mcp",
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

🛠️ 源码安装用户

{
  "mcpServers": {
    "misonote": {
      "command": "node",
      "args": ["/path/to/misonote-mcp-client/misonote-mcp-client.js"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3000",
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

🔑 获取 API 密钥

在 Misonote Markdown 服务器管理界面中创建 API 密钥：

1. 启动服务器

   # 本地开发
   pnpm dev
   
   # 或 Docker 部署（设置管理员密码）
   docker run -p 3000:3000 -e ADMIN_PASSWORD=your_password leeguo/misonote-markdown

2. 访问管理界面

   • 打开浏览器访问：http://localhost:3000/admin
   • 使用管理员密码登录（Docker 默认：admin123）

3. 创建 API 密钥

   • 进入 "API 密钥管理" 页面
   • 点击 "创建新密钥" 按钮
   • 设置密钥名称（如：MCP Client）
   • 选择权限：建议选择 read, write, mcp 权限
   • 点击创建，复制生成的 API 密钥

4. 密钥格式

   • API 密钥格式：mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   • 请妥善保存，密钥只显示一次

重要: API 密钥现在完全通过管理界面创建，不再依赖环境变量。

🎯 使用示例

📝 创建文档

👤 用户: "帮我创建一个 Next.js 部署指南"
🤖 AI: 文档创建成功！
     📄 路径: deployment/nextjs-guide
     🔗 在线地址: http://localhost:3000/docs/deployment/nextjs-guide
     📖 点击地址即可查看文档

🔍 智能搜索

👤 用户: "搜索所有关于 Docker 的文档"
🤖 AI: 🔍 找到 3 个相关文档:
     
     1. **docker-deployment.md** - 相关性: 9/10
        📄 路径: deployment/docker-deployment
        🔗 在线地址: http://localhost:3000/docs/deployment/docker-deployment
        📝 摘要: Docker 容器化部署完整指南...
     
     2. **docker-compose.md** - 相关性: 8/10
        📄 路径: infrastructure/docker-compose
        🔗 在线地址: http://localhost:3000/docs/infrastructure/docker-compose

🧠 记录习惯

👤 用户: "我习惯使用 TypeScript 而不是 JavaScript"
🤖 AI: 🧠 已记录您的编程习惯！
     以后在代码示例中我会优先使用 TypeScript
     
👤 用户: "我偏好使用 Tailwind CSS 进行样式设计"
🤖 AI: 🎨 已记录您的技术偏好！
     在样式相关的建议中我会推荐 Tailwind CSS 方案

⚙️ 环境变量

变量名	描述	默认值	必需
MCP_SERVER_URL	Misonote 服务器地址	http://localhost:3000	✅
MCP_API_KEY	API 认证密钥	-	✅

🔧 API 工具列表

📝 文档操作

工具名	功能	参数
list_documents	获取文档列表	path?
get_document	获取文档内容	path
create_document	创建新文档	path, content, title?, metadata?
update_document	更新文档	path, content, title?, metadata?
delete_document	删除文档	path
search_documents	搜索文档	query, searchType?, path?
get_document_url	获取访问链接	path

🧠 记忆操作

工具名	功能	参数
add_memory	添加记忆	type, content, project?, tags?
get_memories	获取记忆	project?, type?
search_memories	搜索记忆	query, project?, type?
list_memory_projects	列出项目	-

🛠️ 服务器操作

工具名	功能	参数
get_server_info	获取服务器信息	-

🔗 相关链接

📦 安装平台

平台	链接	特点
Smithery.ai	misonote-mcp-client	🌟 一键安装，零配置
NPM	misonote-mcp	📦 全局安装，命令行使用
GitHub	misonote-mcp-client	🛠️ 源码安装，开发调试

🔗 相关项目

项目	链接	描述
Misonote Markdown	GitHub	📝 文档服务器主项目
Docker 镜像	Docker Hub	🐳 容器化部署

🛠️ 维护与更新

# 检查版本
npm info misonote-mcp version

# 检查更新
npm outdated -g misonote-mcp

# 更新到最新版本
npm update -g misonote-mcp

🐛 故障排除

常见问题

1. API Key 无效 (401 错误)

   • 检查 API Key 是否正确复制（完整的 64 位字符）
   • 确认 API Key 格式正确（以 mcp_ 开头）
   • 检查 API Key 是否已过期或被删除
   • 在管理界面重新创建 API Key

2. 权限不足 (403 错误)

   • 确认 API Key 具有 mcp 权限
   • 建议权限设置：read, write, mcp
   • 如需管理功能，添加 admin 权限

3. 连接失败 (ECONNREFUSED)

   • 检查 Misonote 服务器是否正在运行
   • 确认 MCP_SERVER_URL 地址和端口正确
   • 默认端口通常是 3000 或 3002

4. 找不到管理界面

   • 确认访问地址：http://localhost:3000/admin
   • 检查是否已创建管理员账号
   • 查看服务器启动日志获取正确端口

调试模式

MCP 客户端内置详细的错误处理和调试信息，出现问题时会显示：

• HTTP 状态码和错误信息
• 具体的解决建议
• 请求和响应的调试日志

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

---

🤖 让 AI 成为您的智能文档助手！