内容
<picture>
<source media="(prefers-color-scheme: dark)" srcset="logo-pag-rev.svg">
<img src="logo-pag-reg.svg" alt="PAG - 佩福斯智能网关" width="420">
</picture>
# PAG - 佩福斯智能网关
佩福斯智能网关（Perforce Agentic Gateway，简称PAG）是一个本地的MCP网关，提供一种高效的代币模式。AI客户端只需配置一次即可连接到PAG，其他所有MCP服务器都通过PAG配置。这样，客户端无需单独设置和加载每个MCP服务器的工具，而是由PAG管理运行中的MCP服务器进程，在它们崩溃时重启，并将必要的凭证存储在您的操作系统密钥链中。
## 前提条件
- **[uv](https://docs.astral.sh/uv/getting-started/installation/)** - 唯一硬性要求。
- **Docker 或 Podman** - 仅适用于作为容器运行的服务器。
- **每个服务器的依赖项** - PAG代理服务器，它不捆绑这些依赖项（例如，`npx`服务器的Node，API服务器的账户）。
## 快速入门
### 1. 连接您的AI客户端
PAG作为一个**stdio MCP服务器**运行，通过`uvx`启动。
对于 **Claude Code**：
```sh
claude mcp add pag -- uvx perforce-agentic-gateway@latest
```
对于任何使用 **`.mcp.json`** 的客户端（Cursor等）：
```json
{
"mcpServers": {
"pag": {
"command": "uvx",
"args": ["perforce-agentic-gateway@latest"]
}
}
}
```
`@latest` 每次启动时保持PAG更新。添加 `--working-directory <dir>` 以固定项目。其他客户端（Codex，VS Code等）：请参阅 [连接AI客户端](connecting-clients.md)。重启客户端；`pag__*` 工具应出现。
如果您更喜欢一次性安装而不是按需获取？`uv tool install perforce-agentic-gateway` 在您的 `PATH` 中放置一个 `perforce-agentic-gateway` 命令，您可以直接运行它，而不是运行 `uvx perforce-agentic-gateway` - 请参阅 [将PAG安装为工具](reference.md#installing-pag-as-a-tool)。
### 2. 查看可用内容
询问您的助手：
> “PAG注册表中有哪些MCP服务器？”
列出从配置的注册表中可安装的所有内容 - 包括Perforce的第一方服务器，例如P4、BlazeMeter、Perfecto、Delphix、IPLM。
### 3. 从目录启用服务器
Perforce产品支持的MCP服务器可以直接从目录中获取。要求您的助手推荐适合您项目的服务器：
> “有哪些MCP服务器可以帮助完成这个项目？”
PAG扫描您的项目以获取技术信号，并建议目录服务器，始终在启用任何内容之前进行询问。或者，直接命名一个：
> “启用P4服务器。”
PAG将其记录在您的配置文件中并启动它。大多数Perforce服务器需要凭证（通常是服务器URL和访问令牌）；当需要时，助手会为您提供一个仪表板链接以输入它们 - 秘密信息绝不会通过聊天传递。请参阅 [Perforce服务器](using-pag.md#perforce-servers) 和 [秘密信息](secrets.md)。
在任何时候，您都可以通过 `uvx perforce-agentic-gateway view` 浏览完整目录。请参阅 [使用PAG](using-pag.md)。
### 4. 添加自定义服务器
目录中没有的任何内容 - 本地命令、容器或远程HTTP端点 - 都可以直接添加。MCP **fetch** 服务器通过 `uvx` 运行，不需要凭证，因此它是一个方便的零设置服务器，可以运行端到端并查看流程：
> “添加一个名为 `fetch` 的自定义服务器，运行 `uvx mcp-server-fetch`。”
PAG将其写入您的配置文件并启动它。
### 5. 运行真实命令
> “获取 https://modelcontextprotocol.io 并告诉我什么是MCP。”
助手通过PAG调用 `fetch__fetch` 并从实时页面回答。
## 为什么保持快速
```
AI 客户端 -- 一个 stdio 连接 --> PAG --> 服务器 A（命令）
| --> 服务器 B（远程 HTTP）
+-> 服务器 C（容器）
```
PAG不会将下游工具的每个内容转发给您的客户端（20个服务器可能意味着一千个工具）。它公开一个小的、固定的 `pag__*` 集，并将完整的目录保存在网关内：
- **`pag__explore`** 搜索目录；只有助手请求的切片才会进入其上下文。
- **`pag__execute`** 运行JavaScript以调用下游工具，因此循环和跨服务器的扇出只需 **一次** 往返即可完成。
完整的机制（沙盒、限定工具名称、提示和资源）都在 [工具和沙盒](using-pag.md#tools-and-the-sandbox) 中。
## 更深入的了解
- **[连接AI客户端](connecting-clients.md)** - Claude Code、Codex、VS Code、Cursor。
- **[使用PAG](using-pag.md)** - 管理服务器、仪表板、目录和注册表、Perforce服务器、工具/沙盒模型。
- **[秘密信息](secrets.md)** - 输入、存储和查找凭证。
- **[配置](configuration.md)** - 完整的 `config.toml` 参考。
- **[故障排除](troubleshooting.md)** - 日志记录和常见修复。
- **[参考](reference.md)** - 命令行、卸载、词汇表。
## 反馈
错误报告和功能请求通过 [GitHub问题](https://github.com/perforce/perforce-agentic-gateway/issues) 进行。对于设置和运行时问题，请先查看 [故障排除](troubleshooting.md) - 它涵盖了常见情况。
## 许可证
PAG的使用受 [Perforce Agentic Gateway 使用条款](LICENSE.md) 的约束。
