TDZ C64知识
用于管理和搜索Commodore 64文档的MCP服务器。将PDF、文本、Markdown、HTML、Excel和网页摄取到可通过Claude Code或其他MCP客户端访问的可搜索知识库中。
🚀 快速开始
# 1. Install
python -m venv .venv
.venv\Scripts\activate
pip install -e .
# 2. Configure Claude Code
claude mcp add tdz-c64-knowledge -- .venv\Scripts\python.exe server.py
# 3. Add documents
.venv\Scripts\python.exe cli.py add-folder "C:\c64docs" --tags reference --recursive
# 4. Search via Claude Code
# Ask: "Search the C64 docs for VIC-II sprite registers"看 QUICKSTART.md 详细设置。
特性
搜索与检索
- FTS5全文搜索 -查询速度提高480倍（50毫秒对比24秒）
- 语义搜索 -按含义而非关键字查找（例如，“可移动对象”→ “精灵”）
- RAG问答 -通过综合引用文档来回答问题
- 模糊搜索 -打字错误容忍度（“VIC2”→ “VIC-II”、“asembley”→ “组装”）
- 逐步求精 -在结果中搜索以缩小范围
- 混合搜索 -将关键字+语义与可配置权重相结合
- 相似性搜索 -自动发现相关文档
- 查询预处理 -NLTK堵塞和停用词删除
- 智能标记 -按类别提供人工智能标签建议
- 表/代码搜索 -搜索提取的表和代码块
文档管理
- 多格式 -PDF、TXT、MD、HTML、Excel、网页抓取
- 重复检测 -基于内容的重复数据消除
- 分块检索 -获取特定部分而不加载整个文档
- 元数据提取 -作者、主题、页码
- 持久索引 -文档在会话之间保持索引
AI驱动的功能
- 实体提取 -提取硬件、内存地址、指令、概念（使用C64正则表达式模式速度提高5000倍）
- 关系映射 -基于距离的强度评分共现分析
- 文件比较 -基于相似性得分的并排分析
- 自然语言查询翻译 -将查询解析为结构化搜索参数
- 异常检测 -基于机器学习的URL源内容基线学习（3400+文档/秒）
- 时间分析 -事件检测、时间线构建、历史背景（5种事件类型，8种日期格式）
- 高级可视化 -3D知识图、层次捆绑、Sankey流程图
Wiki导出（v2.23.15新增）
- 静态HTML维基 -将整个知识库导出到可浏览的网站
- 文档相似性图 -基于UMAP/t-SNE降维的二维可视化
- 交互式时间线 -带有缩放级别和事件过滤器的水平可滚动时间线
- 知识图谱 -D3.js力有向图（178个实体，20个关系）
- 增强的用户界面 -说明框、突出的ASK AI按钮、文件类型检测
- 可点击的集群 -浏览带有链接文档的k-means聚类
- 无需服务器 -纯客户端JavaScript，离线工作
- 全文搜索 -Fuse.js支持所有内容的搜索
- 看 WIKI_EXPORT_GUIDE.md 供使用
REST API（可选）
- 27个端点 -完整的CRUD、搜索、分析、导出
- OpenAPI/Swagger文档 -交互式API
/api/docs - API认证 -通过X-API-Key头进行安全
- 看 docs/REST_API.md文件 详情
演出
- 可扩展性 -对5000多份文档进行了测试
- 并发吞吐量 -5712次查询/秒（10名工人）
- 延迟加载 -100k+文档支持
- 搜索缓存 -重复查询速度提高50-100倍
安装（Windows）
先决条件
- Python 3.10+ - https://python.org（勾选“将Python添加到PATH”）
- 紫外线 （推荐）或pip：
pip install uv
设置
cd C:\Users\YourName\mcp-servers\tdz-c64-knowledge
# Using uv (faster)
uv venv
.venv\Scripts\activate
uv pip install mcp pypdf rank-bm25 nltk
# Or using pip
python -m venv .venv
.venv\Scripts\activate
pip install mcp pypdf rank-bm25 nltk
# Test
python server.py # Press Ctrl+C to stop配置
克劳德代码
claude mcp add tdz-c64-knowledge -- C:\path\.venv\Scripts\python.exe C:\path\server.py或添加到 .claude/settings.json:
{
"mcpServers": {
"tdz-c64-knowledge": {
"command": "C:\\path\\.venv\\Scripts\\python.exe",
"args": ["C:\\path\\server.py"],
"env": {
"TDZ_DATA_DIR": "C:\\c64-knowledge-data"
}
}
}
}克劳德桌面
添加到 %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"tdz-c64-knowledge": {
"command": "C:\\path\\.venv\\Scripts\\python.exe",
"args": ["C:\\path\\server.py"],
"env": {
"TDZ_DATA_DIR": "C:\\c64-knowledge-data"
}
}
}
}环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
TDZ_DATA_DIR | 数据库目录 | ~/.tdz-c64-knowledge |
USE_FTS5 | 启用FTS5搜索（推荐） | 0 |
USE_SEMANTIC_SEARCH | 启用语义搜索 | 0 |
SEMANTIC_MODEL | 句子转换模型 | all-MiniLM-L6-v2 |
USE_BM25 | 启用BM25回退 | 1 |
USE_QUERY_PREPROCESSING | 启用NLTK预处理 | 1 |
USE_FUZZY_SEARCH | 启用模糊搜索 | 1 |
FUZZY_THRESHOLD | 模糊相似性（0-100） | 80 |
USE_OCR | 为扫描的PDF启用OCR | 1 |
SEARCH_CACHE_SIZE | 最大缓存结果 | 100 |
SEARCH_CACHE_TTL | 缓存TTL（秒） | 300 |
ALLOWED_DOCS_DIRS | 文档目录白名单 | 无 |
搜索功能
FTS5全文搜索（推荐）
启用 USE_FTS5=1 为了获得最佳性能：
- 速度提高480倍 比BM25
- 原生SQLite BM25排名
- 波特词干标记器
语义搜索
启用 USE_SEMANTIC_SEARCH=1:
- 基于意义的搜索（例如，“可移动对象”找到“精灵”）
- 使用句子变换器的FAISS向量相似性
- 嵌入构建后，每个查询约7-16ms
- 预构建嵌入：
pip install sentence-transformers faiss-cpu
短语搜索
精确短语使用双引号：
search_docs(query='"VIC-II chip" registers')模糊搜索
自动处理拼写错误 USE_FUZZY_SEARCH=1:
- “VIC-I”→ “VIC-II”（83%相似性）
- “涂鸦”→ “图形”（88%相似性）
- 可配置阈值（默认值：80%）
用于扫描PDF的OCR
自动带 USE_OCR=1:
- 检测扫描的PDF（提取的字符数小于100）
- 使用Tesseract OCR
- 安装：
pip install pytesseract pdf2image Pillow+Tesseract二进制 - 每页约1-2秒
时间分析和可视化
提取事件、构建时间线并可视化知识图。
事件检测
自动检测文档中的重要事件：
- 5事件类型 -产品发布、公司里程碑、技术创新、文化活动、版本更新
- 8日期格式 -完整日期、月-年、年范围、十年、括号中的日期
- 信心评分 -基于邻近度的置信度模式匹配（0.0-1.0）
- 实体协会 -自动将实体链接到事件
# Extract events from a document
result = kb.extract_document_events('doc_id', min_confidence=0.7)
# Returns: event_count, filtered_count, stored_count, events list时间线构建
通过灵活的查询构建按时间顺序排列的时间线：
- 自动时间线构建 -按日期按时间顺序排序（YYYYMMDD整数排序）
- 类别式组织 -按十年类型组合分组（例如“20世纪80年代发布”）
- 重要性级别 -基于置信度的1-5分制
- 日期范围筛选 -按年份范围、类型、重要性查询事件
# Build timeline from events
timeline_result = kb.build_timeline(min_confidence=0.5)
# Query timeline
timeline = kb.get_timeline(start_year=1980, end_year=1989, min_importance=3)
# Get historical context
context = kb.get_historical_context(year=1982, context_years=2)交互式可视化
使用Plotly和NetworkX生成交互式HTML可视化：
时间线可视化：
- 交互式时间线 -具有缩放/平移功能的水平时间线，按事件类型进行颜色编码
- 事件网络 -显示事件关系的春季布局
- 趋势图 -多个子地块仪表板（条形图、堆叠面积、累积线）
高级图形可视化：
- 3D知识图谱 -带有旋转控件的交互式三维实体关系图
- 分层捆绑 -圆形布局，弯曲边缘穿过中心
- 桑基图 -主题随时间变化（按十年或年份分组）
# Generate visualizations
kb.visualize_timeline(start_year=1980, end_year=1990, output_path="timeline.html")
kb.visualize_knowledge_graph_3d(max_entities=50, output_path="graph_3d.html")
kb.visualize_hierarchical_bundling(max_entities=30, output_path="bundling.html")
kb.visualize_topic_flow_sankey(time_period='decade', output_path="flow.html")MCP时间线工具
4个特定于时间线的MCP工具：
extract_document_events-从文档中提取和存储事件get_timeline-使用过滤器查询按时间顺序排列的时间线search_events_by_date-按日期范围和类型搜索事件get_historical_context-获取特定年份的活动
看 阶段3_TEMPORAL_ANALYSIS.md 以获取完整的文档。
工具
按类别组织的62个MCP工具。下面列出的关键工具。
搜索工具
search_docs -全文搜索
search_docs(query="SID register", max_results=5, tags=["sid"])语义研究 -基于意义的搜索
semantic_search(query="How do sprites work?", max_results=5)混合搜索 -组合关键字+语义
hybrid_search(query="SID chip", semantic_weight=0.7, max_results=10)answer_问题 -基于RAG的问答与引用
answer_question(
question="How do I program sprites on the VIC-II?",
max_sources=5,
search_mode="auto"
)模糊搜索 -拼写错误容忍搜索
fuzzy_search(query="VIC2 asembly", similarity_threshold=80)搜索结果 -逐步完善
# Broad search, then refine
results = search_docs(query="VIC-II", max_results=50)
refined = search_within_results(results, "sprite collision", max_results=5)find_类似物 -查找相关文档
find_similar(doc_id="abc123", max_results=5)文档管理
add_document -添加文件
add_document(
filepath="C:/docs/c64_ref.pdf",
title="C64 Programmer's Reference",
tags=["reference", "memory-map"]
)add_documents_bulk -批量进口
add_documents_bulk(
directory="C:/c64docs",
pattern="**/*.{pdf,txt}",
tags=["reference"],
recursive=true
)list_docs -列出所有文件
get_chunk -获取特定块
get_chunk(doc_id="abc123", chunk_id=5)remove_document -删除文档
remove_documents_bulk -按ID或标签批量删除
remove_documents_bulk(tags=["outdated"])check_updates -检查文件更改
check_updates(auto_update=false)URL抓取
scrape_url -报废文件网站
scrape_url(
url="https://www.c64-wiki.com/wiki/VIC",
tags=["wiki"],
depth=2,
threads=5
)重新扫描_文档 -重新抓取以获取更新
rescrape_document(doc_id="abc123", force=false)check_url_updates -检查所有报废文档
check_url_updates(auto_rescrape=false, check_structure=true)人工智能与分析
提取物 -提取命名实体
extract_entities(doc_id="abc123", confidence_threshold=0.6)search_entities -跨实体搜索
search_entities(query="VIC-II", entity_types=["hardware"])get_entity_analytics -综合实体统计
提取-细节关系 -提取共现
extract_entity_relationships(doc_id="abc123", min_strength=0.3)search_entity_pair -查找具有实体对的文档
search_entity_pair(entity1="VIC-II", entity2="sprite")比较文档 -并排比较
compare_documents(doc_id_1="abc", doc_id_2="def", comparison_type="full")建议标签 -基于AI的标签建议
suggest_tags(doc_id="abc123", confidence_threshold=0.6)get_tags_by_category -按类别浏览标签
translatequery -解析自然语言查询
translate_query(query="find sprites on VIC-II chip")导出工具
出口地点 -导出为CSV/JSON
export_entities(format="csv", output_path="entities.csv", min_confidence=0.7)出口关系 -出口关系
export_relationships(format="json", output_path="rels.json", min_strength=0.5)系统
kb_stats -知识库统计
健康检查 -系统诊断
数据存储
包含12个以上表的SQLite数据库：
- 文件 -文档元数据
- 块 -分块内容（1500字，200个重叠）
- document_tables -提取的PDF表格
- 文档代码块 -检测到的代码块
- 文档_时间 -提取实体
- 实体关系 -共现追踪
- 加上：摘要、摘录、监控历史等。
优点：
- 延迟加载（启动时加载元数据，按需加载块）
- ACID事务
- 可扩展到100000多个文档
- FTS5全文索引
默认位置： ~/.tdz-c64-knowledge 或 TDZ_DATA_DIR
使用示例
询问克劳德代码：
- “在C64文档中搜索SID语音寄存器”
- “内存映射对400美元有什么看法？”
- “查找有关精灵多路复用的信息”
- “添加C:/docs/mapping_the_c64.pdf，并标记内存映射、引用”
- “如何在VIC-II上编程光栅中断？”（使用RAG）
建议标签
使用一致的标签组织文档：
reference,memory-map,basic,assemblysid,vic-ii,cia,kernalhardware,disk,graphics,sound
故障排除
“未安装pypdf” -运行： pip install pypdf rank-bm25
“找不到mcp模块” -运行： pip install mcp
服务器未响应 -从虚拟环境中使用Python，而不是系统Python
PDF提取问题 -使用OCR或添加纯文本版本
BM25问题 -检查登录 TDZ_DATA_DIR/server.log，试试看 USE_BM25=0
发展
测试
pip install -e ".[dev]"
# Run all tests
pytest test_server.py test_wiki_export.py -v
# With coverage
pytest test_server.py -v --cov=server --cov-report=term
# Wiki export tests only
pytest test_wiki_export.py -v测试覆盖范围：
test_server.py-核心服务器功能（搜索、实体、RAG等）test_wiki_export.py-Wiki生成功能（16个测试）：
- 文档坐标导出（UMAP/t-SNE） - 文件类型检测（HTML/MD） - 集群文档导出 - 带解释框的HTML生成 - 用于交互式功能的JavaScript生成
CI/CD
GitHub Actions在Windows/Linux/macOS上对Python 3.10/3.11/3.12进行工作流测试，并进行Ruff代码质量检查。
文档
核心文件
- README.md （此文件）-安装、功能、工具、用法
- QUICKSTART.md -快速设置指南（5分钟）
- 建筑.md -技术深度挖掘、数据库模式、算法
- 内容.md -项目状态、快速统计数据、版本历史
- CLAUDE.md -Claude代码集成快速参考
- 更改日志.md -完整的版本历史记录
功能文档
浏览 docs/ 有关特定功能的详细指南：
API与集成：
- REST API -FastAPI REST服务器（27个端点）
AI驱动的功能：
数据来源：
设置和部署：
用户界面：
- GUI指南 -流线型网络界面
发展：
版本历史
v2.23.0 -RAG问答和高级搜索（第2阶段完成）
- 基于RAG的答案_带引用的问题
- 基于快速模糊的模糊搜索
- 渐进式搜索优化
- 智能标签系统
v2.22.0 -搜索改进（第一阶段完成）
- 增强的实体分析
- C64特定正则表达式模式（速度快5000倍）
- 性能优化
v2.21.0 -异常检测
- 基于机器学习的基线学习
- 性能提升1500倍
v2.18.0 -REST API和后台处理
- FastAPI REST服务器（27个端点）
- 背景实体提取
v2.15.0+ -实体情报
- 实体提取、关系、分析
有关完整的版本历史记录，请参阅CONTEXT.md。
许可证
MIT许可证-免费用于您的逆向计算项目！