首席建筑师服务

一个全面的模型上下文协议（MCP）服务器，用于通过人工智能开发工具管理产品计划、技术要求、架构决策和相关文档。

🎯 概述

这个统一的MCP服务器提供 8个领域的42多种工具 帮助软件架构师和产品团队：

架构决策记录（ADR） -使用选项、结果和Confluence同步记录和跟踪架构决策
技术要求 -使用Confluence发布创建和管理功能需求
产品要求 -定义产品规格和要求
业务规则文档 -记录业务规则和逻辑
技术估算 -跟踪工作量估算和容量规划
倡议资源 -管理产品计划和功能
倡议发布 -计划和跟踪发布时间表
技术选择 -记录技术选择和标准

🚀 快速开始

先决条件

Node.js 18+ （必填）
NX Monorepo 工具已安装
API服务器正在运行 在 http://localhost:3000/api

构建MCP服务器

# Clone and enter the repository
cd principal-architect-service

# Install dependencies
npm install

# Build the MCP server
npx nx build product-initiatives-mcp

启动API服务器

MCP服务器要求API后端运行：

# Start the API server (default: http://localhost:3000)
npx nx serve product-initiatives-api

______________________________________________________________________

📱 工具安装

🖥️ 克劳德桌面

Claude Desktop将MCP服务器作为子进程运行，并通过stdio进行通信。

配置步骤

找到您的Claude Desktop配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

添加MCP服务器配置：

{
  "mcpServers": {
    "principal-architect": {
      "command": "node",
      "args": [
        "/absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js"
      ],
      "env": {
        "API_URL": "http://localhost:3000/api",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重要提示： 替换 /absolute/path/to/ 根据您的实际项目路径。

替代方案：使用npx（如果在项目目录中）

{
  "mcpServers": {
    "principal-architect": {
      "command": "npx",
      "args": ["nx", "serve", "product-initiatives-mcp"],
      "cwd": "/absolute/path/to/principal-architect-service",
      "env": {
        "API_URL": "http://localhost:3000/api",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重新启动克劳德桌面 完全（退出并重新启动）

验证安装：

- 打开克劳德桌面 - 寻找🔌 聊天界面中的图标 - 你应该看到“首席架构师”列出了大约42个工具 - 试着问： _“列出所有架构决策记录”_

克劳德桌面故障排除

服务器无法启动：

# Check the build output exists
ls -la dist/product-initiatives-mcp/main.js

# Test the server manually
node dist/product-initiatives-mcp/main.js

工具未出现：

打开克劳德桌面开发工具（帮助→ 开发人员工具）
检查控制台选项卡中的MCP错误
验证API服务器是否正在运行： curl http://localhost:3000/api/health

______________________________________________________________________

💻 克劳德代码（CLI）

Claude Code可以通过stdio传输使用MCP服务器。配置存储在 ~/.claude/config.yaml.

配置步骤

创建或编辑您的Claude代码配置：

# Create config directory if needed
mkdir -p ~/.claude

# Edit the config file
nano ~/.claude/config.yaml

添加MCP服务器配置：

mcpServers:
  principal-architect:
    command: node
    args:
      - /absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js
    env:
      API_URL: http://localhost:3000/api
      LOG_LEVEL: info

重要提示： 替换 /absolute/path/to/ 根据您的实际项目路径。

mcpServers:
  principal-architect:
    command: npx
    args:
      - nx
      - serve
      - product-initiatives-mcp
    cwd: /absolute/path/to/principal-architect-service
    env:
      API_URL: http://localhost:3000/api
      LOG_LEVEL: info

重新启动Claude代码：

# If running in a session, exit and restart
# Or start a new session
claude-code

验证安装：

# In Claude Code, ask:
"What MCP servers are available?"

# Test a tool:
"List all ADRs"

在Claude代码会话中使用

配置后，您可以使用自然语言与工具进行交互：

You: "Create a new ADR for choosing between REST and GraphQL APIs"
Claude: [Uses create_architecture_decision_records tool]

You: "Show me all ADRs related to authentication"
Claude: [Uses search_architecture_decision_records tool]

You: "Update ADR-001 to mark the REST option as selected"
Claude: [Uses update_architecture_decision_records tool]

克劳德代码故障排除

检查MCP服务器状态：

# View available MCP servers
cat ~/.claude/config.yaml

# Test server manually
node dist/product-initiatives-mcp/main.js

调试模式： 集 LOG_LEVEL: debug 在您的配置中查看详细日志。

______________________________________________________________________

🌊 帆板运动

Windsurf支持类似于Claude Desktop的MCP服务器，配置存储在应用程序设置中。

配置步骤

找到Windsurf MCP配置：

- macOS: ~/Library/Application Support/Windsurf/User/globalStorage/windsurf.json - 视窗: %APPDATA%\Windsurf\User\globalStorage\windsurf.json - Linux: ~/.config/Windsurf/User/globalStorage/windsurf.json

_注意：确切路径可能因Windsurf版本而异。检查设置→ 配置位置的MCP服务器。_

添加MCP服务器配置：

{
  "mcpServers": {
    "principal-architect": {
      "command": "node",
      "args": [
        "/absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js"
      ],
      "env": {
        "API_URL": "http://localhost:3000/api",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重要提示： 替换 /absolute/path/to/ 根据您的实际项目路径。

替代方案：通过Windsurf用户界面

一些Windsurf版本支持基于UI的MCP配置：

- 打开设置→ 扩展→ MCP服务器 - 点击“添加MCP服务器” - 填写： - 名字: principal-architect - 命令: node - 参数: /absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js - 环境变量: - API_URL=http://localhost:3000/api - LOG_LEVEL=info

重新加载Windsurf：

- 完全重新启动Windsurf - 或者使用命令面板：“重新加载窗口”

验证安装：

- 打开AI聊天面板 - 查找MCP服务器指示器 - 尝试： _“主架构师服务器提供了哪些工具？”_

在Windsurf中使用

Windsurf将MCP工具集成到AI编码助手中：

You: "Create an ADR for our database selection"
Windsurf: [Uses create_architecture_decision_records]

You: "Show me the ADR we created yesterday"
Windsurf: [Uses list_architecture_decision_records with filters]

Windsurf故障排除

服务器未加载：

检查Windsurf的输出面板→ MCP服务器
验证main.js的路径是否正确且绝对
确保API服务器正在运行

权限问题：

# Make sure the main.js file is executable
chmod +x dist/product-initiatives-mcp/main.js

______________________________________________________________________

🛠️ 可用工具

架构决策记录（ADR）

记录架构决策的8个工具：

工具	说明
`create_architecture_decision_records`	使用标题、问题陈述和选项创建新的ADR
`list_architecture_decision_records`	列出所有ADR（支持分页和过滤）
`get_architecture_decision_records`	按ID获取详细的ADR，包括所有选项和结果
`update_architecture_decision_records`	更新ADR元数据、问题陈述或决策结果
`update_architecture_decision_record_option`	更新特定选项详细信息、图表或代码示例
`search_architecture_decision_records`	按具有相关性评分的关键字搜索ADR
`delete_architecture_decision_records`	删除ADR（软删除保留历史记录）
`publish_architecture_decision_record`	使用ADF格式将ADR发布到Confluence

技术要求

5个功能要求工具：

工具	说明
`create_technical_requirements`	创建技术要求文档
`list_technical_requirements`	列出所有技术要求
`get_technical_requirements`	按ID获取技术要求
`update_technical_requirements`	更新技术要求
`publish_technical_requirements_to_confluence`	发布到Confluence

产品要求

产品规格的5个工具：

工具	说明
`create_product_requirements`	创建产品需求文档
`list_product_requirements`	列出所有产品要求
`get_product_requirements`	按ID获取产品要求
`update_product_requirements`	更新产品要求
`publish_product_requirements`	发布到Confluence

业务规则文档

4种业务逻辑工具：

工具	说明
`create_business_rule_document`	创建业务规则文档
`list_business_rule_documents`	列出所有业务规则文档
`get_business_rule_document`	按ID获取业务规则
`update_business_rule_document`	更新业务规则

技术估算

4种工作量估算工具：

工具	说明
`create_technical_estimates`	创建技术估算文档
`list_technical_estimates`	列出所有技术估算
`get_technical_estimates`	按ID获取技术估算
`update_technical_estimates`	更新技术估算

倡议资源

管理计划的4个工具：

工具	说明
`create_product_initiative`	创建产品计划
`list_product_initiatives`	列出所有举措
`get_product_initiative`	通过ID获得主动权
`update_product_initiative`	更新倡议

倡议发布

发布计划的5个工具：

工具	说明
`create_initiative_releases`	创建倡议发布
`list_initiative_releases`	列出所有版本
`get_initiative_releases`	通过ID获得释放
`update_initiative_releases`	更新版本
`publish_initiative_releases`	发布到Confluence

技术选择

8种技术决策工具：

工具	说明
`create_technology_selection`	记录技术选择
`list_technology_selections`	列出所有技术选择
`get_technology_selection`	按ID获取技术选择
`update_technology_selection`	更新技术选择
`delete_technology_selection`	删除技术选择
`search_technology_selections`	搜索技术选择
`filter_technology_selections_by_category`	按类别筛选
`deprecate_technology_selection`	将技术标记为已弃用

______________________________________________________________________

💡 使用示例

示例1：创建ADR（任何工具）

You: Create an ADR for choosing between MongoDB and PostgreSQL for our user database

AI: I'll create an Architecture Decision Record for the database selection...
[Uses create_architecture_decision_records tool]

Result: Created ADR-001 with:
- Title: "Database Selection for User Management"
- Problem: Need to choose a database for user data storage
- Options: MongoDB (document), PostgreSQL (relational)
- Status: Proposed

示例2：搜索ADR（克劳德桌面）

You: Find all ADRs related to authentication

Claude: [Uses search_architecture_decision_records tool with keyword="authentication"]

Found 3 ADRs:
1. ADR-005: OAuth vs JWT Authentication
2. ADR-012: Multi-Factor Authentication Implementation
3. ADR-018: Session Management Strategy

示例3：发布到Confluence（克劳德代码）

claude-code

You: Publish ADR-001 to Confluence

Claude: I'll publish the ADR to Confluence with proper formatting...
[Uses publish_architecture_decision_record tool]

✅ Published to Confluence:
- Page ID: 123456
- URL: https://your-domain.atlassian.net/wiki/spaces/ARCH/pages/123456
- Status: Published
- Stakeholders notified via @mentions

示例4：更新选项（Windsurf）

You: Update the MongoDB option in ADR-001 to include performance benchmarks

Windsurf: [Uses update_architecture_decision_record_option tool]

Updated option "MongoDB" with:
- Performance data: 10K writes/sec
- Latency: ~5ms p95
- Scalability: Horizontal sharding

示例5：创建技术要求（Claude Desktop）

You: Create technical requirements for a user authentication feature

Claude: [Uses create_technical_requirements tool]

Created: TECH-REQ-001
- Feature: User Authentication
- Functional Requirements: Login, logout, password reset
- Non-functional: <2s response time, 99.9% uptime
- Dependencies: OAuth library, email service

______________________________________________________________________

🎨 高级功能

汇流集成

多种工具支持 发布到Confluence 与：

✅ 自动ADF（Atlassian文档格式）转换
✅ @向利益相关者提及决议
✅ 链接图和代码示例
✅ 状态徽章和元数据

汇流同步要求：

API服务器配置中的API凭据冲突
使用空格键配置的工作区
用户创建/编辑页面的权限

搜索和发现

关键字搜索 相关性评分：

在所有ADR字段中进行全文搜索
结果中突出显示的片段
排名的相关性得分

技术标准化

追踪你的 经批准的技术栈:

按层分类（前端、后端、数据库等）
将技术标记为已批准/已弃用
记录基本原理和替代方案
按类别搜索和筛选

______________________________________________________________________

⚙️ 配置

环境变量

变量	默认值	描述
`API_URL`	`http://localhost:3000/api`	后端API基本URL
`LOG_LEVEL`	`info`	日志记录级别： `error`, `warn`, `info`, `debug`

自定义API URL

如果API运行在不同的端口或主机上：

{
  "mcpServers": {
    "principal-architect": {
      "env": {
        "API_URL": "http://localhost:8080/api"
      }
    }
  }
}

调试模式

启用详细日志以进行故障排除：

{
  "mcpServers": {
    "principal-architect": {
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

______________________________________________________________________

🔧 发展

项目结构

principal-architect-service/
├── apps/
│   └── product-initiatives-api/      # NestJS API backend
├── product-initiatives-mcp/           # MCP server
│   ├── src/
│   │   ├── main.ts                   # Server entry point
│   │   ├── tools/                    # Domain-specific tools
│   │   │   ├── adrs.tools.ts
│   │   │   ├── technical-requirements.tools.ts
│   │   │   ├── product-requirements.tools.ts
│   │   │   └── ...
│   │   └── utils/                    # Shared utilities
│   │       ├── logger.ts
│   │       ├── api-client.ts
│   │       └── error-handler.ts
│   └── README.md
├── libs/                             # Shared libraries
│   ├── resource-schemas/             # JSON schemas
│   ├── mcp-tool-generator/           # Tool generation
│   └── confluence-client/            # Confluence integration
└── dist/                             # Build output

运行测试

# Run all tests
npm test

# Run specific domain tests
npx nx test product-initiatives-api

# Run with coverage
npm run test:coverage

# Run e2e tests
npm run test:e2e

生产大楼

# Build MCP server
npx nx build product-initiatives-mcp

# Build API server
npx nx build product-initiatives-api

# Build all
npm run build

本地开发

# Start API server (watch mode)
npx nx serve product-initiatives-api

# In another terminal, test MCP server
node dist/product-initiatives-mcp/main.js

# Or use the development build
npx nx serve product-initiatives-mcp

______________________________________________________________________

🐛 故障排除

常见问题

1.“连接被拒绝”错误

问题： MCP服务器无法访问API后端

解决方案：

# Check if API is running
curl http://localhost:3000/api/health

# Start the API if needed
npx nx serve product-initiatives-api

2.“未知工具”错误

问题： 未找到或未加载工具

解决方案：

# Rebuild the MCP server
npx nx build product-initiatives-mcp

# Restart Claude Desktop/Code/Windsurf

3.架构验证错误

问题： 输入格式无效

解决方案：

在工具列表中检查工具的输入模式
确保提供必填字段
验证数据类型是否匹配（字符串、数字、布尔值）

4.Windows上的路径问题

问题： 无法识别Windows路径格式

解决方案： 使用正斜杠或转义反斜杠：

{
  "command": "node",
  "args": [
    "C:/Users/YourName/principal-architect-service/dist/product-initiatives-mcp/main.js"
  ]
}

5.港口冲突

问题： API服务器端口3000已在使用

解决方案：

# Use different port
PORT=3001 npx nx serve product-initiatives-api

# Update MCP config
"API_URL": "http://localhost:3001/api"

调试检查表

\[\]API服务器正在运行(curl http://localhost:3000/api/health)
\[\]已构建MCP服务器(ls dist/product-initiatives-mcp/main.js)
\[\]配置文件具有正确的绝对路径
\[\]环境变量设置正确
\[\]克劳德桌面/代码/Windsurf已重新启动
\[\]无端口冲突（检查 lsof -i :3000)
\[\]日志显示工具初始化成功

查看日志

克劳德桌面：

Help → 开发者工具→ 控制台

克劳德代码：

# Set debug level in config
LOG_LEVEL: debug

# Logs output to stderr

风浪：

View → 输出→ MCP服务器

______________________________________________________________________

📚 相关文件

______________________________________________________________________

🤝 贡献

欢迎投稿！请遵循以下指南：

提交前进行质量检查：

   npm run lint
   npm test
   npm run typecheck

遵循现有模式：

- 将NX生成器用于新工具 - 遵循TypeScript严格模式 - 添加新功能的测试

提交消息格式：

   feat: add new ADR search capabilities
   fix: resolve Confluence publish error
   docs: update installation instructions

______________________________________________________________________

📄 许可证

MIT许可证

______________________________________________________________________

🆘 支持

问题？

检查故障排除章节
查看AI工具开发人员控制台中的日志
验证API服务器是否正在运行并可访问
确保安装了所有依赖项

问题？

查看使用示例
检查中的工具说明可用工具章节
请咨询 MCP规范

需要帮助？ 在GitHub上打开一个问题：

您的环境（克劳德桌面/代码/Windsurf版本）
配置文件内容（清除敏感数据）
相关日志或错误消息
重现问题的步骤

______________________________________________________________________

🎉 入门检查表

\[\]克隆存储库
\[\]运行 npm install
\[\]构建MCP服务器： npx nx build product-initiatives-mcp
\[\]启动API服务器： npx nx serve product-initiatives-api
\[\]配置你的人工智能工具（克劳德桌面/代码/Windsurf）
\[\]重新启动AI工具
\[\]测试：“列出所有架构决策记录”
\[\]成功！ 🎊

准备好记录您的架构决策了吗？从以下内容开始：

"Create an ADR for our first major technical decision"

Principal Architect Service

快速接入

详细介绍

首席建筑师服务

🎯 概述

🚀 快速开始

先决条件

构建MCP服务器

启动API服务器

📱 工具安装

🖥️ 克劳德桌面

配置步骤

克劳德桌面故障排除

💻 克劳德代码（CLI）

配置步骤

在Claude代码会话中使用

克劳德代码故障排除

🌊 帆板运动

配置步骤

在Windsurf中使用

Windsurf故障排除

🛠️ 可用工具

架构决策记录（ADR）

技术要求

产品要求

业务规则文档

技术估算

倡议资源

倡议发布

技术选择

💡 使用示例

示例1：创建ADR（任何工具）

示例2：搜索ADR（克劳德桌面）

示例3：发布到Confluence（克劳德代码）

示例4：更新选项（Windsurf）

示例5：创建技术要求（Claude Desktop）

🎨 高级功能

汇流集成

搜索和发现

技术标准化

⚙️ 配置

环境变量

自定义API URL

调试模式

🔧 发展

项目结构

运行测试

生产大楼

本地开发

🐛 故障排除

常见问题

1.“连接被拒绝”错误

2.“未知工具”错误

3.架构验证错误

4.Windows上的路径问题

5.港口冲突

调试检查表

查看日志

📚 相关文件

🤝 贡献

📄 许可证

🆘 支持

🎉 入门检查表

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP