TDZ C64 Knowledge

You run a self-contained MCP server that ingests Commodore 64 documentation from PDFs, text, Markdown, HTML, Excel, and web pages, builds a searchable knowledge base, and lets you query it via MCP clients like Claude Code. It supports fast full-text search, semantic search, RAG-style Q&A with citations, and rich document management features so you can explore, compare, and visualize C64 information efficiently.

How to use

You connect your MCP client to the TDZ C64 Knowledge server and perform three core workflows: ingest documents, index and search the knowledge base, and pose questions that the system answers with citations.

Ingest documents through the provided command-line interface from your local file system or web-scraped sources. After ingestion, the server processes content into chunks, extracts entities, and builds search indexes so you can retrieve precise information quickly.

When you search, you can use fast full-text search, semantic search for meaning-based results, and a hybrid mode that blends keyword and semantic signals. For complex questions, ask using natural language and request citations to the relevant sources.

How to install

# Prerequisites
# 1) Install Python 3.10+ and ensure Python is on PATH

# 2) Create a virtual environment and install the MCP locally
python -m venv .venv
.venv\Scripts\activate
pip install -e .

# Optional but recommended: install OCR and extra tools when you need PDF OCR
# Example for Windows with OCR enabled at runtime:
pip install pytesseract pdf2image Pillow

After installation, you will configure the MCP client to connect to the server and then run the server from your environment.

# Start the server (windows paths shown as in examples)
.venv\Scripts\python.exe server.py

Configuration and deployment notes

If you use Claude Code or Claude Desktop as your MCP client, you configure the MCP connection by specifying the Python runtime and the server script, along with an environment variable that defines the data directory.

Environment variables you may use include TDZ_DATA_DIR to designate the database directory and various flags to enable or tune features such as FTS5, semantic search, and fuzzy search.

Troubleshooting and tips

If you encounter missing Python components, install the required packages (for example, pypdf, rank-bm25, nltk) and ensure you are using the virtual environment’s Python. If the server does not respond, verify you started the process from within the active virtual environment.

For PDF extraction issues, enable OCR support or provide a plain-text version of documents. If search performance is not as expected, review the environment variable settings to ensure FTS5 and semantic search are enabled according to your needs.

Example workflows

Ingest a folder of documents with tags and recursive traversal, then search for specific topics and refine results progressively.

# Example: add-folder command (replace paths and tags as needed)
.venv\Scripts\python.exe cli.py add-folder "C:\\c64docs" --tags reference --recursive

# Example: search with a Claude Code client after indexing
# Use your MCP client to issue a search like: 'Search the C64 docs for VIC-II registers'

Notes

This MCP server provides multi-format document handling, persistent indexing, and advanced search features such as semantic search, RAG-based Q&A with citations, and table/code search to help you locate precise information about the Commodore 64.

Available tools

search_docs

Full-text search across documents with optional parameters for max results and tags.

semantic_search

Meaning-based search using vector embeddings to find results by concept rather than exact keywords.

hybrid_search

Combine keyword and semantic signals with configurable weighting for better results.

answer_question

RAG-based question answering with citations to source documents.

fuzzy_search

Typo-tolerant search with configurable similarity threshold.

search_within_results

Progressively refine search results by narrowing within an initial result set.

find_similar

Find documents related to a given document based on content similarity.

add_document

Add a single document with metadata such as title and tags.

add_documents_bulk

Bulk import documents from a directory with tagging and recursive options.

list_docs

List all indexed documents and their metadata.

get_chunk

Retrieve a specific content chunk from a document.

remove_document

Remove a single document by ID.

remove_documents_bulk

Bulk remove documents by IDs or tags.

check_updates

Check for changes in provided file paths and update the index.

scrape_url

Scrape a documentation website and import content into the knowledge base.

rescrape_document

Re-scrape a document to fetch updates from the source.

check_url_updates

Check all scraped URLs for content changes.

extract_entities

Extract named entities from documents, such as hardware, memory addresses, and concepts.

search_entities

Search across extracted entities by query.

get_entity_analytics

Provide statistics about extracted entities and usage.

extract_entity_relationships

Build relationships based on co-occurrence of entities.

search_entity_pair

Find documents containing a specific pair of entities.

compare_documents

Side-by-side document comparison with similarity scoring.

suggest_tags

AI-powered tag suggestions based on document content.

get_tags_by_category

Browse tags organized by category.

translate_query

Parse natural language queries into structured search parameters.

export_entities

Export entity data to CSV or JSON.

export_relationships

Export entity relationship data to JSON.

kb_stats

Knowledge base statistics and usage metrics.

health_check

System diagnostics for MCP server health.