dsh-vscode-mode 0.1.10 → 0.1.11

package/src/mcp.ts

@@ -0,0 +1,123 @@
+/**
+ * dsh-vscode-mode host — MCP 运行时管理适配层。
+ * 只操作已装配的 @deepseek-ai/dsh-mcp-client loader entry，不在浏览器侧连接 MCP。
+ * 作者 ddj 2026年08月22号
+ */
+import type { MpcConfig, MpcServer, MpcTool } from './shared/mcp.js'
+import type { Ctx } from './store.js'
+
+const MCP_PACKAGE = '@deepseek-ai/dsh-mcp-client'
+/** 项目级 MCP 的 loader entry id 固定前缀（区分 profile 全局 MCP；注意 loader id 不能用 ':' 分隔，故用 '.'）。 */
+export const PROJECT_ENTRY_PREFIX = 'vsm-mcp.'
+const LEGACY_PROJECT_PREFIX = 'vsm-mcp:'
+
+/** 判断新旧格式项目 entry id，避免旧残留被显示为全局 MCP。 */
+export function isProjectEntryId(id: string): boolean {
+  return id.startsWith(PROJECT_ENTRY_PREFIX) || id.startsWith(LEGACY_PROJECT_PREFIX)
+}
+
+/** 列出当前 loader 中的 MCP entry。 */
+function entriesOf(ctx: Ctx): any[] {
+  const loader = ctx.get('loader')
+  if (!loader || typeof loader.entries !== 'function') return []
+  return [...loader.entries()].filter((entry) => entry?.options?.name === MCP_PACKAGE)
+}
+export { entriesOf }
+
+/** 脱敏配置并保留可编辑字段的存在性。 */
+export function publicConfig(config: Record<string, unknown>): MpcConfig {
+  const out = { ...config } as Record<string, unknown>
+  if (out.env && typeof out.env === 'object') out.env = Object.fromEntries(Object.keys(out.env as object).map((key) => [key, '••••••']))
+  if (out.headers && typeof out.headers === 'object') out.headers = Object.fromEntries(Object.keys(out.headers as object).map((key) => [key, '••••••']))
+  return out as unknown as MpcConfig
+}
+
+/** 从工具注册表读取服务器命名空间下的工具摘要。 */
+export function toolsOf(ctx: Ctx, serverName: string): MpcTool[] {
+  const tools = ctx.get('tools')
+  const view = tools?.view?.(void 0)
+  const visible = view?.visible
+  if (!(visible instanceof Map)) return []
+  const prefix = `mcp__${serverName}__`
+  return [...visible.entries()].filter(([name]) => String(name).startsWith(prefix)).map(([name, definition]) => ({
+    name: String(name).slice(prefix.length),
+    description: typeof definition?.description === 'string' ? definition.description : undefined,
+  }))
+}
+
+/** 将 loader entry 映射为设置页摘要。 */
+export function serverOf(ctx: Ctx, entry: any): MpcServer {
+  const config = (entry.options?.config ?? {}) as Record<string, unknown>
+  const serverName = typeof config.serverName === 'string' ? config.serverName : entry.options?.id ?? 'unknown'
+  const tools = toolsOf(ctx, serverName)
+  const state = entry.fiber?.state
+  return {
+    id: String(entry.id ?? entry.options?.id ?? serverName),
+    serverName,
+    enabled: entry.disabled !== true,
+    transport: config.transport === 'streamable-http' ? 'streamable-http' : 'stdio',
+    config: publicConfig(config),
+    status: state === 2 ? 'connected' : state === 1 ? 'connecting' : 'error',
+    toolCount: tools.length,
+    tools,
+    error: state === 3 ? 'MCP 插件未正常运行' : undefined,
+  }
+}
+
+/** 校验 MCP 配置。 */
+export function validateConfig(config: MpcConfig): void {
+  if (!/^[A-Za-z0-9_-]{1,32}$/.test(config.serverName)) throw new Error('serverName 只能包含字母、数字、下划线和连字符（最多 32 位）')
+  if (config.transport === 'stdio' && !config.command?.trim()) throw new Error('stdio MCP 必须填写 command')
+  if (config.transport === 'streamable-http' && !/^https?:\/\//.test(config.url ?? '')) throw new Error('HTTP MCP 必须填写 http(s) URL')
+}
+
+/** 列出全局（profile）MCP 服务，过滤掉新旧格式的项目级条目。 */
+export function listMcp(ctx: Ctx): { servers: MpcServer[] } {
+  return { servers: entriesOf(ctx).filter((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? ''))).map((entry) => serverOf(ctx, entry)) }
+}
+
+/** 保存 MCP 服务配置并触发 loader 热更新。 */
+export async function saveMcp(ctx: Ctx, config: MpcConfig): Promise<MpcServer> {
+  validateConfig(config)
+  const loader = ctx.get('loader')
+  if (!loader) throw new Error('缺少 loader 服务')
+  const existing = entriesOf(ctx).find((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? '')) && entry.options?.config?.serverName === config.serverName)
+  if (existing) {
+    await loader.update(existing.id, { config: { ...config } })
+    return serverOf(ctx, loader.resolve(existing.id))
+  }
+  const id = await loader.create({ name: MCP_PACKAGE, config: { ...config } })
+  return serverOf(ctx, loader.resolve(id))
+}
+
+/** 删除 MCP 服务。 */
+export async function removeMcp(ctx: Ctx, id: string): Promise<void> {
+  const loader = ctx.get('loader')
+  if (!loader) throw new Error('缺少 loader 服务')
+  const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id)
+  if (!entry) throw new Error('MCP 服务不存在')
+  await loader.remove(entry.id)
+}
+
+/** 切换 MCP 服务启用状态。 */
+export async function toggleMcp(ctx: Ctx, id: string, enabled: boolean): Promise<MpcServer> {
+  const loader = ctx.get('loader')
+  if (!loader) throw new Error('缺少 loader 服务')
+  const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id)
+  if (!entry) throw new Error('MCP 服务不存在')
+  await loader.update(entry.id, { disabled: !enabled })
+  return serverOf(ctx, loader.resolve(entry.id))
+}
+
+/** 重新加载 MCP 服务。 */
+export async function refreshMcp(ctx: Ctx, id: string): Promise<MpcServer> {
+  const loader = ctx.get('loader')
+  if (!loader) throw new Error('缺少 loader 服务')
+  const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id)
+  if (!entry) throw new Error('MCP 服务不存在')
+  await loader.update(entry.id, { config: { ...(entry.options?.config ?? {}) } })
+  return serverOf(ctx, loader.resolve(entry.id))
+}
+
+export type { MpcConfig, MpcServer }
+export const mcpPackageName = MCP_PACKAGE

package/src/mcpIsolation.ts

@@ -0,0 +1,160 @@
+/**
+ * dsh-vscode-mode host — 项目 MCP 的 agent 级隔离。
+ * 项目 MCP 连接仍由 Host 维护，但每个 agent 只继承当前 workspace 的项目工具；
+ * tools.restrict() 负责模型可见性，tools.guard() 负责执行层兜底拒绝。
+ * 作者 ddj 2026年08月22号
+ */
+import { PROJECT_ENTRY_PREFIX, entriesOf } from './mcp.js'
+import { hashWorkspace } from './mcpProject.js'
+import type { Ctx } from './store.js'
+
+const LEGACY_PREFIX = 'vsm-mcp:'
+const UNKNOWN_PROJECT = '__unknown_project__'
+
+type ToolProjects = Map<string, string>
+type AgentState = { dispose?: () => void; denyKey: string }
+
+/** 统一 workspace 路径，供 cwd 父路径匹配。 */
+export function normalizePath(path: string): string {
+  const value = String(path ?? '').replace(/\\/g, '/').replace(/\/+/g, '/')
+  return value.replace(/\/$/, '').toLowerCase()
+}
+
+/** 在已注册 workspace 中匹配 cwd，优先最长父路径。 */
+export function matchWorkspace(cwd: string | undefined, paths: string[]): string | undefined {
+  if (!cwd) return undefined
+  const target = normalizePath(cwd)
+  const matches = paths.filter((path) => {
+    const root = normalizePath(path)
+    return target === root || target.startsWith(root + '/')
+  })
+  matches.sort((a, b) => normalizePath(b).length - normalizePath(a).length)
+  return matches[0]
+}
+
+/** 根据 entry id 判断是否为新旧格式项目 MCP。 */
+export function isProjectEntry(id: string): boolean {
+  return id.startsWith(PROJECT_ENTRY_PREFIX) || id.startsWith(LEGACY_PREFIX)
+}
+
+/** 从项目 entry id 解析 workspace hash。 */
+function entryHash(id: string): string | undefined {
+  if (id.startsWith(PROJECT_ENTRY_PREFIX)) return id.slice(PROJECT_ENTRY_PREFIX.length).split('.')[0]
+  if (id.startsWith(LEGACY_PREFIX)) return id.slice(LEGACY_PREFIX.length).split(':')[0]
+  return undefined
+}
+
+/** 返回一个 agent 不应继承的项目工具名。 */
+export function denyTools(toolProjects: ToolProjects, currentPath: string | undefined): string[] {
+  return [...toolProjects.entries()].filter(([, owner]) => owner !== currentPath).map(([name]) => name).sort()
+}
+
+/** 从 loader entry 和工具注册表建立工具到项目路径的映射。 */
+function projectTools(ctx: Ctx): ToolProjects {
+  const result: ToolProjects = new Map()
+  const registry = ctx.get('workspaceRegistry')
+  const workspaces = registry?.list?.() ?? []
+  const byHash: Map<string, string> = new Map(workspaces.map((ws: { path: string }) => [hashWorkspace(ws.path), ws.path] as [string, string]))
+  const visible = ctx.get('tools')?.view?.(void 0)?.visible
+  if (!(visible instanceof Map)) return result
+  for (const entry of entriesOf(ctx)) {
+    const id = String(entry.id ?? entry.options?.id ?? '')
+    if (!isProjectEntry(id)) continue
+    const hash = entryHash(id)
+    const owner = hash ? byHash.get(hash) ?? UNKNOWN_PROJECT : UNKNOWN_PROJECT
+    const serverName = entry.options?.config?.serverName
+    if (typeof serverName !== 'string') continue
+    const prefix = `mcp__${serverName}__`
+    for (const name of visible.keys()) if (String(name).startsWith(prefix)) result.set(String(name), owner)
+  }
+  return result
+}
+
+/** 取得 agent 当前 cwd 所属 workspace。 */
+function agentWorkspace(ctx: Ctx, agent: any): string | undefined {
+  const cwd = agent?.session?.header?.cwd
+  const paths = (ctx.get('workspaceRegistry')?.list?.() ?? []).map((ws: { path: string }) => ws.path)
+  return matchWorkspace(cwd, paths)
+}
+
+/** 同步一个 agent 的项目工具 deny 列表。 */
+function syncAgent(ctx: Ctx, state: AgentState, agent: any, tools: ToolProjects): void {
+  const current = agentWorkspace(ctx, agent)
+  const denied = denyTools(tools, current)
+  const nextKey = denied.join('\n')
+  if (state.denyKey === nextKey) return
+  state.dispose?.()
+  state.dispose = undefined
+  if (denied.length > 0) {
+    try {
+      state.dispose = agent.ctx.tools.restrict({ deny: denied })
+    } catch (error) {
+      ctx.logger?.warn?.('[dsh-vscode-mode] MCP agent restriction failed: ' + String(error))
+      return
+    }
+  }
+  state.denyKey = nextKey
+}
+
+/** 为当前 Host 安装项目 MCP 的 agent restriction 与执行 guard。 */
+export function installIsolation(ctx: Ctx): void {
+  const tools = ctx.get('tools')
+  const agents = ctx.get('agents')
+  if (!tools || !agents) return
+  const states = new Map<any, AgentState>()
+  let toolProjects = projectTools(ctx)
+  let scheduled = false
+  let syncing = false
+
+  const syncAll = () => {
+    if (syncing) return
+    syncing = true
+    try {
+      toolProjects = projectTools(ctx)
+      for (const agent of agents.list?.() ?? []) {
+        const state = states.get(agent) ?? { denyKey: '' }
+        states.set(agent, state)
+        syncAgent(ctx, state, agent, toolProjects)
+      }
+    } finally {
+      syncing = false
+    }
+  }
+  const scheduleSync = () => {
+    if (scheduled) return
+    scheduled = true
+    queueMicrotask(() => {
+      scheduled = false
+      syncAll()
+    })
+  }
+  const onCreated = ctx.on('agent/created', ({ agent }: { agent: any }) => {
+    const state = { denyKey: '' }
+    states.set(agent, state)
+    syncAgent(ctx, state, agent, toolProjects)
+  })
+  const onDisposed = ctx.on('agent/disposed', ({ agent }: { agent: any }) => {
+    const state = states.get(agent)
+    state?.dispose?.()
+    states.delete(agent)
+  })
+  const onToolsChange = ctx.on('tools/change', scheduleSync)
+  const stopGuard = tools.guard((exec: any) => {
+    const owner = toolProjects.get(String(exec?.name ?? ''))
+    if (!owner) return undefined
+    const current = agentWorkspace(ctx, exec.agent)
+    if (owner === current) return undefined
+    return current === undefined
+      ? '项目 MCP 需要在已注册工作区的对话中使用'
+      : '已拒绝：当前对话工作区不能使用其他项目的 MCP'
+  })
+  syncAll()
+  ctx.effect(() => () => {
+    onCreated?.()
+    onDisposed?.()
+    onToolsChange?.()
+    stopGuard?.()
+    for (const state of states.values()) state.dispose?.()
+    states.clear()
+  }, 'vscode-mode:mcp-isolation')
+}

package/src/mcpProject.ts

@@ -0,0 +1,258 @@
+/**
+ * dsh-vscode-mode host — 项目级 MCP 管理。
+ * 配置以项目根目录 .mcp.json（mcpServers 格式，对齐 Claude Code/Cursor）存储；
+ * 工具经 loader 动态激活（entry id 带 PROJECT_ENTRY_PREFIX，全局生效）。
+ * 重启后由本项目从各 .mcp.json 恢复激活；.mcp.json 为持久真相，reconcile 以文件为准。
+ * 作者 ddj 2026年08月22号
+ */
+import { createHash } from 'node:crypto'
+import { PROJECT_ENTRY_PREFIX, entriesOf, serverOf, validateConfig } from './mcp.js'
+import type { MpcConfig, MpcProject, MpcServer } from './shared/mcp.js'
+import type { Ctx } from './store.js'
+
+const FILE_NAME = '.mcp.json'
+
+/** 校验项目路径属于 DSH 已注册 workspace，避免 RPC 写入任意目录。 */
+function requireWorkspace(ctx: Ctx, workspacePath: string): { path: string; title?: string } {
+  const workspace = (ctx.get('workspaceRegistry')?.list?.() ?? []).find((item: { path: string }) => item.path === workspacePath)
+  if (!workspace) throw new Error('项目未注册为 DSH workspace，不能管理项目 MCP')
+  return workspace
+}
+
+/** 用户显式 GUI 管理操作的写策略：danger-full-access（写入路径固定为 workspacePath/.mcp.json）。 */
+function fullPolicy(ctx: Ctx): unknown {
+  const svc = ctx.get('sandboxPolicy')
+  if (!svc || typeof svc.resolve !== 'function') return undefined
+  return svc.resolve({ mode: 'danger-full-access' })
+}
+
+/** workspace 路径 → 确定性短哈希（entry id 归属段，重启后稳定可解码）。 */
+export function hashWorkspace(path: string): string {
+  return createHash('sha1').update(path).digest('hex').slice(0, 10)
+}
+
+/** 项目 MCP 的 loader entry id：vsm-mcp.<pathHash>.<serverName>（loader id 不能用冒号）。 */
+export function projectEntryId(workspacePath: string, serverName: string): string {
+  return PROJECT_ENTRY_PREFIX + hashWorkspace(workspacePath) + '.' + serverName
+}
+
+/** 读取项目 .mcp.json 顶层对象（缺失 → 空；非法 → 抛错带文案）。 */
+async function readProjectJson(ctx: Ctx, workspacePath: string): Promise<Record<string, unknown>> {
+  const fs = ctx.get('fs')
+  if (!fs) throw new Error('缺少 fs 服务')
+  const target = await fs.resolve(FILE_NAME, { cwd: workspacePath })
+  let text: string
+  try {
+    text = await fs.readText(target)
+  } catch (error) {
+    return {}
+  }
+  let data: unknown
+  try {
+    data = JSON.parse(text)
+  } catch (error) {
+    throw new Error('.mcp.json 解析失败：' + String(error))
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) throw new Error('.mcp.json 顶层必须是对象')
+  return data as Record<string, unknown>
+}
+
+/** 读取并校验 .mcp.json 的 mcpServers 映射（纯函数，可单测）。 */
+export function serversOf(data: Record<string, unknown>): Record<string, Record<string, unknown>> {
+  const raw = data.mcpServers
+  if (raw === undefined) return {}
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('.mcp.json 的 mcpServers 必须是对象')
+  const out: Record<string, Record<string, unknown>> = {}
+  for (const [name, value] of Object.entries(raw)) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) continue
+    out[name] = value as Record<string, unknown>
+  }
+  return out
+}
+
+/** 把 .mcp.json 单条 server 定义归一化为 MpcConfig（缺传输必填 → null，纯函数可单测）。 */
+export function configFromDef(def: Record<string, unknown> | undefined, serverName: string): MpcConfig | null {
+  if (!def) return null
+  const transport = typeof def.url === 'string' ? 'streamable-http' : 'stdio'
+  const config: MpcConfig = { serverName, transport }
+  if (transport === 'stdio') {
+    config.command = typeof def.command === 'string' ? def.command : ''
+    config.args = Array.isArray(def.args) ? def.args.map(String) : []
+    if (typeof def.cwd === 'string') config.cwd = def.cwd
+    if (def.env && typeof def.env === 'object') config.env = Object.fromEntries(Object.entries(def.env as Record<string, unknown>).map(([k, v]) => [k, String(v)]))
+  } else {
+    config.url = def.url as string
+    if (def.headers && typeof def.headers === 'object') config.headers = Object.fromEntries(Object.entries(def.headers as Record<string, unknown>).map(([k, v]) => [k, String(v)]))
+  }
+  if (typeof def.toolCallTimeoutMs === 'number') config.toolCallTimeoutMs = def.toolCallTimeoutMs
+  return config
+}
+
+/** 写回 .mcp.json（保留顶层未知字段与其余 mcpServers，仅改目标 serverName）。 */
+async function writeProjectJson(ctx: Ctx, workspacePath: string, data: Record<string, unknown>, mcpServers: Record<string, Record<string, unknown>>): Promise<void> {
+  const fs = ctx.get('fs')
+  if (!fs) throw new Error('缺少 fs 服务')
+  const target = await fs.resolve(FILE_NAME, { cwd: workspacePath })
+  const next = { ...data, mcpServers }
+  await fs.writeText(target, JSON.stringify(next, null, 2) + '\n', void 0, void 0, fullPolicy(ctx))
+}
+
+/** 查重：目标 serverName 是否已被其他 loader entry（全局或他项目）占用。 */
+function findConflict(ctx: Ctx, workspacePath: string, serverName: string): string | null {
+  const ownId = projectEntryId(workspacePath, serverName)
+  for (const entry of entriesOf(ctx)) {
+    if (String(entry.id ?? entry.options?.id ?? '') === ownId) continue
+    if (entry.options?.config?.serverName === serverName) {
+      return 'serverName "' + serverName + '" 已被另一个 MCP 使用（全局或其他项目），请换一个名称'
+    }
+  }
+  return null
+}
+
+/** 激活一个项目 MCP：校验 + 查重 + loader.create。 */
+export async function activateProjectMcp(ctx: Ctx, workspacePath: string, config: MpcConfig): Promise<MpcServer> {
+  validateConfig(config)
+  const conflict = findConflict(ctx, workspacePath, config.serverName)
+  if (conflict) throw new Error(conflict)
+  const loader = ctx.get('loader')
+  if (!loader) throw new Error('缺少 loader 服务')
+  const id = projectEntryId(workspacePath, config.serverName)
+  const existing = entriesOf(ctx).find((entry) => String(entry.id ?? entry.options?.id ?? '') === id)
+  if (existing) {
+    await loader.update(existing.id, { config: { ...config } })
+    return serverOf(ctx, loader.resolve(existing.id))
+  }
+  const created = await loader.create({ id, name: '@deepseek-ai/dsh-mcp-client', config: { ...config } })
+  const entry = entriesOf(ctx).find((candidate) => String(candidate.id ?? candidate.options?.id ?? '') === id)
+  if (!entry) throw new Error('MCP 已创建但未能找到 entry（id=' + id + '）')
+  return serverOf(ctx, entry)
+}
+
+/** 停用一个项目 MCP（按 entry id）。 */
+export async function deactivateMcp(ctx: Ctx, entryId: string): Promise<void> {
+  const loader = ctx.get('loader')
+  if (!loader) throw new Error('缺少 loader 服务')
+  const entry = entriesOf(ctx).find((candidate) => String(candidate.id ?? candidate.options?.id ?? '') === entryId)
+  if (!entry) return
+  await loader.remove(entry.id)
+}
+
+/** 以 .mcp.json 为真相 reconcile 该项目的激活状态（幂等）。 */
+export async function reconcileProject(ctx: Ctx, workspacePath: string): Promise<void> {
+  const data = await readProjectJson(ctx, workspacePath)
+  const fileServers = new Set(Object.keys(serversOf(data)))
+  const prefix = PROJECT_ENTRY_PREFIX + hashWorkspace(workspacePath) + '.'
+  for (const entry of entriesOf(ctx)) {
+    const id = String(entry.id ?? entry.options?.id ?? '')
+    if (!id.startsWith(prefix)) continue
+    const serverName = id.slice(prefix.length)
+    if (fileServers.has(serverName)) continue
+    await deactivateMcp(ctx, id)
+  }
+  for (const serverName of fileServers) {
+    const config = await configOfServer(ctx, workspacePath, serverName)
+    if (config === null) continue
+    const id = projectEntryId(workspacePath, serverName)
+    if (entriesOf(ctx).some((entry) => String(entry.id ?? entry.options?.id ?? '') === id)) continue
+    await activateProjectMcp(ctx, workspacePath, { ...config, serverName })
+  }
+}
+
+/** 把 .mcp.json 单条 server 定义归一化为 MpcConfig（缺传输必填 → null）。 */
+async function configOfServer(ctx: Ctx, workspacePath: string, serverName: string): Promise<MpcConfig | null> {
+  const data = await readProjectJson(ctx, workspacePath)
+  return configFromDef(serversOf(data)[serverName], serverName)
+}
+
+/** 单个项目的完整视图（fileData + 激活状态合并）。 */
+async function projectOf(ctx: Ctx, workspacePath: string, title: string): Promise<MpcProject> {
+  const fs = ctx.get('fs')
+  if (!fs) return { workspacePath, title, servers: [], source: 'project' }
+  try {
+    const target = await fs.resolve(workspacePath)
+    const info = await fs.stat(target)
+    if (!info || info.type !== 'directory') return { workspacePath, title, servers: [], source: 'project', missingDir: true }
+  } catch (error) {
+    return { workspacePath, title, servers: [], source: 'project', missingDir: true }
+  }
+  await reconcileProject(ctx, workspacePath)
+  let servers: MpcServer[] = []
+  let fileError: string | undefined
+  try {
+    const data = await readProjectJson(ctx, workspacePath)
+    const prefix = PROJECT_ENTRY_PREFIX + hashWorkspace(workspacePath) + '.'
+    servers = entriesOf(ctx).filter((entry) => String(entry.id ?? entry.options?.id ?? '').startsWith(prefix)).map((entry) => serverOf(ctx, entry))
+    servers.sort((a, b) => (a.serverName < b.serverName ? -1 : 1))
+  } catch (error) {
+    fileError = String(error)
+  }
+  return { workspacePath, title, servers, source: 'project', fileError }
+}
+
+/** 列出全部项目及其项目级 MCP。 */
+export async function listProjects(ctx: Ctx): Promise<{ projects: MpcProject[] }> {
+  const registry = ctx.get('workspaceRegistry')
+  const workspaces = registry?.list?.() ?? []
+  const projects: MpcProject[] = []
+  for (const ws of workspaces) projects.push(await projectOf(ctx, ws.path, ws.title ?? ''))
+  return { projects }
+}
+
+/** 保存（新增/更新）一个项目 MCP：写 .mcp.json → 激活。 */
+export async function projectSave(ctx: Ctx, workspacePath: string, serverName: string, config: MpcConfig): Promise<MpcProject> {
+  const workspace = requireWorkspace(ctx, workspacePath)
+  validateConfig({ ...config, serverName })
+  const conflict = findConflict(ctx, workspacePath, serverName)
+  if (conflict) throw new Error(conflict)
+  const data = await readProjectJson(ctx, workspacePath)
+  const servers = serversOf(data)
+  const next = { ...config } as unknown as Record<string, unknown>
+  delete next.serverName
+  delete next.transport
+  delete next.disabled // disabled 由 projectToggle 管理，保存恒为启用
+  servers[serverName] = next
+  await writeProjectJson(ctx, workspacePath, data, servers)
+  await activateProjectMcp(ctx, workspacePath, { ...config, serverName })
+  return projectOf(ctx, workspacePath, workspace.title ?? '')
+}
+
+/** 删除一个项目 MCP：停用 → 从 .mcp.json 移除。 */
+export async function projectRemove(ctx: Ctx, workspacePath: string, serverName: string): Promise<MpcProject> {
+  const workspace = requireWorkspace(ctx, workspacePath)
+  await deactivateMcp(ctx, projectEntryId(workspacePath, serverName))
+  const data = await readProjectJson(ctx, workspacePath)
+  const servers = serversOf(data)
+  delete servers[serverName]
+  await writeProjectJson(ctx, workspacePath, data, servers)
+  return projectOf(ctx, workspacePath, workspace.title ?? '')
+}
+
+/** 切换项目 MCP 启用状态（持久化到 .mcp.json + loader.update）。 */
+export async function projectToggle(ctx: Ctx, workspacePath: string, serverName: string, enabled: boolean): Promise<MpcProject> {
+  const workspace = requireWorkspace(ctx, workspacePath)
+  const data = await readProjectJson(ctx, workspacePath)
+  const servers = serversOf(data)
+  const def = servers[serverName]
+  if (!def) throw new Error('项目中不存在该 MCP')
+  if (enabled) delete def.disabled
+  else def.disabled = true
+  await writeProjectJson(ctx, workspacePath, data, servers)
+  const loader = ctx.get('loader')
+  if (loader) {
+    const entry = entriesOf(ctx).find((candidate) => String(candidate.id ?? candidate.options?.id ?? '') === projectEntryId(workspacePath, serverName))
+    if (entry) await loader.update(entry.id, { disabled: !enabled })
+  }
+  return projectOf(ctx, workspacePath, workspace.title ?? '')
+}
+
+/** 刷新（重连）项目 MCP。 */
+export async function projectRefresh(ctx: Ctx, workspacePath: string, serverName: string): Promise<MpcProject> {
+  const workspace = requireWorkspace(ctx, workspacePath)
+  const loader = ctx.get('loader')
+  if (!loader) throw new Error('缺少 loader 服务')
+  const id = projectEntryId(workspacePath, serverName)
+  const entry = entriesOf(ctx).find((candidate) => String(candidate.id ?? candidate.options?.id ?? '') === id)
+  if (!entry) throw new Error('该项目 MCP 未激活')
+  await loader.update(entry.id, { config: { ...(entry.options?.config ?? {}) } })
+  return projectOf(ctx, workspacePath, workspace.title ?? '')
+}