misonote-mcp
Version:
MCP (Model Context Protocol) client for Misonote Markdown documentation system - AI-native document management
296 lines (219 loc) • 9.6 kB
Markdown
# 🤖 Misonote MCP Client
[](https://www.npmjs.com/package/misonote-mcp)
[](https://www.npmjs.com/package/misonote-mcp)
[](https://smithery.ai/server/@leeguooooo/misonote-mcp-client)
[](https://opensource.org/licenses/MIT)
> **AI 原生的文档管理系统** - 通过 MCP 协议将 Misonote Markdown 与 Cursor 编辑器深度集成，让 AI 成为您的智能文档助手
## 🌟 核心特性
- **🤖 AI 原生设计** - 专为 AI 编辑器优化的文档管理体验
- **📝 智能文档操作** - 创建、编辑、搜索文档，一切通过自然语言完成
- **🧠 记忆系统** - AI 记住您的习惯、偏好和项目经验
- **🔍 智能搜索** - 全文搜索，相关性排序，智能摘要
- **🔗 即时分享** - 自动生成在线访问链接
- **⚡ 即插即用** - 支持 Smithery.ai 一键安装
## 📋 功能详情
| 功能模块 | 描述 | 支持的操作 |
|---------|------|-----------|
| **📝 文档管理** | 完整的文档生命周期管理 | 创建、读取、更新、删除、列表 |
| **🔍 智能搜索** | 全文搜索与智能排序 | 内容搜索、标题搜索、路径搜索 |
| **🧠 记忆系统** | AI 个性化记忆存储 | 习惯、偏好、复盘、洞察 |
| **🔗 链接生成** | 自动生成分享链接 | 在线访问、即时分享 |
| **🛠️ 服务器管理** | 服务器状态与能力查询 | 健康检查、能力查询 |
### 🧠 记忆系统详解
| 记忆类型 | 用途 | 示例 |
|---------|------|------|
| **habits** | 工作习惯记录 | "我习惯使用 TypeScript 而不是 JavaScript" |
| **preferences** | 技术偏好 | "我偏好使用 Tailwind CSS 进行样式设计" |
| **retrospectives** | 项目复盘 | "这次重构学到了组件设计的重要性" |
| **insights** | 学习洞察 | "发现使用 React Query 能大幅简化状态管理" |
> **依赖项目**: 需要配合 [misonote-markdown](https://github.com/leeguooooo/misonote-markdown) 文档服务器使用
## 🚀 快速开始
### 📦 安装方式
#### 🌟 方式一：Smithery.ai（推荐）
**一键安装，零配置！**
1. 访问 [Smithery.ai](https://smithery.ai/server/@leeguooooo/misonote-mcp-client)
2. 配置 
3. 测试 
4. 点击 "Install" 按钮
5. 自动配置完成，立即可用
#### 📦 方式二：NPM 全局安装
```bash
npm install -g misonote-mcp
```
#### 🛠️ 方式三：源码安装
```bash
git clone https://github.com/leeguooooo/misonote-mcp-client.git
cd misonote-mcp-client
npm install
```
### ⚙️ Cursor 配置
#### 🌟 Smithery.ai 用户
**无需配置！** 安装后自动生效。
#### 📦 NPM 全局安装用户
在 Cursor 设置中添加：
```json
{
"mcpServers": {
"misonote": {
"command": "misonote-mcp",
"env": {
"MCP_SERVER_URL": "http://localhost:3000",
"MCP_API_KEY": "your-api-key-here"
}
}
}
}
```
#### 🛠️ 源码安装用户
```json
{
"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. **启动服务器**
```bash
# 本地开发
pnpm dev
# 或 Docker 部署
docker run -p 3000:3000 leeguo/misonote-markdown
```
2. **访问管理界面**
- 打开浏览器访问：`http://localhost:3000/admin`
- 使用管理员账号登录
3. **创建 API 密钥**
- 进入 "API 密钥管理" 页面
- 点击 "创建新密钥" 按钮
- 设置密钥名称（如：`MCP Client`）
- 选择权限：建议选择 `read`, `write`, `mcp` 权限
- 点击创建，复制生成的 API 密钥
4. **密钥格式**
- API 密钥格式：`mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- 请妥善保存，密钥只显示一次
## 🎯 使用示例
### 📝 创建文档
```
👤 用户: "帮我创建一个 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](https://smithery.ai/server/@leeguooooo/misonote-mcp-client) | 🌟 一键安装，零配置 |
| **NPM** | [misonote-mcp](https://www.npmjs.com/package/misonote-mcp) | 📦 全局安装，命令行使用 |
| **GitHub** | [misonote-mcp-client](https://github.com/leeguooooo/misonote-mcp-client) | 🛠️ 源码安装，开发调试 |
### 🔗 相关项目
| 项目 | 链接 | 描述 |
|------|------|------|
| **Misonote Markdown** | [GitHub](https://github.com/leeguooooo/misonote-markdown) | 📝 文档服务器主项目 |
| **Docker 镜像** | [Docker Hub](https://hub.docker.com/r/leeguo/misonote-markdown) | 🐳 容器化部署 |
## 🛠️ 维护与更新
```bash
# 检查版本
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](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
---
<div align="center">
**🤖 让 AI 成为您的智能文档助手！**
[](https://smithery.ai/server/@leeguooooo/misonote-mcp-client)
[](https://www.npmjs.com/package/misonote-mcp)
</div>