本地开发：使用 pnpm link 同时开发框架和应用

本文档介绍如何使用 pnpm link 同时开发 BestMCP 框架和使用 BestMCP 的应用项目，适用于需要修改框架代码并在应用中立即验证效果的场景。

开发场景

典型使用场景

框架功能调试：在 BestMCP 框架中添加调试代码（如 console.log、debugger），需要在应用项目中观察输出
新功能开发：开发框架新功能时，需要在实际应用中测试和验证
Bug 修复：修复框架层面的 Bug，需要在应用项目中验证修复效果
性能优化：优化框架性能时，需要在真实应用环境中测量效果

与纯框架开发的区别

纯框架开发：只修改 packages/ 中的代码，通过 examples/ 验证
本地联动开发：同时修改框架代码和外部应用代码，需要实时同步

环境准备

前置条件

确保项目结构：


# 假设项目目录结构
~/workspace/
├── bestmcp/           # BestMCP 框架项目
└── my-mcp-app/        # 使用 BestMCP 的应用项目

安装依赖：


# 在 bestmcp 项目中
cd ~/workspace/bestmcp
pnpm install
 
# 在应用项目中（确保已安装 bestmcp）
cd ~/workspace/my-mcp-app
pnpm install

检查框架构建状态：
```
cd ~/workspace/bestmcp
pnpm build
```

pnpm link 具体步骤

第一步：构建 BestMCP 框架

在开始链接之前，确保 BestMCP 框架已构建：


cd ~/workspace/bestmcp
 
# 构建所有核心包
pnpm build
 
# 或者启用开发模式（推荐）
pnpm dev

提示：使用 pnpm dev 启动开发模式，这样修改代码后会自动重新构建。

第二步：在应用项目中链接 BestMCP

在应用项目目录中执行链接：


cd ~/workspace/my-mcp-app
 
# 链接本地的 bestmcp 包
pnpm link ~/workspace/bestmcp/packages/bestmcp
 
# 验证链接状态
pnpm list bestmcp

链接成功后，你会看到类似输出：


bestmcp -> /Users/yourname/workspace/bestmcp/packages/bestmcp

第三步：验证链接状态

检查链接是否正确建立：


# 在应用项目中检查依赖
cd ~/workspace/my-mcp-app
pnpm ls bestmcp
 
# 检查链接的实际路径
ls -la node_modules/bestmcp

应该显示链接到本地的 bestmcp 目录，而不是 npm 仓库的版本。

第四步：启动开发模式

现在可以启动两个项目的开发模式：


# 终端 1：启动 BestMCP 框架开发模式
cd ~/workspace/bestmcp
pnpm dev
 
# 终端 2：启动应用项目开发模式
cd ~/workspace/my-mcp-app
# 根据应用项目的启动方式，例如：
pnpm dev
# 或
pnpm start

调试配置

确保调试信息可见

由于你已经在 packages/server/src/server.ts 的 run 方法中添加了调试代码：


// packages/server/src/server.ts:422-442
async run(options: RunOptions = {}): Promise<void> {
  debugger; // 这个断点会在调试时触发
  const transportType = options.transport || "stdio";
 
  // 设置工具请求处理器
  this.setupToolRequestHandlers();
 
  // 初始化传输层
  await this.initializeTransport(transportType, options);
 
  // 启动传输层
  await this.transportManager.startCurrentTransport(this.server!);
 
  // 如果是 HTTP 传输，启动 HTTP 服务器
  if (transportType === "http") {
    await this.startHTTPServer(options);
  }
 
  console.log(`${this.name} v${this.version} 已启动`);
  console.log(`999传输层: ${transportType}`);  // 这个调试信息会显示
  console.log(`已注册 ${this.tools.size} 个工具`);
}

这些调试信息现在会在你的应用项目中运行时显示出来。

Source Map 配置

确保调试时能正确映射到源代码：

检查构建配置：BestMCP 的 tsup.config.ts 已经配置了 source map

Node.js 调试：如果需要断点调试，使用：


node --inspect --loader tsx/esm your-app-entry.ts

TypeScript 类型同步

由于使用链接，TypeScript 类型应该自动同步。如果遇到类型问题：


# 在应用项目中重新生成类型
cd ~/workspace/my-mcp-app
pnpm exec tsc --noEmit
 
# 或重启 TypeScript 服务器（如果在 VS Code 中）
# Cmd+Shift+P -> "TypeScript: Restart TS Server"

开发工作流

修改框架代码后的流程

修改代码：在 bestmcp/packages/server/src/ 中修改代码
自动构建：开发模式会自动重新构建
验证效果：在应用项目中立即看到修改效果
测试验证：运行应用项目的测试或手动测试

示例工作流


# 1. 修改框架代码（添加新的 console.log）
cd ~/workspace/bestmcp
# 编辑 packages/server/src/server.ts
 
# 2. 框架会自动重新构建（pnpm dev 运行中）
 
# 3. 在应用项目中验证
cd ~/workspace/my-mcp-app
# 重启应用或等待热重载
pnpm dev
 
# 4. 观察调试输出
# 应该能看到新添加的 console.log 信息

常见问题排查

链接失败

问题：pnpm link 命令失败


# 解决方案
cd ~/workspace/bestmcp
pnpm build  # 确保已构建
 
cd ~/workspace/my-mcp-app
pnpm install --force  # 强制重新安装
pnpm link ~/workspace/bestmcp/packages/bestmcp

构建缓存问题

问题：修改代码后看不到效果


# 解决方案：清理缓存
cd ~/workspace/bestmcp
pnpm clean
pnpm build
 
cd ~/workspace/my-mcp-app
rm -rf node_modules/.cache
pnpm install

TypeScript 类型不同步

问题：类型错误或智能提示不工作


# 解决方案
cd ~/workspace/my-mcp-app
rm -rf node_modules/bestmcp
pnpm link ~/workspace/bestmcp/packages/bestmcp
 
# 重启 TypeScript 服务器
# VS Code: Cmd+Shift+P -> "TypeScript: Restart TS Server"

调试信息不显示

问题：在应用中看不到 console.log 输出


# 检查步骤
# 1. 确认链接正确
cd ~/workspace/my-mcp-app
pnpm ls bestmcp
 
# 2. 确认构建包含最新代码
cd ~/workspace/bestmcp
git status  # 确认修改已保存
pnpm build  # 手动构建
 
# 3. 重启应用
cd ~/workspace/my-mcp-app
# 重启应用进程

取消链接

开发完成后，取消链接并恢复正常依赖：


cd ~/workspace/my-mcp-app
 
# 取消 bestmcp 链接
pnpm unlink bestmcp
 
# 重新安装 npm 版本
pnpm install bestmcp@latest
 
# 验证恢复到 npm 版本
pnpm ls bestmcp

最佳实践

开发环境配置

使用终端多路复用：


# 使用 tmux 或类似工具管理多个终端
# 一个终端运行 bestmcp dev
# 一个终端运行应用 dev

Git 工作流：


# 在 bestmcp 项目中
git checkout -b feature/new-debug-feature
# 开发完成后提交 PR

环境隔离：
- 为不同的项目使用不同的 Node.js 版本（如果需要）
- 使用环境变量管理开发/生产配置

团队协作建议

文档化修改：记录对框架的修改，方便团队成员理解
版本同步：定期同步 bestmcp 的最新版本
测试覆盖：确保修改有相应的测试用例

性能考虑

构建速度：使用 pnpm dev 的增量构建
内存使用：同时运行两个开发模式会增加内存使用
热重载：利用热重载减少重启次数

替代方案

Workspace 协议

如果你的应用项目也在同一个 monorepo 中，可以使用 workspace 协议：


// 在应用项目的 package.json 中
{
  "dependencies": {
    "bestmcp": "workspace:*"
  }
}

npm pack

另一种方式是使用 npm pack：


# 在 bestmcp 项目中
cd ~/workspace/bestmcp/packages/bestmcp
npm pack
 
# 在应用项目中
cd ~/workspace/my-mcp-app
npm install ~/workspace/bestmcp/packages/bestmcp/bestmcp-0.1.3.tgz

总结

使用 pnpm link 进行本地联动开发是调试和测试框架修改的有效方法。关键步骤是：

构建框架：确保 bestmcp 已构建
建立链接：在应用项目中链接本地 bestmcp
开发模式：同时运行两个项目的开发模式
验证效果：在应用中观察修改效果
清理恢复：开发完成后取消链接

这种方式特别适合需要频繁修改框架代码并立即验证效果的开发场景。