@crossdelta/pf-mcp

中文文档

0.1.5发布于 2026/10/25MITTypeScriptESM + CJS近 30 天下载 2193

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

文档目录26 节

概览
安装
使用量
自动发现( 建议)
手动配置
MCP SDK 版本战略
当前版本 : ^1.25.1 (v1.x-最新稳定)
版本历史
可用工具
MCP (建筑)
效果类型
工具示例
测试
手动测试( CLI)
VS 代码集成( 副驾驶代理模式)
单位测试
发展
建筑
设计原则
外观 API 表面
路线图
第一阶段:核心工具(当前)
第2阶段:增强能力
第3阶段:高级特征
捐款
许可证

@ crossdelta/pf-mcp (英语)

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

概览

此软件包在示范背景协议SDK 和平台 SDK,将插件命令曝光为MCP工具.

结构 :

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

安装

bun add @crossdelta/pf-mcp

使用量

自动发现( 建议)

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

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

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

这将:

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

手动配置

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

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.

为什么是凯特牧场?

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

版本政策

允许更新 :

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

手动升级的时间 :

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

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

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

安装 : bun add @modelcontextprotocol/server (替换) @modelcontextprotocol/sdk(中文(简体) )
更新导入 : Server → McpServer,软件包路径 : @modelcontextprotocol/sdk/server → @modelcontextprotocol/server
审查 v2 运输/ 处理器 API 的中断变化
以 v2 为例的测试 : 服务器.md
更新此读取器

如何升级 :

审查 MCP SDK 更改日志以打破更改
首先在 dev 环境中进行测试
如果处理器 APIs 更改, 更新适配器代码
运行集成测试
更新版本于 package.json
此 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: "...")

生成服务响应结构

{
  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 工作流程

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

效果类型

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

工具示例

扫描工作空间

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

生成服务(干线运行)

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

生成服务( 应用)

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

测试

手动测试( CLI)

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

# 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数字 :

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

或为已建版本( npm 包):

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

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

单位测试

cd packages/pf-mcp
bun test

发展

# 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.)
└─────────────────┘

设计原则

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

外观 API 表面

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

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可以在不突破这个适配器的情况下重构内部.

路线图

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

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

第2阶段:增强能力

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

第3阶段:高级特征

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

捐款

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

许可证

麻省理工学院横跨德尔塔

版本与发布记录

@crossdelta/pf-mcp 共发布 6 个版本，首次发布于 2026/02/22；过去 12 个月发布了 6 个版本。

版本	发布日期	距今
`0.1.5`latest	2026/10/25	16 天前
`0.1.4`	2026/10/11	1 个月前
`0.1.3`	2026/03/14	7 个月前
`0.1.2`	2026/03/13	7 个月前
`0.1.1`	2026/02/27	8 个月前
`0.1.0`	2026/02/22	8 个月前

关于 @crossdelta/pf-mcp 的常见问题

@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 和提交记录判断。

npm install @crossdelta/pf-mcp

pnpmpnpm add @crossdelta/pf-mcp
yarnyarn add @crossdelta/pf-mcp
bunbun add @crossdelta/pf-mcp

peer 依赖@crossdelta/platform-sdk ^0.26.7

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

命令行npx pf-mcp

在你的项目目录中运行此命令。

近 30 天下载

2,193

约 2193 次日均 73 次

统计周期 2026/10/11 – 2026/11/09
数据来自 npm 官方下载统计，今天更新

最新版本0.1.5发布于 16 天前

开源许可MIT宽松许可

包体积1.2 MB14 个文件 · 解压后

运行依赖2 个另有 1 个 peer 依赖

模块格式ESM + CJS

TypeScript自带类型

Node.js>=18.0.0

发布版本6 个近 12 个月 6 个

首次发布2026/02/228 个月前

元数据更新2026/10/25

每一个软件包背后，
都有分享与创造的人。