YLuneMCPHub

<div align="center"> <h1>月弦</h1> <p><b>统一 MCP 网关</b> — 接入 · 按用户授权工具 · 用户 Key · 对外端点</p> <p><b>简体中文</b> · <a href="README.en.md">English</a></p> 在 **WorkBuddy** 或 **Cursor** 里只配一个 HTTP MCP，就能用上本机或机房里已经接好的全部工具。 月弦跑在**你们自己的机器**上：管理员用**控制台账号**加服务、建用户、按人勾工具；智能体只用该用户的 **Access Key** 连 `/mcp`。 库口令等 **Credential** 进凭据中心（加密入库）。仓库里没有 Token、没有密码、没有真实主机名。 <p> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?labelColor=1f2937" alt="Apache 2.0"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node-20+-339933?logo=nodedotjs&logoColor=white&labelColor=1f2937" alt="Node 20+"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-HTTP-7c3aed?labelColor=1f2937" alt="MCP HTTP"></a> <img src="https://img.shields.io/badge/auth-per--user%20tools-059669?labelColor=1f2937" alt="per-user tools"> </p> <p> <b><a href="#快速开始">快速开始</a></b> · <a href="#界面">界面</a> · <a href="#和-devopsmcp">和 DevOpsMCP</a> · <a href="#它做什么">它做什么</a> · <a href="#怎么工作">怎么工作</a> · <a href="#适配的智能体">适配的智能体</a> · <a href="#谁能调用什么">谁能调用什么</a> · <a href="#安全模型">安全</a> · <a href="#测试阶段与免责">测试与免责</a> · <a href="#文档">文档</a> </p> </div> --- 值班要查告警、发版、数据库时，工具本身在 [DevOpsMCP](https://github.com/isYaoNoistu/DevOpsMCP) 里：夜莺、Jenkins、PostgreSQL 三个只读 stdio 进程。 **月弦不重复实现这些工具。** 它把已经编好的 MCP 收进来，按用户勾选工具，再以一条 HTTP 端点交给智能体。 一个人接 Cursor 时，可以直接跑 DevOpsMCP 的三个二进制。人一多、要按人裁工具、要统一入口时，才上月弦。 ## 界面 控制台默认黑底 + 月光青，右上角灯泡可切浅色，登录页始终是黑的。按功能看一眼就知道月弦管什么。 ### 登录 内部入口，没有公开注册。**只有控制台账号能登录**；MCP 用户只拿 Access Key。管理员还可以建 **Demo 账号**：能登录看工作区，但不能改配置、不能看用户/凭据/设置。同一来源短时间失败太多次会被暂时拒绝。智能体不走这页。  ### 仪表盘 网关只读总览：四格摘要（服务健康、工具、今日/七日调用）、运行快照和紧凑的七日调用/失败折线。管理员还能看到故障提示、到期中心，并导出配置备份。不是管理员自己在调工具。本页不复制 mcp.json、不授权、不加服务器。  ### 服务器 添加、导入、启用或禁用 MCP。列表里有一张内置卡 `ylune`：不能删、不能改配置、不能授权给普通用户；只有管理员 Access Key 能在 `/mcp` 调它的只读工具。右上角灯泡可切浅色，这张是浅色。  ### 用户权限 管理员按人勾 MCP 和 **具体 tools**。勾选时有权限预览。需要凭据的 MCP 在该服务器下面勾凭据，可多选。管理员开了 MCP 后也按 MCP 勾凭据。不勾则这个 Access Key 连 `/mcp` 看不到任何工具。MCP 用户不能登录控制台。仅后台管理员能登录，默认不签发 Key。**Demo 账号**能登录，但只能看仪表盘/服务器/提示词/资源/调试台，系统菜单发灰，页面按钮不可用。Key 过期只挡住智能体，不影响后台。侧栏还有凭据中心、调试台和操作审计。  浅色同一张表单：  ### 调用日志 每次工具调用一条记录：谁、哪个服务、哪个工具、成功或失败、耗时、来源 IP。点详情可再看入参出参（若设置里打开了存储调用内容；Token 等密钥会脱敏）。  | 现场 | 只接 DevOpsMCP | 前面再加月弦 | | ------ | ----------------------------------- | -------------------------------------------- | | 一个人值班 | `mcp.json` 写三个 stdio，本机直连 | 用得上，但不必 | | 多人共用 | 每人一份路径和 Token，工具全集都在 | 管理员建用户、按人勾工具；用户只贴一段 `/mcp` + 自己的 Key | | 工具变多 | 客户端工具数容易顶满 | 默认 `/mcp` 只暴露该用户勾过的工具 | | 新同事入职 | 再抄一份本机配置 | 控制台建用户，复制生成的 JSON 或 TOML 即可 | ## 它做什么 - **统一网关** — 一个进程对外提供 `/mcp`、`/mcp/{服务}`、`/mcp/$smart`。上游可以是 stdio、HTTP、SSE、OpenAPI。 - **内置 `ylune`** — 控制台服务器列表里有一张不能添加/删除/改配置的只读卡片。工具是 `list_servers`、`list_tools`、`usage_summary`、`recent_failures`。只有**管理员 Access Key** 能在 `/mcp` 调用（短名或 `ylune-` 前缀都可以）；系统 Key、普通用户、Demo、仅后台管理员都不能调。这不是一个要再注册的上游进程。 - **按用户授权** — 管理员在用户页勾该用户能用的 MCP 和 tools。普通用户默认 `/mcp` = 自己的授权清单；空清单 = 零工具。管理员默认全部已启用服务（不含把 `ylune` 授权给别人）。 - **用户与 Access Key** — 创建 MCP 用户后系统才签发 Access Key。用户列表和编辑页随时可以再复制 Cursor / WorkBuddy 的 JSON，或 Codex 的 TOML（合并进 `~/.codex/config.toml`，不要整文件覆盖），也可以轮换 Key。仅后台管理员没有 Key。 - **控制台** — 服务器、用户、凭据中心、调试台、操作审计、设置、内置提示词 / 资源、日志与调用记录。私有化部署默认不展示外部市场。 - **凭据中心** — 一条凭据就是一个键值包，默认带出 HOST / PORT / TOKEN，绑定 MCP 可选且不改字段。平台会扫 MCP 配置里的 env / `${VAR}` 并在绑定区标明是否声明了变量；配置为空时仍可绑定。绑上之后，创建用户或管理员时能选它。同一页可对已绑凭据测试 `listTools`；测试或绑定成功后，服务器页显示在线并缓存工具。调用时覆盖该 MCP 的环境变量，不往工具参数里塞密文或租约 ID。主密钥是 `YLUNE_MASTER_KEY`。列表只显示变量名和「已配置」；管理员创建 / 编辑时明文可见，点编辑会载入已保存的值。多套环境请复制为新服务器并另建凭据，不要把多个地址堆在同一 MCP 上。 凭据值支持「文本 / 多行 / JSON」：JSON 可格式化并校验，多行适合 PEM 私钥和证书。原始文本（包含密码空格、换行及大整数文本）不会自动改写；只有点击格式化才调整 JSON 外部空白。编辑格式随凭据一起加密保存，重新打开恢复；运行时仍只注入字符串键值，不注入编辑元数据，不生成凭据文件。旧凭据无需迁移，未保存模式时根据字段名及内容选择编辑方式，可手动切换。单字段最多 64 KiB（UTF-8），最多 64 个字段，总键值大小最多 256 KiB；操作系统的环境变量限制可能更小，大清单应拆成独立实例。 例如接入 Kafka MCP，在凭据中心添加键 `KAFKA_TARGETS_JSON`，选择 JSON，将完整 targets 对象直接填入值；绑定服务器并授权用户后由月弦注入。该值不是文件路径，也不需要额外给 JSON 加一层引号。显示/隐藏按钮仅控制编辑器显示，列表仍不展示凭据值。 - **可选能力** — 智能路由（`$smart` + pgvector）、工具结果压缩、OAuth 2.0 授权服务器、Better Auth 第三方登录、PostgreSQL 配置库、CLI。 不是再写一套夜莺 / Jenkins / PostgreSQL 客户端，也不是 CMDB。具体只读工具在 DevOpsMCP；月弦负责收口、授权、对外。 ## 和 DevOpsMCP ``` 值班同学 │ ▼ WorkBuddy · Cursor · … │ 一段 HTTP MCP：url + Bearer ▼ ┌─────────────────────────────────────┐ │ 月弦（本仓库） │ │ 控制台 · 用户授权 · 用户 Key · /mcp │ └─────────────────────────────────────┘ │ stdio / HTTP 拉起上游 ▼ ┌─────────────────────────────────────┐ │ DevOpsMCP（独立仓库） │ │ nightingale · jenkins · postgres │ │ 只读工具，编一次，路径写进月弦「添加服务器」 │ └─────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ 夜莺 API Jenkins REST PostgreSQL ``` 1. 按 [DevOpsMCP](https://github.com/isYaoNoistu/DevOpsMCP) 编出三个二进制（`deploy/pack-linux.sh` 或 `pack-windows.cmd`），本机验收 `command` / `env` 能通。 2. 在月弦控制台把它们加成服务器（类型 STDIO，`command` 填月弦进程能看见的绝对路径）。Docker 月弦用 DevOpsMCP 的 `deploy/attach.sh` 自动注册。 3. 在用户页给普通用户勾需要的服务器和工具。 4. 用户把控制台给出的 JSON（Cursor / WorkBuddy）或 TOML（Codex）贴进智能体，只连月弦。 Linux 上若目录是 `/data/DevOpsMCP` + `/data/YLuneMCPHub`：月弦 `docker compose up`，再 `DevOpsMCP/deploy/attach.sh`。见 [docs/linux-deploy.md](docs/linux-deploy.md)。 DevOpsMCP 的凭据约定仍然成立：仓库和文档不写 Token；Jenkins / 夜莺 Token、PostgreSQL 口令只放运行环境或 `${ENV}`。 ## 怎么工作 - **配置在 PostgreSQL。** 仓库里的 `mcp_settings.json` 是空种子。本机没有 `DB_URL` 时，开发模式才写 `data/mcp_settings.dev.json`（不进 git）。生产必须设 `DB_URL`，迁走只迁库。见 [配置与数据](docs/config-and-data.md)。 - **热更新**：控制台改服务器、用户授权、开关后即时生效，不必为加一个工具重启网关。 - **调用权看该用户勾过的工具，不看「公开」标签。** 服务可见性只影响控制台谁能改配置；要让 `test` 调 Jenkins，必须在用户页给 `test` 勾 Jenkins 的工具。 - **系统 Key** 的 `all` / `groups` / `servers` / `custom` 不跟成员名单走，继续给流水线和机器人用。 ## 适配的智能体 月弦对外是 **HTTP MCP**（`url` + `Authorization: Bearer`），和 DevOpsMCP 的本机 stdio 不是同一种接法。 | 客户端 | 配置放哪 | 怎么接 | | ---------------- | ---------------------------- | ------------------------------------------------------------------- | | **WorkBuddy** | 用户级或项目 `mcp.json` | 用控制台选 JSON 再「复制内容」，或手写 `url` + `headers.Authorization` | | **Cursor** | `~/.cursor/mcp.json` 或项目级 | 同一份 JSON。保存后在 MCP 面板确认该服务是绿的 | | **Codex** | `~/.codex/config.toml` | 控制台选 TOML 复制，**合并**进该文件，不要整文件覆盖；写成 HTTP MCP：`url` + bearer，不是 `command` | | **Claude Code** | 用户级 MCP JSON | 同一套 `url` + Header | | **其它 MCP 客户端** | 以该产品文档为准 | 只要支持远程 / HTTP MCP，指向月弦的 `/mcp` 即可 | **通的是网关后面的工具，不是对话框习惯。** 查夜莺 / Jenkins / 库时，仍建议沿用 DevOpsMCP 仓库里的 Skill 顺序（先列表后详情，未明确要求则不写）。 ## 快速开始 需要 **Node 20+** 与 **pnpm**。 ```bash git clone https://github.com/isYaoNoistu/YLuneMCPHub.git cd YLuneMCPHub pnpm install ``` Windows 请拆开跑： ```bash pnpm backend:dev pnpm frontend:dev ``` 浏览器打开 http://127.0.0.1:5173 。后端 API 与 MCP 在 http://127.0.0.1:3000 。 开发默认账号 `admin` / `admin123`，**登录后立刻改密码**。没有 `DB_URL` 时配置才写在 `data/mcp_settings.dev.json`。真用请接 Postgres。 要用 Docker 整套拉起（Postgres + 月弦），见 [deploy/README.md](deploy/README.md)。默认构建多阶段精简 `runtime` 镜像，仍支持动态 `npx` / `uvx` 和 `/opt/mcp`；只有需要容器内浏览器、Rust 或 Docker daemon 时才选 `full`。仓库根目录不再放 compose。两仓都在 `/data`、还要挂 DevOpsMCP 时，见 [docs/linux-deploy.md](docs/linux-deploy.md)。 第一次把 Jenkins 给普通用户用： 1. 管理员登录 → **服务器** → 添加 STDIO 服务，`command` 指向 DevOpsMCP 编好的 `jenkins-mcp-server.exe`（或 Linux 二进制），环境变量按 [DevOpsMCP Jenkins README](https://github.com/isYaoNoistu/DevOpsMCP/blob/main/jenkins-mcp-server/README.md) 填。 2. **用户** → 创建 `test`（不要勾管理员），勾 Jenkins 需要的工具。系统会签发 Key。 3. 在用户列表随时 **复制 mcp.json** 交给对方。对方的 `/mcp` 只有勾过的工具。 字段怎么填、其它页签怎么用：见 [使用教程](docs/user-guide.md)。 ## 谁能调用什么 | 身份 | 默认 `/mcp` | 改授权 | | ------------- | ---------------------- | ------------- | | 管理员（开了 MCP 的 Key） | 全部已启用服务 + 内置 `ylune` | 可以 | | 普通用户（用户 Key） | 该用户勾过的工具；空清单则没有工具 | 不可以 | | 系统 Key `all` | 全部已启用上游服务，不含 `ylune` | 不可以 | ## 安全模型 ``` 控制台账号登录后台、改授权、改服务 + Access Key 只能调 /mcp，且只看到该用户勾过的工具 + Credential 加密进库，控制台永不回显明文 + 仓库禁止 Token / 密码 / 真实主机名 ``` - 开发默认密码只用于本机。对内发布前改掉，并关掉「免登录」。 - 环境变量用 `${JENKINS_API_TOKEN}` 这类占位，值放运行环境，不要写进 git。 - 智能路由、Better Auth、OAuth 服务器都是可选；用不到就保持关闭。 ## 测试阶段与免责 本仓库尚在**测试阶段**：用户授权、控制台字段、默认端点语义都可能改。按 [Apache License 2.0](LICENSE) 以「按现状」提供，**不构成对任何生产环境的承诺或担保**。 你自行部署、接入真实 MCP 与真实平台之后，因误授权、凭据配错、Agent 幻觉、上游变更或网络故障导致的影响，**由使用者自行承担**。上线前用只读上游账号验收；先查月弦用户授权、用户 Key 和上游 MCP，而不是默认是仓库的锅。 ## 什么时候用 · 什么时候不用 **适合**：已经有一份或几份 MCP（尤其是 DevOpsMCP）；希望多人共用一个入口；要按人裁工具；智能体只支持 HTTP MCP，或不想在每台电脑上维护三套 stdio。 **不适合**：还没有任何 MCP 可接（先去做 DevOpsMCP 或其它上游）；只要一个人在本机查夜莺 / Jenkins / 库（直接 stdio 更简单）；需要月弦去点「立即构建」或改告警（月弦不提供这些写操作，上游 DevOpsMCP 默认也没有写工具）。 ## 文档 | 先看这个 | 再往下 | | ----------------------------------------- | -------------------------------------------------------------------------------------------- | | [使用教程](docs/user-guide.md) | 登录、加服务器、用户授权、设置里每一项怎么填 | | [配置与数据](docs/config-and-data.md) | 配置进 PostgreSQL；JSON 不是运行时存储 | | [和 DevOpsMCP](#和-devopsmcp) | [DevOpsMCP 仓库](https://github.com/isYaoNoistu/DevOpsMCP) · 夜莺 / Jenkins / PostgreSQL 怎么编、怎么拿凭据 | | [适配的智能体](#适配的智能体) | 控制台用户页给出的 JSON / TOML | | [Docker 部署](deploy/README.md) | Compose、环境变量、验收、反代；Linux 两仓示例：[docs/linux-deploy.md](docs/linux-deploy.md) | ## 仓库布局 ```text src/ 网关与管理 API frontend/ 控制台（默认黑底，可切浅色） hub/ 控制台视觉标尺（静态） login/ 登录页视觉标尺（静态） locales/ 文案 docs/user-guide.md 字段级操作说明 docs/images/ 控制台截图（README 用） docs/config-and-data.md 配置进库、迁库 docs/linux-deploy.md /data 两仓：月弦 compose + DevOpsMCP attach deploy/ Docker Compose 整包与部署流程 examples/ 配置样例（无真实凭据） README.md 中文（GitHub 默认） README.en.md English ``` ## 许可证 仓库整体为 [Apache License 2.0](LICENSE)。第三方来源见 [NOTICE](NOTICE)。请不要提交生产 Token、密码、内网地址或客户名。