企业官网建设流程全解析

pi-mcp-adapter是一个专为 Pi 编程智能体打造的 Token 节省型 MCP 适配器：它用一个约 200 Token 的代理工具替代成百上千的工具定义，让 MCP 服务器按需懒加载，从而在对话开始前就为你的上下文窗口省下大量 Token。无论你是想接入数据库、浏览器、API 等 MCP 生态工具，又不想被冗余的工具定义拖垮上下文，这份指南都能帮你在几分钟内完成配置。

为什么 MCP 工具定义会吃光上下文？

很多新手接入 MCP 服务器后都会遇到同一个问题：上下文窗口还没开始对话就被耗掉了一半。

原因在于 MCP 的机制：每连接一个 MCP 服务器，它的全部工具定义（名称、描述、参数 Schema）都会进入模型上下文。一个中等规模的服务器就可能烧掉10k+ Token，而且不管你用不用这些工具，这笔费用每轮对话都在支付。

传统解法有两个，都不完美：

pi-mcp-adapter 的思路是第三条路：保留 MCP 生态的全部能力，但让模型按需发现工具。

工作原理：一个代理工具替代数百个定义

pi-mcp-adapter 的核心设计只有四个关键词：

• 单一代理：上下文里只有一个mcp工具（约 200 Token），而不是每个 MCP 工具各占一份定义
• 懒加载（lazy）：服务器默认不启动，模型第一次调用其工具时才连接
• 元数据缓存：工具清单缓存到磁盘，搜索、列表、描述操作无需实时连接
• 空闲自动断开：默认 10 分钟无活动即停掉服务器，下次调用 0.1–0.3 秒自动重新拉起

实际使用体验是"两次调用"模式。以截图工具为例，模型只需要：

mcp({ search: "screenshot" })

mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })

两次轻量 JSON 调用，替代了 26 个工具定义对上下文的长期占用。官方在 README.md 的 "How It Works" 部分有完整说明。

快速上手：两步完成安装配置

第一步：安装

pi install npm:pi-mcp-adapter

安装后重启 Pi。安装时它会自动关闭 Pi 内置的 MCP 扩展，避免两套机制同时运行。

第二步：添加你的第一个 MCP 服务器

在项目根目录创建.mcp.json：

{ "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@1.6.0"] } } }

就这么多。服务器默认是懒加载的——你不调用它的工具，它连进程都不会启动。

从 Cursor / Claude Code 迁移？一键导入

如果你已经在 Cursor、Claude Code、Codex 或 VS Code 里配置过 MCP 服务器，可以直接导入，无需手工转换：

/mcp-adapter setup

这个引导式面板会扫描本机已有的配置，让你勾选要导入的项，并在写入前预览每个文件的精确改动。支持的来源包括cursor、claude-code、claude-desktop、opencode、vscode、windsurf、codex。配置文件的完整层级与优先级规则见 docs/configuration.md。

实测数据：100 个服务器下能省多少？

pi-mcp-adapter 提供了可复现的基准测试（脚本位于 bench/server-memory.mjs）。在 100 个本地服务器、每个 50 个工具的测试环境下：

Token 成本方面，官方用 GPT 与 Claude 双模型实测了日常任务（数据见 docs/pi-builtin-comparison.md）：

单次轻量查询普遍节省 10–33%；批量任务若开启settings.scriptMode，节省可达数倍。值得注意的是，停掉的服务器并不会失去工具——模型仍能搜索到它们，下次调用时自动重新连接。

进阶配置：按需调整工具暴露方式

默认全部走代理是 Token 最省的方案，但某些高频工具可以直接"转正"。以下三个配置最常用：

1.directTools— 把常用工具放进模型工具列表

{ "mcpServers": { "github": { "directTools": ["search_repositories", "get_file_contents"] } } }

设为true可注册该服务器的全部工具；设为"search"则工具先隐藏、搜索命中后才激活，兼顾省 Token 与调用直接性。

2.approveTools— 危险操作先审批

{ "mcpServers": { "my-server": { "approveTools": "destructive" } } }

标记为破坏性的工具执行前会先征求你的确认，内置支持无需额外扩展。

3.lifecycle— 服务器生命周期模式

更多字段（includeTools、excludeTools、searchKeywords、超时控制等）完整参考 docs/servers.md 和 docs/tools.md。

常用命令速查表

面板支持ctrl+d启用/禁用服务器、ctrl+a触发 OAuth、ctrl+p导入 Pi 内置 MCP 的已有登录态。

安全亮点：Token 存入系统钥匙串

很多 MCP 工具会把 OAuth 登录凭据写在明文 JSON 文件里。pi-mcp-adapter 的默认行为更安全：

• OS 密钥链存储：macOS Keychain、Windows Credential Manager 或 Linux Secret Service，无明文回退
• OAuth 全自动：自动发现端点（RFC 9728）、动态客户端注册（RFC 7591）、本地回调服务、自动刷新过期 Token
• 项目服务器信任机制：项目级配置中的服务器不会仅因打开仓库就启动，需你逐次审批（详见 docs/configuration.md 的 "Project server trust" 一节）
• 脚本沙箱：mcpScript脚本在无文件、网络、进程访问的沙箱中运行

完整的认证机制（含远程/无头环境的 SSH 登录流程）见 docs/auth.md。

常见问题

Q：停掉服务器后工具还会丢吗？不会。工具元数据缓存在磁盘，搜索、列表、描述均可离线工作；下次调用会自动重连（本地小服务器约 0.1–0.3 秒）。

Q：能和 Pi 内置 MCP 共存吗？不需要也不应该。安装 pi-mcp-adapter 后它会自动接管 Pi 的 MCP 职责并关闭内置扩展；若卸载适配器，记得在pi config中把内置 MCP 重新打开。

Q：支持哪些传输协议？stdio、Streamable HTTP、传统 SSE，以及可跨会话共享进程的rmcp-muxUnix socket。

延伸阅读

核心源码入口：适配器主逻辑在 index.ts，服务器生命周期管理在 server-manager.ts，懒加载策略在 lazy-loader.ts。

一句话总结：pi-mcp-adapter 让你在完整享受 MCP 生态的同时，把"工具定义税"从每次对话的固定开销，变成了用一次才付一次的按需成本——这就是它能省下大量上下文 Token 的全部秘密。