project-knowledge-mcp

Project Knowledge MCP Server

用于 Model Context Protocol（MCP）的跨项目知识图谱。 在移动端、后端和管理端代码库之间映射功能，让 AI Agent 在测试、编写代码、调试或添加功能时掌握完整的全栈上下文。

---

快速开始

npx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json

然后添加到 MCP 设置中：

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json"
      ],
      "autoApprove": []
    }
  }
}

---

目录

• 概览
• 功能
• 前置条件
• 安装与配置
• 知识文件管理
• 工具参考
• 使用指南
• 安全性
• 参与贡献
• 许可证

---

概览

问题

在一个包含多个代码库的项目中工作时——例如，React Native 移动应用、NestJS 后端和 Next.js 管理面板——AI Agent 无法了解单个功能如何在这三者之间流转。这会导致上下文不完整、遗漏依赖项，以及本可提前发现的破坏性变更。

解决方案

此 MCP 服务会存储一个知识图谱，记录项目中的功能，并将每个工作流步骤映射到各个项目中相关的屏幕、端点、控制器和文件。随后，AI Agent 可以查询此图谱，了解功能的端到端流程，在编辑文件前检测跨项目影响，并使各代码库中的类型定义保持同步。

---

功能

• 多项目感知 — 注册任意数量的项目（移动端、后端、管理端等）
• 功能工作流映射 — 将功能定义为跨所有项目的有序步骤
• 自动扫描 — 自动发现 NestJS 端点、Next.js 页面和 React Native 屏幕
• 全文搜索 — 搜索功能、端点、文件和屏幕
• 交叉引用查询 — 给定文件路径，查找引用该文件的功能
• 丰富上下文 — 获取特定工作流步骤中某项功能的所有端点、屏幕和文件
• 破坏性变更检测 — 编辑文件前，查看会影响哪些其他项目
• 类型／架构同步 — 映射不同项目中的等效类型（例如，ProductCreateDto ↔ ProductFormSchema）
• 架构探索 — 浏览任意项目的目录树，支持关键词筛选和内容高亮
• 健康状态验证 — 验证所有已注册文件路径是否仍然存在；自动检测过时条目
• 持久化知识 — 每次变更后自动保存到 JSON 文件；可纳入 Git 跟踪并共享
• 100% 动态化 — 所有配置均通过 CLI 参数和运行时工具完成；无需修改源代码

---

前置条件

• Node.js >= 18
• npm >= 9（或 pnpm / yarn 等效工具）
• 兼容 MCP 的客户端（例如，搭配 Cline 的 VS Code，或任何 AI 驱动的 IDE）

---

安装与配置

从 npm 安装（推荐）

npm install --save-dev project-knowledge-mcp

或无需安装，直接运行：

npx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json

从源代码构建

git clone https://github.com/punic-pillars/project-knowledge-mcp.git
cd project-knowledge-mcp
npm install
npm run build

CLI 标志

所有配置均通过 CLI 参数提供。无需环境变量或配置文件。

标志	描述	默认值
--backend-path	后端项目的绝对路径	—
--backend-framework	后端框架（nestjs、nextjs、react-native 或 auto）	auto
--backend-name	后端项目的自定义名称	backend
--mobile-path	移动端项目的绝对路径	—
--mobile-framework	移动端框架	auto
--mobile-name	移动端项目的自定义名称	mobile
--admin-path	管理端项目的绝对路径	—
--admin-framework	管理端框架	auto
--admin-name	管理端项目的自定义名称	admin
--knowledge-file	用于持久化知识 JSON 的绝对路径	./project-knowledge.json

MCP 客户端配置

基础设置 — 通过工具在运行时注册项目：

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json"
      ],
      "autoApprove": []
    }
  }
}

引导设置 — 在启动时预先注册项目：

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json",
        "--backend-path", "C:\\projects\\backend",
        "--mobile-path", "C:\\projects\\mobile",
        "--admin-path", "C:\\projects\\admin"
      ],
      "autoApprove": []
    }
  }
}

---

知识文件管理

知识文件是一个纯 JSON 文件，用于存储所有已注册的项目、功能工作流和类型映射。了解它的存放位置对于维护一致的知识图谱至关重要。

共享文件模式

如果你的全栈项目位于不同目录（例如 backend/、mobile/、admin/），每个 IDE 窗口都会从不同的工作目录启动 MCP 服务。如果不使用 --knowledge-file，每个实例都会创建自己的片段：

backend/
└── project-knowledge.json   ← only backend context

mobile/
└── project-knowledge.json   ← only mobile context

admin/
└── project-knowledge.json   ← only admin context

这会违背跨项目感知的初衷。始终使用 --knowledge-file 并指定绝对路径，让所有 IDE 窗口指向同一个文件：

projects/
├── project-knowledge.json   ← single source of truth
├── backend/
├── mobile/
└── admin/

无论你打开的是哪个子项目，每个 IDE 窗口都要使用相同的 --knowledge-file 路径。所有实例都会读写同一个文件，从而保持知识图谱完整且一致。

默认路径何时安全

仅当你打开单体仓库根目录（包含所有子项目的单个目录）时，默认路径（不使用 --knowledge-file）才是安全的：

my-monorepo/              ← open this in your IDE
├── project-knowledge.json   ← created here, covers everything
├── backend/
├── mobile/
└── admin/

如果你的项目位于不同的仓库或目录中，请始终使用 --knowledge-file。

与团队共享

由于知识文件是纯 JSON 文件，你可以将它提交到版本控制中并与团队共享：

# Track the knowledge graph
git add project-knowledge.json
git commit -m "chore: add project knowledge graph"

# Or keep it local
echo "project-knowledge.json" >> .gitignore

指南：一个全栈项目 = 一个知识文件。如果你的项目位于不同目录中，请始终使用 --knowledge-file 并指定绝对路径。

---

工具参考

项目管理

工具	描述
register_project	使用名称、路径和框架注册项目
remove_project	移除已注册的项目
scan_project	从项目中自动发现端点、屏幕或页面

功能管理

工具	描述
register_feature	定义包含多个项目工作流步骤的功能
remove_feature	移除功能
get_feature	获取完整的功能详情（精简或详细模式，可选健康检查）

搜索与查询

工具	描述
search	搜索功能、端点、文件和屏幕
reverse_lookup	查找文件在所有项目中的跨项目引用（图谱注册和扫描发现），以及引用该文件的功能
get_context	获取功能或步骤的跨项目上下文（可选影响分析）

类型/架构同步

工具	描述
register_type_mappings	注册一个或多个类型映射（接受单个对象或数组）
check_type_mapping	查找所有定义或引用某个类型的项目文件
suggest_type_mappings	通过扫描所有项目自动检测潜在的类型映射

架构探索

工具	描述
get_architecture	探索项目目录树，可选使用 filter（路径关键词）、highlight（带 ★ 标记的内容关键词）和 showAll（显示完整目录树并标记匹配项）

验证

工具	描述
validate_knowledge	检查所有已注册的文件路径是否有过时条目；可选使用 fix=true 自动修复

持久化

工具	描述
export_knowledge	确认知识文件路径并触发显式保存（每次变更后都会自动持久化）
import_knowledge	从 JSON 文件加载知识（合并或替换，并提供预览）

---

使用流程演示

本演示使用一个真实的多项目配置（NestJS 后端、React Native 移动应用、Next.js 管理面板），展示核心工作流。领域名称已匿名化——用“产品”代替“站点”，用“订单”代替“报告”——但所有展示的命令都在实际项目中运行过。

步骤 1：注册项目

register_project { name: "backend", path: "C:/projects/backend", framework: "nestjs" }
register_project { name: "mobile", path: "C:/projects/mobile", framework: "react-native" }
register_project { name: "admin", path: "C:/projects/admin", framework: "auto" }

步骤 2：扫描项目

自动发现端点、屏幕和页面：

scan_project { projectName: "backend" }
scan_project { projectName: "mobile" }
scan_project { projectName: "admin" }

扫描器在所有已注册项目中发现了 150+ 个端点、200+ 个屏幕以及多个管理页面。

步骤 3：定义功能

注册一个 auth 功能——这是一个涉及全部三个项目的简单流程：

register_feature {
  name: "auth",
  description: "Authentication flow — login, register, forgot password, email confirmation",
  workflow: [
    {
      step: 1, name: "Login",
      description: "User logs in with email and password",
      mobile: { screen: "LoginScreen", api: "POST /api/v1/auth/email/login" },
      backend: { endpoint: "POST /api/v1/auth/email/login", controller: "AuthController", file: "src/auth/auth.controller.ts" },
      admin: { page: "/login", file: "src/pages/Login" }
    },
    {
      step: 2, name: "Register",
      description: "User registers a new account",
      mobile: { screen: "RegisterScreen", api: "POST /api/v1/auth/email/register" },
      backend: { endpoint: "POST /api/v1/auth/email/register", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 3, name: "Email Confirmation",
      description: "Confirm email address",
      mobile: { api: "POST /api/v1/auth/email/confirm" },
      backend: { endpoint: "POST /api/v1/auth/email/confirm", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 4, name: "Forgot Password",
      description: "Request password reset",
      mobile: { screen: "ForgotPasswordScreen", api: "POST /api/v1/auth/forgot/password" },
      backend: { endpoint: "POST /api/v1/auth/forgot/password", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 5, name: "Reset Password",
      description: "Reset password with token",
      mobile: { screen: "ResetPasswordScreen", api: "POST /api/v1/auth/reset/password" },
      backend: { endpoint: "POST /api/v1/auth/reset/password", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    }
  ],
  test_scenarios: [
    "Login with valid credentials returns token",
    "Login with invalid email returns 401",
    "Register with existing email returns conflict",
    "Forgot password sends email",
    "Reset password with valid token works"
  ]
}

步骤 4：查询功能

紧凑模式——获取摘要：

get_feature { name: "auth" }

返回：5 个步骤、5 个测试场景，移动端=5 个屏幕，后端=5 个端点，管理端=1 个页面。

详细模式——获取完整工作流详情：

get_feature { name: "auth", verbose: true }

返回全部 5 个步骤，以及完整的移动端屏幕、后端端点、控制器和文件路径。

附带健康检查——验证所有已注册路径是否存在：

get_feature { name: "auth", includeHealth: true }

返回：健康状态：后端 5/5 正常，移动端=5/5，管理端=1/5，5 个测试场景。

步骤 5：搜索和交叉引用

跨知识图谱搜索：

search { query: "product" }

返回 100 多条结果，涵盖功能、工作流步骤、后端映射、移动端映射、类型映射和文件内容。

查找对某个文件的跨项目引用：

reverse_lookup { filePath: "auth.controller.ts" }

返回：

• 功能关联：引用此文件的功能（auth 功能的第 1–5 步）
• 图谱已注册项：5 个完全匹配项（auth 功能的第 1–5 步，全部为后端），以及管理端的 Login 页面
• 扫描发现项：所有项目中导入或引用 auth.controller.ts 的文件

步骤 6：类型映射

注册跨项目类型映射：

register_type_mappings {
  mapping: {
    typeName: "productId",
    sourceProject: "backend",
    sourceFile: "src/products/infrastructure/persistence/relational/entities/product.entity.ts",
    targetProject: "mobile",
    targetFile: "app/_types/ProductTypes.ts",
    description: "Standardizing productId as numeric INTEGER across all projects"
  }
}

更改类型前，检查哪些内容引用了该类型：

check_type_mapping { typeName: "productId" }

返回所有项目中定义或引用 productId 的文件。

自动发现潜在的类型映射：

suggest_type_mappings { limit: 5, confidence: "high" }

扫描所有已注册项目，查找完全匹配的类型名称——返回建议，并附上可直接用于注册的源文件和目标文件路径。

步骤 7：验证并导出

验证知识健康状态：

validate_knowledge

检查所有功能和类型映射中已注册的文件路径，并返回现存和缺失条目的报告。

确认持久化状态：

每次变更后，知识图谱都会自动持久化——register_project、register_feature、register_type_mappings 以及使用 fix=true 的 validate_knowledge 都会立即写入磁盘。提交到版本控制前，使用 export_knowledge 确认文件路径：

export_knowledge

返回知识文件的路径。将此文件纳入 Git 跟踪，以便与团队共享上下文。

---

安全

• 知识文件是纯 JSON——存储位置和访问权限由你控制
• 不存储凭据——此 MCP 仅存储项目路径和功能映射
• 文件扫描为只读操作——扫描器只读取文件，不会修改文件

---

贡献

欢迎贡献。若有任何改进、错误修复或功能请求，请提交 issue 或拉取请求。

---

许可证

MIT