codegenie-knowledge (DevEco 知识库 MCP)

通过 npx 一键启动 DevEco 本地知识库 MCP 服务:自动拉取 JAR(若无)并启动 Java STDIO 服务,供 Cursor 等 MCP 客户端使用。

快速开始

1. (推荐)首次使用先预下载 JAR,避免在 Cursor 里等太久或超时:

   npx -y codegenie-knowledge --prepare

2. 在 Cursor 的 MCP 配置里添加(或参考 mcp.json.example):

   {
     "mcpServers": {
       "deveco-knowledge-base": {
         "command": "npx",
         "args": ["-y", "codegenie-knowledge"]
       }
     }
   }

3. 重启 Cursor / 重载 MCP,即可使用。

环境要求

• Node.js ≥14 (用于运行本脚本)
• JDK 17+ (用于运行 MCP JAR)

🎯 关于 Java 环境

好消息！ 如果你已经安装了 DevEco Studio,无需单独安装 Java！

本工具会自动查找并使用:

• ✅ DevEco Studio 内置 JDK (优先,推荐)
• ✅ 系统安装的 JDK
• ✅ PATH 环境变量中的 Java

查找顺序 (Mac 为例):

1. DevEco Studio: /Applications/DevEco-Studio.app/Contents/jbr/
2. 系统 JDK: /Library/Java/JavaVirtualMachines/
3. PATH: java 命令

如果没有 DevEco Studio,可以安装:

• Mac: brew install openjdk@17 或从 Adoptium 下载
• Windows: 从 Adoptium 下载安装
• Linux: sudo apt install openjdk-17-jdk

常用环境变量

| 变量 | 说明 | |------|------| | DEVECO_MCP_HOME | JAR 与数据目录,默认 ~/.deveco-knowledge | | DEVECO_MCP_DEBUG | 设为 1 时输出详细日志与错误栈,便于排查 | | DEVECO_MCP_JAR_URL | 直接指定 JAR 下载地址,跳过 GitHub(适合内网/镜像) | | DEVECO_MCP_MIRROR | GitHub 下载镜像,默认 https://ghproxy.com; 设为空则直连 GitHub | | DEVECO_MCP_UPDATE | 设为 1 时强制重新下载 JAR | | JAVA_HOME | 指定 Java 路径(可选,通常会自动找到) |

Mac 用户特别说明 ⚠️

Mac 上 Cursor 不会将 mcp.json 中的 env 传递给 MCP 服务进程,导致配置的 ENABLE_INDEX=true 不生效。

解决方案: 使用 .env 文件

1. 创建 user-docs 目录并添加文档:

   mkdir -p ~/.deveco-knowledge/user-docs
   cp your-docs/*.md ~/.deveco-knowledge/user-docs/

2. 创建 .env 文件启用索引构建:

   echo 'ENABLE_INDEX=true' > ~/.deveco-knowledge/.env

3. 重启 Cursor,服务会自动读取 .env 并构建索引

4. 验证索引是否构建成功:

   # 应该能看到 user-index 目录
   ls -la ~/.deveco-knowledge/

详细说明请参考: Mac 上构建用户索引指南

脚本会自动读取 .env 文件并通过 -D 参数传递给 Java 进程,无需在 mcp.json 中配置 env。

添加自定义文档

Windows 用户

# 1. 创建目录
New-Item -ItemType Directory -Path "$env:USERPROFILE\.deveco-knowledge\user-docs" -Force

# 2. 添加文档
Copy-Item "your-docs\*.md" "$env:USERPROFILE\.deveco-knowledge\user-docs\"

# 3. 在 Cursor 配置中启用索引
# settings.json 或 mcp.json:
{
  "mcpServers": {
    "deveco-knowledge-base": {
      "command": "npx",
      "args": ["-y", "codegenie-knowledge"],
      "env": {
        "ENABLE_INDEX": "true"
      }
    }
  }
}

# 4. 重启 Cursor

Mac/Linux 用户

# 1. 创建目录并添加文档
mkdir -p ~/.deveco-knowledge/user-docs
cp your-docs/*.md ~/.deveco-knowledge/user-docs/

# 2. 创建 .env 文件 (Mac 必须用这种方式)
echo 'ENABLE_INDEX=true' > ~/.deveco-knowledge/.env

# 3. Cursor 配置保持简单即可
{
  "mcpServers": {
    "deveco-knowledge-base": {
      "command": "npx",
      "args": ["-y", "codegenie-knowledge"]
    }
  }
}

# 4. 重启 Cursor

常见问题

Java 相关

• "unable to locate a java runtime":

  • 如果有 DevEco Studio,会自动找到其内置 JDK
  • 否则需要安装 JDK 17+ 或设置 JAVA_HOME
  • 在 .env 文件中设置: JAVA_HOME=/path/to/jdk

• 想确认使用的是哪个 JDK:

  export DEVECO_MCP_DEBUG=1
  npx -y codegenie-knowledge --prepare
  # 查看日志,会显示 Java 路径

下载相关

• 首次启动一直卡住 / 超时: 先在本机终端执行 npx -y codegenie-knowledge --prepare 完成下载,再在 Cursor 里启用 MCP。

• 国内网络拉取失败: 可设置 DEVECO_MCP_JAR_URL 指向内网或镜像的 JAR 直链,或保持默认镜像; 失败时错误信息会提示设置方式。

索引相关

• Mac 上无法构建索引: 参考上面的 "Mac 用户特别说明" 使用 .env 文件。

• 添加文档后查询不到:

  1. 确认设置了 ENABLE_INDEX=true
  2. Mac 用户必须用 .env 文件
  3. 检查是否有 user-index 目录生成
  4. 启用 DEVECO_MCP_DEBUG=1 查看详细日志

调试

• 排查错误: 设置 DEVECO_MCP_DEBUG=1 后重新执行,查看完整错误栈与日志。

支持的文档格式

• ✅ Markdown (.md)
• ✅ HTML (.html, .htm) - 自动转换为 Markdown
• ✅ 纯文本 (.txt)

特性

• ✅ 自动下载 JAR - 首次使用自动从 GitHub 下载
• ✅ 智能 Java 查找 - 自动查找 DevEco Studio / 系统 JDK
• ✅ 镜像加速 - 默认使用 ghproxy 加速下载
• ✅ 自定义文档 - 支持添加项目文档并索引
• ✅ 离线使用 - 下载后完全离线运行
• ✅ 跨平台 - 支持 Windows / Mac / Linux
• ✅ .env 配置 - Mac 上通过 .env 文件配置环境变量

目录结构

~/.deveco-knowledge/          # 默认安装目录
├── .env                      # 环境变量配置 (Mac 必需)
├── know-0.0.1.jar           # MCP 服务 JAR
├── user-docs/               # 用户自定义文档
│   ├── project-api.md
│   └── team-guide.md
└── user-index/              # 自动生成的索引
    ├── segments_1
    └── ...

更新日志

v1.0.13 (2026-03-13)

• ✅ 支持自动查找 DevEco Studio 内置 JDK
• ✅ 优化 Java 查找逻辑,DevEco Studio JDK 优先级最高
• ✅ 改进调试日志,显示使用的 JDK 路径

v1.0.12 (2026-03-13)

• ✅ 修复 v1.0.11 的语法错误

v1.0.11 (2026-03-13)

• ✅ 增强 .env 文件加载功能
• ✅ 改进启动日志,显示环境变量来源
• ✅ 完善 Mac 上的索引构建支持

相关文档

• 快速开始指南
• 常见问题解答
• Mac 索引构建指南
• Mac 故障排查
• 更新日志 v1.0.13

许可证

MIT License

支持

• 📧 GitHub Issues
• 📖 查看完整文档
• 💬 社区讨论

提示: 如果你是 HarmonyOS 开发者,已经安装了 DevEco Studio,那么无需任何额外配置即可使用！