zk-doc-mcp-server 0.9.3

MCP server for searching ZK Framework documentation

ZK Documentation MCP Server

An MCP (Model Context Protocol) server for the ZK Framework documentation that provides semantic search, intelligent Q&A, and documentation indexing capabilities.

Overview

This server integrates ChromaDB for vector-based semantic search and implements MCP tools for:

• Searching ZK documentation
• Retrieving specific documentation content
• Answering questions based on documentation
• Managing documentation indices
• Browsing documentation categories

Quick Start

Prerequisites

Your environment should have the following installed:

• Python 3.10 or higher.
• uv package manager (https://docs.astral.sh/uv/) - optional but recommended
• Git (2.7 or higher) - Required for automatic documentation synchronization

Installation zk doc MCP server from PyPI

create a virtual environment of Python 3.10

uv venv --python 3.10

# Using uv (recommended)
uv pip install zk-doc-mcp-server
# This command installs the package into the currently active virtual environment.

List installed package

uv pip list

Upgrade it if you installed

uv pip install --upgrade zk-doc-mcp-server

The package is available at:

• PyPI (production): https://pypi.org/project/zk-doc-mcp-server/

Initialize Documentation (Optional Setup)

After installation, you can optionally pre-index the ZK documentation for faster server startup:

uvx zk-doc-mcp-server init

This command:

1. Clones/syncs the documentation repository to ZK_DOC_SRC_DIR
2. Pre-indexes the documentation for semantic search

After running init, subsequent server startups can be immediately ready for doc search. Otherwise, you might need to wait for several minutes for background indexing.

Check status or re-index after documentation updates:

# Re-sync and re-index if documentation has changed
uvx zk-doc-mcp-server init

# Force complete re-clone and re-index
uvx zk-doc-mcp-server init --force

The server uses incremental indexing that automatically detects documentation changes and only re-indexes modified files, making updates fast and efficient.

When to use init:

• First-time setup
• After significant documentation updates
• When you want immediate search availability without waiting for background indexing

Using with Claude Code

The easiest way to use this MCP server is through Claude Code or Gemini CLI.

1. Add the ZK Documentation MCP server:

claude mcp add zk-doc -- uvx zk-doc-mcp-server

2. Start using it in Claude Code:

Search the ZK doc for "what is desktop"

Claude Code will automatically use the ZK documentation MCP server to search and retrieve information.

Using with Gemini CLI

1. Add the MCP server to your Gemini configuration file (typically ~/.gemini/config.json or similar):

{
  "mcpServers": {
    "zk-doc": {
      "command": "uvx",
      "args": ["zk-doc-mcp-server"]
    }
  }
}

3. Start using it:

Ask the zk-doc server about ZK Framework components

MCP Tools

search_zk_docs

Search ZK documentation for relevant content using semantic search.

Parameters:

• query (string, required): Search query
• limit (integer, optional, default: 5): Maximum results to return (1-20)

Response:

{
  "results": [],
  "query": "your search query",
  "limit": 5,
  "message": "Search functionality coming soon"
}

submit_feedback

Submit feedback about search results to improve documentation.

When search results don't meet user expectations, this tool captures feedback that helps the documentation team understand gaps and improve content.

Parameters:

• query (string, required): The search query that produced unsatisfactory results
• results (list, required): List of search results returned (each with title, file_path, content)
• expected (string, required): What the user expected to find
• comments (string, optional): Additional context about why results don't match

Features:

• Feedback is always saved locally to ~/.zk-doc-mcp/feedback/
• Automatically submitted as GitHub issue to https://github.com/zkoss/zkdoc/issues
• Non-blocking operation - returns immediately while GitHub submission happens in background
• Graceful fallback - feedback is preserved locally if network fails

Response:

{
  "success": true,
  "feedback_id": "feedback_20250114_a7k9m2x8",
  "local_path": "/home/user/.zk-doc-mcp/feedback/feedback_20250114_a7k9m2x8.json",
  "github_issue_url": "https://github.com/zkoss/zkdoc/issues/456",
  "message": "Feedback saved and submitted to https://github.com/zkoss/zkdoc/issues/456"
}

show_settings

Display all configuration settings for the ZK Doc MCP Server.

This tool enables you to inspect the current server configuration, including all environment variables and their effective values. It's useful for debugging, configuration verification, and discovering available settings.

Parameters: None - this tool takes no parameters.

Response:

{
  "settings": {
    "ZK_DOC_SRC_DIR": "~/.zk-doc-mcp/repo",
    "ZK_DOC_VECTOR_DB_DIR": "~/.zk-doc-mcp/chroma_db",
    "ZK_DOC_FORCE_REINDEX": false,
    "ZK_DOC_LOG_LEVEL": "INFO",
    "ZK_DOC_USE_GIT": true,
    "ZK_DOC_CLONE_METHOD": "https",
    "ZK_DOC_REPO_URL": "https://github.com/zkoss/zkdoc.git",
    "ZK_DOC_GIT_BRANCH": "master",
    "ZK_DOC_FEEDBACK_ENABLED": true,
    "ZK_DOC_FEEDBACK_RETENTION_DAYS": 90,
    "ZK_DOC_FEEDBACK_GITHUB_REPO": "zkoss/zkdoc"
  },
  "summary": {
    "total_settings": 11,
    "git_enabled": true,
    "feedback_enabled": true
  }
}

Usage in Claude Code:

Show me the current ZK doc MCP server settings

Usage in Gemini CLI:

Use the show_settings tool from zk-doc server

Common use cases:

• Verify that Git synchronization is enabled/disabled
• Check which documentation branch is being used
• Confirm the vector database location
• Debug configuration issues
• Discover available configuration options

Configuration

The MCP server behavior can be customized using environment variables. These settings control documentation sources, indexing, and Git integration.

Available Settings

The server provides the following configurable settings:

Setting	Type	Default	Description
ZK_DOC_SRC_DIR	string	~/.zk-doc-mcp/repo	Documentation source directory (Git repo or local docs)
ZK_DOC_VECTOR_DB_DIR	string	~/.zk-doc-mcp/chroma_db	Vector database directory for storing embeddings and search indices
ZK_DOC_FORCE_REINDEX	boolean	false	Force re-indexing of documentation on startup
ZK_DOC_LOG_LEVEL	enum	INFO	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
ZK_DOC_USE_GIT	boolean	true	Enable Git synchronization for documentation
ZK_DOC_CLONE_METHOD	enum	https	Git clone method (https or ssh)
ZK_DOC_REPO_URL	string	https://github.com/zkoss/zkdoc.git	Repository URL to clone documentation from
ZK_DOC_GIT_BRANCH	string	master	Git branch to pull documentation from
ZK_DOC_FEEDBACK_ENABLED	boolean	true	Enable feedback collection for search improvements
ZK_DOC_FEEDBACK_RETENTION_DAYS	integer	90	Days to retain local feedback files
ZK_DOC_FEEDBACK_GITHUB_REPO	string	zkoss/zkdoc	GitHub repository for feedback issues (built-in)

Viewing Current Settings

To see all current settings and their values:

# Start the server
uv run python3 -m zk_doc_mcp

# In another terminal, or use the show_settings tool in Claude
# The server provides a show_settings tool that displays all configuration

Setting Environment Variables

Example: Enabling Git Synchronization

By default, Git synchronization is enabled (ZK_DOC_USE_GIT=true). To change this behavior:

Disable Git sync:

export ZK_DOC_USE_GIT=false
uv run python3 -m zk_doc_mcp

Example: Using SSH for Git Clone

To clone the documentation repository using SSH instead of HTTPS:

export ZK_DOC_CLONE_METHOD=ssh
export ZK_DOC_USE_GIT=true
uv run python3 -m zk_doc_mcp

Prerequisites for SSH:

• SSH key configured and added to ssh-agent
• SSH key authorized on GitHub (or your Git hosting service)

Example: Using a Custom Documentation Directory

To use a local documentation directory instead of cloning from Git:

# Disable Git sync and point to local directory
export ZK_DOC_USE_GIT=false
export ZK_DOC_SRC_DIR=/path/to/local/docs
uv run python3 -m zk_doc_mcp

Example: Force Re-indexing Documentation

To rebuild the vector search index from scratch:

export ZK_DOC_FORCE_REINDEX=true
uv run python3 -m zk_doc_mcp

After re-indexing completes, the server will run normally with the updated index.

Example: Using a Different Git Branch

To pull documentation from a different branch (e.g., develop instead of master):

export ZK_DOC_GIT_BRANCH=develop
export ZK_DOC_USE_GIT=true
uv run python3 -m zk_doc_mcp

Example: Configuring Feedback Collection

Feedback collection is enabled by default and automatically submits feedback to https://github.com/zkoss/zkdoc/issues.

To disable feedback collection:

export ZK_DOC_FEEDBACK_ENABLED=false
uv run python3 -m zk_doc_mcp

To change feedback retention period (default: 90 days):

export ZK_DOC_FEEDBACK_RETENTION_DAYS=30
uv run python3 -m zk_doc_mcp

Feedback is automatically created as GitHub issues for documentation team review, helping improve search results and content gaps.

Persisting Configuration

To persist settings across sessions, add them to your shell profile, for example

For bash (add to ~/.bashrc or ~/.bash_profile):

export ZK_DOC_USE_GIT=true
export ZK_DOC_CLONE_METHOD=https
export ZK_DOC_GIT_BRANCH=main

Configuration Verification

Use the show_settings tool to verify your configuration is correct:

Running the Server Standalone

After installation from PyPI, you can run the server directly:

# Using the installed command
zk-doc-mcp-server

# Or using Python module
python -m zk_doc_mcp

Troubleshooting

Installation issues

Permission denied errors:

# Ensure you have execute permissions
chmod +x ~/.claude/mcp/zk-doc

Module import errors:

# Reinstall the package
uvx --refresh zk-doc-mcp-server

Server not appearing in claude mcp list:

# Check if the command is accessible
uvx zk-doc-mcp-server --help

For development-related troubleshooting (setup, testing, building), see README_DEV.md.

License

MIT License