mcp-architector

MCP Architector

用于架构与系统设计的 Model Context Protocol (MCP) 服务

本地优先的 MCP 服务，用于存储和管理项目架构信息。所有数据都存储在本地的 ~/.mcp-architector 中，最大限度地保护隐私和机密性。

📦 安装：npm install -g mcp-architector，或通过 npx 使用 🌐 npm：https://www.npmjs.com/package/mcp-architector 🔗 GitHub：https://github.com/theSharque/mcp-architect

如何连接 Claude Desktop / IDE

将服务添加到 MCP 配置中。claude_desktop_config.json 配置示例：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

对于 Cursor IDE：前往 Settings → Features → Model Context Protocol → Edit Config，然后在 mcpServers 中添加相同的代码块。更多选项请参阅 集成 部分。

Cursor 规则（推荐）

对于 Cursor IDE 和 Cursor Cloud Agents，请使用分阶段的引导规则，避免 Agent 一次性将整个代码库加载到上下文中。

1. 将 .cursor/rules/architector-onboarding.mdc 复制到你的项目中（即你要编写文档的代码库）：

   mkdir -p /path/to/your-app/.cursor/rules
   cp /path/to/mcp-architector/.cursor/rules/architector-onboarding.mdc /path/to/your-app/.cursor/rules/
   

2. 确保 MCP Architector 已连接。Agent 必须调用 list-projects，并在每次写入时传入 projectId — 不要依赖省略该参数。

3. 在聊天中提出请求，例如：“将此代码库导入 architector — 先制定第 0 阶段计划” 或 “逐个模块导入架构”。

此规则的设置为 alwaysApply: false — 当任务符合架构导入/引导场景时，Cursor 会附加该规则。规则要求：结构 → 每步一个模块 → 每步之后执行 validate → 仅使用精简工具。

如果你正在开发此服务的代码库，请在此处保留同一文件，以便贡献者和 Cloud Agents 在更新 ~/.mcp-architector/_qs_mcp-architector/ 时遵循相同的工作流。

概览

存储和管理项目架构、模块、脚本、数据流及用法示例 — 所有数据都在本地保存，完全保护隐私。

功能

• 本地存储：所有数据都存储在 ~/.mcp-architector 中（隐私优先）
• 项目架构：存储和获取整体项目架构
• 模块详情：每个模块的详细信息
• 资源：通过资源访问架构数据

存储结构

~/.mcp-architector/
└── {projectId}/
    ├── architecture.json      # Modules + dataFlow (vertical structure)
    ├── modules/
    │   ├── {moduleId}.json
    │   └── ...
    ├── entries/
    │   ├── index.json         # Catalog (no duplicate bodies)
    │   └── {entryId}.json     # Canonical facts (API, domain, flows, …)
    ├── slices/
    │   └── {sliceId}.json     # Custom filters only (no items)

数据模型

层	用途	工具
模块	垂直结构：组件、依赖项、数据流	set-project-architecture、set-module-details、set-module-data-flow、rebuild-data-flow、validate-architecture
条目	横向事实的唯一事实来源（一个事实 = 一个文件）	set-entry、set-entries、get-entry、list-entries
切片	基于条目的只读视图（内置或自定义筛选器）	list-slices、get-slice

反模式（不重复）： 不要将 module.description 复制到 entry.summary。请使用 refs.moduleName 建立关联。切片不会存储条目副本 — 只在 slices/*.json 中保存筛选器。

请勿直接编辑 ~/.mcp-architector — 始终使用 MCP 工具，以确保时间戳、合并语义以及 dataFlow 反向同步保持一致。

Agent 工作流

1. list-projects — 查找此工作区的 projectId（按文件夹名称查询）。将其传给其他所有工具。绝不省略。绝不使用 default-project。
2. 结构任务 → get-project-architecture / set-project-architecture。
3. 每个模块 → 在同一次调用中使用 set-module-details，并提供 files + facts[]（端点、实体、术语表）；或者使用 set-entries / set-entry，并提供 refs.moduleName。
4. 单个模块的图边 → set-module-data-flow。
5. 批量重建数据流（多个模块） → rebuild-data-flow。
6. 编辑后，验证所有内容 → validate（摘要 + issues[]；不加载完整项目）。
7. 需要某一类别（所有 API、所有领域术语）→ list-slices → 使用 format=compact 或 table 调用 get-slice；当 hasMore 为 true 时使用 offset。
8. 按名称查找 → search-entries → 使用 get-entry 获取完整数据。
9. 代码重构后（模块不变） → refactor-architecture：scan → dryRun 预览 → 使用 confirm=true 应用。

场景	工具
更新一个模块及其 API/事实	使用 facts[] 调用 set-module-details
批量添加某个领域的事实	使用 moduleName 调用 set-entries
修补一个模块的 dataFlow	set-module-data-flow
重建所有模块的边	rebuild-data-flow
诊断图和空切片	validate（或 validate-architecture）
目录 JSON 损坏（JSON 后有额外数据）	fix-data
重构后同步路径/名称	refactor-architecture（先 dryRun，再确认）
索引不同步	rebuild-entry-index
从头创建项目	使用 replaceModules: true 调用 set-project-architecture
为新克隆的 git 仓库分阶段完成引导	复制 .cursor/rules/architector-onboarding.mdc → 让 Agent 分阶段完成引导

完整项目概况： 仅有模块不会填充切片——如果没有 http-endpoint（及其他类型）的条目，api 切片就会保持为空。新增模块时 → 同一步骤中添加 facts 或条目。

示例：使用 facts: [{ kind: "http-endpoint", title: "POST /orders", ... }] 调用 set-module-details，然后调用 get-slice，设置 sliceId=api 和 format=table。

快速开始

用户使用（使用 npm 包）

# No installation needed - use directly in Cursor/Claude Desktop
# Just configure it as described in Integration section below

开发者使用

1. 克隆仓库：

git clone https://github.com/theSharque/mcp-architect.git
cd mcp-architect

2. 安装依赖：

npm install

3. 构建项目：

npm run build

使用方法

开发模式

启用热重载运行：

npm run dev

生产模式

启动服务：

npm start

MCP Inspector

使用 MCP Inspector 调试和测试你的服务：

npm run inspector

集成

Cursor IDE

1. 打开 Cursor 设置 → 功能 → Model Context Protocol
2. 点击“Edit Config”按钮
3. 添加以下配置之一

选项 1：通过 npm（推荐）

自动从 npm 注册表安装：

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

选项 2：通过 npm link（开发）

用于支持实时变更的本地开发：

{
  "mcpServers": {
    "architector": {
      "command": "mcp-architector",
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

需要执行：cd /path/to/mcp-architector && npm link -g

选项 3：直接路径

{
  "mcpServers": {
    "architector": {
      "command": "node",
      "args": ["/path/to/mcp-architector/dist/index.js"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Continue.dev

编辑 .continue/config.json：

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

使用 Project ID

除 list-projects 外，每个工具都必须提供 projectId。没有默认的转储项目。

1. 先调用 list-projects（可选传入 query = 工作区文件夹名称）
2. 将匹配的 projectId 传给其他所有工具
3. 如果没有匹配项，请使用基于工作区路径的稳定 ID（例如 _qs_my-app）调用 set-project-architecture 创建一个项目

MCP_PROJECT_ID 只是提示（isCurrent / suggestedProjectId）。它不会用作静默写入目标。禁止使用 default-project 和未经替换的 ${workspaceFolder} ID。

工具

set-project-architecture

创建或更新项目的整体架构。默认按名称合并模块和 dataFlow；省略 dataFlow 可保留现有流程。dependsOn 是规范字段；保存时会重新计算 providesTo。

输入：

• projectId（必填）：来自 list-projects 的项目 ID。切勿省略。禁止使用 default-project。
• description：项目整体描述
• modules：模块对象数组，包含：
  • name：模块名称
  • description：模块简要描述
  • inputs（可选）：此模块运行所需的内容
  • outputs（可选）：此模块生成或产出的内容
• dataFlow（可选）：描述模块间数据流的对象（省略则保留现有内容）：
  • 键：模块名称
  • 值：包含以下内容的对象：
    • dependsOn（可选）：此模块所依赖的模块名称数组
    • providesTo（可选）：保存时根据所有 dependsOn 关系推导
    • dataTransformation（可选）：模块间数据的转换方式
• replaceModules（可选）：替换整个模块列表（默认 false = 按名称合并）
• replaceDataFlow（可选）：替换整个 dataFlow（默认 false = 按模块名称合并）

输出：

• 项目 ID 和成功消息

get-project-architecture

获取项目的整体架构。

输入：

• projectId（必填）：来自 list-projects 的项目 ID。切勿省略。禁止使用 default-project。

输出：

• 完整的项目架构

list-projects

列出本地存储（~/.mcp-architector）中的所有项目。**请先调用此工具。**按文件夹名称匹配当前工作区，然后将 projectId 传递给其他所有工具。

输入：

• query（可选）：按 projectId 或描述中的子字符串筛选（不区分大小写）

输出：

• projects[]：projectId、description、moduleCount、updatedAt、isCurrent（来自 MCP_PROJECT_ID 的提示）、forbidden（default-project 和未替换的 workspaceFolder 转储）
• suggestedProjectId：当前的 MCP_PROJECT_ID（如果是有效 ID），否则为 null
• reminder：始终传递 projectId；切勿使用 default-project

Entries 和 slices

工具	用途
set-entry	新增或更新一条事实；若缺少模块或未关联模块，响应可能包含 reminder
set-entries	批量新增或更新（最多 200 条）；可选的 moduleName 会为所有条目设置 refs.moduleName
get-entry	按 id 获取完整条目
delete-entry	删除条目
list-entries	不含负载的目录；按 kind、tags、query 筛选
search-entries	精简文本搜索，包含 snippet、slices、moduleName、分页；筛选条件：moduleName、kind、tags
list-slices	内置和自定义 slices，包含条目计数
get-slice	筛选后的视图：sliceId、format、query、limit、offset、hasMore
set-slice	保存自定义筛选条件（kinds、tags）— 不包含条目
delete-slice	删除自定义 slice
rebuild-entry-index	根据条目文件重建 entries/index.json
fix-data	修复遗留或损坏的目录 JSON；重建索引

内置 sliceId 值： api、persistence、events、domain、flows、integrations、config、runtime、decisions、scripts。

search-entries

精简导航搜索——返回足够的上下文以便选择命中项，然后调用 get-entry 获取完整负载。

输入： query（必填）、moduleName、kind、tags、limit（默认 10，最大 50）、offset（默认 0）

输出： summary、total、returned、offset、hasMore、results[]，包含 snippet、matchedIn、slices、moduleName，以及旧版字段 summary、tags、refs

推荐的 kind 示例（允许使用任何字符串）：

sliceId	kinds
api	http-endpoint、grpc-method、mcp-tool、cli-command、…
persistence	db-table、entity、repository
domain	glossary、invariant、lifecycle
scripts	script — 使用 set-entry / get-slice sliceId=scripts

set-module-details

创建或更新模块的详细信息。切片读取条目，而非模块文本——传入 facts[]，即可在一次调用中创建关联条目。

输入：

• projectId（必需）：来自 list-projects 的项目 ID
• name：模块名称
• description：模块的详细描述
• inputs：模块接受的输入
• outputs：模块生成的输出
• dependencies（可选）：模块依赖项列表（提供时会同步到 dataFlow.dependsOn）
• files（可选）：属于此模块的文件列表
• facts（可选）：横向事实数组（kind、title、summary、…）——每项都会作为条目插入或更新，并设置 refs.moduleName = 模块名称
• usageExamples（可选）：用法示例数组，字段如下：
  • title：示例标题
  • description（可选）：示例描述
  • command（可选）：命令或代码片段
  • input（可选）：输入数据
  • output（可选）：预期输出
  • notes（可选）：关于此示例的补充说明
• notes（可选）：补充说明

输出：

• 模块 ID 和成功消息

set-module-data-flow

为单个模块更新 dataFlow，无需发送完整架构。

输入：

• projectId（必需）：来自 list-projects 的项目 ID
• moduleName：模块名称
• dependsOn（可选）：此模块依赖的模块（规范值）
• dataTransformation（可选）：数据的转换方式
• syncInverse（可选）：重新计算 providesTo（默认值为 true）

输出：

• 模块名称和成功消息

rebuild-data-flow

根据模块文件中的 dependencies 或现有的 dependsOn 边，为所有模块重建 dataFlow。替代对 architecture.json 的批量手动编辑。

输入：

• projectId（必需）：来自 list-projects 的项目 ID
• source（可选）：module-dependencies（默认值）或 dataFlow-dependsOn
• syncInverse（可选）：重新计算 providesTo（默认值为 true）
• pruneOrphans（可选）：移除无效的模块引用（默认值为 true）

输出：

• edgesAdded、edgesRemoved、modulesUpdated、消息

validate

主要的编辑后检查。 只读验证，并生成简洁、便于 Agent 使用的报告。不会修改数据。

检查项（仅限可从已存储的 JSON 中验证的规则）：

• dataFlow：反向关系偏差、悬空的 dependsOn / providesTo、孤立的流程键
• module.dependencies 与 dataFlow.dependsOn 的一致性
• 条目：entries-without-modules、entry-unlinked、orphan-entry-module、module-no-entries、module-missing-api / module-missing-persistence、entry-slice-orphan、module-too-many-entries、module-too-few-entries
• 存储：缺失的 modules/{id}.json、孤立的模块文件、条目索引偏差
• 切片：存在模块时，内置的 api / domain / persistence 为空

输入： projectId、checkInverse、checkModuleDeps、checkEntryCoverage、checkStorage、checkEmptySlices、checkSliceCoverage、checkModuleEntryCounts、moduleEntryMax（默认值为 50）、moduleEntryMin（可选；省略则禁用最小值检查）——除特别注明外，所有布尔标志的默认值均为 true

输出： valid、issueCount、summary、stats、issuesByKind、issues[]、coverage、checksRun

fix-data

当目录 JSON 已损坏时运行（例如，list-modules / validate 因 JSON 后存在额外数据而失败）。截去 architecture.json、modules/、entries/ 和 slices/ 中第一个有效 JSON 对象之后的残留字节；移除残留的 .tmp 文件；重建条目索引。不会删除事实。目录写入采用临时文件加重命名的方式，因此不会再次出现此类残留。

输入： projectId、dryRun（可选，默认值为 false）

输出： summary、scanned、repaired、unreadable、tmpRemoved、indexItemCount、files[]（仅包含已修复或不可读取的文件）

refactor-architecture

在代码重构后预览或应用架构内同步，适用于模块边界保持不变的情况。Agent 是事实来源——不访问工作区或 Git。dryRun=true 为默认值。

工作流：（1）使用 file 或 text 执行 scan → 获取精简命中结果；（2）构建变更操作；（3）通过 dryRun 预览；（4）设置 dryRun=false 并使用 confirm=true 应用。

操作（每次调用最多 10 个）： scan、move-file、replace-path-prefix、rename-text、patch-entry、merge-files、remove-file-ref。

范围（可选）： moduleName、kinds、tags — 限定受影响的条目/模块。

文件操作后，会删除 refs.files 为空且没有 refs.entryIds 的孤立条目。

输入： projectId、operations[]、scope、dryRun（默认值为 true）、confirm（应用时必需）、limit、offset

输出： summary、stats、hits（scan）或分页后的 changes、warnings、hasMore

validate-architecture

与 validate 相同（旧版别名）。编辑后优先使用 validate。

输出：

• valid（布尔值）、issues 数组

get-module-details

获取特定模块的详细信息。

输入：

• projectId（必需）：来自 list-projects 的项目 ID
• moduleName：要获取的模块名称

输出：

• 完整的模块详情

list-modules

列出项目架构中的所有模块。

输入：

• projectId（必需）：来自 list-projects 的项目 ID

输出：

• 模块摘要数组

delete-module

从项目架构中删除模块。

输入：

• projectId（必需）：来自 list-projects 的项目 ID
• moduleName：要删除的模块名称

输出：

• 成功消息

资源

architecture

提供对项目架构资源的访问。

用法： 通过 URI 访问：arch://{projectId}

module

提供对模块详情资源的访问。

用法： 通过 URI 访问：module://{projectId}/{moduleId}

开发

项目结构

mcp-architector/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── types.ts          # Type definitions
│   └── storage.ts        # Storage utilities
├── dist/                 # Compiled output (generated)
├── package.json
├── tsconfig.json
└── README.md

项目 ID

服务会将每个项目存储在 ~/.mcp-architector/{projectId}/ 中。除 list-projects 外，每次调用工具时都必须显式传入 projectId。

• 调用 list-projects（将 query 设置为工作区文件夹名称）以查找 ID
• MCP_PROJECT_ID 仅为列表查询提示（isCurrent / suggestedProjectId），不会作为隐式写入目标
• 禁止使用 default-project 和未替换的 ${workspaceFolder} ID

要启动新项目，请将根据工作区路径生成的稳定 ID（例如 _qs_my-app）传给 set-project-architecture。

扩展服务

要添加新工具、资源或提示词，请编辑 src/index.ts：

// Add a tool
server.registerTool(
  "tool-name",
  { /* tool config */ },
  async (params) => { /* handler */ }
);

// Add a resource
server.registerResource(
  "resource-name",
  new ResourceTemplate("uri-template", { /* options */ }),
  { /* resource config */ },
  async (uri, params) => { /* handler */ }
);

// Add a prompt
server.registerPrompt(
  "prompt-name",
  { /* prompt config */ },
  (args) => { /* handler */ }
);

许可证

MIT