TDZ C64 Knowledge
Summary: The TDZ C64 Knowledge server is an MCP-based knowledge base for Commodore 64 documentation, enabling ingestion, search, AI analysis, and visualization of C64-related content.
Ingest documents: Add PDFs, text, markdown, HTML, Excel, and web pages; bulk import; scrape URLs; rescrape and check for updates.
Search: Full-text (FTS5), semantic, hybrid, fuzzy, phrase, faceted, table/code search, and progressive refinement; also search within results, find similar docs, and get autocomplete suggestions.
AI-powered Q&A: Ask questions with RAG-based answers and citations (answer_question).
Entity & relationship analysis: Extract entities (hardware, addresses, instructions), map relationships, compare documents, and build knowledge graphs.
Temporal analysis: Extract events, build timelines, get historical context.
Topic modeling & clustering: Train LDA/NMF/BERTopic models, cluster documents (K-Means, DBSCAN, HDBSCAN), generate visualizations (wordclouds, heatmaps, scatter plots).
Graph analytics: Compute PageRank, centrality, community detection, find shortest paths, and visualize interactive knowledge graphs.
Management: List, update tags, remove documents, create/restore backups, export results and metadata.
Monitoring: Check updates, detect anomalies, view health and stats.
Visualization: Generate interactive HTML timelines, 3D knowledge graphs, Sankey diagrams, cluster scatter plots, and export a static wiki.
API: Expose REST API with Swagger docs and optional authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TDZ C64 Knowledge Search for VIC-II sprite registers and their memory addresses"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TDZ C64 Knowledge
MCP server for managing and searching Commodore 64 documentation. Ingest PDFs, text, Markdown, HTML, Excel, and web pages into a searchable knowledge base accessible via Claude Code or other MCP clients.
🚀 Quick Start
# 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"See QUICKSTART.md for detailed setup.
Related MCP server: ragi
Features
Search & Retrieval
FTS5 full-text search - 480x faster queries (50ms vs 24s)
Semantic search - Find by meaning, not keywords (e.g., "movable objects" → "sprites")
RAG question answering - Answer questions by synthesizing docs with citations
Fuzzy search - Typo tolerance ("VIC2" → "VIC-II", "asembly" → "assembly")
Progressive refinement - Search within results to narrow down
Hybrid search - Combines keyword + semantic with configurable weighting
Similarity search - Discover related documentation automatically
Query preprocessing - NLTK stemming and stopword removal
Smart tagging - AI-powered tag suggestions by category
Table/code search - Search extracted tables and code blocks
Document Management
Multi-format - PDF, TXT, MD, HTML, Excel, web scraping, and (optional
markitdownextra) DOCX, PPTX, EPUB, CSV, JSON, XML - install withpip install -e ".[markitdown]"; disable at runtime withTDZ_MARKITDOWN=0even when installed. PDF and ZIP (HVSC SID archives) never route through markitdown - seedocs/ARCHITECTURE.md's "Extending File Type Support" for why.Duplicate detection - Content-based deduplication
Chunked retrieval - Get specific sections without loading entire docs
Metadata extraction - Author, subject, page numbers
Persistent index - Documents stay indexed between sessions
AI-Powered Features
Entity extraction - Extract hardware, memory addresses, instructions, concepts (5000x faster with C64 regex patterns)
Relationship mapping - Co-occurrence analysis with distance-based strength scoring
Document comparison - Side-by-side analysis with similarity scores
Natural language query translation - Parse queries into structured search parameters
Anomaly detection - ML-based baseline learning for URL-sourced content (3400+ docs/second)
Temporal analysis - Event detection, timeline construction, historical context (5 event types, 8 date formats)
Advanced visualizations - 3D knowledge graphs, hierarchical bundling, Sankey flow diagrams
Wiki Export (NEW in v2.23.15)
Static HTML wiki - Export entire knowledge base to browsable website
Document similarity map - 2D visualization using UMAP/t-SNE dimensionality reduction
Interactive timeline - Horizontal scrollable timeline with zoom levels and event filters
Knowledge graph - D3.js force-directed graph (178 entities, 20 relationships)
Enhanced UI - Explanation boxes, prominent ASK AI button, file type detection
Clickable clusters - Browse k-means clusters with linked documents
No server required - Pure client-side JavaScript, works offline
Full-text search - Fuse.js powered search across all content
See WIKI_EXPORT_GUIDE.md for usage
REST API (Optional)
18 endpoints - Full CRUD, search, analytics, export
OpenAPI/Swagger docs - Interactive API at
/api/docsAPI authentication - Secure via X-API-Key header
See docs/REST_API.md for details
Performance
Scalability - Tested to 5,000+ documents
Concurrent throughput - 5,712 queries/sec (10 workers)
Lazy loading - 100k+ document support
Search caching - 50-100x speedup for repeated queries
Installation (Windows)
Prerequisites
Python 3.10+ - https://python.org (check "Add Python to PATH")
uv (recommended) or pip:
pip install uv
Setup
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 stopConfiguration
Claude Code
claude mcp add tdz-c64-knowledge -- C:\path\.venv\Scripts\python.exe C:\path\server.pyOr add to .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"
}
}
}
}Claude Desktop
Add to %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"
}
}
}
}Environment Variables
Variable | Description | Default |
| Database directory |
|
|
|
|
| Bind address for the HTTP transport |
|
| Port for the HTTP transport |
|
| Comma-separated API keys; shared with the REST API. Required to bind the HTTP transport off loopback | (unset) |
| Disables a refusal. |
|
|
| (unset) |
| Set to |
|
| Widens the path allowlist. |
|
| Disables a refusal. |
|
| Honour |
|
| User-Agent string sent on outbound scrapes |
|
| Base URL for DeepSID ingestion ( |
|
| SQLite busy-timeout, in ms, for WAL-mode concurrent server processes |
|
| Max seconds an ordinary MCP tool call may run before it is aborted; |
|
| Same bound, applied instead of |
|
| Max seconds a tool call waits to acquire the shared dispatch lock before giving up; |
|
| Seconds between progress notifications on a long-running tool call |
|
| Max seconds to wait for the sentence-transformers model to load on first semantic-search use before continuing in the background |
|
| Max seconds to wait for the lazy NLTK import/download before giving up |
|
| Console log level; |
|
| Recover interrupted extraction jobs found stale at startup. |
|
| Minutes since last update before an in-progress extraction job is considered stale and eligible for recovery |
|
| Max number of stale extraction jobs recovered per startup pass |
|
| Enable FTS5 search (recommended) |
|
| Enable semantic search |
|
| Sentence-transformers model |
|
| Enable BM25 fallback |
|
| Enable NLTK preprocessing |
|
| Enable fuzzy search |
|
| Fuzzy similarity (0-100) |
|
| Enable OCR for scanned PDFs |
|
| Tesseract exe or its directory, when not on PATH | (unset) |
| Max cached results |
|
| Cache TTL (seconds) |
|
| Document directory whitelist | None |
| Words per encoder window when building embeddings (0 = whole chunk, no windowing) |
|
| Word overlap between consecutive embedding windows |
|
| Token budget for |
|
|
|
|
| Rank-fusion damping constant for |
|
| Rerank hybrid/semantic results with a cross-encoder |
|
| Cross-encoder model for reranking |
|
| First-stage candidates fed to the reranker |
|
| Check |
|
| Max characters per cited source shown to the grounding check |
|
| Use a local NLI cross-encoder for claim verification instead of a second LLM call |
|
| Cross-encoder model for NLI-based claim verification |
|
| Max input tokens for the NLI model |
|
Search Features
FTS5 Full-Text Search (Recommended)
Enable with USE_FTS5=1 for maximum performance:
480x faster than BM25
Native SQLite BM25 ranking
Porter stemming tokenizer
Semantic Search
Enable with USE_SEMANTIC_SEARCH=1:
Meaning-based search (e.g., "movable objects" finds "sprites")
FAISS vector similarity with sentence-transformers
~7-16ms per query after embeddings built
Pre-build embeddings:
pip install sentence-transformers faiss-cpu
Phrase Search
Use double quotes for exact phrases:
search_docs(query='"VIC-II chip" registers')Fuzzy Search
Handles typos automatically with USE_FUZZY_SEARCH=1:
"VIC-I" → "VIC-II" (83% similarity)
"grafics" → "graphics" (88% similarity)
Configurable threshold (default: 80%)
OCR for Scanned PDFs
Automatic with USE_OCR=1:
Detects scanned PDFs (< 100 chars extracted)
Uses Tesseract OCR
Install:
pip install pytesseract pdf2image Pillow+ Tesseract binary~1-2 seconds per page
Temporal Analysis & Visualizations
Extract events, construct timelines, and visualize knowledge graphs.
Event Detection
Automatically detect significant events in documents:
5 Event Types - Product releases, company milestones, technical innovations, cultural events, version updates
8 Date Formats - Full dates, month-year, year ranges, decades, parenthetical dates
Confidence Scoring - Pattern matching with proximity-based confidence (0.0-1.0)
Entity Association - Automatically link entities to events
# Extract events from a document
result = kb.extract_document_events('doc_id', min_confidence=0.7)
# Returns: event_count, filtered_count, stored_count, events listTimeline Construction
Build chronological timelines with flexible querying:
Automatic Timeline Building - Chronologically sorted by date (YYYYMMDD integer sort)
Category Organization - Group by decade-type combinations (e.g., "1980s-release")
Importance Levels - 1-5 scale based on confidence
Date Range Filtering - Query events by year range, type, importance
# 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)Interactive Visualizations
Generate interactive HTML visualizations with Plotly and NetworkX:
Timeline Visualizations:
Interactive Timeline - Horizontal timeline with zoom/pan, color-coded by event type
Event Network - Spring layout showing event relationships
Trend Charts - Multi-subplot dashboard (bar chart, stacked area, cumulative line)
Advanced Graph Visualizations:
3D Knowledge Graph - Interactive 3D entity-relationship graph with rotation controls
Hierarchical Bundling - Circular layout with curved edges bundled through center
Sankey Diagrams - Topic flow over time (decade or year grouping)
# 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 Tools for Timeline
4 timeline-specific MCP tools:
extract_document_events- Extract and store events from documentsget_timeline- Query chronological timeline with filterssearch_events_by_date- Search events by date range and typeget_historical_context- Get events around a specific year
See PHASE3_TEMPORAL_ANALYSIS.md for complete documentation.
Tools
95 MCP tools organized by category. Key tools listed below.
Search Tools
search_docs - Full-text search
search_docs(query="SID register", max_results=5, tags=["sid"])semantic_search - Meaning-based search
semantic_search(query="How do sprites work?", max_results=5)hybrid_search - Combined keyword + semantic
hybrid_search(query="SID chip", semantic_weight=0.7, max_results=10)answer_question - RAG-based Q&A with citations
answer_question(
question="How do I program sprites on the VIC-II?",
max_sources=5,
search_mode="auto"
)search_figures - Search text OCR'd out of document figures
search_figures(query="raster interrupt", max_results=10)Finds content that exists only inside images - memory-map diagrams, register tables, pinout drawings - which plain document search cannot reach. Requires a figure-OCR pass first (see below).
Figure OCR Tools
Ingest-time OCR only runs on PDFs detected as entirely scanned. A normal text PDF gets its text layer indexed while its embedded figures are never read - and in C64 documentation those figures are often where the reference data actually lives. These tools run a background batch pass over PDFs already in the knowledge base, extracting each embedded image and OCRing it into searchable text stored separately from the document's own text.
batch_ocr_figures - Queue the whole knowledge base
batch_ocr_figures(limit=50, reprocess=false)Returns immediately; work proceeds on the background worker.
ocr_document_figures - Queue one document
ocr_document_figures(doc_id="89d0943d6009")figure_ocr_status - Coverage and pending-job report
figure_ocr_status()get_document_figures - List one document's figures with OCR text
get_document_figures(doc_id="89d0943d6009", with_text_only=true)Requires PyMuPDF, Tesseract, and USE_OCR=1. Note this path does not
need Poppler - it rasterizes with PyMuPDF rather than pdf2image, unlike the
scanned-page OCR fallback. figure_ocr_status reports exactly what is missing
if the feature is unavailable. If Tesseract is installed but not on PATH,
point TESSERACT_PATH at the executable or its directory. Tuning:
TDZ_FIGURE_MIN_WIDTH, TDZ_FIGURE_MIN_HEIGHT (ignore images too small to be
figures) and TDZ_FIGURE_MIN_CHARS (discard OCR noise).
By default only embedded images are read. Typeset manuals usually draw their
schematics, memory maps and timing diagrams as vector paths, which embed no
image at all - set TDZ_FIGURE_RASTERIZE_PAGES=1 to also render each page's
drawing regions (at TDZ_FIGURE_RASTER_DPI, default 200) and OCR those. Only
the clustered drawing regions are rendered, never the whole page: a full-page
render would OCR the body text a second time on top of what the PDF's own text
layer already contributed. Clusters covering more than
TDZ_FIGURE_RASTER_MAX_AREA (default 0.9) of the page are treated as borders
and skipped. Each row records its source (embedded or vector).
Rasterizing is much more expensive per page, so pair it with
TDZ_FIGURE_OCR_WORKERS (default 1): OCR blocks in a tesseract subprocess
rather than in Python, so a pool scales roughly with core count.
fuzzy_search - Typo-tolerant search
fuzzy_search(query="VIC2 asembly", similarity_threshold=80)search_within_results - Progressive refinement
# Broad search, then refine
results = search_docs(query="VIC-II", max_results=50)
refined = search_within_results(results, "sprite collision", max_results=5)find_similar - Find related documents
find_similar(doc_id="abc123", max_results=5)Document Management
add_document - Add a file
add_document(
filepath="C:/docs/c64_ref.pdf",
title="C64 Programmer's Reference",
tags=["reference", "memory-map"]
)add_documents_bulk - Bulk import
add_documents_bulk(
directory="C:/c64docs",
pattern="**/*.{pdf,txt}",
tags=["reference"],
recursive=true
)list_docs - List all documents
get_chunk - Get specific chunk
get_chunk(doc_id="abc123", chunk_id=5)remove_document - Remove a document
remove_documents_bulk - Bulk remove by IDs or tags
remove_documents_bulk(tags=["outdated"])check_updates - Check for file changes
check_updates(auto_update=false)URL Scraping
scrape_url - Scrape documentation website
scrape_url(
url="https://www.c64-wiki.com/wiki/VIC",
tags=["wiki"],
depth=2,
threads=5
)rescrape_document - Re-scrape for updates
rescrape_document(doc_id="abc123", force=false)check_url_updates - Check all scraped docs
check_url_updates(auto_rescrape=false, check_structure=true)AI & Analytics
extract_entities - Extract named entities
extract_entities(doc_id="abc123", confidence_threshold=0.6)search_entities - Search across entities
search_entities(query="VIC-II", entity_types=["hardware"])get_entity_analytics - Comprehensive entity statistics
extract_entity_relationships - Extract co-occurrences
extract_entity_relationships(doc_id="abc123", min_strength=0.3)search_entity_pair - Find docs with entity pair
search_entity_pair(entity1="VIC-II", entity2="sprite")compare_documents - Side-by-side comparison
compare_documents(doc_id_1="abc", doc_id_2="def", comparison_type="full")suggest_tags - AI-powered tag suggestions
suggest_tags(doc_id="abc123", confidence_threshold=0.6)get_tags_by_category - Browse tags by category
translate_query - Parse natural language queries
translate_query(query="find sprites on VIC-II chip")Export Tools
export_entities - Export to CSV/JSON
export_entities(format="csv", output_path="entities.csv", min_confidence=0.7)export_relationships - Export relationships
export_relationships(format="json", output_path="rels.json", min_strength=0.5)System
kb_stats - Knowledge base statistics
health_check - System diagnostics
Data Storage
SQLite database with 22 tables:
documents - Document metadata
chunks - Chunked content (1500 words, 200 overlap)
document_tables - Extracted PDF tables
document_code_blocks - Detected code blocks
document_entities - Extracted entities
entity_relationships - Co-occurrence tracking
Plus: summaries, extraction_jobs, monitoring_history, etc.
Benefits:
Lazy loading (metadata at startup, chunks on-demand)
ACID transactions
Scalable to 100k+ documents
FTS5 full-text indexes
Default location: ~/.tdz-c64-knowledge or TDZ_DATA_DIR
Usage Examples
Ask Claude Code:
"Search the C64 docs for SID voice registers"
"What does the memory map say about $D400?"
"Find information about sprite multiplexing"
"Add C:/docs/mapping_the_c64.pdf with tags memory-map, reference"
"How do I program raster interrupts on the VIC-II?" (uses RAG)
Suggested Tags
Organize docs with consistent tags:
reference,memory-map,basic,assemblysid,vic-ii,cia,kernalhardware,disk,graphics,sound
Troubleshooting
"pypdf not installed" - Run: pip install pypdf rank-bm25
"mcp module not found" - Run: pip install mcp
Server not responding - Use Python from virtual environment, not system Python
PDF extraction issues - Use OCR or add plain text version
BM25 issues - Check logs in TDZ_DATA_DIR/server.log, try USE_BM25=0
Development
Testing
pip install -e ".[dev]"
# Run all tests
pytest test_card_updates.py test_pdf_viewer.py -v
# With coverage
pytest test_card_updates.py -v --cov=server --cov-report=termTest Coverage:
test_card_updates.py- Card upsert/supersede semantics and chunk cleanup on removetest_pdf_viewer.py- PDF viewer support (requires PyMuPDF)
A larger suite (35 files) lives under archive/tests/ but is not currently wired into CI. CI
itself only runs test_card_updates.py; test_pdf_viewer.py is included above for local runs
but requires PyMuPDF (pip install -e ".[dev]" covers it).
CI/CD
GitHub Actions workflow tests on Python 3.10/3.11/3.12 across Windows/Linux/macOS with Ruff code quality checks.
Documentation
Core Documentation
README.md (this file) - Installation, features, tools, usage
QUICKSTART.md - Fast setup guide (5 minutes)
ARCHITECTURE.md - Technical deep dive, database schema, algorithms
CONTEXT.md - Project status, quick stats, version history
CLAUDE.md - Quick reference for Claude Code integration
CHANGELOG.md - Complete version history
Feature Documentation
Browse docs/ for detailed guides on specific features:
API & Integration:
REST API - FastAPI REST server (18 endpoints)
AI-Powered Features:
Entity Extraction - Extract hardware, memory addresses, instructions
Anomaly Detection - ML-based URL content monitoring
Summarization - AI-powered document summarization
Data Sources:
Web Scraping - Scrape documentation websites
Web Monitoring - Track URL-sourced content changes
Setup & Deployment:
Deployment Guide - Production deployment
Docker Setup - Docker configuration
Environment Setup - Environment variables
Poppler Setup - Poppler installation for PDFs
User Interfaces:
GUI Guide - Streamlit web interface
Development:
Testing Guide - Test suite and CI/CD
Examples - Usage examples and performance analysis
Monitoring Setup - Scheduled monitoring configuration
Roadmap - Future improvements and features
Version History
v2.23.0 - RAG Question Answering & Advanced Search (Phase 2 Complete)
RAG-based answer_question with citations
Fuzzy search with rapidfuzz
Progressive search refinement
Smart tagging system
v2.22.0 - Search Improvements (Phase 1 Complete)
Enhanced entity analytics
C64-specific regex patterns (5000x faster)
Performance optimizations
v2.21.0 - Anomaly Detection
ML-based baseline learning
1500x performance improvement
v2.18.0 - REST API & Background Processing
FastAPI REST server (18 endpoints)
Background entity extraction
v2.15.0+ - Entity Intelligence
Entity extraction, relationships, analytics
See CONTEXT.md for complete version history.
License
MIT License - Use freely for your retro computing projects!
Available Tools
83 toolsadd_documentC
Add a PDF or text file to the knowledge base.
Inputs: filepath (required), title, tags.
add_documents_bulkA
Add multiple documents from a directory at once. Supports glob patterns for file matching.
Inputs: directory (required), pattern, tags, recursive, +1 more.
analyze_graph_pagerankB
Calculate PageRank scores for entities in the knowledge graph. PageRank identifies the most 'important' or 'central' entities based on their connections. Higher scores indicate entities that are more connected and influential in the knowledge network.
Inputs: entity_types, min_occurrences, top_n, alpha.
answer_questionA
Answer questions about C64 documentation using RAG (Retrieval-Augmented Generation). Synthesizes information from multiple sources with citations. Returns answer text with source references and confidence score.
Inputs: question (required), max_sources, search_mode.
auto_tag_allA
Bulk auto-tag multiple documents using AI. Analyzes content and suggests relevant tags for all documents (or subset). Useful for initial organization or re-tagging collections. Can skip already-tagged documents and limit processing count. Requires LLM configuration.
Inputs: confidence_threshold, max_tags, append, skip_tagged, +1 more.
auto_tag_documentA
Automatically generate tags for a document using AI analysis. Analyzes document content and suggests relevant tags across categories: hardware (sid, vic-ii), programming (assembly, basic), document type (tutorial, reference), and difficulty level (beginner, advanced). Requires LLM configuration (set LLM_PROVIDER and API key).
Inputs: doc_id (required), confidence_threshold, max_tags, append.
build_knowledge_graphB
Build a knowledge graph from entities and relationships in the C64 knowledge base. The graph represents entities as nodes and their relationships as weighted edges. Use this to understand the structure of knowledge and find connections between concepts.
Inputs: entity_types, min_occurrences, min_relationship_strength.
calculate_graph_centralityA
Calculate centrality measures for entities in the knowledge graph. Returns betweenness, closeness, and degree centrality. These measures identify entities that bridge different parts of the graph, are close to all others, or have many connections.
Inputs: entity_types, min_occurrences, top_n.
check_updatesA
Check all indexed documents for updates. Detects files that have been modified since indexing and optionally re-indexes them automatically.
Inputs: auto_update.
check_url_updatesB
Check all URL-sourced documents for updates by comparing Last-Modified headers. Detects when source URLs have been modified since last scrape.
Inputs: auto_rescrape.
cluster_documents_dbscanA
Cluster documents using DBSCAN (density-based) algorithm. Automatically discovers clusters and identifies outliers. Does not require specifying number of clusters.
Inputs: eps, min_samples.
cluster_documents_hdbscanB
Cluster documents using HDBSCAN (hierarchical density-based) algorithm. Advanced clustering that handles varying densities. Automatically discovers clusters and outliers.
Inputs: min_cluster_size, min_samples.
cluster_documents_kmeansC
Cluster documents using K-Means algorithm on embeddings. Partitions documents into K clusters. Returns cluster assignments and silhouette score.
Inputs: num_clusters, random_state.
compare_documentsA
Compare two documents side-by-side with similarity scoring, metadata diff, content diff, and entity comparison. Perfect for finding differences between document versions, comparing related documents, or analyzing document similarity. Returns comprehensive comparison with cosine similarity score (0.0-1.0).
Inputs: doc_id_1 (required), doc_id_2 (required), comparison_type.
compute_graph_metricsA
Compute comprehensive graph analysis metrics including PageRank (importance), betweenness centrality (bridge nodes), degree centrality (connections), and community detection. Returns detailed metrics for all entities and graph-level statistics. Metrics are stored in the database for later retrieval.
Inputs: entity_types, min_occurrences, min_relationship_strength, store_results.
create_backupA
Create a backup of the knowledge base. Backs up database and embeddings to a zip file. Use this regularly for data safety and before making major changes.
Inputs: dest_dir (required), compress.
detect_anomaliesA
Detect anomalies in URL monitoring history. Analyzes patterns to identify unusual update frequencies, performance degradation, or unexpected content changes. Returns anomalies with severity scores (normal/minor/moderate/critical) based on learned baselines.
Inputs: min_severity, days.
detect_graph_communitiesB
Detect communities (clusters) in the knowledge graph. Communities are groups of entities that are more densely connected to each other than to the rest of the graph. This helps identify topic clusters and thematic groupings.
Inputs: entity_types, min_occurrences, algorithm.
entity_statsB
Get statistics about extracted entities in the knowledge base. Shows breakdown by type, top entities, and documents with most entities. Useful for understanding the knowledge base content.
Inputs: entity_type.
export_documents_bulkA
Export metadata for multiple documents in JSON, CSV, or Markdown format. Useful for creating reports, backups, or sharing document lists.
Inputs: doc_ids, tags, format.
export_entitiesA
Export all extracted entities to CSV or JSON format. Includes entity text, type, confidence scores, document counts, and occurrence counts. Useful for data analysis, reporting, or importing into other tools.
Inputs: format, entity_types, min_confidence, output_path.
export_relationshipsA
Export all entity relationships to CSV or JSON format. Includes entity pairs, types, relationship strength scores (0.0-1.0), and document counts. Perfect for network analysis, visualization, or data export.
Inputs: format, min_strength, entity_types, output_path.
export_resultsA
Export search results to various formats (markdown, json, html). Use this to save search results for offline use, sharing, or creating custom reference guides.
Inputs: results (required), format, query.
extract_document_eventsB
Extract temporal events from a document (product releases, company milestones, technical innovations, cultural events). Detects event patterns and dates, then stores to database.
Inputs: doc_id (required), min_confidence.
extract_entitiesA
Extract named entities from a C64 document using AI. Identifies hardware (SID, VIC-II, CIA, 6502), memory addresses ($D000), assembly instructions (LDA, STA), people, companies, products, and technical concepts. Returns entities with type, confidence score, and context. Requires LLM configuration.
Inputs: doc_id (required), confidence_threshold, force_regenerate.
extract_entities_bulkA
Bulk extract entities from multiple documents in the knowledge base. Processes documents in batch, skips documents that already have entities (unless force_regenerate). Returns statistics about processed documents and extracted entities.
Inputs: confidence_threshold, force_regenerate, max_docs, skip_existing.
extract_entity_relationshipsA
Extract co-occurrence relationships between entities in a document. Analyzes how entities appear together (e.g., VIC-II + raster interrupt, SID + sound programming). Returns entity pairs with relationship strength and context snippets.
Inputs: doc_id (required), min_confidence.
faceted_searchB
Search with faceted filtering. Filter results by hardware components (SID, VIC-II, CIA, etc.), assembly instructions (LDA, STA, etc.), or memory registers ($D000, etc.). Great for narrowing down search results to specific technical domains.
Inputs: query (required), facet_filters, max_results, tags.
find_by_referenceA
Find documents by cross-reference. Search for documents containing specific memory addresses ($D020), register offsets (VIC+0, SID+4), or page references (page 156). Great for tracking how specific registers or memory locations are documented.
Inputs: ref_type (required), ref_value (required), max_results.
find_entity_pathA
Find the shortest path between two entities in the knowledge graph. Shows how entities are connected through intermediate relationships. Useful for understanding conceptual connections and knowledge pathways.
Inputs: entity1 (required), entity2 (required), min_occurrences.
find_similarA
Find documents similar to a given document. Uses semantic embeddings if available, falls back to TF-IDF. Great for discovering related content.
Inputs: doc_id (required), chunk_id, max_results, tags.
fuzzy_searchB
Search with typo tolerance using fuzzy string matching. Handles misspellings and variations like 'VIC2' → 'VIC-II', 'asembly' → 'assembly', '6052' → '6502'. Returns exact matches first, then fuzzy matches if needed.
Inputs: query (required), max_results, tags, similarity_threshold.
generate_topic_heatmapA
Generate heatmap showing document-topic probability matrix. Visualizes which topics are most prominent in which documents.
Inputs: model_type (required), output_path (required), max_topics, max_documents.
generate_topic_wordcloudB
Generate word cloud visualization for a topic. Creates an image file showing the most important words in a topic with size proportional to their weights.
Inputs: topic_id (required), output_path (required), width, height, +1 more.
get_chunkA
Get the full content of a specific document chunk. Use after search_docs to read more context.
Inputs: doc_id (required), chunk_id (required).
get_cluster_documentsA
Get all documents in a specific cluster, including distances from centroid. Shows which documents are grouped together.
Inputs: cluster_id (required), algorithm, max_results.
get_documentB
Get the full content of a document by ID.
Inputs: doc_id (required).
get_document_topicsA
Get topics assigned to a specific document, including probabilities and top words for each topic. Shows which topics the document belongs to.
Inputs: doc_id (required), model_type.
get_entity_analyticsB
Get comprehensive entity analytics for dashboard visualization. Provides entity distribution by type, top entities by document count, relationship statistics, top entity relationships, and extraction timeline trends over time.
Inputs: time_range_days.
get_entity_communityA
Get all entities in the same community as the specified entity. Communities are groups of closely related entities detected through graph analysis. Returns community ID, member count, and list of community members with their types.
Inputs: entity_text (required), max_members.
get_entity_metricsA
Retrieve stored graph metrics for a specific entity. Returns PageRank score, betweenness centrality, degree centrality, community ID, entity type, and computation timestamp. Useful for understanding an entity's importance and role in the knowledge graph.
Inputs: entity_text (required), metric_types.
get_entity_relationshipsA
Get all entities related to a specific entity. Shows which other entities frequently co-occur with the target entity, sorted by relationship strength. Great for discovering related concepts, hardware, and techniques.
Inputs: entity_text (required), min_strength, max_results.
get_extraction_jobsA
Get all entity extraction jobs with optional status filtering. Shows job queue, running jobs, completed extractions, and failed jobs. Useful for monitoring background extraction progress across all documents.
Inputs: status_filter, limit.
get_extraction_statusA
Get the entity extraction status for a document. Shows whether entities exist, extraction job status (queued/running/completed/failed), timestamps, and error messages if any. Use this to check if extraction is complete before querying entities.
Inputs: doc_id (required).
get_graph_statisticsA
Get statistical overview of the knowledge graph including node count, edge count, density, connected components, and degree distribution. Provides insight into the overall structure and complexity of the knowledge network.
Inputs: entity_types, min_occurrences.
get_historical_contextA
Get historical context for a specific year. Returns events from the target year plus surrounding years to provide temporal context.
Inputs: year (required), context_years.
get_summaryA
Retrieve a cached summary of a document without regenerating it.
Inputs: doc_id (required), summary_type.
get_tags_by_categoryA
Browse all tags organized by category (hardware, programming, document-type, difficulty, custom). Shows tag usage count and sample documents. Useful for discovering and organizing content.
Inputs: no named parameters.
get_timelineB
Get chronological timeline of events with optional filtering. Returns timeline entries sorted by date with event details.
Inputs: start_year, end_year, category, min_importance, +1 more.
get_top_entitiesA
Get top-ranked entities by a specific metric (PageRank, betweenness, or degree centrality). Returns ranked list of entities with their scores, types, and other metrics. Useful for discovering the most important, central, or well-connected entities in the knowledge graph.
Inputs: metric, limit, entity_types.
health_checkA
Perform health check on the knowledge base system. Returns status, metrics, feature availability, and any issues detected.
Inputs: no named parameters.
hybrid_searchA
Perform hybrid search combining FTS5 keyword search and semantic search. Best of both worlds - finds exact keyword matches AND conceptually related content. Returns results ranked by weighted combination of both scores.
Inputs: query (required), max_results, tags, semantic_weight.
kb_statsC
Get statistics about the knowledge base.
Inputs: no named parameters.
list_docsA
List all documents in the C64 knowledge base.
Inputs: no named parameters.
list_entitiesB
List all entities extracted from a document, grouped by type (hardware, memory_address, instruction, person, company, product, concept). Great for getting an overview of what a document covers.
Inputs: doc_id (required), entity_types, min_confidence.
queue_entity_extractionA
Queue a document for background entity extraction. Extraction happens asynchronously without blocking. Use this to extract entities from documents without waiting for LLM processing. Returns job ID for tracking progress.
Inputs: doc_id (required), confidence_threshold, skip_if_exists.
remove_documentB
Remove a document from the knowledge base.
Inputs: doc_id (required).
remove_documents_bulkA
Remove multiple documents by IDs or tags. Useful for cleaning up the knowledge base.
Inputs: doc_ids, tags.
rescrape_documentA
Re-scrape a URL-sourced document to check for updates. Removes the old version and re-scrapes the original URL with the same configuration.
Inputs: doc_id (required).
restore_backupA
Restore knowledge base from a backup. WARNING: This will replace the current database. A safety backup is created automatically before restoration.
Inputs: backup_path (required), verify.
scrape_urlA
Scrape a documentation website and add all pages to the knowledge base. Supports recursive scraping of entire sites by following links. Great for ingesting online documentation like http://www.sidmusic.org/sid/. Converts HTML to searchable markdown.
Inputs: url (required), title, tags, follow_links, +7 more.
search_analyticsB
Get search analytics and insights. Shows popular queries, failed searches, search mode usage, and performance metrics.
Inputs: days, limit.
search_codeA
Search for code blocks in documents (BASIC, Assembly, Hex dumps). Finds programming examples and code snippets. Returns code with type (basic/assembly/hex), line count, and page numbers.
Inputs: query (required), max_results, block_type, tags.
search_docsB
Search the C64 knowledge base for information. Use this to find documentation about memory maps, opcodes, BASIC commands, SID, VIC-II, CIA chips, etc.
Inputs: query (required), max_results, tags.
search_entitiesC
Search for entities across all documents using full-text search. Find all documents mentioning specific hardware, addresses, instructions, people, companies, products, or concepts.
Inputs: query (required), entity_types, min_confidence, max_results.
search_entity_pairA
Find documents that contain both entities. Useful for finding documentation about specific combinations (e.g., 'VIC-II' AND 'raster interrupt'). Returns documents with both entity counts and context snippets.
Inputs: entity1 (required), entity2 (required), max_results.
search_events_by_dateA
Search for events within a date range. Filter by year range, event type (release, milestone, innovation, cultural, update), and confidence.
Inputs: start_year, end_year, event_type, min_confidence.
search_tablesA
Search for tables in PDF documents. Tables contain structured data like memory maps, register definitions, and command references. Returns tables in markdown format with page numbers.
Inputs: query (required), max_results, tags.
search_within_resultsA
Refine previous search results with an additional query. Useful for progressive search refinement: first search broadly (e.g., 'VIC-II'), then refine (e.g., 'sprite collision'). Returns filtered and re-ranked results from previous search set.
Inputs: previous_results (required), refinement_query (required), max_results.
semantic_searchA
Search the knowledge base using semantic/conceptual similarity (requires USE_SEMANTIC_SEARCH=1). Finds documents based on meaning, not just keywords. Example: searching for 'movable objects' can find 'sprites'.
Inputs: query (required), max_results, tags.
suggest_queriesA
Get autocomplete suggestions for partial queries. Suggests technical terms, memory addresses, instructions, and concepts based on indexed content. Great for discovering searchable content and learning proper terminology.
Inputs: partial (required), max_suggestions, category.
suggest_tagsB
Get tag suggestions for a document based on content analysis. Detects hardware components (SID, VIC-II, CIA), programming topics (assembly, BASIC, graphics), document types (reference, tutorial), and difficulty levels. Useful for organizing documents.
Inputs: doc_id (required), confidence_threshold.
summarize_allB
Bulk generate summaries for all documents in the knowledge base.
Inputs: summary_types, force_regenerate, max_docs.
summarize_documentA
Generate an AI-powered summary of a document. Supports brief (200-300 words), detailed (500-800 words), or bullet-point summaries.
Inputs: doc_id (required), summary_type, force_regenerate.
train_bertopicB
Train BERTopic model using document embeddings. State-of-the-art topic modeling with UMAP + HDBSCAN clustering. Automatically discovers topics from semantic embeddings.
Inputs: num_topics, min_cluster_size.
train_lda_topicsA
Train LDA (Latent Dirichlet Allocation) topic model on documents. Discovers latent topics using probabilistic modeling. Returns topics with top words and document assignments.
Inputs: num_topics, max_iter, random_state.
train_nmf_topicsA
Train NMF (Non-negative Matrix Factorization) topic model on documents. Often produces more coherent topics than LDA using matrix factorization. Returns topics with top words and document assignments.
Inputs: num_topics, max_iter, random_state.
translate_queryA
Translate a natural language query into structured search parameters. Uses AI to extract entities, keywords, and determine optimal search strategy. Perfect for conversational queries like 'find info about sprites on VIC-II' or 'how does sound work?'. Returns structured parameters that can be used directly with other search tools.
Inputs: query (required), confidence_threshold.
update_tags_bulkA
Update tags for multiple documents in bulk. Add, remove, or replace tags for documents selected by ID or existing tags. Useful for reorganizing and categorizing the knowledge base.
Inputs: doc_ids, existing_tags, add_tags, remove_tags, +1 more.
visualize_cluster_distributionB
Generate bar chart showing cluster size distribution. Shows how many documents are in each cluster.
Inputs: algorithm (required), output_path (required), width, height.
visualize_cluster_scatterB
Generate 2D scatter plot of document clusters using UMAP projection. Shows how documents are distributed across clusters in 2D space.
Inputs: algorithm (required), output_path (required), width, height, +2 more.
visualize_graphA
Generate interactive HTML visualization of the knowledge graph using PyVis. Creates a beautiful network diagram with customizable node colors (by entity type or community), node sizes (by PageRank/betweenness/degree), and interactive physics simulation. Perfect for exploring entity relationships and discovering patterns in the knowledge base.
Inputs: output_path, entity_types, min_occurrences, min_relationship_strength, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 83 tools
Most tools have clearly distinct purposes, with detailed descriptions that differentiate them. However, there is some overlap among multiple search and clustering methods, which could cause confusion if descriptions are not carefully read.
Tool names mix various patterns (verb_noun, noun_verb, phrases) and sometimes use inconsistent conventions (e.g., 'auto_tag_all' vs 'add_documents_bulk', 'search_docs' vs 'search_code'). No clear consistent naming pattern is followed.
With 83 tools, the server is excessively large for a knowledge base system. While each tool serves a specific function, the sheer number is overwhelming and suggests scope creep beyond core use cases.
The tool set covers virtually every aspect of knowledge base management: CRUD, search (multiple modes), entity extraction, graph analysis, topic modeling, clustering, backup/restore, and more. There are no obvious gaps in functionality.
Maintenance
Related MCP Connectors
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
MCP server for querying Forkast documentation
Related MCP Servers
- FlicenseAqualityDmaintenanceAn MCP server that indexes PDF documentation and text into Elasticsearch for semantic search and retrieval. It enables users to query knowledge bases, ingest new files, and dynamically update content through MCP-compatible clients like Claude Desktop and Cursor.41-
- AlicenseAqualityDmaintenanceLocal-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.36 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that indexes documents and serves relevant context to LLMs via Retrieval Augmented Generation (RAG).36MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for team documentation and knowledge bases, enabling semantic search over documentation files using local embeddings.MIT