pi-mcp-adapter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pi-mcp-adapter

Skill by ara.so — MCP Skills collection.

由ara.so开发的Skill — MCP Skills合集。

Overview

概述

pi-mcp-adapter is a token-efficient proxy for Model Context Protocol (MCP) servers in the Pi coding agent. Instead of exposing hundreds of tool definitions (10k+ tokens per server), it provides a single ~200 token proxy tool that discovers MCP capabilities on-demand. Servers lazy-load when needed, keeping your context window clean.

Key benefits:

One proxy tool instead of hundreds cluttering context
Lazy server loading — only connect when tools are called
Direct tool registration for high-priority tools
Standard MCP file support — reads
```
.mcp.json
```
and
```
~/.config/mcp/mcp.json
```
Interactive configuration via
```
/mcp
```
overlay

pi-mcp-adapter是Pi编码代理中Model Context Protocol（MCP）服务器的Token高效代理工具。它无需暴露数百个工具定义（每个服务器占用10k+ Token），而是提供一个仅约200 Token的代理工具，可按需发现MCP功能。服务器仅在需要时延迟加载，保持上下文窗口整洁。

核心优势：

单一代理工具，避免数百个工具占用上下文
延迟服务器加载 — 仅在调用工具时建立连接
高优先级工具直接注册
标准MCP文件支持 — 读取
```
.mcp.json
```
和
```
~/.config/mcp/mcp.json
```
通过
/mcp
交互面板进行配置

Installation

安装

bash

pi install npm:pi-mcp-adapter

Restart Pi after installation. The adapter auto-detects standard MCP config files on first run.

bash

pi install npm:pi-mcp-adapter

安装后重启Pi。适配器会在首次运行时自动检测标准MCP配置文件。

Configuration Files

配置文件

File Precedence

文件优先级

Pi reads MCP configs in this order (later overrides earlier):

```
~/.config/mcp/mcp.json
```
— User-global shared config

~/.pi/agent/mcp.json

— Pi global override (or

$PI_CODING_AGENT_DIR/mcp.json

)

```
.mcp.json
```
— Project-local shared config
```
.pi/mcp.json
```
— Pi project override

Pi按以下顺序读取MCP配置（后续文件覆盖前置文件）：

```
~/.config/mcp/mcp.json
```
— 用户全局共享配置

~/.pi/agent/mcp.json

— Pi全局覆盖配置（或

$PI_CODING_AGENT_DIR/mcp.json

）

```
.mcp.json
```
— 项目本地共享配置
```
.pi/mcp.json
```
— Pi项目覆盖配置

Basic Server Configuration

基础服务器配置

Create

.mcp.json

in your project root:

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

在项目根目录创建

.mcp.json

：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

HTTP/SSE Servers

HTTP/SSE服务器

For servers with HTTP endpoints:

json

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3845/mcp",
      "headers": {
        "Authorization": "Bearer ${FIGMA_TOKEN}"
      }
    }
  }
}

针对带有HTTP端点的服务器：

json

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3845/mcp",
      "headers": {
        "Authorization": "Bearer ${FIGMA_TOKEN}"
      }
    }
  }
}

OAuth Configuration

OAuth配置

For servers requiring OAuth:

json

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "gdrive-mcp"],
      "auth": "oauth",
      "oauth": {
        "grantType": "authorization_code"
      }
    },
    "api-service": {
      "url": "https://api.example.com/mcp",
      "auth": "oauth",
      "oauth": {
        "grantType": "client_credentials"
      },
      "env": {
        "CLIENT_ID": "${API_CLIENT_ID}",
        "CLIENT_SECRET": "${API_CLIENT_SECRET}"
      }
    }
  },
  "settings": {
    "autoAuth": true
  }
}

OAuth flow:

With
```
autoAuth: true
```
, adapter runs OAuth automatically on first tool call
Without
```
autoAuth
```
, run
```
/mcp
```
and press Enter on the server or use
```
ctrl+a
```
```
client_credentials
```
grant skips interactive prompts for machine-to-machine auth

针对需要OAuth认证的服务器：

json

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "gdrive-mcp"],
      "auth": "oauth",
      "oauth": {
        "grantType": "authorization_code"
      }
    },
    "api-service": {
      "url": "https://api.example.com/mcp",
      "auth": "oauth",
      "oauth": {
        "grantType": "client_credentials"
      },
      "env": {
        "CLIENT_ID": "${API_CLIENT_ID}",
        "CLIENT_SECRET": "${API_CLIENT_SECRET}"
      }
    }
  },
  "settings": {
    "autoAuth": true
  }
}

OAuth流程：

若设置
```
autoAuth: true
```
，适配器会在首次调用工具时自动执行OAuth流程
未设置
```
autoAuth
```
时，运行
```
/mcp
```
并选中服务器按Enter，或使用
```
ctrl+a
```
触发
```
client_credentials
```
授权类型会跳过交互提示，适用于机器对机器认证

Using MCP Tools

使用MCP工具

Proxy Mode (Default)

代理模式（默认）

All MCP tools are accessed through the

mcp

proxy tool:

typescript

// Search for available tools
mcp({ search: "screenshot" })
// Returns: chrome_devtools_take_screenshot - Take a screenshot of the page...

// Describe a specific tool
mcp({ describe: "chrome_devtools_take_screenshot" })
// Returns: Full parameter schema

// Call a tool (args must be JSON string)
mcp({ 
  tool: "chrome_devtools_take_screenshot", 
  args: '{"format": "png", "fullPage": true}' 
})

Available proxy actions:

```
{ search: "query" }
```
— Find tools by keyword
```
{ list: true }
```
— List all available tools
```
{ describe: "tool_name" }
```
— Get tool details
```
{ tool: "name", args: "json" }
```
— Execute a tool
```
{ action: "resources", server: "name" }
```
— List server resources

{ action: "read-resource", server: "name", uri: "file://..." }

— Read resource content

```
{ action: "ui-messages" }
```
— Get pending UI messages

所有MCP工具通过

mcp

代理工具访问：

typescript

// 搜索可用工具
mcp({ search: "screenshot" })
// 返回：chrome_devtools_take_screenshot - 截取页面截图...

// 查看特定工具详情
mcp({ describe: "chrome_devtools_take_screenshot" })
// 返回：完整参数 schema

// 调用工具（参数必须为JSON字符串）
mcp({ 
  tool: "chrome_devtools_take_screenshot", 
  args: '{"format": "png", "fullPage": true}' 
})

支持的代理操作：

```
{ search: "query" }
```
— 通过关键词查找工具
```
{ list: true }
```
— 列出所有可用工具
```
{ describe: "tool_name" }
```
— 获取工具详细信息
```
{ tool: "name", args: "json" }
```
— 执行工具
```
{ action: "resources", server: "name" }
```
— 列出服务器资源

{ action: "read-resource", server: "name", uri: "file://..." }

— 读取资源内容

```
{ action: "ui-messages" }
```
— 获取待处理UI消息

Direct Tools

直接工具

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "directTools": true
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"]
    }
  }
}

Direct tool options:

```
true
```
— Register all tools from this server
```
["tool_a", "tool_b"]
```
— Register only specified tools
```
false
```
or omitted — Proxy only (default)

Token cost: Each direct tool adds ~150-300 tokens to system prompt. Good for 5-20 high-priority tools.

单独注册特定工具，让LLM直接可见：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "directTools": true
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"]
    }
  }
}

直接工具选项：

```
true
```
— 注册该服务器的所有工具
```
["tool_a", "tool_b"]
```
— 仅注册指定工具
```
false
```
或省略 — 仅通过代理访问（默认）

Token成本： 每个直接工具会向系统提示添加约150-300 Token。适合注册5-20个高优先级工具。

Global Direct Tool Default

全局直接工具默认设置

json

{
  "settings": {
    "directTools": true
  },
  "mcpServers": {
    "huge-server": {
      "command": "npx",
      "args": ["-y", "mega-mcp@latest"],
      "directTools": false
    }
  }
}

json

{
  "settings": {
    "directTools": true
  },
  "mcpServers": {
    "huge-server": {
      "command": "npx",
      "args": ["-y", "mega-mcp@latest"],
      "directTools": false
    }
  }
}

Excluding Tools

排除工具

Hide specific tools from proxy and direct registration:

json

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3845/mcp",
      "directTools": true,
      "excludeTools": ["get_figjam", "figma_get_code_connect_map"]
    }
  }
}

在代理和直接注册中隐藏特定工具：

json

{
  "mcpServers": {
    "figma": {
      "url": "http://localhost:3845/mcp",
      "directTools": true,
      "excludeTools": ["get_figjam", "figma_get_code_connect_map"]
    }
  }
}

Lifecycle Management

生命周期管理

Lifecycle Modes

生命周期模式

json

{
  "mcpServers": {
    "lazy-server": {
      "command": "npx",
      "args": ["-y", "some-mcp"],
      "lifecycle": "lazy",
      "idleTimeout": 10
    },
    "eager-server": {
      "command": "npx",
      "args": ["-y", "another-mcp"],
      "lifecycle": "eager"
    },
    "critical-server": {
      "command": "npx",
      "args": ["-y", "important-mcp"],
      "lifecycle": "keep-alive"
    }
  }
}

Lifecycle options:

lazy
(default) — Connect on first use, disconnect after idle timeout. Cached metadata keeps search working without connections.
eager
— Connect at startup, no auto-reconnect. No idle timeout unless explicitly set.
keep-alive
— Connect at startup, auto-reconnect, never timeout. For always-available servers.

json

{
  "mcpServers": {
    "lazy-server": {
      "command": "npx",
      "args": ["-y", "some-mcp"],
      "lifecycle": "lazy",
      "idleTimeout": 10
    },
    "eager-server": {
      "command": "npx",
      "args": ["-y", "another-mcp"],
      "lifecycle": "eager"
    },
    "critical-server": {
      "command": "npx",
      "args": ["-y", "important-mcp"],
      "lifecycle": "keep-alive"
    }
  }
}

生命周期选项：

lazy
（默认） — 首次使用时建立连接，闲置超时后断开连接。缓存的元数据可在无连接时维持搜索功能。
eager
— 启动时建立连接，不会自动重连。除非明确设置，否则无闲置超时。
keep-alive
— 启动时建立连接，自动重连，永不超时。适用于需始终可用的服务器。

Idle Timeout

闲置超时

json

{
  "settings": {
    "idleTimeout": 10
  },
  "mcpServers": {
    "keep-warm": {
      "command": "npx",
      "args": ["-y", "warm-mcp"],
      "idleTimeout": 0
    }
  }
}

Global

idleTimeout

(default 10 minutes) applies to all servers. Set to

to disable. Per-server overrides global setting.

json

{
  "settings": {
    "idleTimeout": 10
  },
  "mcpServers": {
    "keep-warm": {
      "command": "npx",
      "args": ["-y", "warm-mcp"],
      "idleTimeout": 0
    }
  }
}

全局

idleTimeout

（默认10分钟）适用于所有服务器。设置为

可禁用。服务器级设置会覆盖全局设置。

Tool Prefixing

工具前缀

Control how tool names are prefixed:

json

{
  "settings": {
    "toolPrefix": "server"
  }
}

Prefix modes:

```
"server"
```
(default) —
```
chrome_devtools_take_screenshot
```

"short"

— Strips

-mcp

suffix:

chrome_devtools_take_screenshot

```
"none"
```
— No prefix:
```
take_screenshot
```

控制工具名称的前缀方式：

json

{
  "settings": {
    "toolPrefix": "server"
  }
}

前缀模式：

```
"server"
```
（默认） —
```
chrome_devtools_take_screenshot
```

"short"

— 去除

-mcp

后缀：

chrome_devtools_take_screenshot

```
"none"
```
— 无前缀：
```
take_screenshot
```

Interactive Configuration

交互式配置

/mcp

Overlay

/mcp

交互面板

Run

/mcp

in Pi to open interactive panel:

View all configured servers with connection status
See tool counts and lifecycle modes
Toggle tools between direct and proxy registration
Reconnect servers manually
Trigger OAuth authentication (Enter on server or
```
ctrl+a
```
)

在Pi中运行

/mcp

打开交互式面板：

查看所有已配置服务器的连接状态
查看工具数量和生命周期模式
在直接注册和代理模式之间切换工具
手动重新连接服务器
触发OAuth认证（选中服务器按Enter或使用
```
ctrl+a
```
）

/mcp setup

Guided Setup

/mcp setup

引导式设置

Run

/mcp setup

for first-time configuration:

Detect existing configs — Scans for
```
.mcp.json
```
,
```
~/.config/mcp/mcp.json
```
, and host-specific configs (Cursor, Claude Code, etc.)
Import compatibility — Adopt host configs into Pi with preview before writing
Scaffold minimal config — Create basic
```
.mcp.json
```
with prompts
Quick-add RepoPrompt — One-shot add popular MCP servers
Preview file changes — Shows exact before/after diffs before any writes

首次配置时运行

/mcp setup

：

检测现有配置 — 扫描
```
.mcp.json
```
、
```
~/.config/mcp/mcp.json
```
以及宿主特定配置（Cursor、Claude Code等）
导入兼容性 — 将宿主配置适配到Pi中，写入前可预览
生成极简配置 — 通过提示创建基础
```
.mcp.json
```
快速添加RepoPrompt — 一键添加热门MCP服务器
预览文件变更 — 写入前显示精确的修改前后差异

CLI Tool

CLI工具

After installation,

pi-mcp-adapter

CLI is available:

bash

undefined

安装后，

pi-mcp-adapter

CLI可用：

bash

undefined

Scan for host configs and create compatibility imports

扫描宿主配置并创建兼容性导入

pi-mcp-adapter init

Show detected config files

显示检测到的配置文件

pi-mcp-adapter info

undefined

pi-mcp-adapter info

undefined

Environment Variables

环境变量

Variable Interpolation

变量插值

Supports

${VAR}

and

$env:VAR

syntax:

json

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "db-mcp"],
      "env": {
        "DATABASE_URL": "${DB_URL}",
        "API_KEY": "$env:SECRET_KEY"
      },
      "cwd": "${PROJECT_ROOT}/data"
    }
  }
}

Home directory expansion:

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"]
    }
  }
}

支持

${VAR}

和

$env:VAR

语法：

json

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "db-mcp"],
      "env": {
        "DATABASE_URL": "${DB_URL}",
        "API_KEY": "$env:SECRET_KEY"
      },
      "cwd": "${PROJECT_ROOT}/data"
    }
  }
}

主目录扩展：

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"]
    }
  }
}

Advanced Settings

高级设置

Complete Settings Reference

完整设置参考

json

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 10,
    "directTools": false,
    "disableProxyTool": false,
    "autoAuth": false,
    "sampling": true,
    "samplingAutoApprove": false
  }
}

Settings:

```
toolPrefix
```
—
```
"server"
```
,
```
"short"
```
, or
```
"none"
```
```
idleTimeout
```
— Minutes before disconnect (0 to disable)
```
directTools
```
— Global default for all servers
```
disableProxyTool
```
— Hide
```
mcp
```
proxy once direct tools are cached
```
autoAuth
```
— Auto-run OAuth on tool calls
```
sampling
```
— Allow MCP servers to sample through Pi models
```
samplingAutoApprove
```
— Skip sampling confirmation prompts (required for non-UI sessions)

json

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 10,
    "directTools": false,
    "disableProxyTool": false,
    "autoAuth": false,
    "sampling": true,
    "samplingAutoApprove": false
  }
}

设置说明：

```
toolPrefix
```
—
```
"server"
```
、
```
"short"
```
或
```
"none"
```
```
idleTimeout
```
— 断开连接前的闲置分钟数（0表示禁用）
```
directTools
```
— 所有服务器的全局默认设置
```
disableProxyTool
```
— 缓存直接工具后隐藏
```
mcp
```
代理
```
autoAuth
```
— 调用工具时自动执行OAuth
```
sampling
```
— 允许MCP服务器通过Pi模型进行采样
```
samplingAutoApprove
```
— 跳过采样确认提示（非UI会话必填）

Debugging

调试

Enable server stderr output:

json

{
  "mcpServers": {
    "problematic": {
      "command": "npx",
      "args": ["-y", "debug-mcp"],
      "debug": true
    }
  }
}

启用服务器标准错误输出：

json

{
  "mcpServers": {
    "problematic": {
      "command": "npx",
      "args": ["-y", "debug-mcp"],
      "debug": true
    }
  }
}

MCP UI Integration

MCP UI集成

Servers can ship interactive UIs via MCP UI standard. When a tool returns UI metadata, pi-mcp-adapter opens it in a native window (macOS with Glimpse) or browser.

服务器可通过MCP UI标准提供交互式UI。当工具返回UI元数据时，pi-mcp-adapter会在原生窗口（macOS使用Glimpse）或浏览器中打开它。

Installing Glimpse (macOS)

安装Glimpse（macOS）

bash

pi install npm:glimpseui

Force browser rendering:

bash

export MCP_UI_VIEWER=browser

Require native rendering:

bash

export MCP_UI_VIEWER=glimpse

bash

pi install npm:glimpseui

强制浏览器渲染：

bash

export MCP_UI_VIEWER=browser

强制原生渲染：

bash

export MCP_UI_VIEWER=glimpse

UI Communication Flow

UI通信流程

Agent calls tool with UI resource:

mcp({ tool: "launch_dashboard", args: "{}" })

Adapter fetches UI HTML from
```
_meta.ui.resourceUri
```
UI opens in native window or browser
UI can call MCP tools and send messages back
Agent retrieves messages:
```
mcp({ action: "ui-messages" })
```
Agent responds, enabling bidirectional conversation

代理调用带UI资源的工具：

mcp({ tool: "launch_dashboard", args: "{}" })

适配器从
```
_meta.ui.resourceUri
```
获取UI HTML
在原生窗口或浏览器中打开UI
UI可调用MCP工具并发送消息返回
代理获取消息：
```
mcp({ action: "ui-messages" })
```
代理响应，实现双向交互

Session Reuse

会话复用

When the agent calls the same tool while its UI is open, the adapter pushes new results to the existing window instead of replacing it. Enables live updates without losing current view.

当代理在UI打开时调用同一工具，适配器会将新结果推送到现有窗口而非替换它。支持实时更新且不丢失当前视图。

Common Patterns

常见模式

Multi-Server Project Setup

多服务器项目配置

json

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 15,
    "directTools": false
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"],
      "lifecycle": "keep-alive",
      "directTools": ["read_file", "write_file", "list_directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "directTools": ["search_repositories", "get_file_contents", "create_issue"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

json

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 15,
    "directTools": false
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT}"],
      "lifecycle": "keep-alive",
      "directTools": ["read_file", "write_file", "list_directory"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "directTools": ["search_repositories", "get_file_contents", "create_issue"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

Working with Resources

资源操作

MCP servers can expose resources (files, data) that aren't tools:

typescript

// List resources from a server
mcp({ action: "resources", server: "filesystem" })
// Returns: List of available resources with URIs

// Read a specific resource
mcp({ 
  action: "read-resource", 
  server: "filesystem", 
  uri: "file:///Users/me/project/README.md" 
})

Enable/disable resource tools:

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"],
      "exposeResources": true
    }
  }
}

Default is

true

. Set to

false

to hide resource-access tools.

MCP服务器可暴露非工具类资源（文件、数据）：

typescript

// 列出服务器资源
mcp({ action: "resources", server: "filesystem" })
// 返回：带URI的可用资源列表

// 读取特定资源
mcp({ 
  action: "read-resource", 
  server: "filesystem", 
  uri: "file:///Users/me/project/README.md" 
})

启用/禁用资源工具：

json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"],
      "exposeResources": true
    }
  }
}

默认值为

true

。设置为

false

可隐藏资源访问工具。

Subagent Integration

子代理集成

Subagents can request direct MCP tools in frontmatter:

markdown

---
name: github-reviewer
tools:
  - read
  - edit
  - mcp:github
---

Review pull request and create detailed comments using GitHub MCP tools.

mcp:server-name

syntax requests all direct tools from that server.

子代理可在前置元数据中请求直接MCP工具：

markdown

---
name: github-reviewer
tools:
  - read
  - edit
  - mcp:github
---

使用GitHub MCP工具审核拉取请求并创建详细评论。

mcp:server-name

语法会请求该服务器的所有直接工具。

Troubleshooting

故障排查

Server Won't Connect

服务器无法连接

Check config syntax:

bash

cat .mcp.json | jq .

Enable debug output:

json

{
  "mcpServers": {
    "failing-server": {
      "command": "npx",
      "args": ["-y", "problem-mcp"],
      "debug": true
    }
  }
}

Force reconnect:

Run

/mcp

and press Enter on the server, or:

typescript

mcp({ action: "reconnect", server: "failing-server" })

检查配置语法：

bash

cat .mcp.json | jq .

启用调试输出：

json

{
  "mcpServers": {
    "failing-server": {
      "command": "npx",
      "args": ["-y", "problem-mcp"],
      "debug": true
    }
  }
}

强制重连：

运行

/mcp

并选中服务器按Enter，或：

typescript

mcp({ action: "reconnect", server: "failing-server" })

Tools Not Appearing

工具未显示

Check cache:

Direct tools load from cache at

~/.pi/agent/mcp-cache.json

. On first run after adding

directTools

, cache won't exist yet.

Force cache refresh:

bash

undefined

检查缓存：

直接工具从

~/.pi/agent/mcp-cache.json

加载缓存。添加

directTools

后的首次运行时，缓存尚未生成。

强制刷新缓存：

bash

undefined

In Pi

在Pi中运行

/mcp reconnect <server-name>


**Verify tool registration:**

```typescript
// List all available tools
mcp({ list: true })

// Search for specific tool
mcp({ search: "expected_tool_name" })

/mcp reconnect <server-name>


**验证工具注册：**

```typescript
// 列出所有可用工具
mcp({ list: true })

// 搜索特定工具
mcp({ search: "expected_tool_name" })

OAuth Not Working

OAuth无法工作

Manual OAuth trigger:

Run
```
/mcp
```
Navigate to OAuth server
Press Enter or
```
ctrl+a
```

Enable auto-auth:

json

{
  "settings": {
    "autoAuth": true
  }
}

Check client credentials:

For

client_credentials

grant, ensure env vars are set:

bash

export API_CLIENT_ID="your-client-id"
export API_CLIENT_SECRET="your-secret"

手动触发OAuth：

运行
```
/mcp
```
导航到需OAuth的服务器
按Enter或
```
ctrl+a
```

启用自动认证：

json

{
  "settings": {
    "autoAuth": true
  }
}

检查客户端凭证：

对于

client_credentials

授权类型，确保环境变量已设置：

bash

export API_CLIENT_ID="your-client-id"
export API_CLIENT_SECRET="your-secret"

High Token Usage

Token占用过高

Problem: Too many direct tools burning context.

Solution 1 — Use proxy only:

json

{
  "mcpServers": {
    "huge-server": {
      "command": "npx",
      "args": ["-y", "mega-mcp"],
      "directTools": false
    }
  }
}

Solution 2 — Select specific tools:

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"]
    }
  }
}

Solution 3 — Hide proxy tool:

json

{
  "settings": {
    "disableProxyTool": true,
    "directTools": true
  }
}

Only works when all needed tools are registered direct and cached.

问题： 过多直接工具消耗上下文Token。

解决方案1 — 仅使用代理：

json

{
  "mcpServers": {
    "huge-server": {
      "command": "npx",
      "args": ["-y", "mega-mcp"],
      "directTools": false
    }
  }
}

解决方案2 — 选择特定工具：

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "directTools": ["search_repositories", "get_file_contents"]
    }
  }
}

解决方案3 — 隐藏代理工具：

json

{
  "settings": {
    "disableProxyTool": true,
    "directTools": true
  }
}

仅当所有所需工具均已直接注册并缓存时生效。

Environment Variables Not Expanding

环境变量未展开

Ensure proper syntax:

json

{
  "env": {
    "CORRECT": "${MY_VAR}",
    "ALSO_CORRECT": "$env:MY_VAR",
    "WRONG": "$MY_VAR"
  }
}

Check variable is exported:

bash

echo $MY_VAR

确保语法正确：

json

{
  "env": {
    "CORRECT": "${MY_VAR}",
    "ALSO_CORRECT": "$env:MY_VAR",
    "WRONG": "$MY_VAR"
  }
}

检查变量已导出：

bash

echo $MY_VAR

Should print value

应输出变量值

export MY_VAR="value"

undefined

export MY_VAR="value"

undefined

Server Keeps Disconnecting

服务器频繁断开

Adjust idle timeout:

json

{
  "mcpServers": {
    "chatty-server": {
      "command": "npx",
      "args": ["-y", "active-mcp"],
      "idleTimeout": 0
    }
  }
}

Or use keep-alive:

json

{
  "mcpServers": {
    "critical": {
      "command": "npx",
      "args": ["-y", "important-mcp"],
      "lifecycle": "keep-alive"
    }
  }
}

调整闲置超时：

json

{
  "mcpServers": {
    "chatty-server": {
      "command": "npx",
      "args": ["-y", "active-mcp"],
      "idleTimeout": 0
    }
  }
}

或使用保持连接模式：

json

{
  "mcpServers": {
    "critical": {
      "command": "npx",
      "args": ["-y", "important-mcp"],
      "lifecycle": "keep-alive"
    }
  }
}

File Locations

文件位置

Global shared config:
```
~/.config/mcp/mcp.json
```

Pi global override:

~/.pi/agent/mcp.json

(or

$PI_CODING_AGENT_DIR/mcp.json

)

Project shared config:
```
.mcp.json
```
Pi project override:
```
.pi/mcp.json
```

Tool cache:

~/.pi/agent/mcp-cache.json

(or

$PI_CODING_AGENT_DIR/mcp-cache.json

)

全局共享配置：
```
~/.config/mcp/mcp.json
```

Pi全局覆盖配置：

~/.pi/agent/mcp.json

（或

$PI_CODING_AGENT_DIR/mcp.json

）

项目本地共享配置：
```
.mcp.json
```
Pi项目覆盖配置：
```
.pi/mcp.json
```

工具缓存：

~/.pi/agent/mcp-cache.json

（或

$PI_CODING_AGENT_DIR/mcp-cache.json

）

Key Commands Summary

核心命令汇总

Command	Purpose
`/mcp`	Open interactive config overlay
`/mcp setup`	Guided first-run configuration
`/mcp reconnect <server>`	Force server reconnection
`mcp({ search: "query" })`	Find tools by keyword
`mcp({ list: true })`	List all available tools
`mcp({ describe: "tool" })`	Get tool schema
`mcp({ tool: "name", args: "json" })`	Execute MCP tool
`mcp({ action: "resources", server: "name" })`	List server resources
`mcp({ action: "ui-messages" })`	Get pending UI messages

命令	用途
`/mcp`	打开交互式配置面板
`/mcp setup`	引导式首次配置
`/mcp reconnect <server>`	强制服务器重连
`mcp({ search: "query" })`	通过关键词查找工具
`mcp({ list: true })`	列出所有可用工具
`mcp({ describe: "tool" })`	获取工具Schema
`mcp({ tool: "name", args: "json" })`	执行MCP工具
`mcp({ action: "resources", server: "name" })`	列出服务器资源
`mcp({ action: "ui-messages" })`	获取待处理UI消息

Example: Complete Chrome DevTools Setup

示例：完整Chrome DevTools配置

json

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 5
  },
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "lifecycle": "lazy",
      "directTools": [
        "take_screenshot",
        "get_console_logs",
        "execute_javascript"
      ],
      "excludeTools": ["deprecated_tool"]
    }
  }
}

Usage:

typescript

// Direct tool (appears in agent's tool list)
chrome_devtools_take_screenshot({ format: "png", fullPage: true })

// Or via proxy
mcp({ 
  tool: "chrome_devtools_get_console_logs", 
  args: '{}' 
})

// Search for other tools
mcp({ search: "navigate" })

json

{
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 5
  },
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "lifecycle": "lazy",
      "directTools": [
        "take_screenshot",
        "get_console_logs",
        "execute_javascript"
      ],
      "excludeTools": ["deprecated_tool"]
    }
  }
}

使用方式：

typescript

// 直接工具（显示在代理工具列表中）
chrome_devtools_take_screenshot({ format: "png", fullPage: true })

// 或通过代理调用
mcp({ 
  tool: "chrome_devtools_get_console_logs", 
  args: '{}' 
})

// 搜索其他工具
mcp({ search: "navigate" })

pi-mcp-adapter

Original

Translation

pi-mcp-adapter

pi-mcp-adapter

Overview

概述

Installation

安装

Configuration Files

配置文件

File Precedence

文件优先级

Basic Server Configuration

基础服务器配置

HTTP/SSE Servers

HTTP/SSE服务器

OAuth Configuration

OAuth配置

Using MCP Tools

使用MCP工具

Proxy Mode (Default)

代理模式（默认）

Direct Tools

直接工具

Global Direct Tool Default

全局直接工具默认设置

Excluding Tools

排除工具

Lifecycle Management

生命周期管理

Lifecycle Modes

生命周期模式

Idle Timeout

闲置超时

Tool Prefixing

工具前缀

Interactive Configuration

交互式配置

/mcp Overlay

/mcp交互面板

/mcp setup Guided Setup

/mcp setup引导式设置

CLI Tool

CLI工具

Scan for host configs and create compatibility imports

扫描宿主配置并创建兼容性导入

Show detected config files

显示检测到的配置文件

Environment Variables

环境变量

Variable Interpolation

变量插值

Advanced Settings

高级设置

Complete Settings Reference

完整设置参考

Debugging

调试

MCP UI Integration

MCP UI集成

Installing Glimpse (macOS)

安装Glimpse（macOS）

UI Communication Flow

UI通信流程

Session Reuse

会话复用

Common Patterns

常见模式

Multi-Server Project Setup

多服务器项目配置

Working with Resources

资源操作

Subagent Integration

子代理集成

Troubleshooting

故障排查

Server Won't Connect

服务器无法连接

Tools Not Appearing

`/mcp`
Overlay

`/mcp`
交互面板

`/mcp setup`
Guided Setup

`/mcp setup`
引导式设置