# 震海乐享 MCP

让 Codex、Claude、Gemini CLI 和腾讯 WorkBuddy 通过本地 MCP 服务安全读取腾讯乐享知识库。

本项目只提供只读功能：

- `list_kb_tree`：读取知识库目录；
- `rag_search`：AI 搜索不可用时自动回退为关键词搜索；
- `get_kb_entry`：读取知识条目详情与可直接获取的文本正文。

所有乐享凭据仅保存于用户自己的电脑，绝不会写入 MCP 配置、Git、Release 或工具返回值。

> **安全提示**：请勿使用旧工具包内的 `.env`。若其曾被上传、分享或提交到版本控制，请先在乐享后台轮换 App Secret 和其他密钥。

## 安装

从 [Releases](https://github.com/Lonid-C/zhenhai-lexiang-mcp/releases) 下载 ZIP 并解压后，只需启动一个文件：

```bash
# macOS：Finder 中双击“安装.command”；首次如被拦截，请右键选择“打开”。
# Linux：在终端运行
./scripts/install.sh
```

Windows PowerShell：

```powershell
# Windows：双击“安装.bat”
```

安装器会自动创建隔离的 Python 环境，随后以隐藏输入收集 `LEXIANG_APP_KEY`、`LEXIANG_APP_SECRET`、`LEXIANG_TEAM_ID`、`LEXIANG_STAFF_ID`，验证连接、列出可访问知识库并让用户按编号选择默认库，最后选择接入的智能体。无需手动安装依赖、编辑 JSON 或配置 PATH。配置文件位置：

| 系统 | 私有配置位置 |
| --- | --- |
| macOS | `~/Library/Application Support/ZhenhaiLexiang/.env` |
| Windows | `%APPDATA%\ZhenhaiLexiang\.env` |
| Linux | `${XDG_CONFIG_HOME:-~/.config}/zhenhai-lexiang/.env` |

macOS/Linux 上配置文件权限会自动限制为当前用户。运行 `lexiang-mcp doctor` 验证令牌与知识库连接；它不会显示密钥。

## 连接智能体

如需以后再添加另一个智能体，可运行安装器显示的 `lexiang-mcp` 路径并执行：

```bash
lexiang-mcp install --target codex
lexiang-mcp install --target claude
lexiang-mcp install --target gemini
lexiang-mcp install --target workbuddy
```

- **Codex**：本仓库根目录也是一个 Codex 插件，包含 `.codex-plugin/plugin.json`、`.mcp.json` 和中文配置 Skill。安装 Python 包后，将该目录作为本地插件安装；也可使用上面的 CLI 注册 MCP 服务。
- **Claude Code / Claude Desktop**：CLI 会注册用户级 stdio MCP。桌面端也可将下方 JSON 合并进其 MCP 配置。
- **Gemini CLI**：CLI 使用用户级 `gemini mcp add`；其 MCP 配置标准见 [Gemini CLI 文档](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)。
- **腾讯 WorkBuddy**：CLI 会生成可导入的 `workbuddy-mcp.json`，请在 WorkBuddy 的“自定义 MCP”入口导入。

通用 stdio 配置（不包含密钥）：

```json
{
  "mcpServers": {
    "zhenhai-lexiang": {
      "command": "lexiang-mcp",
      "args": ["serve"]
    }
  }
}
```

## 使用示例

配置并重启客户端后，可以直接询问：

- “列出默认乐享知识库两层目录。”
- “检索：月月谈最近讨论了什么？”
- “读取乐享知识节点 `ENTRY_ID` 的正文。”

服务仅使用标准输入/输出进行 MCP 通信。请勿手动运行 `lexiang-mcp serve` 后向其标准输出写入日志。

## 开发与发布

```bash
python3 -m pip install '.[test]'
pytest
python3 scripts/security_check.py
python3 -m build
python3 /Users/a1234/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
```

GitHub Actions 会在 macOS、Windows 和 Linux 上测试 Python 3.10–3.12，并在推送 `v*` 标签时生成 wheel、source distribution、离线 ZIP 与 SHA-256 校验文件。

## English quick start

Double-click the platform installer after extracting the release ZIP. It creates an isolated Python environment, prompts for credentials without echoing them, verifies access, lets the user pick a knowledge base by number, and connects the selected agent. Credentials stay in the user-private configuration file and are never included in MCP client configuration or tool responses.