Project Hub MCP Server

Project Hub MCP 服务

一个 MCP 服务，提供全面的项目管理、本地 Git 功能和 GitHub 集成能力。此服务支持管理本地项目、跟踪更改、创建本地提交，以及与 GitHub 仓库同步。

功能

项目管理

• 创建和管理项目，支持灵活、不区分大小写的部分名称搜索
• 扫描和监控源文件，并可自定义排除模式
• 跟踪和更新项目元数据

本地 Git 功能

• 创建和管理本地提交，无需 GitHub
• 分支管理（创建、切换、列出）
• 文件快照及其元数据（大小、创建时间、修改时间）
• 还原功能，可回退到之前的提交或分支
• 克隆功能，可从提交或分支创建新实例

更改跟踪

• 记录和跟踪更改及其相关文件
• 按类型分类更改（功能、修复、重构等）
• 将更改关联到提交，以便完整追溯历史

笔记系统

• 创建和管理包含丰富 Markdown 内容的项目笔记
• 对笔记进行分类和标记，以便更好地整理
• 搜索功能可查找相关文档

GitHub 集成

• 仓库管理（创建、更新、删除、重命名）
• 提交管理及文件内容跟踪
• 分支操作（创建、删除、合并）
• 创建和管理拉取请求
• 克隆仓库并在本地设置
• 支持多个 GitHub 账户

工具

项目管理

create_project

创建项目，并管理本地和远程仓库。

• name：项目名称
• path：本地项目路径
• type：项目类型
• description：项目描述

find_project

按名称查找项目（灵活、不区分大小写、部分匹配）。返回详细的项目信息，包括更改和笔记。

• name：要搜索的项目名称

list_projects

列出所有项目，可选进行筛选。

• type：按项目类型筛选（可选）
• has_repo：按是否存在仓库筛选（可选）
• page：分页页码（可选）
• page_size：每页项目数（可选）

update_project_details

更新现有项目的详细信息。

• projectId：项目 ID
• name：新项目名称（可选）
• path：新项目路径（可选）
• type：新项目类型（可选）
• description：新项目描述（可选）
• status：新项目状态（可选）

delete_project

删除项目。

• projectId：项目 ID

scan_project_files

扫描项目目录中的源文件并更新项目记录。

• projectId：项目 ID
• excludePatterns：用于排除文件的正则表达式模式（可选）

projectdb_location

获取项目数据库位置的完整路径。

更改管理

record_change

记录项目中的更改。

• projectId：项目 ID
• type：更改类型
• description：更改描述
• files：受此更改影响的文件路径列表（可选）

get_pending_changes

获取项目的待处理更改。

• projectId：项目 ID

clear_committed_changes

清除项目中已提交的更改。

• projectId：项目 ID

本地 Git 功能

init_local_repository

为项目初始化本地 Git 仓库。

• projectId：项目 ID

create_local_commit

根据待处理更改创建本地提交。

• projectId：项目 ID
• message：提交信息
• authorName：作者姓名（可选）
• authorEmail：作者电子邮箱（可选）

get_local_commit_history

获取项目的本地提交历史。

• projectId：项目 ID

create_local_branch

创建新的本地分支。

• projectId：项目 ID
• name：分支名称
• startingCommitId：起始提交 ID（可选）

switch_local_branch

切换到其他本地分支。

• projectId：项目 ID
• branchName：分支名称

list_local_branches

列出项目的所有本地分支。

• projectId：项目 ID

restore_to_local_commit

将项目文件还原到指定的本地提交。

• projectId：项目 ID
• commitId：要还原到的提交 ID

restore_to_local_branch

将项目文件还原到指定的本地分支。

• projectId：项目 ID
• branchName：要还原到的分支名称

restore_local_commit_to_new_location

将指定的本地提交还原到新文件夹位置。

• projectId：项目 ID
• commitId：要还原的提交 ID
• newLocation：要还原到的新文件夹路径

restore_local_branch_to_new_location

将指定的本地分支还原到新文件夹位置。

• projectId：项目 ID
• branchName：要还原的分支名称
• newLocation：要还原到的新文件夹路径

push_local_commits

将本地提交推送到 GitHub。

• projectId：项目 ID
• repo：仓库名称
• branch：分支名称（可选）

force_local_commit

强制提交项目中的所有文件，不论是否有待处理的更改。

• projectId：项目 ID
• message：提交信息
• authorName：作者姓名（可选）
• authorEmail：作者邮箱（可选）

cleanup_project_files

从项目的 Project Hub 数据中移除不存在文件的记录。

• projectId：项目 ID

文件快照管理

get_file_snapshots

获取提交的文件快照。

• commitId：提交 ID

get_file_snapshots_metadata

获取提交的文件快照元数据（不含文件内容）。

• commitId：提交 ID

get_file_content

获取快照的文件内容。

• snapshotId：快照 ID

便笺管理

create_note

为项目创建新的便笺。

• project_name：项目名称
• title：便笺标题
• content：便笺内容
• category：便笺类别（可选）
• tags：便笺标签（可选）

update_note

更新现有便笺。

• project_name：项目名称
• note_id：便笺 ID
• title：新便笺标题（可选）
• content：新便笺内容（可选）
• category：新便笺类别（可选）
• tags：新便笺标签（可选）

delete_note

删除便笺。

• project_name：项目名称
• note_id：便笺 ID

search_notes

搜索项目中的便笺。

• project_name：项目名称
• query：搜索查询
• category：按类别筛选（可选）

仓库管理

create_repository

创建新的 GitHub 仓库。

• name：仓库名称
• description：仓库描述（可选）
• isPrivate：仓库是否为私有（可选）

get_repository

获取特定仓库的详细信息。

• name：仓库名称

update_repository

更新仓库设置。

• name：仓库名称
• description：新的仓库描述（可选）
• private：更改仓库可见性（可选）
• default_branch：更改默认分支（可选）
• has_issues：启用/禁用 Issues（可选）
• has_wiki：启用/禁用 Wiki（可选）

delete_repository

删除 GitHub 仓库。

• name：仓库名称

rename_repository

重命名 GitHub 仓库。

• oldName：当前仓库名称
• newName：新仓库名称

list_repositories

列出已通过身份验证的用户的所有仓库。

• visibility：按可见性筛选仓库（可选）
• sort：按字段对仓库排序（可选）
• per_page：每页结果数（可选）

fork_repository

派生现有仓库。

• name：要派生的仓库名称
• organization：要派生到的组织（可选）

transfer_repository

转移仓库所有权。

• name：仓库名称
• new_owner：新所有者的用户名或组织名称
• team_ids：要添加到仓库的团队 ID（可选）

clone_repository

将存储库克隆到指定文件夹。

• repo：存储库名称
• targetFolder：克隆存储库的目标文件夹
• branch：要克隆的分支（可选）

文件管理

get_file

获取 GitHub 存储库中的文件内容。

• repo：存储库名称
• path：存储库中的文件路径
• ref：Git 引用（分支、标签或提交 SHA）（可选）

提交管理

create_commit

在 GitHub 存储库中创建提交。

• repo：存储库名称
• branch：分支名称（可选，默认为 main）
• message：提交消息
• changes：文件更改数组（路径、内容、操作）

list_commits

列出 GitHub 存储库中的提交。

• repo：存储库名称
• branch：分支名称（可选）

get_commit

获取 GitHub 存储库中的提交详情。

• repo：存储库名称
• sha：提交 SHA

revert_commit

还原 GitHub 存储库中的提交。

• repo：要还原的提交 SHA

分支管理

create_branch

在 GitHub 存储库中创建新分支。

• repo：存储库名称
• name：新分支名称
• sourceBranch：从中创建新分支的源分支（可选，默认为 main）

delete_branch

删除存储库中的分支。

• repo：存储库名称
• name：要删除的分支名称

list_branches

列出存储库中的所有分支。

• repo：存储库名称

get_branch

获取特定分支的详情。

• repo：存储库名称
• name：分支名称

merge_branches

合并存储库中的两个分支。

• repo：存储库名称
• base：基分支名称
• head：头部分支名称
• message：合并提交消息（可选）

拉取请求管理

create_pull_request

创建新的拉取请求。

• repo：存储库名称
• title：拉取请求标题
• head：头部分支名称
• base：基分支名称
• body：拉取请求描述（可选）
• draft：创建为草稿 PR（可选）
• maintainer_can_modify：允许维护者修改（可选）

实用工具

list_tools

列出 Project Hub MCP 中所有可用的工具。

架构

数据库架构

Project Hub MCP 服务使用 SQLite 存储数据，其中包含以下关键表：

• projects：存储项目元数据
• changes：跟踪对项目所做的更改
• notes：存储项目文档
• source_files：汇总项目中的文件
• local_commits：存储本地提交信息
• local_branches：跟踪分支信息
• file_snapshots：存储提交时的文件内容和元数据
• commit_changes：将提交映射到更改

关键组件

• ProjectManager：处理项目的增删改查操作和元数据
• LocalGitService：管理本地 Git 功能
• FileSnapshotService：处理文件快照操作
• GitHubService：与 GitHub API 交互
• StorageService：管理数据库操作
• SourceScanner：扫描并汇总项目文件

安装

1. 克隆存储库：

git clone https://github.com/peterparker57/project-hub-mcp-server.git
cd project-hub-mcp-server

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

配置

将服务添加到 MCP 设置文件中：

{
  "mcpServers": {
    "project-hub": {
      "command": "node",
      "args": ["path/to/project-hub-mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "DEFAULT_PRIVATE": "true",
        "DEFAULT_OWNER": "your-github-username",
        "GITHUB_TOKEN": "your-github-token",
        "GIT_PATH": "C:\\Program Files\\Git\\bin\\git.exe"
      },
      "alwaysAllow": [
        "list_projects",
        "find_project",
        "get_pending_changes",
        "get_local_commit_history",
        "list_local_branches"
      ]
    }
  }
}

环境变量

• NODE_ENV：设置为 "development" 或 "production"
• DEFAULT_PRIVATE：新存储库是否应默认设为私有
• DEFAULT_OWNER：存储库操作的默认 GitHub 用户名
• GITHUB_TOKEN：具有相应权限的 GitHub 个人访问令牌
• GIT_PATH：本地 Git 操作所用的 Git 可执行文件路径

使用示例

项目管理

// Create a new project
await mcp.use("project-hub", "create_project", {
  name: "my-project",
  path: "./projects/my-project",
  type: "typescript",
  description: "A new TypeScript project"
});

// Find a project (flexible name search)
await mcp.use("project-hub", "find_project", {
  name: "my-project" // Works with "My-Project", "MY-PROJECT", "my project notes", etc.
});

// Record a change
await mcp.use("project-hub", "record_change", {
  projectId: "project-id",
  description: "Added new feature",
  type: "feature",
  files: ["src/feature.ts"]
});

// Scan project files
await mcp.use("project-hub", "scan_project_files", {
  projectId: "project-id",
  excludePatterns: ["node_modules", "\\.git", "dist", "build"]
});

本地 Git 功能

// Initialize local repository
await mcp.use("project-hub", "init_local_repository", {
  projectId: "project-id"
});

// Create a local commit
await mcp.use("project-hub", "create_local_commit", {
  projectId: "project-id",
  message: "Implemented new feature",
  authorName: "John Doe",
  authorEmail: "[email protected]"
});

// Create a new branch
await mcp.use("project-hub", "create_local_branch", {
  projectId: "project-id",
  name: "feature/new-feature"
});

// Switch to a branch
await mcp.use("project-hub", "switch_local_branch", {
  projectId: "project-id",
  branchName: "feature/new-feature"
});

// Restore to a previous commit
await mcp.use("project-hub", "restore_to_local_commit", {
  projectId: "project-id",
  commitId: "commit-id"
});

// Clone a branch to a new location
await mcp.use("project-hub", "restore_local_branch_to_new_location", {
  projectId: "project-id",
  branchName: "main",
  newLocation: "C:/Projects/new-clone"
});

// Push local commits to GitHub
await mcp.use("project-hub", "push_local_commits", {
  projectId: "project-id",
  repo: "my-project",
  branch: "main"
});

笔记管理

// Create a project note
await mcp.use("project-hub", "create_note", {
  project_name: "my-project",
  title: "Architecture Decision Record",
  content: "# ADR-001: Project Structure\n\n...",
  category: "documentation",
  tags: ["architecture", "decision"]
});

// Search notes
await mcp.use("project-hub", "search_notes", {
  project_name: "my-project",
  query: "architecture",
  category: "documentation"
});

GitHub 集成

// Create and link repository
await mcp.use("project-hub", "create_repository", {
  name: "my-project",
  description: "A new TypeScript project",
  isPrivate: true
});

// Clone a repository
await mcp.use("project-hub", "clone_repository", {
  repo: "my-project",
  targetFolder: "./projects/my-project",
  branch: "main"
});

// Create a feature branch
await mcp.use("project-hub", "create_branch", {
  repo: "my-project",
  name: "feature/new-feature",
  sourceBranch: "main"
});

// Create a commit on the feature branch
await mcp.use("project-hub", "create_commit", {
  repo: "my-project",
  changes: [{
    path: "src/feature.ts",
    content: "// New feature code",
    operation: "add"
  }],
  message: "feat: add new feature",
  branch: "feature/new-feature"
});

// Create pull request
await mcp.use("project-hub", "create_pull_request", {
  repo: "my-project",
  title: "Add new feature",
  head: "feature/new-feature",
  base: "main",
  body: "This PR adds a new feature",
  draft: false,
  maintainer_can_modify: true
});

// After PR review, merge the branches
await mcp.use("project-hub", "merge_branches", {
  repo: "my-project",
  base: "main",
  head: "feature/new-feature",
  message: "Merge feature/new-feature into main"
});

开发

1. 修改源代码
2. 运行测试：

npm test

3. 构建项目：

npm run build

近期增强

本地 Git 功能（2025 年 3 月）

• 添加了全面的本地 Git 功能，包括提交、分支和文件快照
• 实现了还原功能，可恢复到之前的状态
• 添加了克隆功能，可根据提交或分支创建新实例
• 增强了文件快照，支持跟踪元数据（大小、创建时间、修改时间）

项目管理改进（2025 年 2 月）

• 添加了 clone_repository 工具，可将 GitHub 仓库克隆到指定文件夹
• 实现了 scan_project_files 工具，可扫描项目目录并整理源文件目录
• 改进了项目搜索，支持灵活、不区分大小写的部分名称匹配
• 改进了文件跟踪，提供更完善的元数据

贡献

1. Fork 此仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

MIT