使用说明

Markdown笔记MCP CLI

一个强大的命令行界面，用于使用MCP（模型上下文协议）和机器学习嵌入提供的高级语义搜索来管理和搜索markdown注释。

🚀 特性

语义搜索：使用人工智能相关性评分的自然语言查询查找笔记
问答：使用Google Gemini询问有关笔记的问题并获得人工智能生成的答案
笔记生成：根据提示或现有内容创建新笔记
多种输出格式：文本、JSON、表格、PDF、HTML和Markdown导出
自动标记：自动为新笔记生成相关标签
MCP服务器集成：已准备好与GitHub Copilot集成
高级统计：具有可定制时间段的全面分析
灵活出口：使用自定义文件名以多种格式导出搜索结果
稳健的错误处理：优雅的回退和全面的错误恢复
批量操作：高效处理多个笔记
高级搜索选项：阈值筛选、导出功能和自定义限制
后备系统：多种回退实现，实现最大可靠性
环境配置：通过环境变量进行自定义设置
综合测试：用于验证的内置测试脚本

📋 目录

安装
快速开始
命令
配置
例子
故障排除
测试
贡献
许可证

🔧 安装

先决条件

Python 3.8或更高版本
虚拟环境（推荐）

设置

克隆或导航到您的项目目录：

cd C:\Users\Devarshi\PycharmProjects\markdown-notes-mcp

创建并激活虚拟环境：

python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

安装依赖项：
```
pip install -r requirements.txt
```
验证安装：
```
python mcp_cli_fixed.py --help
```

🚀 快速开始

基本用法

# Search for notes
python mcp_cli_fixed.py search "machine learning" --limit 5

# Add a new note with auto-tagging
python mcp_cli_fixed.py add-note ./my_note.md --auto-tag

# Export search results as PDF
python mcp_cli_fixed.py export-search "PCA" --format pdf

# View weekly statistics
python mcp_cli_fixed.py stats --period week

# Start MCP server for Copilot integration
python mcp_cli_fixed.py server

# Ask questions about your notes
python mcp_cli_fixed.py qa "Explain PCA from my notes"

# Generate new notes
python mcp_cli_fixed.py generate-note "Web development best practices"

# Generate with reference
python mcp_cli_fixed.py generate-note "Advanced ML" --base-note ml_notes.md

高级用法

# Search with export functionality
python mcp_cli_fixed.py search "cloud computing" --export results.json --format json

# List notes in JSON format (fixed datetime serialization)
python mcp_cli_fixed.py list-notes --format json

# Rebuild index with custom settings
python mcp_cli_fixed.py rebuild-index --chunk-size 300 --overlap 100

# Start server with custom configuration
python mcp_cli_fixed.py server --host 0.0.0.0 --port 8080

📖 命令

搜索命令

使用带有高级选项的语义搜索来搜索您的降价笔记。

python mcp_cli_fixed.py search [OPTIONS] QUERY

选项：

--format {text,json,table}：输出格式（默认：文本）
--limit INTEGER：最大结果数（默认值：10）
--threshold FLOAT：最小相关性阈值（默认值：0.0）
--export PATH：将结果导出到JSON文件

示例：

# Basic search
python mcp_cli_fixed.py search "machine learning"

# Search with JSON output
python mcp_cli_fixed.py search "python data science" --format json --limit 5

# Search with table format and threshold
python mcp_cli_fixed.py search "algorithms" --format table --threshold 0.8

# Search and export results (NEW!)
python mcp_cli_fixed.py search "cloud computing" --export search_results.json --format json

添加注释命令

使用高级标记选项将新的标记注释添加到您的收藏中。

python mcp_cli_fixed.py add-note [OPTIONS] FILE

选项：

--auto-tag：自动为笔记生成标签
--rebuild：添加注释后重建搜索索引

示例：

# Add note without tags
python mcp_cli_fixed.py add-note ./my_note.md

# Add note with auto-tagging
python mcp_cli_fixed.py add-note ./research.md --auto-tag

# Add note and rebuild index
python mcp_cli_fixed.py add-note ./new_findings.md --auto-tag --rebuild

导出搜索命令

使用自定义输出路径以各种格式导出搜索结果。

python mcp_cli_fixed.py export-search [OPTIONS] QUERY

选项：

--format {pdf,html,markdown,json}：导出格式（默认：pdf）
--output PATH：输出文件路径
--limit INTEGER：要导出的最大结果数（默认值：20）

示例：

# Export as PDF
python mcp_cli_fixed.py export-search "machine learning" --format pdf

# Export as HTML with custom output
python mcp_cli_fixed.py export-search "web development" --format html --output web_guide.html

# Export as Markdown
python mcp_cli_fixed.py export-search "docker" --format markdown --output docker_guide.md

# Export as JSON with limit
python mcp_cli_fixed.py export-search "python" --format json --limit 15 --output python_topics.json

统计命令

查看多个时间段的综合系统统计数据。

python mcp_cli_fixed.py stats [OPTIONS]

选项：

--period {day,week,month,all}：统计时间段（默认值：周）
--format {text,json}：输出格式（默认：文本）

示例：

# Weekly statistics
python mcp_cli_fixed.py stats --period week

# Monthly statistics in JSON
python mcp_cli_fixed.py stats --period month --format json

# Daily statistics
python mcp_cli_fixed.py stats --period day

# All-time statistics
python mcp_cli_fixed.py stats --period all

列出注释命令

列出所有可用的注释，包括元数据和排序选项。

python mcp_cli_fixed.py list-notes [OPTIONS]

选项：

--sort {name,modified,size}：排序顺序（默认：名称）
--format {text,json}：输出格式（默认：文本）

示例：

# List notes sorted by name
python mcp_cli_fixed.py list-notes

# List notes sorted by modification date
python mcp_cli_fixed.py list-notes --sort modified

# List notes sorted by size
python mcp_cli_fixed.py list-notes --sort size

# List notes in JSON format (FIXED: datetime serialization)
python mcp_cli_fixed.py list-notes --format json

重建索引命令

使用高级配置选项重建搜索索引。

python mcp_cli_fixed.py rebuild-index [OPTIONS] [NOTES_ROOT]

选项：

--model TEXT：嵌入要使用的模型
--chunk-size INTEGER：文本块大小
--overlap INTEGER：块重叠大小
--force：即使文件未更改，也强制重建

示例：

# Basic rebuild
python mcp_cli_fixed.py rebuild-index

# Rebuild with different model
python mcp_cli_fixed.py rebuild-index --model all-mpnet-base-v2

# Rebuild with custom chunk settings (FIXED!)
python mcp_cli_fixed.py rebuild-index --chunk-size 300 --overlap 100

# Force rebuild
python mcp_cli_fixed.py rebuild-index --force

# Rebuild specific directory
python mcp_cli_fixed.py rebuild-index ./my_notes

服务器命令

启动MCP服务器以进行Copilot集成，并改进错误处理。

python mcp_cli_fixed.py server [OPTIONS]

选项：

--host TEXT：服务器主机（默认值：127.0.0.1）
--port INTEGER：服务器端口（默认值：8181）
--no-admin：禁用管理员HTTP接口

示例：

# Start server with defaults
python mcp_cli_fixed.py server

# Start server on custom port
python mcp_cli_fixed.py server --port 8080

# Start server on custom host
python mcp_cli_fixed.py server --host 0.0.0.0

# Start server without admin interface
python mcp_cli_fixed.py server --no-admin

# Start server with custom host and port
python mcp_cli_fixed.py server --host 0.0.0.0 --port 9090

QA命令（新增！）

使用人工智能问答功能询问有关笔记的问题。

python mcp_cli_fixed.py qa [OPTIONS] QUESTION

选项：

--limit INTEGER：最大上下文块（默认值：5）
--model TEXT：要使用的AI模型（默认值：gemini-1.5-pro）

示例：

# Ask a question
python mcp_cli_fixed.py qa "Explain PCA from my notes"

# Ask with more context
python mcp_cli_fixed.py qa "What are machine learning algorithms?" --limit 10

生成注释命令（新增！）

使用AI根据提示生成新笔记。

python mcp_cli_fixed.py generate-note [OPTIONS] PROMPT

选项：

--base-note PATH：使用现有注释作为参考
--output PATH：自定义输出文件名
--model TEXT：要使用的AI模型（默认值：gemini-1.5-pro）

示例：

# Generate a note
python mcp_cli_fixed.py generate-note "Web development best practices"

# Generate with reference
python mcp_cli_fixed.py generate-note "Advanced PCA" --base-note pca_notes.md

# Custom output
python mcp_cli_fixed.py generate-note "ML algorithms" --output ml_guide.md

⚙️ 配置

环境变量

使用环境变量自定义行为：

# Set embedding model
set MCP_MODEL_NAME=all-mpnet-base-v2

# Set chunk size for text processing
set MCP_CHUNK_SIZE=200

# Set chunk overlap
set MCP_OVERLAP=50

# Set environment
set MCP_ENVIRONMENT=production

配置文件

系统使用 config.py 用于高级配置。您可以修改：

嵌入模型设置
文本分块参数
索引和元数据的文件路径
服务器配置

后备系统

CLI包括多个回退系统，以实现最大可靠性：

MCP服务器回退：如果完全MCP不可用，则退回到简单实施
文本搜索回退：如果语义搜索失败，则使用基本文本匹配
出口回退：如果PDF/HTML生成失败，则返回文本格式
目录创建：如果缺少笔记目录，则自动创建笔记目录

📚 例子

完成工作流程

# 1. Setup and check system
python mcp_cli_fixed.py list-notes
python mcp_cli_fixed.py stats

# 2. Add new research notes
echo "# Machine Learning Research
Recent advances in neural networks and deep learning" > research.md
python mcp_cli_fixed.py add-note ./research.md --auto-tag --rebuild

# 3. Search and analyze
python mcp_cli_fixed.py search "neural networks" --format table --limit 5

# 4. Export findings
python mcp_cli_fixed.py export-search "deep learning" --format pdf --output ml_research.pdf

# 5. View statistics
python mcp_cli_fixed.py stats --period week --format json

# 6. Start server for Copilot
python mcp_cli_fixed.py server

批处理

# Add multiple notes
for file in ./new_notes/*.md; do
    python mcp_cli_fixed.py add-note "$file" --auto-tag
done

# Rebuild index after batch
python mcp_cli_fixed.py rebuild-index

# Export multiple searches
python mcp_cli_fixed.py export-search "machine learning" --format pdf --output ml.pdf
python mcp_cli_fixed.py export-search "web development" --format html --output web.html
python mcp_cli_fixed.py export-search "docker" --format markdown --output docker.md

高级搜索

# High-precision search
python mcp_cli_fixed.py search "machine learning algorithms" --threshold 0.8 --limit 10

# Export search with custom filename
python mcp_cli_fixed.py search "data science" --export ds_results.json --format json

# Search with table output
python mcp_cli_fixed.py search "python libraries" --format table --limit 8

环境配置

# Set custom model
set MCP_MODEL_NAME=all-mpnet-base-v2
set MCP_CHUNK_SIZE=300
set MCP_OVERLAP=100

# Test with new settings
python mcp_cli_fixed.py rebuild-index
python mcp_cli_fixed.py search "machine learning" --limit 5

🔧 故障排除

常见问题

1.导入错误：

# Check dependencies
pip install -r requirements.txt

# Verify Python path
python -c "import sys; print(sys.path)"

2.搜索不起作用：

# Rebuild index
python mcp_cli_fixed.py rebuild-index

# Check if notes directory exists
dir notes\*.md

3.JSON序列化错误（已修复！）：

# This now works automatically
python mcp_cli_fixed.py list-notes --format json

4.导出功能（新增！）：

# Export search results
python mcp_cli_fixed.py search "query" --export results.json --format json

5.服务器未启动：

# Check port availability
netstat -an | findstr :8181

# Try different port
python mcp_cli_fixed.py server --port 8080

6.重建索引问题（已修复！）：

# Now supports all arguments
python mcp_cli_fixed.py rebuild-index --chunk-size 300 --overlap 100

调试模式

启用调试输出以进行故障排除：

# Run with verbose output
python mcp_cli_fixed.py search "test" --limit 3

🧪 测试

测试脚本

运行全面测试以验证所有功能：

# Run all diagnostic tests
python debug_cli.py
python quick_fix.py
python test_cli_simple.py
python test_cli_fixes.py
python test_all_fixes.py
python final_test.py

测试单个组件

# Test CLI help
python mcp_cli_fixed.py --help

# Test basic functionality
python mcp_cli_fixed.py list-notes
python mcp_cli_fixed.py stats

# Test search
python mcp_cli_fixed.py search "test" --limit 3

# Test export
python mcp_cli_fixed.py search "test" --export test.json --format json

测试后备系统

# Test without MCP server (uses fallback)
python mcp_cli_fixed.py search "test" --limit 3

# Test with missing dependencies (graceful degradation)
python mcp_cli_fixed.py export-search "test" --format pdf

🤝 贡献

分叉存储库
创建要素分支： git checkout -b feature-name
进行更改
添加新功能的测试
运行测试： python -m pytest
提交您的更改： git commit -am 'Add new feature'
推到分支： git push origin feature-name
提交拉取请求

开发设置

# Clone repository
git clone https://github.com/your-repo/markdown-notes-mcp.git
cd markdown-notes-mcp

# Create development environment
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
python -m pytest

# Run linting
flake8 mcp_cli_fixed.py
black mcp_cli_fixed.py

📄 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

内置于句子变换器用于语义搜索
用途费斯用于高效的相似性搜索
PDF生成由报告实验室
表格格式制表
实施了稳健的错误处理和回退系统

📞 支持

有关支持和问题：

在GitHub上创建问题
检查上面的故障排除部分
查看常见用例的示例
运行测试脚本进行验证

使用人工智能搜索进行愉快的笔记记录！ 🚀📝

最后更新日期：2025年9月

🆕 最近的更新

2.1版功能

🤖 AI问答：就笔记提出自然语言问题
📝 AI笔记生成：根据提示或现有内容创建新笔记
🔄 谷歌Gemini集成：用于智能响应的先进人工智能模型
⚙️ 增强配置：全面的AI设置和模型选择
🛡️ 稳健的错误处理：AI功能的自动重试和回退系统
📊 上下文感知响应：智能检索相关笔记部分
🎯 基于参考的生成：使用现有注释作为新内容的上下文
⚡ 性能优化：高效使用API并进行速率限制处理

使用说明

Markdown笔记MCP CLI

🚀 特性

📋 目录

🔧 安装

先决条件

设置

🚀 快速开始

基本用法

高级用法

📖 命令

搜索命令

添加注释命令

导出搜索命令

统计命令

列出注释命令

重建索引命令

服务器命令

QA命令（新增！）

生成注释命令（新增！）

⚙️ 配置

环境变量

配置文件

后备系统

📚 例子

完成工作流程

批处理

高级搜索

环境配置

🔧 故障排除

常见问题

调试模式

最近修复

🧪 测试

测试脚本

测试单个组件

测试后备系统

🤝 贡献

开发设置

📄 许可证

🙏 致谢

📞 支持

🆕 最近的更新

2.1版功能

相关 MCP

AI持久记忆服务器

iOS/macOS 构建 MCP 服务器与命令行工具

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

Flomo笔记服务

小红书内容访问服务