Repository navigation
Conversation
BREAKING CHANGE: In catalog mode, MCP servers are no longer connected at startup. Instead, indexing is triggered on the first search and runs in the background. Changes: - Remove LLM-based catalog generation (use pure schema parsing) - Remove catalog caching and persistence - Remove per-tool agent registration in catalog mode - Add lazy server indexing on first search - Add proper resource cleanup (resolve waiters before clearing) - Add fallback for missing toolMask (log warning, use allow-all) - Simplify config sync to stop + start Implementation: - start(): Skip connection in catalog mode, only initialize server records - search_mcp_tools: Trigger indexing on first search if _definitions is empty - _ensureIndexing(): Prevent duplicate indexing with _indexing flag - _indexAllServers(): Concurrently connect all servers and populate _definitions - stop(): Resolve all waiters before clearing to prevent Promise leaks - getRequiredToolCallMask(): Fallback to allow-all with warning Benefits: - Startup time: 15-30s → ~100ms (100-300x faster for 50 servers) - Startup memory: ~50MB → ~1MB - First search: +5-10s for indexing (one-time cost, concurrent) - Subsequent searches: unchanged (~50ms) - No LLM calls, no caching, simpler codebase Addresses reviewer feedback on PR ChatLunaLab#1005: - 'Why call the model' → Removed LLM generation - 'Catalog meaning unclear' → Clear lazy loading semantics - 'Entire MCP code can be simplified' → 621 lines vs 700+ in original PR
Walkthrough新增 MCP catalog 模式。服务通过固定网关按需搜索工具、加载 Schema 和调用工具。配置新增 ChangesMCP 目录懒加载
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant 模型
participant ChatLunaAgentMcpService
participant search_mcp_tools
participant invoke_mcp_tool
participant MCPClient
模型->>search_mcp_tools: 查询工具
search_mcp_tools->>ChatLunaAgentMcpService: 请求目录索引
ChatLunaAgentMcpService->>MCPClient: 按需连接并获取工具
MCPClient-->>search_mcp_tools: 返回工具摘要
search_mcp_tools-->>模型: 返回摘要
模型->>invoke_mcp_tool: 提交工具参数
invoke_mcp_tool->>ChatLunaAgentMcpService: 校验并调用
ChatLunaAgentMcpService->>MCPClient: 加载 Schema 并执行工具
MCPClient-->>invoke_mcp_tool: 返回结构化结果
invoke_mcp_tool-->>模型: 返回工具结果
Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (2)
packages/extension-agent/src/mcp/catalog.ts (1)
42-65: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value说明空
query会让所有工具得 100 分。
text.includes('')返回true。当value为空字符串时,每个工具都得到 100 分。当前唯一调用方在mcp.ts的 search 分支已拦截空 query,所以现在没有缺陷。如果以后新增调用方,排序结果会退化为字母序。建议在函数开头加一行if (!value) return 0,或在此处留一句注释说明前置条件。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/extension-agent/src/mcp/catalog.ts` around lines 42 - 65, Update scoreMcpCatalogTool so that after deriving the trimmed, lowercased value, it immediately returns 0 when value is empty; leave the existing scoring behavior unchanged for non-empty queries.packages/extension-agent/tests/mcp_catalog.spec.ts (1)
141-205: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win建议补充网关行为与索引重试的测试。
当前测试覆盖了评分、摘要/schema 分离、参数校验和关闭时序。以下 catalog 模式的核心路径没有覆盖:
search_mcp_tools的action="search"与action="schema"分支,包括工具遮罩过滤。_ensureIndexing在索引失败后能否重新触发索引。getRequiredToolCallMask在 mask 缺失时的行为。需要我生成这些测试用例吗?
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/extension-agent/tests/mcp_catalog.spec.ts` around lines 141 - 205, 补充 catalog 模式测试,覆盖 search_mcp_tools 的 action="search" 与 action="schema" 分支及工具遮罩过滤;增加 _ensureIndexing 索引失败后可再次触发的测试;验证 getRequiredToolCallMask 在缺少 mask 时的预期行为。复用现有测试中的服务与内部状态构造方式,并断言各路径的返回结果和调用行为。
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/extension-agent/src/service/mcp.ts`:
- Around line 79-82: Run Prettier on the affected MCP service code, including
the logger.info statement and the reported lines, and commit the resulting
indentation and line-wrapping changes without altering behavior.
- Around line 196-199: 更新 Mcp sync 方法:当 _prev.mcpServers 与 _next.mcpServers
相同时跳过 stop/start,仅重新注册受配置影响的工具;仅在 mcpServers 发生变化时执行完整重启,以避免保存单个工具的 enabled 或
timeout 时重连所有服务器。
- Around line 156-163: Update the reload flow around _registerGateways and
_runInBackground so catalog mode does not call reconnect for every server. In
catalog mode, reset each server to the same idle state used by start, keep
gateway registration, and allow the first search to trigger indexing; preserve
the existing reconnect behavior for non-catalog modes.
- Around line 1115-1129: Update getRequiredToolCallMask so a missing tool mask
in catalog mode returns a deny-all mask instead of the current allow-all
fallback, preventing gateway-registered search_mcp_tools and invoke_mcp_tool
calls from accessing every MCP tool. Preserve the existing mask lookup order and
return valid masks unchanged; if any allow-all fallback remains for other modes,
downgrade its logging and deduplicate it per session.
- Around line 1013-1024: Update _ensureIndexing so its finally cleanup resets
both _indexing and _indexingPromise, allowing a later call to start indexing
again after failure or completion. In the search path that checks
_definitions.size === 0 && !this._indexing, await the promise returned by
_ensureIndexing() before continuing, so retries complete before producing search
results.
In `@packages/extension-agent/tests/mcp_catalog.spec.ts`:
- Around line 132-134: Update the stop() timing assertions around the stopping
and closed checks, including the corresponding assertion near line 171, to yield
through enough asynchronous work to reach client.close(); use repeated
event-loop yields or a setTimeout-based macrotask rather than a single
Promise.resolve(). Preserve the expected closed === false result while stop() is
intentionally blocked.
---
Nitpick comments:
In `@packages/extension-agent/src/mcp/catalog.ts`:
- Around line 42-65: Update scoreMcpCatalogTool so that after deriving the
trimmed, lowercased value, it immediately returns 0 when value is empty; leave
the existing scoring behavior unchanged for non-empty queries.
In `@packages/extension-agent/tests/mcp_catalog.spec.ts`:
- Around line 141-205: 补充 catalog 模式测试,覆盖 search_mcp_tools 的 action="search" 与
action="schema" 分支及工具遮罩过滤;增加 _ensureIndexing 索引失败后可再次触发的测试;验证
getRequiredToolCallMask 在缺少 mask 时的预期行为。复用现有测试中的服务与内部状态构造方式,并断言各路径的返回结果和调用行为。
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: a6175932-6cf4-4fcb-8750-922479c7c39a
⛔ Files ignored due to path filters (2)
packages/extension-agent/src/locales/en-US.schema.ymlis excluded by!**/*.ymlpackages/extension-agent/src/locales/zh-CN.schema.ymlis excluded by!**/*.yml
📒 Files selected for processing (6)
packages/extension-agent/README.mdpackages/extension-agent/src/index.tspackages/extension-agent/src/mcp/catalog.tspackages/extension-agent/src/service/index.tspackages/extension-agent/src/service/mcp.tspackages/extension-agent/tests/mcp_catalog.spec.ts
| logger.info( | ||
| `MCP catalog mode initialized with ${this._servers.size} server(s). ` + | ||
| `Servers will be indexed on first search.` | ||
| ) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
修复 prettier 格式告警。
CodeFactor 在第 81 行、第 1119 行和第 1124 行报告 prettier 缩进/换行差异。请运行 prettier 格式化,避免 CI 失败。
🧰 Tools
🪛 GitHub Check: CodeFactor
[warning] 81-81: packages/extension-agent/src/service/mcp.ts#L81
Insert ···· (prettier/prettier)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/extension-agent/src/service/mcp.ts` around lines 79 - 82, Run
Prettier on the affected MCP service code, including the logger.info statement
and the reported lines, and commit the resulting indentation and line-wrapping
changes without altering behavior.
Source: Linters/SAST tools
| if (this.plugin.config.mcpToolMode === 'catalog') { | ||
| this._registerGateways() | ||
| } | ||
| this._runInBackground( | ||
| names.map((name) => this.reconnect(name)), | ||
| 'MCP reload' | ||
| ) | ||
| this.ctx.chatluna_agent?.refreshConsoleData() |
There was a problem hiding this comment.
🚀 Performance & Scalability | 🟠 Major | ⚡ Quick win
catalog 模式下 reload 会连接所有服务器,与懒加载目标冲突。
start 在 catalog 模式只把服务器置为 idle 并注册网关,不建立连接。但 reload 对所有服务器调用 this.reconnect(name),这会立即连接全部服务器。ChatLunaAgentService.reload 在 saveConfig 与 saveSkillsConfig 等路径被调用,因此 catalog 模式在任意配置保存后都会付出 15–30 秒的连接成本,失去懒加载收益。
请在 catalog 模式下改为只重置服务器状态并让首次搜索触发索引。
♻️ 建议修改
if (this.plugin.config.mcpToolMode === 'catalog') {
this._registerGateways()
+ for (const name of names) {
+ if (!this._servers.has(name)) {
+ this._servers.set(name, { state: 'idle', attempts: 0 })
+ }
+ }
+ this.ctx.chatluna_agent?.refreshConsoleData()
+ return
}
this._runInBackground(
names.map((name) => this.reconnect(name)),
'MCP reload'
)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/extension-agent/src/service/mcp.ts` around lines 156 - 163, Update
the reload flow around _registerGateways and _runInBackground so catalog mode
does not call reconnect for every server. In catalog mode, reset each server to
the same idle state used by start, keep gateway registration, and allow the
first search to trigger indexing; preserve the existing reconnect behavior for
non-catalog modes.
| async sync(_prev: McpConfig, _next: McpConfig) { | ||
| await this.stop() | ||
| await this.start() | ||
| } |
There was a problem hiding this comment.
🚀 Performance & Scalability | 🟠 Major | ⚡ Quick win
sync 改为全量 stop/start 会让局部配置修改重连所有服务器。
ChatLunaAgentService.saveMcpTool、saveMcpServer 和 removeMcpServer 都调用 mcp.sync。修改单个工具的 enabled 或 timeout 现在会断开并重连全部 MCP 服务器。在 eager 模式下,用户每次在 webui 保存一个工具开关都要等待全部服务器重新握手。
请至少在 _prev 与 _next 的 mcpServers 相同时跳过重启,只重新注册工具。
♻️ 建议修改
- async sync(_prev: McpConfig, _next: McpConfig) {
- await this.stop()
- await this.start()
+ async sync(prev: McpConfig, next: McpConfig) {
+ if (
+ JSON.stringify(prev.mcpServers) === JSON.stringify(next.mcpServers)
+ ) {
+ await this.reload()
+ return
+ }
+ await this.stop()
+ await this.start()
}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/extension-agent/src/service/mcp.ts` around lines 196 - 199, 更新 Mcp
sync 方法:当 _prev.mcpServers 与 _next.mcpServers 相同时跳过 stop/start,仅重新注册受配置影响的工具;仅在
mcpServers 发生变化时执行完整重启,以避免保存单个工具的 enabled 或 timeout 时重连所有服务器。
| private _ensureIndexing() { | ||
| if (this._indexing || this._indexingPromise) { | ||
| return this._indexingPromise | ||
| } | ||
|
|
||
| this._indexing = true | ||
| this._indexingPromise = this._indexAllServers() | ||
| this._indexingPromise.finally(() => { | ||
| this._indexing = false | ||
| }) | ||
| return this._indexingPromise | ||
| } |
There was a problem hiding this comment.
🩺 Stability & Availability | 🔴 Critical | ⚡ Quick win
索引失败后无法重试:_indexingPromise 从不清空。
_ensureIndexing 在 finally 中只重置 _indexing,保留 _indexingPromise。索引结束后,_indexingPromise 一直是一个已完成的 promise。
后果:如果首次索引时所有服务器都连接失败,_definitions 保持为空。之后每次搜索都进入 this._definitions.size === 0 && !this._indexing 分支并调用 _ensureIndexing(),但该方法因 _indexingPromise 非空而直接返回旧 promise,不会再次索引。catalog 模式因此永久返回空搜索结果,直到插件重启。
请在 finally 中清空 _indexingPromise,并让搜索路径 await _ensureIndexing() 的返回值。
🐛 建议修复
private _ensureIndexing() {
- if (this._indexing || this._indexingPromise) {
+ if (this._indexingPromise) {
return this._indexingPromise
}
this._indexing = true
- this._indexingPromise = this._indexAllServers()
- this._indexingPromise.finally(() => {
+ const promise = this._indexAllServers().finally(() => {
this._indexing = false
+ if (this._indexingPromise === promise) {
+ this._indexingPromise = undefined
+ }
})
+ this._indexingPromise = promise
return this._indexingPromise
}搜索路径同步调整:
- if (this._definitions.size === 0 && !this._indexing) {
+ if (this._definitions.size === 0) {
logger.info(
'First search detected, indexing all MCP servers in background...'
)
- this._ensureIndexing()
- }
-
- // 等待索引完成(如果正在进行)
- if (this._indexingPromise) {
- await this._indexingPromise
+ await this._ensureIndexing()
+ } else if (this._indexingPromise) {
+ await this._indexingPromise
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| private _ensureIndexing() { | |
| if (this._indexing || this._indexingPromise) { | |
| return this._indexingPromise | |
| } | |
| this._indexing = true | |
| this._indexingPromise = this._indexAllServers() | |
| this._indexingPromise.finally(() => { | |
| this._indexing = false | |
| }) | |
| return this._indexingPromise | |
| } | |
| private _ensureIndexing() { | |
| if (this._indexingPromise) { | |
| return this._indexingPromise | |
| } | |
| this._indexing = true | |
| const promise = this._indexAllServers().finally(() => { | |
| this._indexing = false | |
| if (this._indexingPromise === promise) { | |
| this._indexingPromise = undefined | |
| } | |
| }) | |
| this._indexingPromise = promise | |
| return this._indexingPromise | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/extension-agent/src/service/mcp.ts` around lines 1013 - 1024, Update
_ensureIndexing so its finally cleanup resets both _indexing and
_indexingPromise, allowing a later call to start indexing again after failure or
completion. In the search path that checks _definitions.size === 0 &&
!this._indexing, await the promise returned by _ensureIndexing() before
continuing, so retries complete before producing search results.
| function getRequiredToolCallMask(config?: RunnableConfig) { | ||
| const mask = (config?.configurable?.['toolMask'] ?? | ||
| config?.configurable?.['agentContext']?.['toolMask'] ?? | ||
| config?.configurable?.['subagentContext']?.['toolMask']) as | ||
| ToolMask | undefined | ||
| const callMask = mask?.toolCallMask ?? mask | ||
| if (!callMask) { | ||
| logger.warn( | ||
| 'MCP tool permission context is unavailable, falling back to allow-all mode. ' + | ||
| 'This may indicate the permission service is not initialized.' | ||
| ) | ||
| return { mode: 'all' as const, tools: [], allow: [], deny: [] } | ||
| } | ||
| return callMask | ||
| } |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# 确认 toolMask 在 agent / subagent 执行路径上是否总是被写入 configurable
rg -nP --type=ts -C4 "toolMask" packages/ -g '!**/node_modules/**'
rg -nP --type=ts -C4 "agentContext|subagentContext" packages/ -g '!**/node_modules/**' | head -60
ast-grep run --pattern 'applyToolMask($$$)' --lang typescript packages/Repository: ChatLunaLab/chatluna
Length of output: 50376
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Focused inspection of the MCP gateway registration/use path and mask handling.
sed -n '1,180p;1080,1145p;1150,1235p' packages/extension-agent/src/service/mcp.ts
# Locate registration points for MCP tools in extension-agent mcp.ts.
rg -n --type=ts -C5 "registerTools|registerTool|search_mcp_tools|invoke_mcp_tool|applyToolMask|createToolsRef" packages/extension-agent/src/service/mcp.tsRepository: ChatLunaLab/chatluna
Length of output: 14382
catalog 模式下 toolMask 丢失不应回退为 allow-all。
getRequiredToolCallMask 会读取 configurable.toolMask、agentContext.toolMask 或 subagentContext.toolMask,但 catalog 模式下 search_mcp_tools / invoke_mcp_tool 是通过 _registerGateways() 注册的,其 selector: () => true 对所有 agent 与子 agent 可见,缺少 mask 时会回退为 mode: 'all',让调用方可以通过网关列举并调用全部 MCP 工具。应改为缺失 mask 时拒绝调用;如果保留回退行为,需要降级并按会话去重日志。
🧰 Tools
🪛 GitHub Check: CodeFactor
[warning] 1119-1119: packages/extension-agent/src/service/mcp.ts#L1119
Replace ToolMask with |·ToolMask⏎······· (prettier/prettier)
[warning] 1124-1124: packages/extension-agent/src/service/mcp.ts#L1124
Insert ···· (prettier/prettier)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/extension-agent/src/service/mcp.ts` around lines 1115 - 1129, Update
getRequiredToolCallMask so a missing tool mask in catalog mode returns a
deny-all mask instead of the current allow-all fallback, preventing
gateway-registered search_mcp_tools and invoke_mcp_tool calls from accessing
every MCP tool. Preserve the existing mask lookup order and return valid masks
unchanged; if any allow-all fallback remains for other modes, downgrade its
logging and deduplicate it per session.
| const stopping = service.stop() | ||
| await Promise.resolve() | ||
| expect(closed).to.equal(false) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
该断言不能区分"正在等待"与"尚未执行到关闭步骤"。
await Promise.resolve() 只推进一个微任务。stop() 在到达 client.close() 之前有多个 await 点。因此 closed === false 即使在没有等待机制的实现里也可能成立。
建议改为多次让出事件循环,或用 setTimeout(resolve, 0) 等待宏任务,让断言真正验证阻塞行为。
💚 建议修改
const stopping = service.stop()
- await Promise.resolve()
+ await new Promise((resolve) => setTimeout(resolve, 0))
expect(closed).to.equal(false)第 171 行同样处理。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/extension-agent/tests/mcp_catalog.spec.ts` around lines 132 - 134,
Update the stop() timing assertions around the stopping and closed checks,
including the corresponding assertion near line 171, to yield through enough
asynchronous work to reach client.close(); use repeated event-loop yields or a
setTimeout-based macrotask rather than a single Promise.resolve(). Preserve the
expected closed === false result while stop() is intentionally blocked.
|
Closed in favor of updating the original PR #1005 with the same changes. |
Summary
Implements true lazy loading for MCP catalog mode:
Changes
Core Implementation
start(): Skip connection in catalog mode, only initialize server recordssearch_mcp_tools: Trigger concurrent indexing on first search_ensureIndexing(): Prevent duplicate indexing with state flag_indexAllServers(): Concurrently connect all servers and populate definitionscatalog.ts: Pure parser for tool metadata (no LLM)Fixes
_activeCallWaiters(prevents hanging Promises)allow-allmode with warning whentoolMaskis unavailable_indexingPromiseinstop()to prevent stale referencesPerformance
Context Impact
In catalog mode, the model sees:
search_mcp_tools,invoke_mcp_tool)Validation
npx tsc --noEmit -p packages/extension-agent/tsconfig.json # ✅ No errorsAddresses Reviewer Feedback
Migration
No breaking changes for users:
eagermode (default): unchanged behaviorcatalogmode: faster startup, same search/invoke flowSupersedes #1005