文档

MCP Power

管理 MCP Server，通过统一入口发现和调用外部工具

MCP Power 是 Desktop 内建的 MCP 管理工具。Sidebar 和 Mainview 展示 Server 状态、工具和错误，Config 配置界面保留。Server 定义由所有 Agent 和 Workspace 全局共享。

配置 Server

每个 Server 默认使用一个 ~/.downcity/powers/mcp/servers/<server_id>.toml 文件，文件名就是 Server ID。如果宿主使用其他 MCP 配置路径，servers 位于该配置文件的同级目录：dirname(config.path)/servers。

已安装的本地 stdio Server 示例：

title = "Filesystem"
enabled = true
command = "mcp-server-filesystem"
args = ["/absolute/allowed/directory"]
cwd = "/absolute/working/directory"
env = { LOG_LEVEL = "info" }
request_timeout_ms = 60000
max_result_chars = 100000

命令和参数需要替换为实际 Server 要求的值。Streamable HTTP Server 示例：

title = "Remote MCP"
url = "https://mcp.example.com/mcp"
headers = { "X-Client" = "downcity" }

command 和 url 必须且只能填写一个非空值。本地程序使用可选的 args、cwd、env，HTTP 端点使用可选的 headers。配置没有 source、install、transport 分层。title 可省略；enabled 默认 true；可选的 request_timeout_ms 和 max_result_chars 默认分别为 60000 毫秒和 100000 字符。需要项目目录的 Server 应明确填写 cwd，共享连接不会继承调用者的 Workspace。参数、工作目录、URL 和请求头中的 ${NAME} 从宿主环境读取变量。

Desktop 编辑器直接读写每个 Server 的真实 TOML 文件，每个 Server 都需要明确点击保存或删除。文件修改会以读取时的原文（expected_content）检查冲突；若文件已被其他编辑修改，会拒绝本次操作，防止过期内容覆盖新内容。此时应重新读取文件后再保存。

初始化、定义读取和单文件保存都只扫描、校验定义，不启动或连接 Server。普通手动文件编辑可通过 Config 重新读取发现，不执行 Server。显式测试、Mainview 刷新连接或首次 tools/call 请求才会连接 Server，因此 Mainview 刷新也会建立连接。校验错误会指向对应文件，其他合法 Server 仍然可用。定义变更、停用或删除时释放对应连接，City 关闭时释放全部连接。

加载、编辑定义不会安装程序。已知的 npx、bunx、uvx 等隐式安装运行器，以及包管理器的安装执行入口会被拒绝；应先通过已有审批流程安装程序，再配置已安装的可执行程序。旧 config.servers 集合不再读取，也不会自动迁移，需要明确创建独立 Server 文件。

HTTP OAuth 授权

支持 MCP 标准 OAuth 的 HTTPS Server 收到 401 后会自动进入授权：Downcity 使用 MCP SDK 发现资源与授权服务器元数据，动态注册客户端，生成 PKCE，并通过系统浏览器打开登录页。完成登录后，授权码返回本机 127.0.0.1 回调，当前连接自动恢复。只有测试、刷新连接、工具发现/调用或点击重新授权才可能打开浏览器；读取状态和保存配置不会打开浏览器。

title = "OAuth MCP"
url = "https://mcp.example.com/mcp"
auth = "oauth"
# 授权服务器不提供动态客户端注册时填写预注册的公共客户端 ID
# client_id = "your-client-id"
# client_name = "Downcity"

OAuth 配置与 url 一样位于 TOML 顶层。auth 可省略，标准 401 会自动触发发现。预注册客户端需要支持本地回环地址与动态端口。授权元数据、issuer、注册及 token 端点必须使用 HTTPS。静态 headers 仍然适用于 API key 等鉴权方式；OAuth token 可用时使用 Bearer token。

MCP Mainview 展示 none、authorizing、authorized、expired 授权状态，提供“重新授权”和“取消授权”。不同 Server 的连接和授权独立；同一 Server 的请求串行执行，避免重复弹出授权窗口。授权最长等待五分钟，并受调用取消和 City 关闭控制。工具请求仍使用 request_timeout_ms，因此调用期间需要重新登录时，剩余调用时限可能更短。

凭据保存在 dirname(config.path)/auth/，按 Server ID、完整 endpoint 与 issuer 生成隔离文件名，文件权限为 0600，目录为 0700。保存的是明文 client/token 与过期时间，不保存授权码、state 或 PKCE verifier，也不向 Agent 状态或日志返回 token。有效 refresh token 由 SDK 刷新，刷新失败可重新登录。HTTP session ID、协议协商和 SSE 由 SDK 管理；明确收到 404 时最多重建一次会话并重试，网络结果不明的调用不会自动重放。

实际 Server 必须提供符合协议的发现与授权接口。Twinkle Cloud 的实际协议兼容性和首登、刷新、重启免登录尚未联调验证。

Agent 如何使用

Agent 使用固定的三个动作。已启用的 Server 不会变成独立 Power，工具也不会全部塞进模型工具清单。

{"action":"servers"}
{"action":"tools","args":{"server_id":"filesystem"}}
{"action":"call","args":{"server_id":"filesystem","tool_name":"read_file","arguments":{"path":"/allowed/example.txt"}}}

先通过 servers 查看已启用连接，再用 tools 读取原始工具名称和输入 JSON Schema，最后调用 call。示例中的工具名和路径需要替换为实际 Server 提供且允许使用的值。调用前会在 MCP 模块内校验参数；停用或定义无效的 Server 不能调用。

这是结构化的发现和调用接口，没有独立 Shell 命令行程序。Server 文件通过 Desktop 管理，Agent 入口为 servers、tools、call。

审批与边界

call 的访问元数据为 write，且 approval: false；调用已启用 Server 时不追加 MCP 审批。MCP 不提供安装、卸载工具，程序安装和卸载通过已有审批执行流程完成。Server 描述和返回值作为外部数据处理，不作为 Agent 指令。请求支持取消和配置的调用超时，过长结果返回截断标记。

stdio Server 会执行本地程序，应由用户明确配置可信 Server。凭据应在所属环境配置中维护，避免在聊天里提交明文。当前不支持 MCP 交互式输入往返。

Server 文件变化后，三个 Agent 动作保持不变，无需重建或同步 Server Power。