内容
# @olaservo/mcp-wrappers
为MCP工具生成类型化的TypeScript包装器，以便代理可以像调用**代码**一样调用它们，而不是通过协议——“MCP即代码”/代码执行模式。
提供生成器、运行时桥接生成的代码调用和一个感知过时生命周期的助手。
## 它是做什么的
给定一个 `.mcp.json` 文件，列出一个或多个MCP服务器，生成器：
1. 连接到每个服务器并列出其工具，
2. 将每个工具的输入/输出JSON模式编译为TypeScript接口，
3. 在 `./servers/<server>/` 目录下为每个工具生成一个包装器函数，以及一个 `index.ts`、一个指向 `README.md` 的指针和一个 `.metadata.json` 文件，
4. 在 `./.claude/skills/<server>-server/` 目录下为每个服务器生成一个**技能**——一个 `SKILL.md` 种子（需手动策划）和一个始终重新生成的 `references/tools.md` 目录，包含描述和行为提示。
每个生成的包装器都从该包的 `/runtime` 出口导入 `callMCPTool`，它维护每个服务器的客户端连接池并解包结果（优先使用 `structuredContent`，文本/JSON备用，`isError` → 抛出 `Error`）。
生成器和运行时都支持 **stdio**、**静态凭证HTTP**（配置中的头部）和 **OAuth 2.1 HTTP** 服务器（见下文）。
## 安装
```bash
npm install @olaservo/mcp-wrappers @modelcontextprotocol/sdk
```
`@modelcontextprotocol/sdk` 是一个同级依赖。
## 命令行界面
```bash
# 为 ./.mcp.json 中的每个服务器生成包装器 + 技能
npx mcp-wrappers generate
# 检查新鲜度并重新生成缺失/过时的包装器（在进程中）
npx mcp-wrappers ensure
```
常见选项： `--config=<path>`、 `--output=<dir>`、 `--skills=<dir>`、 `--timeout=<ms>`、 `--runtime-import=<id>`、 `--no-skill`、 `--no-regenerate`、 `--quiet`。OAuth选项： `--no-interactive`、 `--callback-port=<n>`、 `--oauth-store=<dir>`。CLI从工作目录加载 `.env` 文件，以便在 `.mcp.json` 中进行 `${VAR}` 替换（例如 `Authorization: Bearer ${GITHUB_PAT}`）。
## 服务器配置
`.mcp.json` 文件中 `mcpServers` 下的每个条目都是以下三种形式之一：
```jsonc
{
"mcpServers": {
// stdio — 本地子进程
"local": { "type": "stdio", "command": "my-server", "args": ["--flag"] },
// 具有静态凭证（PAT/API密钥）的HTTP
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
},
// OAuth 2.1 背后的HTTP
"guildbridge": {
"type": "http",
"url": "https://guildbridge.modelcontextprotocol.io/mcp",
"auth": "oauth"
}
}
}
```
## OAuth 2.1 服务器
在HTTP服务器上设置 `"auth": "oauth"`，库会运行完整的授权代码 + PKCE流程，**动态客户端注册** — 无需配置客户端ID/密钥。首次使用时：
1. 注册一个客户端并启动一个本地回调服务器，
2. 打开浏览器到授权页面（如果浏览器未打开，也会打印URL），
3. 交换返回的代码以获取令牌，
4. **缓存**客户端注册 + 令牌到 `~/.mcp-wrappers/oauth/<host>.json`。
后续运行是非交互式的 — 缓存的令牌被重用并自动通过刷新令牌刷新，因此不需要浏览器。这适用于 `generate`/`ensure`（在生成时）和运行时桥接（在调用时）。
对于无头环境，传递 `--no-interactive`（CLI）或 `interactive: false`（API）以快速失败而不是尝试浏览器流程。使用 `--callback-port` / `--oauth-store`（CLI）或 `oauth` 选项（API）调整流程。
> **安全注意：** OAuth令牌在 `~/.mcp-wrappers/oauth/` 下以**明文**缓存在磁盘上。像对待任何其他凭证存储一样对待该目录。删除该目录中的服务器文件以强制重新授权。
## 程序API
```ts
import { generateWrappers, ensureWrappers } from "@olaservo/mcp-wrappers";
await generateWrappers({ configPath: "./.mcp.json", outputDir: "./servers" });
const status = await ensureWrappers({ regenerate: true, timeoutMs: 10000 });
if (!status.success) throw new Error(status.errors.join("; "));
```
生成的包装器通过稳定的标识符导入运行时：
```ts
import { callMCPTool } from "@olaservo/mcp-wrappers/runtime";
```
如果您使用客户端，请使用 `runtimeImport`（例如 `"../client.js"`）覆盖它。如果您的配置位于 `./.mcp.json` 以外的其他位置，请在启动时调用 `configureRuntime({ configPath })`。
## 许可证
Apache-2.0
