Empower Your AI with ZK Knowledge to Boost Development
Overview
This article introduces an approach combining AI tools with ZK knowledge to make your ZK development faster and smoother.
Rather than relying on a centralized, remote AI service, we enable you to run your own dedicated AI assistant directly within your local development environment. This setup leverages popular AI-powered IDEs such as Cursor and Windsurf, giving you the flexibility to select and configure your preferred AI model—whether free or commercial—according to your needs.
We’ll also show how to connect your AI assistant to ZK documents, examples, and even our issue tracker.
Note: AI evolves quickly. What we share here reflects our current approach and observations — feel free to adapt it to your needs or contribute back improvements!
Why This Setup
Complete Control and Customization
- You have the freedom to choose your preferred AI model and potentially fine-tune it for your specific needs
- This means you can select AI models known for their accuracy, speed, or even those specialized in code comprehension, tailoring the AI assistant to your exact requirements and hardware capabilities.
- As new AI models emerge, you can easily swap them into your local setup
Direct Access to Ground Truth
AI directly queries the official ZK documentation and verified example code, ensuring that the answers provided are based on the definitive source of truth, minimizing the risk of outdated or inaccurate information.
Cost Efficiency
You can choose free/open-source AI models or paid commercial AI models based on your preference and budget.
Enhanced Privacy and Security
If you use a local AI model, it eliminates concerns about data being transmitted to third-party servers or used for external model training.
Architecture Overview
This approach works by connecting three key pieces together:
Local AI-Powered IDE (e.g. Cursor, Windsurf)
Acts as your interface to the AI assistant. These editors support MCP (Multi-Component Protocol) servers that enable the AI to interact with files, execute commands, and perform step-by-step reasoning.
MCP Servers (running locally or remotely)
These lightweight servers act as “tools” the AI can call to search your file system, break down complex problems, or fetch web data. You can run them as separate processes or install plugins directly in supported IDEs.
ZK Knowledge Base (your local docs and examples)
You’ll need to clone ZK documentation (zkdoc) and example code (zkbooks) into your local environment. These are what the AI reads and reasons over when answering ZK-related questions.
Getting Started with Cursor
We’ll use Cursor as an example, but the same ideas apply to Windsurf, Claude Code, Trae, or any IDE that supports MCP servers.
Clone zkdoc / zkbooks
ZK knowledge store in documents and example codes, so you need to clone them into your local environment. Since they are mostly text, they don't consume too much disk space.
- https://github.com/zkoss/zkbooks: contains runnable example codes of all zk documents, including ZK Developer's Reference, ZK Component Reference, etc, listed at ZK Documentation
- https://github.com/zkoss/zkdoc: We have turned all ZK documents into GitHub pages.
Add Useful MCP Servers
I suggest installing the following MCP server:
File system
It helps an AI agent read multiple local files and edit files. But notice that its search_file just searches files with a name pattern, not with a file’s content. So I use Mac commands like grep or rg to search file-based content).
Sequential Thinking
AI will use it on its judgment whenever it determines that a task would benefit from a step-by-step, reflective, or multi-step reasoning process.
Features
- Break down complex problems into manageable steps
- Revise and refine thoughts as understanding deepens
- Branch into alternative paths of reasoning
- Adjust the total number of thoughts dynamically
- Generate and verify solution hypotheses
Fetch MCP Server
fetch-mcp: Fetch HTML from the web: enable when you want to reference a page on the web
It can enable an AI agent to check online ZK JavaDoc.
Configure Rules
AI agent does not retain memory between completions. So we need to specify Rules to solve this by providing persistent, reusable context at the prompt level. In Cursor, there are 2 kinds of rules.
User Rule
- Apply to all projects and are always included in your model context
Use them to:
- Set response language or tone
- Add personal style preferences
Notice:
- VS Code doesn’t support exporting the custom rules.
Project Rule
The key part of this approach is to define project rules to instruct AI agents to read zk knowledges first before answering your questions. Below is a set of project rules we’ve found particularly useful in helping AI agents effectively search and use the local ZK knowledge base. Feel free to adapt these based on your setup and preferences.
1 # Path
2 * ZK Documents: /yourPath/zkdoc/
3 * ZK Example Codes: /yourPath/zkbooks/
4
5 # When answering questions related to zk (UI) framework, always follow the steps below:
6 ## Step 1: Search Books TOC
7 read [ZK Documents]/_data/navigation.yml to know overview of all zk documents, then read related pages to find the answer. If there is no direct documentation found related to the question, do the next step.
8 ## Step 2: full-text search
9 * MUST run the actual Mac grep command directly in the shell (e.g. grep -r "keyword" or a similar tool like rg or ag) to perform a full-text search for keywords within all .md files under local file system at [ZK Documents] and its sub-directories. Then read found pages for references.
10 * Do NOT use internal search tools for this step.
11 ### Search Strategy Rule
12 If a direct answer or match is not found for a specific component or property, generalize the query and search for:
13 - global configuration
14 - general approaches that apply to all components
15 ## Step 3: read found pages
16 If relevant documents are found, include their content or summaries in the answer with citations or filenames.
17 ## Others
18 * always search file content with Mac command e.g. grep
19 * If no relevant documents are found, answer questions with your knowledge
20 * When using information from local documents, mention which files or sections were used (e.g., "Based on zk-proof-basics.md...").
21
22 # when providing zk-related codes
23 1. if you don't need to provide a code example, don't search [ZK Example Codes]
24 2. read [ZK Example Codes]/README.md for overview
25 3. search file system at the path [ZK Example Codes] with with grep command or a similar tool, then read found codes to find related example code.
26 4. ZK javadoc is at https://zkoss.org/javadoc/latest/zk/
- Line 2-3: specify your local path that stores zkbooks and zkdoc
- Line 9: Because "file system" MCP server's
search_filesdoesn’t search file content, we tell AI to search files with Mac command. If you are using Windows, just replace it with Windows search command.
Notes:
- Tip: observe AI agent’s action log, ensure that AI agents really read and searches the file system. Because it doesn’t always follow the specified project rule. If AI agent doesn’t follow the project rule, you have to explicitly ask it to follow.
- Recommended rules are updated from time to time. Get the latest rules at Github
Enable AI Agent to Query ZK Tracker
If you want AI agents to check for known issues or bug reports as part of its answer, you can install mcp-atlassian
Fill out jiraUrl, confluenceUrl with https://tracker.zkoss.org/, user name and jiraPersonalToken to install the MCP server. (Although we don't have Confluence, you still need to fill in a URL to activate the plugin). Once it's done, you can ask AI agents to search known ZK bugs from the tracker for you.
Conclusion
This setup is a shared experience that we hope will help fellow ZK developers make better use of AI in their workflow.
We’re continuously improving ZK documentation and examples to give AI agents better knowledge to work with. If you have suggestions, feature requests, or ideas for new examples, feel free to open an issue or PR on zkdoc or zkbooks.