🤖 Misonote MCP Client

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

🌟 核心特性

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

📋 功能详情

🧠 记忆系统详解

依赖项目: 需要配合 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 方案

⚙️ 环境变量

🔧 API 工具列表

📝 文档操作

🧠 记忆操作

🛠️ 服务器操作

🔗 相关链接

📦 安装平台

🔗 相关项目

🛠️ 维护与更新

# 检查版本
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