技术文档摘要

Workspace Bridge MCP Server

⚠️ 开发初期 / 实验性 - 此包正在积极开发中（v0.1.0）。API可能会发生变化。

一个强大的项目感知型MCP服务器，支持跨项目文件访问和git历史记录探索。每个项目通过简单的配置文件定义需要访问的其他项目！

功能

文件访问

• 📂 项目特定配置：每个项目定义其链接的项目
• 🔗 自动加载：当您的MCP客户端打开项目时，自动加载链接的项目
• 📁 跨项目文件访问：从任何链接的项目读取文件
• 🚀 无全局硬编码：配置与每个项目一起存在
• 🔍 浏览项目文件：列出所有链接项目的目录和文件

Git历史

• 🕰️ 提交历史：使用强大的过滤器查看提交历史（作者、日期、分支）
• 🔎 搜索提交：搜索提交消息和代码更改
• 📝 提交详情：获取任何提交的完整差异和统计信息
• 📄 文件历史：跟踪特定文件随时间的变化
• 👥 Git Blame：查看文件中每一行的最后修改者
• 🌿 分支比较：比较不同分支之间的提交
• ℹ️ 仓库信息：获取分支、远程、标签和状态

安装

先决条件

• Node.js（v18或更高版本）
• Git（用于git历史功能）

快速开始

通过npm全局安装：

npm install -g workspace-bridge-mcp

或者使用npx（无需安装）：

npx workspace-bridge-mcp

配置您的MCP客户端

在您的MCP客户端配置文件中添加此服务器：

选项1（无需安装）：

{
  "mcpServers": {
    "workspace-bridge": {
      "command": "npx",
      "args": ["-y", "workspace-bridge-mcp"]
    }
  }
}

替代方案（如果已全局安装）：

{
  "mcpServers": {
    "workspace-bridge": {
      "command": "workspace-bridge-mcp"
    }
  }
}

重启您的MCP客户端以加载服务器。

开发设置

如果您想贡献或从源码运行：

1. 克隆此仓库：

   git clone https://github.com/AmrAbdelmagid/workspace-bridge-mcp.git
   cd workspace-bridge-mcp
   

2. 安装依赖项：

   npm install
   

3. 配置您的MCP客户端以使用本地版本：

   {
     "mcpServers": {
       "workspace-bridge": {
         "command": "node",
         "args": ["/绝对路径到/workspace-bridge-mcp/index.js"]
       }
     }
   }
   

使用方法

第一步：创建配置文件

在主项目中创建一个.workspace-bridge.json文件：

{
  "projects": [
    {
      "name": "project_b",
      "path": "/绝对路径到/project_b"
    },
    {
      "name": "shared_lib",
      "path": "../shared_lib"
    }
  ]
}

注意：路径可以是绝对路径或相对于当前项目目录的相对路径。

第二步：打开您的项目

当您在MCP客户端中打开一个项目时，服务器会自动：

• 注册当前项目
• 加载并注册来自.workspace-bridge.json的所有项目
• 使所有项目可用于跨项目访问

第三步：使用跨项目功能

现在您可以访问所有链接项目的文件和git历史：

• "显示project_b/src文件夹中的文件"
• "从shared_lib读取配置文件"
• "比较project_a和project_b的实现"

可用工具

MCP服务器提供两类工具：

文件访问工具

listProjects

列出所有注册的项目（当前项目+链接项目）。

listFiles

列出项目目录中的文件和文件夹。

参数：

• project（字符串）：项目名称
• dir（字符串，可选）：项目内的子目录路径

示例用法：

• "列出project_b/src文件夹中的文件"
• "显示shared_lib/lib/utils的内容"

readFile

从项目中读取文件内容。

参数：

• project（字符串）：项目名称
• file（字符串）：从项目根目录开始的相对文件路径

示例用法：

• "从project_b读取主文件"
• "显示shared_lib/lib/config.js的内容"

高级工具（运行时管理）

如果您需要在会话期间添加/删除项目而不编辑配置文件：

addProject

动态地在运行时添加项目。

参数：

• name（字符串）：项目的友好名称
• path（字符串）：项目的绝对路径

removeProject

从当前会话中移除项目。

参数：

• name（字符串）：要移除的项目名称

Git历史工具

所有git工具都可以在任何注册项目（当前项目或链接项目）上工作。项目必须是git仓库。

getCommitHistory

获取git提交历史，带有强大的过滤选项。

参数：

• project（字符串）：项目名称
• branch（字符串，可选）：分支名称（默认为当前分支）
• maxCount（数字，可选）：返回的最大提交数（默认：50）
• skip（数字，可选）：跳过提交以进行分页
• author（字符串，可选）：按作者名或邮箱过滤
• since（字符串，可选）：自某日期以来的提交（例如："2_024-01-01"，"1周前"）
• until（字符串，可选）：直到某日期的提交

示例用法：

• "显示project_a的最后20个提交"
• "获取project_b中john@example.com在过去一个月的提交"
• "显示shared_lib中feature-branch上的提交"

searchCommits

搜索提交消息，可选地搜索代码更改。

参数：

• project（字符串）：项目名称
• query（字符串）：要在提交消息中查找的搜索词
• searchInDiff（布尔值，可选）：也搜索代码更改（默认：false）
• maxCount（数字，可选）：最大结果数（默认：50）
• author（字符串，可选）：按作者过滤

示例用法：

• "在project_a中搜索关于'feature X'的提交"
• "查找提到'refactor'的提交，并在project_b中搜索代码更改"
• "搜索由developer@example.com在shared_lib中修复的错误"

getCommitDetails

获取特定提交的详细信息，包括完整的差异。

参数：

• project（字符串）：项目名称
• commitHash（字符串）：提交哈希（完整或短）

示例用法：

• "显示project_a中abc123提交的详细信息"
• "获取project_b中7f3e9a2提交的差异"

getFileHistory

获取特定文件的提交历史。

参数：

• project（字符串）：项目名称
• file（字符串）：相对于项目根目录的文件路径
• maxCount（数字，可选）：最大提交数（默认：50）

示例用法：

• "显示project_a中src/main.js的历史"
• "project_b中的lib/config.js最后一次被修改是什么时候？"
• "获取所有更改此文件的提交在shared_lib中"

gitBlame

显示文件中每一行的最后修改者。

参数：

• project（字符串）：项目名称
• file（字符串）：相对于项目根目录的文件路径
• startLine（数字，可选）：起始行号
• endLine（数字，可选）：结束行号

示例用法：

• "谁写了project_a/src/module.js中的这个函数？"
• "显示project_b/src/main.js中第10-50行的blame"

getRepositoryInfo

获取仓库信息，包括分支、远程、标签和状态。

参数：

• project（字符串）：项目名称

示例用法：

• "project_a中有哪些分支？"
• "显示project_b的git状态"
• "shared_lib中的当前分支是什么？"

compareBranches

比较两个分支之间的提交。

参数：

• project（字符串）：项目名称
• baseBranch（字符串）：基础分支名称
• compareBranch（字符串）：要比较的分支

示例用法：

• "比较project_a中的feature-branch与main"
• "project_b中的develop分支有哪些不在main中的提交？"

使用案例

1. 跨项目升级框架/依赖

在升级主要依赖项或框架版本时，先在一个项目中完成迁移，然后使用此MCP服务器帮助将相同更改应用于其他项目。

工作流程：

1. 在project_a中完成迁移
2. 从project_b使用MCP服务器：
   • "搜索关于'框架升级'的提交在project_a"
   • "显示project_a中abc123提交的详细信息及完整差异"
   • "获取project_a/package.json的文件历史以查看所有依赖项更改"
   • "读取project_a中的迁移说明或更新的配置文件"
3. 根据检查到的模式，在project_b中应用类似的更改

优点：避免重复研究，捕捉已经解决的边缘情况，保持项目间的一致性。

2. 复制相似项目的逻辑变更

当多个项目共享相似业务逻辑时，可以在一个项目中实施变更，然后审查并复制到其他项目。

工作流程：

1. 在project_a中实现一个特性或修复
2. 从project_b：
   • "从project_a/src/utils/handler.js读取更新的模块"
   • "显示project_a/src/utils/handler.js的git blame以查看最近更改"
   • "获取此文件的提交历史以了解演变过程"
   • "比较我的当前实现与project_a的版本"
3. 适应并应用改进到project_b

优点：跨团队分享改进，保持功能一致性，减少重复工作。

3. 向其他项目学习

加入团队或探索不熟悉的代码时，可以查看相关项目中类似问题是如何解决的。

工作流程：

• "显示project_a如何实现特性X"
• "从shared_lib读取实现"
• "获取project_b模块的提交历史以理解设计决策"
• "谁在project_c中实现了这个组件？显示git blame"

优点：更快地融入团队，理解架构模式，从现有解决方案中学习。

4. 类似单体仓库风格的开发而无需单体仓库

像在单体仓库中一样处理多个独立仓库，跨项目访问文件和历史记录，无需重构仓库架构。

工作流程：

• "列出project_a、project_b和shared_lib中的所有配置文件"
• "比较各项目的构建配置"
• "搜索所有链接项目中的TODO注释"
• "追踪每个项目何时更新了CI/CD管道"

优点：保持仓库独立性的同时获得类似单体仓库的可见性和协调性。

5. 跨项目边界调试问题

当一个bug可能源自依赖项目或共享库的更改时，可以跨项目边界进行调查。

工作流程：

• "shared_lib最近什么时候更新了？显示最近的提交"
• "project_a最近是否更改了接口？检查git历史"
• "比较project_a和project_b的数据结构以发现差异"
• "显示哪个开发者最近修改了这两个项目的集成点"

优点：快速找到根本原因，理解跨项目依赖关系，追踪破坏性更改。

示例工作流程

工作流程1：多个相关项目

项目结构：

/workspace/project_a/       ← 您在这里（当前项目）
/workspace/project_b/       ← 需要访问
/workspace/shared_lib/      ← 共享工具

在project_a/.workspace-bridge.json中：

{
  "projects": [
    {
      "name": "project_b",
      "path": "../project_b"
    },
    {
      "name": "shared_lib",
      "path": "../shared_lib"
    }
  ]
}

使用：

• "比较project_a和project_b的实现流程"
• "检查两个项目是否使用相同的模式"
• "读取shared_lib中的工具"

工作流程2：Git历史分析

场景：在project_a中调试问题

命令：

• "搜索project_a中关于'特性X'的提交"
• "显示abc123提交的详细信息及完整差异"
• "谁最近修改了这个文件？显示project_a/src/module.js的git blame"
• "获取过去两个月内此文件的更改历史"

工作流程3：跨项目代码审查与历史

场景：比较项目间的实现及其演变

命令：

• "从project_a和project_b读取服务模块"
• "搜索两个项目中关于'refactor'的提交"
• "显示每个项目何时更新了集成"
• "比较project_a中的feature-branch与main，看看增加了什么"

运作方式

1. 启动时：MCP服务器从当前项目目录读取.workspace-bridge.json
2. 自动注册：当前项目+所有链接项目被注册
3. 每项目配置：每个项目都有自己的独立配置
4. 无全局状态：没有在全局配置文件中硬编码路径

配置文件格式

{
  "projects": [
    {
      "name": "友好名称",      // 必需：工具中使用的名称
      "path": "/绝对或相对路径"  // 必需：项目路径
    }
  ]
}

路径解析：

• 绝对路径：直接使用
• 相对路径：相对于当前项目目录解析

Git要求

为了使git历史工具正常工作：

• ✅ 项目必须是git仓库（有.git文件夹）
• ✅ 系统上必须安装Git
• ✅ 非git项目仍可使用所有文件访问工具

如果项目不是git仓库，文件访问工具将继续正常工作，但git工具将返回明确的错误消息。

重新加载更改

更新MCP服务器代码后，重启您的MCP客户端以加载更改。

注意：更改.workspace-bridge.json时不需要重启MCP客户端——只需重新加载窗口或重启MCP连接。

许可证

本项目根据MIT许可证发布——详情见LICENSE文件。

贡献

欢迎贡献！请随时提交Pull Request。