社区笔记MCP服务器
用于查询和语义搜索社区笔记的模型上下文协议（MCP）服务器。该服务器提供对社区笔记数据的快速访问，支持按状态过滤（有用、无用、需要更多评级）和使用嵌入进行语义相似性搜索。
特性
- 快速查询性能：使用DuckDB进行高效的结构化查询
- 语义搜索：基于嵌入的相似性搜索，用于查找相关笔记
- 综合过滤：按状态、分类、推特ID等过滤
- 统计：深入了解社区笔记数据集
可用工具
1. query_notes
按各种条件查询社区笔记。
参数：
status（可选）：按当前价格、当前价格、NOT_HELPFUL或需求价格筛选classification（可选）：按分类类型筛选tweet_id（可选）：获取特定推文的注释limit（可选）：返回的最大结果数（默认值：10）
2. semantic_search
使用嵌入查找与查询短语含义相似的注释。
参数：
query（必填）：搜索短语limit（可选）：返回的最大结果数（默认值：10）status（可选）：按笔记状态筛选min_similarity（可选）：最小相似性得分0-1（默认值：0.0）
3. get_note_stats
获取有关笔记数据库的统计信息。
按状态、分类和其他指标返回计数。
4. get_note_by_id
通过ID检索特定笔记。
参数：
note_id（必填）：要检索的笔记ID
设置
快速安装（推荐）
运行自动安装脚本：
Linux/Mac：
./install.sh # Full install (all 2M records, 15-30 minutes)
./install.sh --demo # Demo mode (1000 records, 1-2 minutes)窗户：
install.bat # Full install (all 2M records, 15-30 minutes)
install.bat --demo # Demo mode (1000 records, 1-2 minutes)脚本将：
- 下载数据文件（如果不存在）
- 创建虚拟环境
- 安装所有依赖项
- 运行数据接收
- 提供配置说明
对于本地测试，请使用 --demo 模式，快速设置小数据集（1000条记录）。
手动安装
如果您更喜欢手动安装：
1.安装依赖项
pip install -r requirements.txt2.摄入数据
运行摄取脚本来处理TSV文件并生成嵌入：
python ingest_data.py这将：
- 创建DuckDB数据库(
community_notes.db) - 从加载笔记
data/notes-00000.tsv - 加载状态历史记录
data/noteStatusHistory-00000.tsv - 使用以下命令为所有笔记摘要生成嵌入
all-MiniLM-L6-v2模型
备注：摄取过程可能需要一些时间，具体取决于数据集的大小（2M+条记录）。嵌入以1000个为一批生成。
配置MCP客户端
将服务器添加到MCP客户端配置中。对于Claude Desktop，编辑您的配置文件：
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"community-notes": {
"command": "python",
"args": ["/path/to/CommunityNotesMCP/server.py"]
}
}
}备注：如果您使用了安装脚本，它将显示具有正确路径的确切配置。
重新启动Claude Desktop或MCP客户端以加载新服务器。
本地测试
要在连接到MCP客户端之前测试一切是否正常：
# Activate virtual environment
source venv/bin/activate # Linux/Mac
# or
venv\Scripts\activate.bat # Windows
# Run the test script
python test_mcp.py这将测试所有四个工具并显示示例输出，以验证服务器是否正常工作。
使用示例
按状态查询注释
Use the query_notes tool to find 5 helpful community notes语义搜索
Use semantic_search to find notes about "election misinformation"获取统计信息
Use get_note_stats to show me statistics about the community notes dataset获取特定注释
Use get_note_by_id to retrieve note 1783179305159200982数据库模式
notes 表格
noteId：唯一钞票标识符tweetId：关联的推特IDsummary：注释文本内容classification：注释分类类型summary_embedding：384维嵌入向量- 各种误导性/非误导性标志
- 元数据字段
note_status_history 表格
noteId：指向笔记表的链接currentStatus：当前评级状态currentDecidedBy：决定状态的模型- 用于状态更改的各种时间戳字段
技术细节
- 数据库：DuckDB（嵌入式快速分析查询）
- 嵌入：句子转换器
all-MiniLM-L6-v2型号（384个维度） - 相似性：用于语义匹配的余弦相似度
- 演出：索引查询，嵌入的批处理
数据源
此服务器需要两个TSV文件 data/ 目录：
notes-00000.tsv：附有摘要和分类的社区说明noteStatusHistory-00000.tsv：状态评级（有用/无用/需要更多评级）
发展
要修改嵌入模型，请编辑 ingest_data.py 并更改 model_name 参数。流行的替代方案：
all-MiniLM-L6-v2（默认，384调光，快速）all-mpnet-base-v2（768调暗，更准确，更慢）paraphrase-multilingual-MiniLM-L12-v2（多语言支持）
故障排除
“找不到数据库”错误
跑 python ingest_data.py 首先创建数据库。
语义搜索速度慢
- 减小数据集大小或限制查询结果
- 考虑使用较小的嵌入模型
- 语义搜索前按状态预过滤
摄入过程中内存不足
- 减小batch_size
ingest_data.py - 分块处理笔记
- 使用较小的嵌入模型