Content
# 🤖 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 Native Document Management System** - Deeply integrates Misonote Markdown with the Cursor editor through the MCP protocol, making AI your intelligent document assistant.
## 🌟 Core Features
- **🤖 AI Native Design** - Document management experience optimized for AI editors.
- **📝 Intelligent Document Operations** - Create, edit, and search documents, all done through natural language.
- **🧠 Memory System** - AI remembers your habits, preferences, and project experiences.
- **🔍 Intelligent Search** - Full-text search, relevance ranking, and smart summaries.
- **🔗 Instant Sharing** - Automatically generates online access links.
- **⚡ Plug and Play** - Supports one-click installation via Smithery.ai.
## 📋 Feature Details
| Feature Module | Description | Supported Operations |
|----------------|-------------|----------------------|
| **📝 Document Management** | Complete document lifecycle management | Create, Read, Update, Delete, List |
| **🔍 Intelligent Search** | Full-text search and intelligent sorting | Content search, Title search, Path search |
| **🧠 Memory System** | AI personalized memory storage | Habits, Preferences, Retrospectives, Insights |
| **🔗 Link Generation** | Automatically generates sharing links | Online access, Instant sharing |
| **🛠️ Server Management** | Server status and capability queries | Health check, Capability query |
### 🧠 Memory System Explained
| Memory Type | Purpose | Example |
|--------------|---------|---------|
| **habits** | Work habit records | "I prefer using TypeScript instead of JavaScript." |
| **preferences** | Technical preferences | "I prefer using Tailwind CSS for styling." |
| **retrospectives** | Project retrospectives | "I learned the importance of component design during this refactor." |
| **insights** | Learning insights | "I found that using React Query can greatly simplify state management." |
> **Dependencies**: Requires the [misonote-markdown](https://github.com/leeguooooo/misonote-markdown) document server to function.
## 🚀 Quick Start
### 📦 Installation Methods
#### 🌟 Method 1: Smithery.ai (Recommended)
**One-click installation, zero configuration!**
1. Visit [Smithery.ai](https://smithery.ai/server/@leeguooooo/misonote-mcp-client)
2. Configure 
3. Test 
4. Click the "Install" button.
5. Automatic configuration is complete and ready to use.
#### 📦 Method 2: NPM Global Installation
```bash
npm install -g misonote-mcp
```
#### 🛠️ Method 3: Source Installation
```bash
git clone https://github.com/leeguooooo/misonote-mcp-client.git
cd misonote-mcp-client
npm install
```
### ⚙️ Cursor Configuration
#### 🌟 Smithery.ai Users
**No configuration needed!** It will take effect automatically after installation.
#### 📦 NPM Global Installation Users
Add the following in Cursor settings:
```json
{
"mcpServers": {
"misonote": {
"command": "misonote-mcp",
"env": {
"MCP_SERVER_URL": "http://localhost:3000",
"MCP_API_KEY": "your-api-key-here"
}
}
}
}
```
#### 🛠️ Source Installation Users
```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"
}
}
}
}
```
### 🔑 Obtaining API Key
Create an API key in the Misonote Markdown server management interface:
1. **Start the server**
```bash
# Local development
pnpm dev
# Or Docker deployment (set admin password)
docker run -p 3000:3000 -e ADMIN_PASSWORD=your_password leeguo/misonote-markdown
```
2. **Access the management interface**
- Open your browser and go to: `http://localhost:3000/admin`
- Log in with the admin password (default for Docker: admin123)
3. **Create an API key**
- Go to the "API Key Management" page.
- Click the "Create New Key" button.
- Set the key name (e.g., `MCP Client`).
- Choose permissions: it is recommended to select `read`, `write`, `mcp` permissions.
- Click create and copy the generated API key.
4. **Key Format**
- API key format: `mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
- Please keep it safe, as the key is displayed only once.
> **Important**: API keys are now created entirely through the management interface and no longer rely on environment variables.
## 🎯 Usage Examples
### 📝 Create Document
```
👤 User: "Help me create a Next.js deployment guide."
🤖 AI: Document created successfully!
📄 Path: deployment/nextjs-guide
🔗 Online Address: http://localhost:3000/docs/deployment/nextjs-guide
📖 Click the address to view the document.
```
### 🔍 Intelligent Search
```
👤 User: "Search for all documents about Docker."
🤖 AI: 🔍 Found 3 related documents:
1. **docker-deployment.md** - Relevance: 9/10
📄 Path: deployment/docker-deployment
🔗 Online Address: http://localhost:3000/docs/deployment/docker-deployment
📝 Summary: Complete guide to Docker container deployment...
2. **docker-compose.md** - Relevance: 8/10
📄 Path: infrastructure/docker-compose
🔗 Online Address: http://localhost:3000/docs/infrastructure/docker-compose
```
### 🧠 Record Habits
```
👤 User: "I prefer using TypeScript instead of JavaScript."
🤖 AI: 🧠 Your programming habit has been recorded!
I will prioritize using TypeScript in code examples from now on.
👤 User: "I prefer using Tailwind CSS for styling."
🤖 AI: 🎨 Your technical preference has been recorded!
I will recommend Tailwind CSS solutions in styling-related suggestions.
```
## ⚙️ Environment Variables
| Variable Name | Description | Default Value | Required |
|---------------|-------------|---------------|----------|
| `MCP_SERVER_URL` | Misonote server address | `http://localhost:3000` | ✅ |
| `MCP_API_KEY` | API authentication key | - | ✅ |
## 🔧 API Tool List
### 📝 Document Operations
| Tool Name | Function | Parameters |
|-----------|----------|------------|
| `list_documents` | Get document list | `path?` |
| `get_document` | Get document content | `path` |
| `create_document` | Create new document | `path`, `content`, `title?`, `metadata?` |
| `update_document` | Update document | `path`, `content`, `title?`, `metadata?` |
| `delete_document` | Delete document | `path` |
| `search_documents` | Search documents | `query`, `searchType?`, `path?` |
| `get_document_url` | Get access link | `path` |
### 🧠 Memory Operations
| Tool Name | Function | Parameters |
|-----------|----------|------------|
| `add_memory` | Add memory | `type`, `content`, `project?`, `tags?` |
| `get_memories` | Get memories | `project?`, `type?` |
| `search_memories` | Search memories | `query`, `project?`, `type?` |
| `list_memory_projects` | List projects | - |
### 🛠️ Server Operations
| Tool Name | Function | Parameters |
|-----------|----------|------------|
| `get_server_info` | Get server information | - |
## 🔗 Related Links
### 📦 Installation Platforms
| Platform | Link | Features |
|----------|------|----------|
| **Smithery.ai** | [misonote-mcp-client](https://smithery.ai/server/@leeguooooo/misonote-mcp-client) | 🌟 One-click installation, zero configuration |
| **NPM** | [misonote-mcp](https://www.npmjs.com/package/misonote-mcp) | 📦 Global installation, command line usage |
| **GitHub** | [misonote-mcp-client](https://github.com/leeguooooo/misonote-mcp-client) | 🛠️ Source installation, development debugging |
### 🔗 Related Projects
| Project | Link | Description |
|---------|------|-------------|
| **Misonote Markdown** | [GitHub](https://github.com/leeguooooo/misonote-markdown) | 📝 Main project for document server |
| **Docker Image** | [Docker Hub](https://hub.docker.com/r/leeguo/misonote-markdown) | 🐳 Containerized deployment |
## 🛠️ Maintenance and Updates
```bash
# Check version
npm info misonote-mcp version
# Check for updates
npm outdated -g misonote-mcp
# Update to the latest version
npm update -g misonote-mcp
```
## 🐛 Troubleshooting
### Common Issues
1. **Invalid API Key (401 Error)**
- Check if the API Key is copied correctly (full 64-character string).
- Ensure the API Key format is correct (starts with `mcp_`).
- Check if the API Key has expired or been deleted.
- Recreate the API Key in the management interface.
2. **Insufficient Permissions (403 Error)**
- Ensure the API Key has `mcp` permissions.
- Recommended permission settings: `read`, `write`, `mcp`.
- For management features, add `admin` permissions.
3. **Connection Failed (ECONNREFUSED)**
- Check if the Misonote server is running.
- Ensure the `MCP_SERVER_URL` address and port are correct.
- The default port is usually 3000 or 3002.
4. **Management Interface Not Found**
- Confirm the access address: `http://localhost:3000/admin`.
- Check if the admin account has been created.
- Review server startup logs for the correct port.
### Debug Mode
The MCP client has built-in detailed error handling and debugging information. When issues arise, it will display:
- HTTP status codes and error messages.
- Specific troubleshooting suggestions.
- Debug logs for requests and responses.
## 📄 License
MIT License - See [LICENSE](LICENSE) file for details.
## 🤝 Contribution Guidelines
Contributions are welcome! Please follow these steps:
1. Fork this repository.
2. Create a feature branch (`git checkout -b feature/amazing-feature`).
3. Commit your changes (`git commit -m 'Add amazing feature'`).
4. Push to the branch (`git push origin feature/amazing-feature`).
5. Open a Pull Request.
---
<div align="center">
**🤖 Let AI be your intelligent document assistant!**
[](https://smithery.ai/server/@leeguooooo/misonote-mcp-client)
[](https://www.npmjs.com/package/misonote-mcp)
</div>
