zerokit MCP server
Commit Nov 15, 2026A plugin runner that derives CLI, MCP, launcher, and AI workbench interfaces from a single plain-text manifest.
Also known as nicholyx/zerokit
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is zerokit MCP?
zerokit is a plugin runner that derives CLI, MCP, launcher, and AI workbench interfaces from a single plain-text manifest.
Summary generated from the project's README
About zerokit MCP server
Developers who want to build tools that work across multiple environments can use zerokit to derive CLI, MCP, launcher, and web interfaces from a single plain-text manifest. Instead of writing separate integrations for different platforms, you define your actions in a plugin directory using a plugin.toml file. This single declaration automatically generates command-line arguments, MCP input schemas, and web forms.
This tool runs locally on macOS, Linux, or Windows using Node.js 22.18 or via pre-built installers. It connects to AI clients like Claude Desktop, Cursor, and VS Code by generating configuration snippets through the zkit mcp config command. For security, it follows a fail-closed model where actions marked with a risk level of mutate or destructive require explicit authorization before they can be executed by an AI client.
By using zerokit, the effort required to make a tool available to an AI agent is essentially zero. The system handles the translation between your manifest and the specific requirements of various clients, ensuring that the same tool available in your terminal is also ready for use in an AI workbench or a web-based interface.
What you can do with it
- 1Automated configuration for AI clientsQuickly set up MCP server settings for specific editors like Cursor or Windsurf.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenicholyx/zerokit is public and reachablegithub.com/nicholyx/zerokit ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/nicholyx/zerokit ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 4.7 / 10; weakest: Code-Review 0, Maintained 0, CII-Best-Practices 0scorecard.dev/viewer/?uri=github.com/nicholyx/zerokit ↗Partial 7/15
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubzerokit
一份清单,四个面:启动器 / CLI / MCP / Web。不绑定宿主的插件集市。
zerokit 解决的问题是:你为某个工具写的扩展,被锁死在那个工具里了。
uTools 的插件是 JS 调 utools.* 私有 API,DeepSeek Harness 的插件是 npm 包,
它们都只能在自己的客户端里跑。zerokit 的插件是一份纯文本清单,同一份清单同时派生:
| 面 | 从同一份声明派生出的东西 |
|---|---|
| CLI | zkit run <插件> <动作> --参数 值 |
| MCP | 工具 <插件id>__<动作id>,inputSchema 自动生成,任何 AI 客户端可直接调用 |
| 启动器 | 关键词命中 → 动作列表 → 参数表单 → 结果卡片 |
| AI 工作台 | 同一批动作变成模型的工具,对话式调用,副作用动作先弹确认 |
| Web | 动作声明 render = "web" 时,结果交给插件自带的 web/index.html 渲染(沙箱 iframe + postMessage 桥,zkit web <插件id> 直达) |
所以「给 AI 用」不是额外开发,而是免费副产品。复制一个插件目录(或一个 .toolpack
单文件),能力就整体搬到了任何地方——终端、启动器、Claude Code、Cursor、VS Code 都行。
启动器和 AI 工作台是同一个窗口的两种模式:输入框里直接打字是命令模式,
以 ? 开头切到工作台。两者共用同一份插件清单,所以在工作台里能用的工具,
和 Claude Code / Cursor 里能用的完全一致。
快速开始
脚本消费者:CLI JSON 契约
写脚本/CI 断言消费 zkit <cmd> --json 时,看 docs/contract/cli-json-v1.md——
标注「稳定」的字段 v1 内不改名不删除;其余字段随时可能变。
要求:Node ≥ 22.18(直接跑 TS 源码,无构建步骤);三平台均可(macOS / Linux / Windows)。 Windows 上建议 Git Bash 或 WSL;PowerShell 也能跑,但示例命令按 bash 写。
git clone <this-repo> && cd zerokit
npm install
node src/cli.ts market add . # 把本仓库当集市加进去(仓库自带 market.json)
node src/cli.ts market search # 看看有什么
node src/cli.ts plugin install sysinfo # 安装(先把全部能力摊开给你看,确认后才装;脚本里加 --yes 跳过确认)
node src/cli.ts doctor # 环境自检(依赖、插件清单)
node src/cli.ts run sysinfo.overview # 跑一个动作(点分简写;两段式 `run sysinfo overview` 等价)
node src/cli.ts ui --open # 打开启动器:顶部「集市」标签可直接浏览、预览、安装
# (工作台在搜索框打 ? 开头)
eval "$(node src/cli.ts completion bash)" # 顺手开 shell 补全(也有 zsh / fish)
装不上 / 跑不起来先看 START-HERE 的常见问题;
完整命令参考终端里 node src/cli.ts man。
装好之后可以把 zkit 链接到全局:
npm link # 之后直接用 zkit / zkit-mcp
界面
zkit ui # 启动本地界面(默认随机端口,只绑 127.0.0.1)
zkit ui --open # 顺便打开浏览器
浏览器里是一个键盘优先的启动器:模糊搜索、↑↓ 选择、回车执行、按参数声明自动生成的表单、
按 render 类型渲染的结果卡片。输入框里打 ? 切到 AI 工作台。
搜索支持拼音与首字母:打 dl 出「代理」、xtxx 出「系统信息」、daili 也认。
这一层完全在前端本地算,不联网也不经过服务端;汉字表是生成期产物
(node scripts/gen-pinyin.mjs,运行时不引任何依赖)。
下载安装包(免 Node 环境)
每个 Release 附带三平台安装包, 流水线构建、不本地打包:
| 平台 | 资产 |
|---|---|
| macOS(Apple Silicon) | zerokit_X.Y.Z_aarch64.dmg |
| macOS(Intel) | zerokit_X.Y.Z_x64.dmg |
| Windows | zerokit_X.Y.Z_x64-setup.exe |
安装包内嵌 Node 运行时(启动即用);开发者路径仍是上面的 npm install(免构建、直接跑 TS 源码)。
也可以从源码套上原生壳(全局热键 Alt+Space、托盘、无边框窗口):
cd apps/desktop/src-tauri && cargo run
接入 AI 客户端
zkit mcp config # 打印各家客户端的配置片段
zkit mcp config cursor --write # 直接写入(会先备份原文件)
zkit mcp serve # 手动以 stdio 方式跑起来看看
支持的客户端:Claude Desktop / Claude Code / Cursor / Windsurf / VS Code (Copilot) / Cline。
注意各家配置只是事实标准、不是规范——比如 VS Code 用的是 servers 键而不是
mcpServers,且每项要多一个 "type": "stdio"。zerokit 已按客户端分别处理。
安全默认:MCP 侧只读动作默认放行,有副作用的动作必须先显式授权一次:
zkit mcp allow proxy.allow-domain # 授权这一个动作
zkit mcp allow # 看已授权哪些
理由是 MCP 规范明确要求客户端「必须把 annotations 当作不可信」——不能指望 AI 客户端
替我们把关,所以默认拒绝(fail-closed)。
写一个插件
插件 = 一个目录 + 一份 plugin.toml,放任何语言都行;最简单的插件一行代码都不用写:
[plugin]
id = "ip" # ASCII,用作目录名 / CLI 名 / MCP 工具名前缀
name = "出口 IP" # 显示名,可中文
version = "1.0.0"
summary = "查本机访问外网时用的公网 IP"
keywords = ["ip", "公网", "网络"] # 同时供模糊搜索和模型路由
[[action]]
id = "public"
title = "查公网 IP"
description = "返回本机访问外网时使用的公网 IP。想知道当前出口 IP 时用这个。"
type = "http" # 零代码:只发一个请求
url = "https://api.ipify.org?format=json"
output = "json"
risk = "read" # read / mutate / destructive(必填)
需要写代码时用 run,注意是数组而不是字符串:
[[action]]
id = "allow-domain"
title = "添加允许域名"
description = "把一个域名加入白名单,约 2 秒自动生效。需要放行新站点时用这个。"
run = ["{python}", "proxy.py", "config", "domain", "add", "{domain}"]
output = "text"
risk = "mutate"
[[action.param]]
name = "domain"
type = "string"
required = true
description = "要允许的域名,例如 example.com(含所有子域)"
加一个参数,四个面同时多出来:CLI 多了 --domain,MCP 的 inputSchema 多了这个属性,
启动器和 Web 多了这个表单字段。
三个必须理解的字段
description是写给人和模型两个人的。 它既是启动器的搜索词来源,又是 MCP 里 决定模型选不选这个工具的唯一信号。写清「做什么 / 什么时候用 / 返回什么」。risk是必填的,不是装饰。 副作用常常超出接口名所示("查询订单"内部可能带消息推送 和写盘)。它同时决定确认策略(read放行 /mutate首次确认并记住 /destructive每次确认)和 MCP 的readOnlyHint/destructiveHint标注。run是 argv 数组,默认不经 shell。 参数作为数组元素直接传入,不做字符串拼接, 从根上消除参数注入。确实需要管道时才加shell = true,此时风险等级会被强制提升为destructive。
完整字段说明见 docs/reference/plugin-spec.md。
命令一览
zkit list / ls 列出插件与动作
zkit show <插件> [动作] 详情(含生成的 MCP 工具名、JSON Schema、依赖自检)
zkit run <插件> <动作> 执行;--json 输出结构化结果,--yes 跳过确认
zkit doctor 自检环境、依赖、插件清单
zkit ui 启动器 / 工作台界面
zkit ps 看正在运行的东西(托管的进程 + 插件声明的服务)
zkit kill <进程id|插件.服务> 结束一个;kill all 全部结束
zkit market add <地址|目录> 添加集市(集市 = 一个 git 仓库 + 根目录 market.json)
zkit market search [词] 在集市里找插件
zkit market refresh 拉取最新索引
zkit market index [目录] 把一个插件目录生成为集市索引
zkit plugin install <id> 从集市安装(先摊开全部能力再确认)
zkit plugin add <目录|git> 从本地目录或 git 仓库安装
zkit plugin update [插件] 列出来源与可更新状态;带插件 id 检查并更新
zkit plugin export <插件> 打包成单个 .toolpack
zkit plugin import <文件> 从 .toolpack 安装
zkit mcp serve|config|allow MCP 对接
zkit logs [denied] 看审计日志
数据都在一个目录里
~/.zerokit/(可用 ZEROKIT_HOME 改):
config.toml zerokit 自身的设置(含 [ai] 段的模型 provider 与密钥)
plugins/ 插件目录,一个子目录就是一个插件
logs/audit.log 所有调用(谁在什么时候执行了什么、结果如何)
logs/denied.log 被拒/失败的,便于快速排查
data/<插件>/ 插件私有数据,跨更新保留
data/artifacts/ 超大输出的落盘位置
marketplaces.json 已添加的集市
cache/market/ 集市索引的本地缓存
installed/<插件>.json 安装时的清单快照(用于发现装后被偷改)
approvals.json 界面与 CLI 里记住的确认
mcp-allow.json 已授权给 AI 调用的有副作用动作
复制这个目录 = 搬走整套配置和插件。
当前进度
项目层面的完整账本(初衷 / 已完成 550+ 项 / 待办 / 已知差距)见 docs/reference/overview.md;每一版改了什么看 CHANGELOG;全部现成动作看动作速查表。
核心能力(均已实测通过,v0.2.0 → v1.63.0 共一百六十一轮迭代,111 个测试文件 2642 项断言):
- 内核 + 五个面(CLI / MCP / 启动器 / AI 工作台 / Web 渲染)+ 插件集市 + Tauri 桌面壳
- 启动器 200+ 项体验(拼音搜索、键盘流、结果页签、监控、备份、配置档、双语、沙箱、哨兵……)
- 插件开发闭环(脚手架 / lint 二十级体检 / 文档生成 / pack 分发 / dev 链接热改)
- 运维面(审计/历史/书签/数据体检)+ 发布工具化(release-prep 自检 + release-chain 一条龙)
测试:node scripts/test-all.mjs(86 个文件 2220 项断言,不联网、不花钱)。
基准:node scripts/bench.mjs。
还没有的:OS 级能力(读活动窗口/模拟键鼠)、插件签名与来源校验——详见账本「待办」。
参与贡献
项目故事 · CONTRIBUTING.zh-CN.md · SECURITY · SUPPORT 里有完整的十条军规(跨平台坑、
断言写法、提交规范)——都是真实事故换来的。带
good first issue 标签的是适合首次贡献的切入点。
设计取舍
- 内核无 UI 依赖,可以独立当天花板使用。UI 只是它的两个消费者——即使以后换 UI 框架, 内核价值不受影响。
- 执行只有一个收口(
src/core/runner.ts),所以安全策略只在一处实现、一处审计, 加第四个面(比如给别的工具调的 HTTP API)成本极低。 - 不假装是沙箱。 白名单只管得住直接启动的程序名,管不住它自己 spawn 的子进程、 读的配置文件、发起的网络请求。真实隔离只能靠 OS 级方案。
MIT
zerokit MCP questions
Which AI clients are supported?
It supports Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (Copilot), and Cline.
What operating systems does it support?
It is compatible with macOS, Linux, and Windows.