# @crossdelta/pf-mcp 中文文档

规范地址：https://npmcn.com/package/%40crossdelta/pf-mcp/

版本：0\.1\.5
npm 元数据更新时间：2026-10-25T12:40:22.390Z
中文译文更新时间：2026-11-11T11:20:55.312Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crossdelta/pf-mcp
原文对照：https://npmcn.com/package/%40crossdelta/pf-mcp/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.2 MB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- peer 依赖：@crossdelta/platform-sdk ^0\.26\.7
- 首次发布：2026-02-22T12:59:48.790Z
- 最新版本发布：2026-10-25T12:40:22.187Z
- 近 30 天下载量：2193（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

SDK 平台的模型上下文协议(MCP)服务器适配器

## 安装

```sh
npm install @crossdelta/pf-mcp
```

也可以使用：`pnpm add @crossdelta/pf-mcp`、`yarn add @crossdelta/pf-mcp`、`bun add @crossdelta/pf-mcp`

## README

# @ crossdelta/pf-mcp (英语)

用于平台SDK的模型上下文协议(MCP)服务器适配器.

## 概览

此软件包在 [示范背景协议SDK](https://github.com/modelcontextprotocol/typescript-sdk) 和平台 SDK,将插件命令曝光为MCP工具.

**结构 :**

-   取决于SDK平台外观(`@crossdelta/platform-sdk/facade`(中文(简体) )
-   Pins MCP SDK 为稳定精确版本
-   零业务逻辑 - 纯适配器模式
-   插件不可知: 任何平台 SDK 插件的工程

## 安装

```bash
bun add @crossdelta/pf-mcp
```

## 使用量

### 自动发现( 建议)

启动服务器的最简单方法 - 自动发现工作空间配置 `package.json`数字 :

```typescript
import { createMcpServerFromWorkspace } from '@crossdelta/pf-mcp'

await createMcpServerFromWorkspace({
  name: 'platform-mcp-server',
  version: '0.1.0',
  plugins: ['@crossdelta/cloudevents']
})
```

这将:

-   自动发现工作空间根( 从 cwd 到找到软件包 `pf` 配置( c)
-   从 `pf.contracts` 字段
-   从文件系统中发现可用的服务

### 手动配置

为了进行更多的控制,您可以明确提供工作空间配置:

```typescript
import { createMcpServer } from '@crossdelta/pf-mcp'

await createMcpServer({
  name: 'platform-mcp-server',
  version: '0.1.0',
  workspace: {
    workspaceRoot: process.cwd(),
    contracts: { 
      path: 'packages/contracts/src',
      packageName: '@my-org/contracts'
    },
    availableServices: ['orders', 'notifications']
  },
  plugins: ['@crossdelta/cloudevents']
})
```

## MCP SDK 版本战略

### 当前版本 : `^1.25.1` (v1.x-最新稳定)

此软件包使用 **护理范围** 为 MCP SDK 自动接收补丁和小更新.

**SDK 状态**数字 :

-   **v1.x (韩语)** (单位:千美元)`@modelcontextprotocol/sdk`: 当前稳定,在npm上发布,用途 `Server` 类
-   **v2.x (英语)** (单位:千美元)`@modelcontextprotocol/server`:在开发中(主要分支),尚未出版,将使用 `McpServer` 类

这个 `Server` 类中显示的折旧警告指向 `McpServer`,但这是一个前瞻性的通知 对于未释放的v2 API。 我们目前使用的v1.25.1.

#### 为什么是凯特牧场?

1.  **变质 SDK**: MCP SDK 位于 v1.x 有稳定的 API
2.  **自动错误修正**: 安全补丁和修正,不作人工干预
3.  **合规**: SDK 遵循语义版本
4.  **面相隔离**: SDK 平台外观提供稳定性层

#### 版本政策

**允许更新 :**

-   \* 补丁更新(1.25.1 → 1.25.2) - 自动
-   \* 小更新(1.25.x)-自动
-   • 主要更新(1.x-2.0) - 需要手动升级

**手动升级的时间 :**

-   新建 MCP SDK 主要版本, 并打破更改
-   我们要使用的新协议特性
-   二. 重大安全弱点

**迁移到 SDK v2.x (未来):**

当 SDK v2 发布到 npm( 预期Q1 2026) 时 :

1.  安装 : `bun add @modelcontextprotocol/server` (替换) `@modelcontextprotocol/sdk`(中文(简体) )
2.  更新导入 : `Server` → `McpServer`,软件包路径 : `@modelcontextprotocol/sdk/server` → `@modelcontextprotocol/server`
3.  审查 v2 运输/ 处理器 API 的中断变化
4.  以 v2 为例的测试 : [服务器.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
5.  更新此读取器

**如何升级 :**

1.  审查 MCP SDK 更改日志以打破更改
2.  首先在 dev 环境中进行测试
3.  如果处理器 APIs 更改, 更新适配器代码
4.  运行集成测试
5.  更新版本于 `package.json`
6.  此 README 中的文档更改

### 版本历史

| MCP SDK 软件 | 日期 | 变动 | 页:1 |
| --- | --- | --- | --- |
| ^ 1.25.1 (韩语) | 2025-12-28 (中文(简体) ) | 初始版本 | v1.x 稳定放出, v2 在开发中 |

## 可用工具

MCP服务器将这些工具曝光给AI助手:

| 工具 | 说明 |
| --- | --- |
| `scan_workspace` | 扫描服务、合同和配置的工作空间 |
| `generate_service` | 生成一个新的微服务计划( 默认干运行) |
| `plan_review` | 应用前验证生成计划 |
| `apply_changes` | 应用生成计划中的更改 |

### MCP (建筑)

**关键原则:** MCP=规划员(结构),AI=代码生成器(内容)

```
1. AI delivers Intent + Inputs    →  mcp_pf_generate_service(prompt: "...")
2. pf generates Plan + Preview    ←  { files: [], changes: [], planHash }
3. AI generates code for files    →  AI fills content based on intent + inputs
4. Optional: plan_review          →  mcp_pf_plan_review(changes: [...])
5. User OK Gate                   →  User confirms
6. Apply with expectedPlanHash    →  mcp_pf_apply_changes(changes: [...], expectedPlanHash: "...")
```

#### 生成服务响应结构

```typescript
{
  ok: true,
  operation: 'generate_service',
  summary: 'Planned notifications: 10 scaffold files + 3 files for AI to generate',
  
  // Scaffold effects (ready to apply - have content)
  changes: [
    { kind: 'file:write', path: 'services/notifications/package.json', content: '...' },
    { kind: 'file:write', path: 'services/notifications/src/index.ts', content: '...' },
    // ...
  ],
  
  // Files for AI to generate (NO content - AI fills based on intent + inputs)
  files: [
    { 
      path: 'services/notifications/src/events/order-created.handler.ts',
      intent: 'Handle order.created event',
      inputs: { eventType: 'order.created', contractName: 'OrdersCreatedContract' }
    },
    { 
      path: 'services/notifications/src/adapters/push.adapter.ts',
      intent: 'Push notification adapter using pusher-beams',
      inputs: { provider: 'pusher-beams', envVars: ['PUSHER_BEAMS_INSTANCE_ID', 'PUSHER_BEAMS_SECRET_KEY'] }
    },
  ],
  
  // Dependencies to add
  dependencies: [
    { name: '@pusher/push-notifications-server', version: '^1.0.0' }
  ],
  
  // Environment variables needed
  envVars: [
    { key: 'PUSHER_BEAMS_INSTANCE_ID', description: 'Pusher Beams instance ID', required: true }
  ],
  
  // Integrity hash
  planHash: 'abc123...',
}
```

#### AI 工作流程

1.  **调用生成服务( S)** 迅速
2.  **读取文件数组** (路径+意图+投入)
3.  **生成代码** 基于意图+输入的每个文件
4.  **合并为更改** 包含 AI 生成的内容
5.  **调用应用程序 更改** 与合并的更改 + 预期的 PlanHash

### 效果类型

| 效果类 | 说明 |
| --- | --- |
| `file:write` | 将文件写入文件系统 |
| `env:add` | 将环境变量添加到 .env.local |
| `infra:add` | 创建基础设施配置 |
| `deps:add` | 将依赖性添加到 package.json |

### 工具示例

#### 扫描工作空间

```json
{
  "name": "scan_workspace",
  "arguments": {}
}
```

#### 生成服务(干线运行)

```json
{
  "name": "generate_service",
  "arguments": {
    "template": "hono-bun",
    "name": "order-processor",
    "events": ["order.created", "order.updated"]
  }
}
```

#### 生成服务( 应用)

```json
{
  "name": "generate_service",
  "arguments": {
    "template": "hono-bun",
    "name": "order-processor",
    "events": ["order.created"],
    "dryRun": false
  }
}
```

## 测试

### 手动测试( CLI)

直接通过 stdin/ stdout 测试 MCP 服务器 :

```bash
# Build the package first
cd packages/pf-mcp && bun run build

# From workspace root - list available tools
cd /path/to/workspace
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | bun run packages/pf-mcp/bin/server.ts

# Scan workspace
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"scan_workspace","arguments":{}}}' | bun run packages/pf-mcp/bin/server.ts

# Generate service (dry-run)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"generate_service","arguments":{"template":"hono-bun","name":"test-service","events":["order.created"]}}}' | bun run packages/pf-mcp/bin/server.ts
```

### VS 代码集成( 副驾驶代理模式)

添加到您的 VS 代码 `settings.json`数字 :

```json
{
  "github.copilot.chat.mcpServers": {
    "pf": {
      "command": "bun",
      "args": ["run", "${workspaceFolder}/packages/pf-mcp/bin/server.ts"],
      "env": {}
    }
  }
}
```

或为已建版本( npm 包):

```json
{
  "github.copilot.chat.mcpServers": {
    "pf": {
      "command": "node",
      "args": ["${workspaceFolder}/node_modules/@crossdelta/pf-mcp/dist/cli.js", "--stdio"],
      "env": {}
    }
  }
}
```

配置后,重新启动VS代码. 这些工具将随 `mcp_pf_` 在“副驾驶代理模式”中前缀.

### 单位测试

```bash
cd packages/pf-mcp
bun test
```

## 发展

```bash
# Build
bun run build

# Test
bun test

# Watch mode
bun run dev
```

## 建筑

```
┌─────────────────┐
│   MCP Client    │  (Claude Desktop, Zed, etc.)
└────────┬────────┘
         │ stdio
┌────────▼────────┐
│  pf-mcp Server  │  (this package - thin adapter)
└────────┬────────┘
         │ facade API
┌────────▼────────┐
│ Platform SDK    │  (plugin system, execution engine)
│     Facade      │
└────────┬────────┘
         │
┌────────▼────────┐
│    Plugins      │  (@crossdelta/cloudevents, etc.)
└─────────────────┘
```

### 设计原则

1.  **细适配器**: 没有商业逻辑, 纯协议翻译
2.  **表面依赖关系**: 只从下列来源进口: `@crossdelta/platform-sdk/facade`
3.  **插件不可知论**: 与任何符合的插件一起工作 `PfPlugin` 接口
4.  **精确的 SDK 标针**: MCP SDK 版本为稳定而明确控制

### 外观 API 表面

此套件依赖于这些稳定的外观出口:

```typescript
import {
  loadPlugins,          // Load plugins from module names
  createContext,        // Create plugin context
  collectToolSpecs,     // Transform commands → tool specs
  applyEffects,         // Apply command effects
  // Types
  type PfPluginContext,
  type PfWorkspaceContext,
  type LoadedPlugin,
  type ToolSpec,
} from '@crossdelta/platform-sdk/facade'
```

外观提供版本稳定性 - 平台SDK可以在不突破这个适配器的情况下重构内部.

## 路线图

### 第一阶段:核心工具(当前)

-   [x] 有 stdio 传输的服务器骨架
-   [x] `tools/list` 处理器
-   [x] `tools/call` 执行命令的处理器
-   [x] 通过表面应用效果
-   [ ] 用模拟插件进行完全整合测试
-   [ ] 处理和验证出错
-   [ ] 日志和调试支持

### 第2阶段:增强能力

-   [ ] `resources/list` - 将工作空间合同作为资源
-   [ ] `resources/read` - 合同内容检索
-   [ ] `prompts/list` - 基于模板的提示
-   [ ] `prompts/get` - 迅速解决
-   [ ] 安全计划/适用离职

### 第3阶段:高级特征

-   [ ] 通过通知报告进展情况
-   [ ] 对长期业务的应对
-   [ ] 工作空间变化通知
-   [ ] 多工作空间支持

## 捐款

这个包是平台SDK monorepo的一部分. 见捐助准则主要存放处.

## 许可证

麻省理工学院 [横跨德尔塔](https://crossdelta.de/)

## 常见问题

### @crossdelta/pf-mcp 是什么？

SDK 平台的模型上下文协议\(MCP\)服务器适配器

### 如何安装 @crossdelta/pf-mcp？

在项目目录运行 npm install @crossdelta/pf-mcp，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@crossdelta/platform-sdk（^0\.26\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 pf-mcp，可以用 npx pf-mcp 直接运行。

### @crossdelta/pf-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crossdelta/pf-mcp 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @crossdelta/pf-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @crossdelta/pf-mcp 可以商用吗？

@crossdelta/pf-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crossdelta/pf-mcp 的下载量有多少？

根据 npm 官方下载统计，@crossdelta/pf-mcp 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,193 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crossdelta/pf-mcp 还在维护吗？

最新版本 0\.1\.5 发布于 2026/10/25（16 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/02/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。