内容
# lampa-mcp-server
一个用于 [Lampa](https://github.com/yumata/lampa-source) 开源电视应用的 AI 辅助开发的 [MCP](https://modelcontextprotocol.io) 服务器。
它为 AI 代理（Claude, Cursor 等）提供结构化、只读的访问 Lampa 源代码树的能力 — 以便他们在进行更改之前了解仓库。
## 功能
服务器暴露了 **57 个工具** 和 **6 个资源**，跨越九个能力层：
| 层 | 文件 | 工具 | 目的 |
|---|---|---|---|
| 发现 | `discovery.ts` | 6 | 导航仓库结构，列出模块，搜索代码，读取文件 |
| 分析 | `analysis.ts` | 7 | 定位设置，API 调用，UI 组件，翻译，依赖关系图 |
| 规划 | `planning.ts` | 4 | 生成更改计划，影响分析，编辑目标，风险扫描 |
| 编辑 | `editing.ts` | 4 | 草拟补丁，搭建插件，生成钩子/设置模板 |
| 验证 | `validation.ts` | 4 | 质量检查，查找测试，解析构建命令，查询文档 |
| Lampa 深度 | `lampa_deep.ts` | 8 | Lampa 特定深度分析：提供者，事件，翻译，生命周期 |
| 高级 | `advanced.ts` | 8 | 文件读取，存储模式，事件总线映射，网络映射，模式指南 |
| Lampa 现代 | `lampa_modern.ts` | 10 | Maker 模块，CUB API（Lampa 子集），WebSocket，组件，设置，包装 |
| CUB API | `cub.ts` | 6 | 来自 Lampa 源代码的完整 CUB API 接口：目录，身份验证，同步，数据模型 |
### 工具
**发现**
- `repo_overview` — 总结应用结构，文件夹，入口点，插件和脚本
- `list_modules` — 列出任意子文件夹中的 JS/TS 模块
- `find_files` — 按名称模式或扩展名查找文件
- `search_code` — 使用 `ripgrep`（可用时）进行正则表达式/文本搜索，并提供文件：行预览
- `read_file_segment` — 读取任意仓库文件的特定行范围
- `list_scripts` — 显示 `package.json` 中的所有 NPM 脚本
**分析**
- `find_settings` — 定位 `Lampa.Settings.add` 和 `Lampa.Storage` 用例；可选按关键字过滤
- `find_api_calls` — 查找 `fetch`，`$.ajax` 和提供者集成
- `find_ui_component` — 按名称查找模板，组件和视图
- `find_translation_keys` —查找翻译密钥定义和用法，跨所有语言文件
- `find_styles_for_module` — 查找与模块或功能名称相关的 CSS/SCSS 文件
- `module_dependency_map` — 映射导入和反向依赖关系，并具有更改爆炸半径
- `find_feature` — 推断一个命名功能（播放器，目录，IPTV，搜索等）相关的所有文件
**规划**
- `plan_feature_change` — 分步实施计划（在 `draft_patch` 之前调用）
- `impact_analysis` — 目标文件引用计数和风险级别
- `suggest_edit_targets` — 功能请求的最小文件集和安全插入指南
- `risk_scan` — 检测耦合风险：全局事件，存储，共享模板，DOM 全局变量
**编辑**
- `draft_patch` — 有指导的补丁草稿，文件预览和 Lampa 模式（需要先调用 `plan_feature_change`）
- `insert_hook` — 为生命周期触发器查找最佳 `Lampa.Listener` 钩子点
- `add_setting` — 生成带有存储接线的切换/选择/输入设置模板
- `scaffold_plugin_integration` — 具有 `main.js`，CSS 和组件模板的完整插件文件夹脚手架
**验证**
- `run_grep_checks` — 扫描 TODO，`console.log` 残留，未定义的松散检查，硬编码字符串
- `list_related_tests` — 查找与模块或功能相关的规格文件
- `run_build_hint` — 从 `package.json` 解析正确的构建/开发/测试/ lint 命令
- `doc_lookup` — 搜索生成的文档或 README 以获取主题
**Lampa 深度**
- `plugin_deep_dive` — 单次调用分析插件文件夹：文件，Lampa API 用例，事件，设置，入口点预览
- `list_streaming_providers` — 目录所有在线流媒体提供者，基本 URL，方法和使用的 Lampa API
- `translation_coverage` — 比较所有语言文件与英文参考；显示覆盖率 % 和每种语言的缺失密钥
- `trace_event` — 跟踪 `Lampa.Listener` 事件整个代码库：谁发送，谁跟随
- `lampa_api_surface` — 提取完整的 `Lampa.*` 全局 API 接口：每个模块具有子方法和文件使用计数
- `list_templates` — 列出 `src/templates/` 中的所有 UI 模板；可选读取一个以检查 HTML 和数据绑定
- `generate_plugin_boilerplate` — 为选定的功能生成工作插件代码：设置，钩子，存储，语言密钥，IPTV
- `component_lifecycle` — 深度分析组件：生命周期方法，事件，API，存储，模板和设置
**高级**
- `read_file` — 读取完整文件（在 `max_lines` 处截断）；对大文件使用 `read_file_segment`
- `get_storage_schema` — 扫描所有 `Lampa.Storage.get/set` 调用；返回完整的键 → 默认值/读取器/写入器表
- `list_all_events` — 构建完整的 `Lampa.Listener` 事件总线映射：每个事件，侦听器计数，发射器计数，孤立检测
- `get_network_map` — 从任意范围提取所有硬编码 URL，基本 URL 变量和代理名称
- `validate_plugin` — 根据 10 个 Lampa 约定（IIFE，严格模式，`appready` 启动，无 `eval` 等）评估插件
- `extract_template_html` — 从 `src/templates/*.js` 提取实际 HTML 标记，CSS 类和数据绑定占位符
- `get_core_module` — 浏览和读取 `src/core/` 模块；调用时列出所有可用的模块（不带名称）
- `explain_lampa_pattern` — 模式参考指南，以实时源代码示例为后盾：`iife-plugin`，`storage`，`settings`，`events`，`component`，`request`，`template`，`activity`，`player-hook`
**Lampa 现代** （v3.0 架构）
- `maker_module_map` — 映射 Maker 类（Card，Main，Category，Line，...），模块/映射文件和生命周期钩子
- `cub_api_catalog` — 目录所有 CUB 云 REST 端点，具有方法和源文件
- `socket_protocol_map` — WebSocket 入站/出站方法，镜像和有效载体信封
- `activity_component_registry` — 所有 `Component.add` 注册和路由器路由
- `lampa_settings_flags` — `window.lampa_settings` 功能标志和平台覆盖
- `platform_packaging_guide` — 用于 web，webOS，Tizen，GitHub Pages，插件，文档的 gulp 目标
- `content_rows_api` — 所有 `ContentRows.add` 首页注入点
- `favorite_category_schema` —收藏/书签类别类型和时间线标记
- `manifest_mirrors_map` — cub_mirrors，soc_mirrors，cub_domain 解析逻辑
- `upgrade_migration_checker` — 在文件中检测废弃的 2.x API（Lampa.Card，InteractionMain 等）
**CUB API** （来自 [Lampa 源代码](temp/lampa-source) — [CUB 开发人员文档](https://cub.rip/developer/))
- `cub_api_catalog` — 从 Lampa 提取的完整 CUB API 目录（帐户，书签，时间线，AI，集合，TMDB 代理，插件，WebSocket）
- `cub_endpoint_detail` — 单个端点，具有源文件，代码上下文，功能门
- `cub_auth_guide` — 设备/添加登录，令牌/配置文件标头，Permit 门控，Premium，镜像
- `cub_data_models` — 书签类型，时间线存储，收藏类别，同步形状
- `cub_sync_guide` — 书签/时间线/存储同步：REST 转储/更改日志 + WebSocket
- `cub_timeline_hash_guide` — 用于观看进度密钥的 Utils.hash() 算法
### 资源
| URI | 描述 |
|---|---|
| `repo://overview` | 顶级目录列表 |
| `repo://scripts` | NPM 脚本作为 JSON |
| `docs://index` | 生成的 JSDoc（需要 `npm run doc` 在 Lampa 仓库中） |
| `settings://catalog` | 仓库中所有 `Lampa.Settings.add` 注册 |
| `api://integrations` | 所有 API 和网络调用站点 |
| `cub://lampa-api` | 从 Lampa 源代码提取的 CUB API 端点 JSON |
## 要求
- Node.js 20+
- [Lampa 源代码仓库](https://github.com/yumata/lampa-source) 的本地副本
- 可选：[`ripgrep`](https://github.com/BurntSushi/ripgrep) (`rg`) 用于更快的搜索 — 如果不存在，则回退到纯 Node
## 设置
```bash
git clone https://github.com/your-username/lampa-mcp-server
cd lampa-mcp-server
npm install
npm run build
```
通过环境变量设置到您的 Lampa 检出的路径：
```bash
export LAMPA_REPO_PATH=/path/to/lampa-source
```
或在启动服务器时内联传递：
```bash
LAMPA_REPO_PATH=/path/to/lampa-source node dist/index.js
```
## 连接到 Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"lampa-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/lampa-mcp-server/dist/index.js"],
"env": {
"LAMPA_REPO_PATH": "/absolute/path/to/lampa-source"
}
}
}
}
```
## 连接到 Cursor
添加到您的项目中的 `.cursor/mcp.json` （或全局 `~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"lampa-mcp-server": {
"command": "node",
"args": ["/absolute/path/to/lampa-mcp-server/dist/index.js"],
"env": {
"LAMPA_REPO_PATH": "/absolute/path/to/lampa-source"
}
}
}
}
```
## 推荐的代理工作流程
服务器强制执行一个刻意的两步合同：**先规划，再修补**。
```
repo_overview → find_feature → module_dependency_map
→ plan_feature_change → draft_patch
```
对于深度插件工作，从单一调用分析工具开始：
```
plugin_deep_dive → maker_module_map → cub_api_catalog
→ plan_feature_change → draft_patch → validate_plugin
```
对于 CUB 帐户/同步工作：
```
cub_auth_guide → cub_api_catalog → cub_sync_guide
→ cub_data_models → cub_endpoint_detail
```
**最佳结果系统：**
> 您是 Lampa 源代码仓库的 AI 编码代理。
> 始终通过 MCP 工具收集上下文：概述，相关模块，设置，API 调用和依赖关系图。
> 不要发明项目结构或框架模式。
> 在编写代码之前，生成：影响文件，每个文件的原因，实现步骤，风险和验证检查。
> 在生成代码时，请保留目标文件中使用的命名，样式和周围模式。
## 项目结构
```
src/
├── index.ts # 服务器入口点
├── config.ts # LAMPA_REPO_PATH + CUBCTL_PATH 配置
├── utils/
│ ├── fs.ts # 文件系统帮助程序
│ ├── search.ts # ripgrep + Node 备用搜索
│ ├── lampa.ts # Lampa 特定模式，功能映射，风险模式
│ ├── lampa_deep.ts # 深度分析实用程序（事件，生命周期，提供者）
│ ├── lampa_modern.ts # Lampa 3.0 架构提取器（Maker，CUB 子集，套接字）
│ └── cub.ts # 从 Lampa 源代码中提取 CUB API （扫描器 + 元数据）
├── tools/
│ ├── discovery.ts # 阶段 1 — 仓库导航（6 个工具）
│ ├── analysis.ts # 阶段 2 — Lampa 理解（7 个工具）
│ ├── planning.ts # 阶段 3 — 更改规划（4 个工具）
│ ├── editing.ts # 阶段 4 — 辅助编辑（4 个工具）
│ ├── validation.ts # 阶段 5 — 质量检查（4 个工具）
│ ├── lampa_deep.ts # Lampa 特定深度分析（8 个工具）
│ ├── advanced.ts # 文件 I/O，模式，模式指南（8 个工具）
│ ├── lampa_modern.ts # Lampa 3.0 架构工具（10 个工具）
│ └── cub.ts # 从 Lampa 源代码中提取 CUB API （6 个工具）
└── resources/
└── index.ts # MCP 资源（6 个只读稳定上下文端点）
```
## 开发
```bash
npm run build # 编译 TypeScript → dist/
npm run dev # 直接使用 ts-node 运行
npm start # 运行编译后的 dist/index.js
npm run typecheck # 类型检查而不发出
npm run lint # ESLint
npm run lint:fix # ESLint 自动修复
npm run format # Prettier 写入
npm run format:check # Prettier 检查（CI）
```
## 许可证
MIT
