1867 lines
50 KiB
Markdown
1867 lines
50 KiB
Markdown
# MCP Server 基础架构说明文档
|
||
|
||
**文档版本**: 1.0
|
||
**创建日期**: 2025-11-06
|
||
**目标阶段**: M2 (2025-12-01 至 2026-03-31)
|
||
**受众**: 产品经理、后端工程师、架构师
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [MCP Server 概述](#1-mcp-server-概述)
|
||
2. [整体架构设计](#2-整体架构设计)
|
||
3. [暴露的 Resources（资源）](#3-暴露的-resources资源)
|
||
4. [暴露的 Tools（工具）](#4-暴露的-tools工具)
|
||
5. [安全性设计](#5-安全性设计)
|
||
6. [技术实现方案](#6-技术实现方案)
|
||
7. [实现路线图](#7-实现路线图)
|
||
|
||
---
|
||
|
||
## 1. MCP Server 概述
|
||
|
||
### 1.1 MCP 协议简介
|
||
|
||
**MCP (Model Context Protocol)** 是由 Anthropic 提出的一种标准化协议，用于连接 AI 模型与外部数据源和工具。MCP 协议定义了三种核心能力：
|
||
|
||
- **Resources（资源）**: 只读数据暴露，让 AI 读取应用数据
|
||
- **Tools（工具）**: 可执行操作，让 AI 调用功能接口
|
||
- **Prompts（提示词）**: 预设的提示词模板，提升 AI 交互质量
|
||
|
||
**MCP 的核心价值**:
|
||
- 标准化：统一的协议规范，任何 AI 工具都能接入
|
||
- 安全性：细粒度的权限控制和审批机制
|
||
- 可扩展：模块化设计，易于添加新功能
|
||
- 开放生态：促进 AI 工具和应用之间的互操作性
|
||
|
||
### 1.2 ColaFlow MCP Server 的定位
|
||
|
||
ColaFlow MCP Server 是连接 AI 工具和 ColaFlow 项目管理系统的桥梁，它的核心定位是：
|
||
|
||
**让 AI 成为真正的团队成员**
|
||
|
||
- AI 能够读取项目数据（Projects, Epics, Stories, Tasks, Sprints）
|
||
- AI 能够执行项目操作（创建任务、更新状态、分配人员）
|
||
- AI 的所有写操作都需要人工审批（Diff Preview 机制）
|
||
- 所有 AI 操作都有完整的审计追踪
|
||
|
||
### 1.3 与 AI Agent 的交互方式
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ AI Agent Workflow │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
|
||
User Request → AI Agent (Claude/ChatGPT)
|
||
↓
|
||
1. Query Resources (只读操作)
|
||
colaflow://projects.list
|
||
colaflow://issues.search?status=InProgress
|
||
↓
|
||
2. Generate Response with Tool Calls
|
||
"I found 5 open tasks. Would you like me to
|
||
create a new Epic for the login feature?"
|
||
↓
|
||
3. User Confirms → AI Calls Tool
|
||
create_epic(title="User Login Feature")
|
||
↓
|
||
4. MCP Server Generates Diff Preview
|
||
{
|
||
"operation": "CREATE",
|
||
"entityType": "Epic",
|
||
"afterData": { "title": "User Login Feature", ... }
|
||
}
|
||
↓
|
||
5. Human Approval in ColaFlow Dashboard
|
||
✅ Approve → Execute operation
|
||
❌ Reject → Log rejection
|
||
↓
|
||
6. Return Result to AI
|
||
"Epic created successfully. ID: epic-123"
|
||
↓
|
||
AI → User: "Done! The Epic has been created."
|
||
```
|
||
|
||
**关键流程说明**:
|
||
1. **读操作（Resources）**: 直接返回数据，无需审批
|
||
2. **写操作（Tools）**: 先生成 Diff Preview，等待人工审批
|
||
3. **审批后执行**: 审批通过后自动执行实际操作
|
||
4. **实时通知**: 通过 SignalR WebSocket 实时通知用户
|
||
|
||
### 1.4 业务价值
|
||
|
||
**对产品经理**:
|
||
- 减少 50% 手动创建任务的时间
|
||
- AI 自动生成 PRD 和验收标准
|
||
- 自动化的进度报告和风险检测
|
||
|
||
**对开发团队**:
|
||
- 自然语言即可操作项目系统
|
||
- 减少在 Jira 系统中的手动操作
|
||
- AI 辅助任务估算和 Sprint 规划
|
||
|
||
**对企业客户**:
|
||
- 完整的审批和审计机制（合规要求）
|
||
- 支持私有化部署（数据安全）
|
||
- 开放的 MCP 协议（避免供应商锁定）
|
||
|
||
---
|
||
|
||
## 2. 整体架构设计
|
||
|
||
### 2.1 架构分层
|
||
|
||
ColaFlow MCP Server 采用 **Clean Architecture + CQRS + DDD** 设计模式，与现有后端系统无缝集成。
|
||
|
||
```
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ Presentation Layer │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ MCP Protocol Handler (JSON-RPC 2.0 over stdio/SSE) │ │
|
||
│ │ - McpResourceController │ │
|
||
│ │ - McpToolController │ │
|
||
│ │ - McpPromptController │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ REST API for MCP Management │ │
|
||
│ │ - /api/mcp/keys (API Key 管理) │ │
|
||
│ │ - /api/mcp/pending-changes (Diff Preview 审批) │ │
|
||
│ │ - /api/mcp/audit-logs (审计日志查询) │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ Application Layer │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ MCP Services │ │
|
||
│ │ - McpResourceService (读取项目数据) │ │
|
||
│ │ - McpToolService (执行工具操作) │ │
|
||
│ │ - McpPromptService (生成提示词) │ │
|
||
│ │ - DiffPreviewService (生成变更预览) │ │
|
||
│ │ - PendingChangeService (管理待审批变更) │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ CQRS Command/Query Handlers │ │
|
||
│ │ - CreateApiKeyCommandHandler │ │
|
||
│ │ - ApprovePendingChangeCommandHandler │ │
|
||
│ │ - GetPendingChangesQueryHandler │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ Domain Layer │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ MCP Aggregates │ │
|
||
│ │ - McpApiKey (API 密钥聚合根) │ │
|
||
│ │ - PendingChange (待审批变更聚合根) │ │
|
||
│ │ - DiffPreview (变更预览值对象) │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ Domain Events │ │
|
||
│ │ - ApiKeyCreatedEvent │ │
|
||
│ │ - PendingChangeCreatedEvent │ │
|
||
│ │ - PendingChangeApprovedEvent │ │
|
||
│ │ - PendingChangeRejectedEvent │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌───────────────────────────────────────────────────────────────┐
|
||
│ Infrastructure Layer │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ Data Access │ │
|
||
│ │ - McpApiKeyRepository (EF Core) │ │
|
||
│ │ - PendingChangeRepository (EF Core) │ │
|
||
│ │ - Redis Cache (热数据缓存) │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||
│ │ External Services │ │
|
||
│ │ - SignalR Hub (实时通知) │ │
|
||
│ │ - AuditLogService (审计日志) │ │
|
||
│ │ - ProjectService (现有项目模块) │ │
|
||
│ │ - IssueService (现有任务模块) │ │
|
||
│ └─────────────────────────────────────────────────────────┘ │
|
||
└───────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**架构分层职责**:
|
||
|
||
1. **Presentation Layer（展示层）**
|
||
- 处理 MCP 协议通信（JSON-RPC 2.0）
|
||
- 处理 REST API 请求
|
||
- 认证和授权验证
|
||
- 输入验证和错误处理
|
||
|
||
2. **Application Layer（应用层）**
|
||
- 业务流程编排
|
||
- CQRS 命令和查询处理
|
||
- 领域事件分发
|
||
- 跨聚合根协调
|
||
|
||
3. **Domain Layer（领域层）**
|
||
- 核心业务逻辑
|
||
- 聚合根和值对象
|
||
- 领域事件定义
|
||
- 业务规则验证
|
||
|
||
4. **Infrastructure Layer（基础设施层）**
|
||
- 数据持久化（PostgreSQL + EF Core）
|
||
- 缓存（Redis）
|
||
- 外部服务集成
|
||
- 技术实现细节
|
||
|
||
### 2.2 核心组件及职责
|
||
|
||
#### 2.2.1 MCP Protocol Handler
|
||
|
||
**职责**: 处理 MCP 协议的请求和响应
|
||
|
||
**核心功能**:
|
||
- 解析 MCP 协议消息（JSON-RPC 2.0 格式）
|
||
- 路由请求到对应的 Resource/Tool/Prompt 处理器
|
||
- 格式化响应数据符合 MCP 规范
|
||
- 错误处理和异常转换
|
||
|
||
**关键接口**:
|
||
```csharp
|
||
public interface IMcpProtocolHandler
|
||
{
|
||
Task<McpResponse> HandleRequestAsync(
|
||
McpRequest request,
|
||
CancellationToken cancellationToken);
|
||
}
|
||
```
|
||
|
||
#### 2.2.2 McpResourceService
|
||
|
||
**职责**: 暴露只读数据资源
|
||
|
||
**核心功能**:
|
||
- 注册和管理所有 MCP Resources
|
||
- 查询项目数据（Projects, Issues, Sprints, Users）
|
||
- 应用租户隔离和权限过滤
|
||
- 数据格式转换和优化
|
||
|
||
**Resource 注册机制**:
|
||
```csharp
|
||
public interface IMcpResource
|
||
{
|
||
string Uri { get; }
|
||
string Name { get; }
|
||
string Description { get; }
|
||
string MimeType { get; }
|
||
|
||
Task<McpResourceContent> GetContentAsync(
|
||
McpResourceRequest request,
|
||
CancellationToken cancellationToken);
|
||
}
|
||
```
|
||
|
||
#### 2.2.3 McpToolService
|
||
|
||
**职责**: 执行写操作工具
|
||
|
||
**核心功能**:
|
||
- 注册和管理所有 MCP Tools
|
||
- 执行工具操作（CREATE/UPDATE/DELETE）
|
||
- 生成 Diff Preview
|
||
- 与 PendingChangeService 协同处理审批流程
|
||
|
||
**Tool 执行流程**:
|
||
```csharp
|
||
public interface IMcpTool
|
||
{
|
||
string Name { get; }
|
||
string Description { get; }
|
||
McpToolInputSchema InputSchema { get; }
|
||
|
||
Task<McpToolResult> ExecuteAsync(
|
||
McpToolCall toolCall,
|
||
CancellationToken cancellationToken);
|
||
}
|
||
```
|
||
|
||
#### 2.2.4 DiffPreviewService
|
||
|
||
**职责**: 生成变更预览
|
||
|
||
**核心功能**:
|
||
- 生成 before/after 数据快照
|
||
- 计算数据差异（JSON diff）
|
||
- 格式化 diff 输出（人类可读）
|
||
- 验证变更的安全性
|
||
|
||
**Diff 数据结构**:
|
||
```csharp
|
||
public class DiffPreview
|
||
{
|
||
public string ToolName { get; set; }
|
||
public string Operation { get; set; } // CREATE, UPDATE, DELETE
|
||
public string EntityType { get; set; }
|
||
public Guid? EntityId { get; set; }
|
||
public object? BeforeData { get; set; }
|
||
public object? AfterData { get; set; }
|
||
public DiffField[] ChangedFields { get; set; }
|
||
public bool RequiresApproval { get; set; }
|
||
public DateTime CreatedAt { get; set; }
|
||
}
|
||
|
||
public class DiffField
|
||
{
|
||
public string FieldName { get; set; }
|
||
public object? OldValue { get; set; }
|
||
public object? NewValue { get; set; }
|
||
}
|
||
```
|
||
|
||
#### 2.2.5 PendingChangeService
|
||
|
||
**职责**: 管理待审批的变更
|
||
|
||
**核心功能**:
|
||
- 创建待审批变更记录
|
||
- 存储 Diff Preview 数据
|
||
- 处理审批/拒绝操作
|
||
- 24小时自动过期机制
|
||
- 发送实时通知
|
||
|
||
**状态流转**:
|
||
```
|
||
PendingApproval → Approved → Executed
|
||
↘ Rejected
|
||
↘ Expired (24h)
|
||
↘ Cancelled
|
||
```
|
||
|
||
#### 2.2.6 McpApiKeyService
|
||
|
||
**职责**: 管理 MCP API 密钥
|
||
|
||
**核心功能**:
|
||
- 生成 API Key（SHA-256 哈希存储）
|
||
- 验证 API Key
|
||
- 权限范围控制（只读/读写）
|
||
- IP 白名单验证
|
||
- 使用统计和速率限制
|
||
|
||
### 2.3 与现有后端 API 的集成方式
|
||
|
||
MCP Server 不是独立的服务，而是 ColaFlow 后端系统的一个模块。集成方式：
|
||
|
||
**方式 1: 直接调用现有服务**
|
||
```csharp
|
||
// MCP Tool 内部调用现有的 CQRS Command
|
||
public class CreateIssueTool : IMcpTool
|
||
{
|
||
private readonly IMediator _mediator;
|
||
|
||
public async Task<McpToolResult> ExecuteAsync(...)
|
||
{
|
||
// 调用现有的 CreateIssueCommand
|
||
var result = await _mediator.Send(new CreateIssueCommand
|
||
{
|
||
ProjectId = input.ProjectId,
|
||
Title = input.Title,
|
||
Type = input.Type
|
||
});
|
||
|
||
return new McpToolResult { ... };
|
||
}
|
||
}
|
||
```
|
||
|
||
**方式 2: 共享数据仓储**
|
||
```csharp
|
||
// MCP Resource 直接查询现有数据
|
||
public class ProjectsListResource : IMcpResource
|
||
{
|
||
private readonly IProjectRepository _projectRepo;
|
||
|
||
public async Task<McpResourceContent> GetContentAsync(...)
|
||
{
|
||
// 复用现有的 Repository
|
||
var projects = await _projectRepo.GetAllAsync(tenantId);
|
||
|
||
return new McpResourceContent { ... };
|
||
}
|
||
}
|
||
```
|
||
|
||
**方式 3: 领域事件订阅**
|
||
```csharp
|
||
// 监听现有的领域事件
|
||
public class IssueCreatedEventHandler : INotificationHandler<IssueCreatedEvent>
|
||
{
|
||
public async Task Handle(IssueCreatedEvent e, ...)
|
||
{
|
||
// 如果是 MCP 操作触发的，发送通知
|
||
if (e.TriggeredByMcp)
|
||
{
|
||
await _realtimeService.NotifyUserAsync(...);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 数据流向
|
||
|
||
#### 2.4.1 读操作数据流（Resource）
|
||
|
||
```
|
||
AI Agent → MCP Protocol Handler → McpResourceService
|
||
↓
|
||
[权限验证]
|
||
↓
|
||
ProjectRepository / IssueRepository
|
||
↓
|
||
[租户过滤]
|
||
↓
|
||
PostgreSQL Query
|
||
↓
|
||
[Redis Cache (可选)]
|
||
↓
|
||
格式化为 MCP Resource Content
|
||
↓
|
||
返回给 AI Agent
|
||
```
|
||
|
||
**性能优化**:
|
||
- Redis 缓存热数据（TTL 5分钟）
|
||
- 分页查询（默认 limit=50）
|
||
- 只返回必要字段（精简 JSON）
|
||
|
||
#### 2.4.2 写操作数据流（Tool）
|
||
|
||
```
|
||
AI Agent → MCP Protocol Handler → McpToolService
|
||
↓
|
||
[API Key 验证]
|
||
↓
|
||
DiffPreviewService 生成预览
|
||
↓
|
||
PendingChangeService 创建待审批记录
|
||
↓
|
||
存储到 PostgreSQL
|
||
↓
|
||
SignalR 通知用户（实时推送）
|
||
↓
|
||
返回 Diff Preview 给 AI Agent
|
||
|
||
↓
|
||
[用户在 Dashboard 审批]
|
||
↓
|
||
✅ Approve → 执行实际操作
|
||
❌ Reject → 记录日志
|
||
↓
|
||
通知 AI Agent 最终结果
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 暴露的 Resources（资源）
|
||
|
||
### 3.1 Resource 概述
|
||
|
||
Resources 是只读的数据接口，让 AI 能够查询 ColaFlow 的项目数据。所有 Resources 都遵循租户隔离原则。
|
||
|
||
### 3.2 Resource URI 设计规范
|
||
|
||
**URI 格式**: `colaflow://[entity].[action]?[params]`
|
||
|
||
**命名规则**:
|
||
- 使用小写字母和点号分隔
|
||
- 动作使用标准 CRUD 动词（list, get, search）
|
||
- 支持 query 参数传递过滤条件
|
||
|
||
**示例**:
|
||
```
|
||
colaflow://projects.list
|
||
colaflow://projects.get/abc123
|
||
colaflow://issues.search?status=InProgress&assignee=user123
|
||
colaflow://sprints.current
|
||
```
|
||
|
||
### 3.3 核心 Resources 列表
|
||
|
||
#### 3.3.1 Projects Resources
|
||
|
||
**1. colaflow://projects.list**
|
||
|
||
获取当前租户的所有项目列表
|
||
|
||
**返回数据结构**:
|
||
```json
|
||
{
|
||
"projects": [
|
||
{
|
||
"id": "uuid",
|
||
"name": "ColaFlow Development",
|
||
"key": "COLA",
|
||
"description": "Main development project",
|
||
"status": "Active",
|
||
"owner": {
|
||
"id": "uuid",
|
||
"name": "John Doe"
|
||
},
|
||
"issueCount": 145,
|
||
"memberCount": 8,
|
||
"createdAt": "2024-01-01T00:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**2. colaflow://projects.get/{id}**
|
||
|
||
获取单个项目的详细信息
|
||
|
||
**返回数据结构**:
|
||
```json
|
||
{
|
||
"project": {
|
||
"id": "uuid",
|
||
"name": "ColaFlow Development",
|
||
"key": "COLA",
|
||
"description": "...",
|
||
"status": "Active",
|
||
"owner": { "id": "uuid", "name": "John Doe" },
|
||
"statistics": {
|
||
"totalIssues": 145,
|
||
"openIssues": 32,
|
||
"inProgressIssues": 15,
|
||
"completedIssues": 98
|
||
},
|
||
"recentActivity": [
|
||
{
|
||
"type": "IssueCreated",
|
||
"user": "Jane Smith",
|
||
"timestamp": "2024-11-05T10:30:00Z",
|
||
"description": "Created task COLA-146"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3.3.2 Issues Resources
|
||
|
||
**3. colaflow://issues.search**
|
||
|
||
搜索任务（支持高级过滤）
|
||
|
||
**支持的查询参数**:
|
||
- `projectId`: 项目 ID
|
||
- `type`: Epic / Story / Task / Bug
|
||
- `status`: Backlog / Todo / InProgress / Review / Done
|
||
- `priority`: Low / Medium / High / Critical
|
||
- `assignee`: 用户 ID
|
||
- `sprint`: Sprint ID
|
||
- `q`: 关键词搜索（标题和描述）
|
||
- `limit`: 返回数量（默认 50）
|
||
- `offset`: 分页偏移量
|
||
|
||
**返回数据结构**:
|
||
```json
|
||
{
|
||
"issues": [
|
||
{
|
||
"id": "uuid",
|
||
"key": "COLA-146",
|
||
"title": "Implement MCP Server",
|
||
"type": "Epic",
|
||
"status": "InProgress",
|
||
"priority": "High",
|
||
"assignee": {
|
||
"id": "uuid",
|
||
"name": "John Doe"
|
||
},
|
||
"project": {
|
||
"id": "uuid",
|
||
"name": "ColaFlow Development"
|
||
},
|
||
"sprint": {
|
||
"id": "uuid",
|
||
"name": "Sprint 5"
|
||
},
|
||
"estimatedHours": 80,
|
||
"actualHours": 35,
|
||
"createdAt": "2024-11-01T00:00:00Z",
|
||
"updatedAt": "2024-11-05T14:30:00Z"
|
||
}
|
||
],
|
||
"total": 145,
|
||
"limit": 50,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
**4. colaflow://issues.get/{id}**
|
||
|
||
获取单个任务的详细信息（包括评论、附件、历史）
|
||
|
||
**返回数据结构**:
|
||
```json
|
||
{
|
||
"issue": {
|
||
"id": "uuid",
|
||
"key": "COLA-146",
|
||
"title": "Implement MCP Server",
|
||
"description": "Complete implementation of MCP protocol...",
|
||
"type": "Epic",
|
||
"status": "InProgress",
|
||
"priority": "High",
|
||
"assignee": { ... },
|
||
"reporter": { ... },
|
||
"project": { ... },
|
||
"sprint": { ... },
|
||
"parent": {
|
||
"id": "uuid",
|
||
"key": "COLA-100",
|
||
"title": "M2 Phase"
|
||
},
|
||
"children": [
|
||
{
|
||
"id": "uuid",
|
||
"key": "COLA-147",
|
||
"title": "Implement Resources"
|
||
}
|
||
],
|
||
"acceptanceCriteria": [
|
||
"All 11 resources implemented",
|
||
"Performance < 200ms"
|
||
],
|
||
"comments": [
|
||
{
|
||
"id": "uuid",
|
||
"author": "Jane Smith",
|
||
"text": "Started implementation today",
|
||
"createdAt": "2024-11-05T09:00:00Z"
|
||
}
|
||
],
|
||
"activityHistory": [ ... ]
|
||
}
|
||
}
|
||
```
|
||
|
||
**5. colaflow://epics.list**
|
||
|
||
列出所有 Epic
|
||
|
||
**6. colaflow://stories.list**
|
||
|
||
列出所有 Story
|
||
|
||
**7. colaflow://tasks.list**
|
||
|
||
列出所有 Task
|
||
|
||
**注**: 这三个 Resources 本质上是 `issues.search` 的快捷方式，预设了 type 过滤条件。
|
||
|
||
#### 3.3.3 Sprints Resources
|
||
|
||
**8. colaflow://sprints.current**
|
||
|
||
获取当前活跃的 Sprint
|
||
|
||
**返回数据结构**:
|
||
```json
|
||
{
|
||
"sprint": {
|
||
"id": "uuid",
|
||
"name": "Sprint 5",
|
||
"goal": "Complete MCP Server implementation",
|
||
"status": "Active",
|
||
"startDate": "2024-11-01T00:00:00Z",
|
||
"endDate": "2024-11-14T23:59:59Z",
|
||
"progress": {
|
||
"totalIssues": 12,
|
||
"completedIssues": 5,
|
||
"remainingIssues": 7,
|
||
"totalStoryPoints": 34,
|
||
"completedStoryPoints": 13
|
||
},
|
||
"burndown": [
|
||
{ "date": "2024-11-01", "remaining": 34 },
|
||
{ "date": "2024-11-02", "remaining": 32 },
|
||
{ "date": "2024-11-05", "remaining": 21 }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**9. colaflow://sprints.backlog**
|
||
|
||
获取 Backlog 中的任务
|
||
|
||
#### 3.3.4 Users Resources
|
||
|
||
**10. colaflow://users.list**
|
||
|
||
列出当前租户的所有团队成员
|
||
|
||
**返回数据结构**:
|
||
```json
|
||
{
|
||
"users": [
|
||
{
|
||
"id": "uuid",
|
||
"email": "john@example.com",
|
||
"fullName": "John Doe",
|
||
"role": "Admin",
|
||
"status": "Active",
|
||
"avatar": "https://...",
|
||
"statistics": {
|
||
"assignedIssues": 8,
|
||
"completedIssues": 42
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 3.3.5 Reports Resources
|
||
|
||
**11. colaflow://reports.burndown/{sprintId}**
|
||
|
||
获取指定 Sprint 的燃尽图数据
|
||
|
||
### 3.4 资源的组织结构
|
||
|
||
Resources 按照业务领域组织：
|
||
|
||
```
|
||
colaflow://
|
||
├── projects.* # 项目相关
|
||
│ ├── list
|
||
│ └── get/{id}
|
||
├── issues.* # 任务相关
|
||
│ ├── search
|
||
│ ├── get/{id}
|
||
│ ├── (epics.list)
|
||
│ ├── (stories.list)
|
||
│ └── (tasks.list)
|
||
├── sprints.* # Sprint 相关
|
||
│ ├── current
|
||
│ └── backlog
|
||
├── users.* # 用户相关
|
||
│ └── list
|
||
└── reports.* # 报告相关
|
||
└── burndown/{id}
|
||
```
|
||
|
||
### 3.5 权限控制机制
|
||
|
||
**租户隔离**:
|
||
- 所有 Resources 自动应用 TenantId 过滤
|
||
- 通过 EF Core Global Query Filter 实现
|
||
- 用户只能访问自己租户的数据
|
||
|
||
**角色权限**:
|
||
- Owner/Admin: 所有 Resources 可访问
|
||
- Member: 只能访问自己参与的项目
|
||
- Viewer: 只读访问，不能修改
|
||
- Guest: 受限的只读访问
|
||
|
||
**API Key 权限**:
|
||
- 创建 API Key 时指定 Resource 白名单
|
||
- 例如：只允许读取 `projects.*` 和 `issues.search`
|
||
- 超出权限范围返回 403 Forbidden
|
||
|
||
**敏感数据过滤**:
|
||
- 不返回密码哈希、API Key 等敏感字段
|
||
- 不返回其他租户的数据
|
||
- 审计日志中的敏感操作需要额外权限
|
||
|
||
---
|
||
|
||
## 4. 暴露的 Tools（工具）
|
||
|
||
### 4.1 Tool 概述
|
||
|
||
Tools 是可执行的操作接口，让 AI 能够修改 ColaFlow 的数据。所有写操作都需要通过 Diff Preview 和人工审批。
|
||
|
||
### 4.2 Tool 分类
|
||
|
||
#### 4.2.1 读取类工具
|
||
|
||
虽然 Resources 已经提供了读取能力，但某些复杂查询需要专用工具：
|
||
|
||
**1. search_issues (高级搜索)**
|
||
|
||
支持复杂的 JQL（Jira Query Language）风格查询
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"query": "project = COLA AND status = InProgress AND assignee = currentUser()",
|
||
"orderBy": "priority DESC, createdAt ASC",
|
||
"limit": 50
|
||
}
|
||
```
|
||
|
||
#### 4.2.2 写入类工具（需审批）
|
||
|
||
**2. create_project**
|
||
|
||
创建新项目
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"name": "New Product Feature",
|
||
"key": "NPF",
|
||
"description": "A new product feature for Q1 2025",
|
||
"ownerId": "uuid"
|
||
}
|
||
```
|
||
|
||
**Diff Preview 示例**:
|
||
```json
|
||
{
|
||
"operation": "CREATE",
|
||
"entityType": "Project",
|
||
"afterData": {
|
||
"name": "New Product Feature",
|
||
"key": "NPF",
|
||
"status": "Active",
|
||
"owner": "John Doe",
|
||
"createdAt": "2024-11-06T10:00:00Z"
|
||
},
|
||
"requiresApproval": true
|
||
}
|
||
```
|
||
|
||
**3. create_issue**
|
||
|
||
创建新任务
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"projectId": "uuid",
|
||
"title": "Implement user login",
|
||
"description": "Add JWT-based authentication",
|
||
"type": "Story",
|
||
"priority": "High",
|
||
"assigneeId": "uuid",
|
||
"estimatedHours": 16,
|
||
"acceptanceCriteria": [
|
||
"User can login with email/password",
|
||
"JWT token is returned"
|
||
]
|
||
}
|
||
```
|
||
|
||
**4. update_issue**
|
||
|
||
更新任务详情
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"issueId": "uuid",
|
||
"title": "Implement user login (updated)",
|
||
"description": "Add JWT + OAuth authentication",
|
||
"priority": "Critical",
|
||
"estimatedHours": 24
|
||
}
|
||
```
|
||
|
||
**Diff Preview 示例**:
|
||
```json
|
||
{
|
||
"operation": "UPDATE",
|
||
"entityType": "Issue",
|
||
"entityId": "uuid",
|
||
"changedFields": [
|
||
{
|
||
"fieldName": "description",
|
||
"oldValue": "Add JWT-based authentication",
|
||
"newValue": "Add JWT + OAuth authentication"
|
||
},
|
||
{
|
||
"fieldName": "priority",
|
||
"oldValue": "High",
|
||
"newValue": "Critical"
|
||
},
|
||
{
|
||
"fieldName": "estimatedHours",
|
||
"oldValue": 16,
|
||
"newValue": 24
|
||
}
|
||
],
|
||
"requiresApproval": true
|
||
}
|
||
```
|
||
|
||
**5. update_status**
|
||
|
||
更改任务状态
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"issueId": "uuid",
|
||
"status": "InProgress",
|
||
"comment": "Started working on this task"
|
||
}
|
||
```
|
||
|
||
**审批策略**:
|
||
- 可配置：某些状态流转可以无需审批（如 Todo → InProgress）
|
||
- 关键状态变更需要审批（如 InProgress → Done）
|
||
|
||
**6. assign_issue**
|
||
|
||
分配任务给用户
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"issueId": "uuid",
|
||
"assigneeId": "uuid"
|
||
}
|
||
```
|
||
|
||
**7. create_sprint**
|
||
|
||
创建新 Sprint
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"projectId": "uuid",
|
||
"name": "Sprint 6",
|
||
"goal": "Complete authentication module",
|
||
"startDate": "2024-11-15",
|
||
"endDate": "2024-11-28",
|
||
"capacity": 80
|
||
}
|
||
```
|
||
|
||
**8. start_sprint**
|
||
|
||
启动 Sprint
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"sprintId": "uuid",
|
||
"issueIds": ["uuid1", "uuid2", "uuid3"]
|
||
}
|
||
```
|
||
|
||
**9. add_comment**
|
||
|
||
添加评论
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"issueId": "uuid",
|
||
"text": "This task is blocked by COLA-123"
|
||
}
|
||
```
|
||
|
||
**审批策略**:
|
||
- 评论通常不需要审批（可配置）
|
||
- 如果包含敏感信息可以启用审批
|
||
|
||
**10. create_epic**
|
||
|
||
创建 Epic
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"projectId": "uuid",
|
||
"title": "User Authentication System",
|
||
"description": "Complete authentication module with JWT and OAuth",
|
||
"priority": "High"
|
||
}
|
||
```
|
||
|
||
**11. link_issues**
|
||
|
||
关联任务（父子关系）
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"parentId": "uuid",
|
||
"childId": "uuid",
|
||
"linkType": "Parent-Child"
|
||
}
|
||
```
|
||
|
||
#### 4.2.3 分析类工具
|
||
|
||
**12. analyze_burndown**
|
||
|
||
分析燃尽图趋势
|
||
|
||
**输入参数**:
|
||
```json
|
||
{
|
||
"sprintId": "uuid"
|
||
}
|
||
```
|
||
|
||
**输出**:
|
||
```json
|
||
{
|
||
"sprint": "Sprint 5",
|
||
"status": "OnTrack",
|
||
"summary": "The team is on track to complete 34 story points by 2024-11-14.",
|
||
"insights": [
|
||
"Daily completion rate: 2.5 points/day",
|
||
"Predicted completion: 2024-11-13 (1 day early)",
|
||
"Risk: 2 high-priority tasks still in Todo"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.3 Diff Preview 机制的设计思路
|
||
|
||
**核心理念**: **"预览 → 审批 → 执行"** 三步走
|
||
|
||
**为什么需要 Diff Preview**:
|
||
1. **安全性**: 防止 AI 误操作（如删除重要数据）
|
||
2. **透明性**: 用户清楚知道 AI 将要做什么
|
||
3. **合规性**: 满足企业审计要求
|
||
4. **可回滚**: 审批拒绝后不会执行操作
|
||
|
||
**Diff Preview 的生成流程**:
|
||
|
||
```
|
||
Tool 调用 → 收集当前数据 (Before)
|
||
↓
|
||
模拟执行操作
|
||
↓
|
||
生成变更后数据 (After)
|
||
↓
|
||
计算字段差异 (Changed Fields)
|
||
↓
|
||
格式化为人类可读的 Diff
|
||
↓
|
||
存储为 PendingChange 记录
|
||
↓
|
||
返回 Diff Preview 给 AI
|
||
```
|
||
|
||
**Diff 格式设计**:
|
||
|
||
```json
|
||
{
|
||
"pendingChangeId": "uuid",
|
||
"toolName": "update_issue",
|
||
"operation": "UPDATE",
|
||
"entityType": "Issue",
|
||
"entityId": "uuid",
|
||
"entityKey": "COLA-146",
|
||
"summary": "Update issue title, description, and priority",
|
||
"beforeData": {
|
||
"title": "Implement MCP Server",
|
||
"description": "Complete implementation...",
|
||
"priority": "High"
|
||
},
|
||
"afterData": {
|
||
"title": "Implement MCP Server (updated)",
|
||
"description": "Complete implementation with Diff Preview...",
|
||
"priority": "Critical"
|
||
},
|
||
"changedFields": [
|
||
{
|
||
"fieldName": "title",
|
||
"displayName": "Title",
|
||
"oldValue": "Implement MCP Server",
|
||
"newValue": "Implement MCP Server (updated)",
|
||
"diffHtml": "<del>Implement MCP Server</del> <ins>Implement MCP Server (updated)</ins>"
|
||
},
|
||
{
|
||
"fieldName": "priority",
|
||
"displayName": "Priority",
|
||
"oldValue": "High",
|
||
"newValue": "Critical",
|
||
"diffHtml": "<span class='old'>High</span> → <span class='new'>Critical</span>"
|
||
}
|
||
],
|
||
"requiresApproval": true,
|
||
"createdAt": "2024-11-06T10:30:00Z",
|
||
"expiresAt": "2024-11-07T10:30:00Z",
|
||
"createdBy": {
|
||
"id": "uuid",
|
||
"name": "AI Assistant (via John Doe)"
|
||
}
|
||
}
|
||
```
|
||
|
||
**审批界面展示**:
|
||
|
||
前端 Dashboard 会显示：
|
||
- **操作摘要**: "Update issue COLA-146: title, description, priority"
|
||
- **变更对比**: 左侧显示旧值，右侧显示新值，高亮差异
|
||
- **影响范围**: 影响的实体数量、关联任务等
|
||
- **审批按钮**: ✅ Approve / ❌ Reject / ⏸️ Later
|
||
|
||
**自动过期机制**:
|
||
|
||
- PendingChange 创建后 24 小时未审批自动过期
|
||
- 后台定时任务（每小时执行一次）清理过期记录
|
||
- 过期后 AI 会收到通知："Change request expired"
|
||
|
||
---
|
||
|
||
## 5. 安全性设计
|
||
|
||
### 5.1 认证机制（JWT Token + API Key）
|
||
|
||
MCP Server 支持两种认证方式：
|
||
|
||
#### 5.1.1 JWT Token 认证
|
||
|
||
**适用场景**: Web 前端通过浏览器访问 MCP Server
|
||
|
||
**流程**:
|
||
```
|
||
User → Login API → JWT Token
|
||
↓
|
||
User → MCP Request (携带 JWT)
|
||
↓
|
||
MCP Server 验证 JWT → 提取 TenantId、UserId
|
||
↓
|
||
执行操作（应用租户隔离）
|
||
```
|
||
|
||
**JWT Claims**:
|
||
```json
|
||
{
|
||
"sub": "user-uuid",
|
||
"tenant_id": "tenant-uuid",
|
||
"tenant_slug": "acme",
|
||
"email": "john@example.com",
|
||
"role": "Admin",
|
||
"exp": 1699200000
|
||
}
|
||
```
|
||
|
||
#### 5.1.2 API Key 认证
|
||
|
||
**适用场景**: AI 工具（Claude Desktop, ChatGPT）通过 MCP 协议访问
|
||
|
||
**API Key 格式**:
|
||
```
|
||
colaflow_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
|
||
```
|
||
|
||
**生成和存储**:
|
||
1. 用户在 Dashboard 创建 API Key
|
||
2. 系统生成 40 字符随机字符串
|
||
3. 使用 BCrypt 哈希后存储到数据库
|
||
4. 前16字符作为 prefix 明文存储（用于识别）
|
||
5. 完整 Key 只展示一次（创建时）
|
||
|
||
**验证流程**:
|
||
```
|
||
AI Tool → MCP Request (Header: Authorization: Bearer API_KEY)
|
||
↓
|
||
MCP Server 提取 API Key
|
||
↓
|
||
查询数据库（根据 key_prefix）
|
||
↓
|
||
BCrypt 验证哈希
|
||
↓
|
||
验证 IP 白名单（可选）
|
||
↓
|
||
验证权限范围（Resources/Tools 白名单）
|
||
↓
|
||
提取关联的 TenantId、UserId
|
||
↓
|
||
执行操作
|
||
```
|
||
|
||
**数据库表结构**:
|
||
```sql
|
||
CREATE TABLE mcp_api_keys (
|
||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||
tenant_id UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
|
||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||
key_hash VARCHAR(64) NOT NULL UNIQUE,
|
||
key_prefix VARCHAR(16) NOT NULL,
|
||
name VARCHAR(255) NOT NULL,
|
||
description TEXT,
|
||
permissions JSONB NOT NULL,
|
||
ip_whitelist JSONB,
|
||
status INT NOT NULL DEFAULT 1,
|
||
last_used_at TIMESTAMP NULL,
|
||
usage_count BIGINT NOT NULL DEFAULT 0,
|
||
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
|
||
expires_at TIMESTAMP NOT NULL,
|
||
revoked_at TIMESTAMP NULL,
|
||
|
||
INDEX idx_key_prefix (key_prefix),
|
||
INDEX idx_tenant_user (tenant_id, user_id),
|
||
INDEX idx_expires_at (expires_at)
|
||
);
|
||
```
|
||
|
||
### 5.2 授权和权限控制
|
||
|
||
#### 5.2.1 租户隔离
|
||
|
||
**实现方式**: EF Core Global Query Filter
|
||
|
||
所有查询自动添加 `WHERE tenant_id = current_tenant_id`
|
||
|
||
```csharp
|
||
modelBuilder.Entity<Issue>().HasQueryFilter(i =>
|
||
i.TenantId == _tenantContext.CurrentTenantId);
|
||
```
|
||
|
||
**防止跨租户访问**:
|
||
- 即使用户知道其他租户的资源 ID，也无法访问
|
||
- 需要显式使用 `IgnoreQueryFilters()` 才能跨租户查询（仅限系统管理员）
|
||
|
||
#### 5.2.2 角色权限（RBAC）
|
||
|
||
基于现有的 RBAC 系统：
|
||
|
||
| 角色 | Resources 权限 | Tools 权限 | 特殊权限 |
|
||
|------|---------------|-----------|---------|
|
||
| **Owner** | 所有 Resources | 所有 Tools | 创建 API Key |
|
||
| **Admin** | 所有 Resources | 所有 Tools | 审批 Pending Changes |
|
||
| **Member** | 参与的项目 | 有限 Tools | 只能修改自己的任务 |
|
||
| **Viewer** | 参与的项目 | 无 | 只读 |
|
||
| **Guest** | 受限 Resources | 无 | 临时访问 |
|
||
|
||
#### 5.2.3 API Key 权限范围
|
||
|
||
创建 API Key 时，用户可以指定：
|
||
|
||
**1. 资源白名单**:
|
||
```json
|
||
{
|
||
"allowedResources": [
|
||
"colaflow://projects.list",
|
||
"colaflow://issues.search",
|
||
"colaflow://issues.get/*"
|
||
]
|
||
}
|
||
```
|
||
|
||
**2. 工具白名单**:
|
||
```json
|
||
{
|
||
"allowedTools": [
|
||
"create_issue",
|
||
"update_status",
|
||
"add_comment"
|
||
]
|
||
}
|
||
```
|
||
|
||
**3. 只读模式**:
|
||
```json
|
||
{
|
||
"readOnly": true
|
||
}
|
||
```
|
||
|
||
**4. IP 白名单**:
|
||
```json
|
||
{
|
||
"ipWhitelist": [
|
||
"192.168.1.0/24",
|
||
"10.0.0.1"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5.3 AI 的读写权限分级
|
||
|
||
#### Level 0: 只读 (Read-Only)
|
||
|
||
- 允许: 所有 Resources
|
||
- 禁止: 所有 Tools
|
||
- 适用场景: AI 只用于查询和分析
|
||
|
||
#### Level 1: 有限写入 (Limited Write)
|
||
|
||
- 允许: 所有 Resources + 部分 Tools
|
||
- 需审批: 所有写操作
|
||
- 允许的 Tools: `create_issue`, `update_status`, `add_comment`
|
||
- 适用场景: 日常项目管理辅助
|
||
|
||
#### Level 2: 完全写入 (Full Write)
|
||
|
||
- 允许: 所有 Resources + 所有 Tools
|
||
- 需审批: 所有写操作（除非配置为自动审批）
|
||
- 适用场景: 高级自动化
|
||
|
||
#### Level 3: 自动化 (Automation)
|
||
|
||
- 允许: 所有 Resources + 所有 Tools
|
||
- 部分操作自动审批（如状态更新、评论）
|
||
- 关键操作仍需审批（如删除、权限变更）
|
||
- 适用场景: 完全信任的自动化流程
|
||
|
||
**配置示例**:
|
||
```json
|
||
{
|
||
"apiKeyName": "Claude Assistant",
|
||
"permissionLevel": "Limited Write",
|
||
"readOnly": false,
|
||
"autoApproveTools": ["add_comment", "update_status"],
|
||
"requireApprovalTools": ["create_issue", "update_issue", "delete_issue"]
|
||
}
|
||
```
|
||
|
||
### 5.4 敏感数据保护
|
||
|
||
#### 5.4.1 字段级过滤
|
||
|
||
某些字段不应该暴露给 AI：
|
||
|
||
**敏感字段列表**:
|
||
- `password_hash`
|
||
- `api_key_hash`
|
||
- `jwt_refresh_token`
|
||
- `email_verification_token`
|
||
- `password_reset_token`
|
||
- `sso_config.client_secret`
|
||
|
||
**实现方式**:
|
||
|
||
使用 DTO（Data Transfer Object）模式，只返回安全字段：
|
||
|
||
```csharp
|
||
public class UserDto
|
||
{
|
||
public Guid Id { get; set; }
|
||
public string Email { get; set; }
|
||
public string FullName { get; set; }
|
||
public string Role { get; set; }
|
||
// 不包含 PasswordHash, ApiKeys 等敏感字段
|
||
}
|
||
```
|
||
|
||
#### 5.4.2 数据脱敏
|
||
|
||
对于某些敏感信息，返回脱敏后的数据：
|
||
|
||
- Email: `john****@example.com`
|
||
- Phone: `138****5678`
|
||
- IP: `192.168.***.***`
|
||
|
||
### 5.5 审计日志
|
||
|
||
所有 MCP 操作都记录到审计日志：
|
||
|
||
**日志内容**:
|
||
```json
|
||
{
|
||
"tenantId": "uuid",
|
||
"userId": "uuid",
|
||
"action": "McpToolExecuted",
|
||
"entityType": "Issue",
|
||
"entityId": "uuid",
|
||
"toolName": "update_issue",
|
||
"beforeData": { ... },
|
||
"afterData": { ... },
|
||
"ipAddress": "192.168.1.100",
|
||
"userAgent": "Claude Desktop MCP Client",
|
||
"apiKeyId": "uuid",
|
||
"pendingChangeId": "uuid",
|
||
"approvedBy": "uuid",
|
||
"timestamp": "2024-11-06T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
**审计查询**:
|
||
- 按用户查询（谁做了什么）
|
||
- 按实体查询（某个任务的所有变更历史）
|
||
- 按时间范围查询
|
||
- 按操作类型查询（CREATE/UPDATE/DELETE）
|
||
|
||
**审计日志保留策略**:
|
||
- 热数据（30天）: PostgreSQL
|
||
- 温数据（90天）: PostgreSQL 表分区
|
||
- 冷数据（1年）: 归档到 S3/Azure Blob
|
||
- 合规数据（7年）: 冷存储 + 加密
|
||
|
||
---
|
||
|
||
## 6. 技术实现方案
|
||
|
||
### 6.1 MCP Server 技术栈选型
|
||
|
||
**选型决策**: 自定义 .NET 9 实现（不使用官方 Node.js SDK）
|
||
|
||
**理由**:
|
||
1. **原生集成**: 与现有 ASP.NET Core 后端无缝集成
|
||
2. **性能优势**: .NET 9 性能优于 Node.js（特别是并发场景）
|
||
3. **类型安全**: C# 强类型系统减少运行时错误
|
||
4. **无额外依赖**: 不需要部署 Node.js 环境
|
||
5. **团队技能**: 团队已熟悉 .NET 生态
|
||
|
||
**实现方式**: 手动实现 MCP 协议规范（JSON-RPC 2.0）
|
||
|
||
### 6.2 与后端 ASP.NET Core API 的通信方式
|
||
|
||
**方式 1: 直接调用现有服务（推荐）**
|
||
|
||
MCP Server 作为后端系统的一个模块，直接调用现有的 Application Layer 服务：
|
||
|
||
```csharp
|
||
// MCP Tool 内部调用 CQRS Command
|
||
public class CreateIssueTool : IMcpTool
|
||
{
|
||
private readonly IMediator _mediator;
|
||
|
||
public async Task<McpToolResult> ExecuteAsync(...)
|
||
{
|
||
var result = await _mediator.Send(new CreateIssueCommand
|
||
{
|
||
ProjectId = input.ProjectId,
|
||
Title = input.Title,
|
||
Type = input.Type
|
||
});
|
||
|
||
return new McpToolResult { ... };
|
||
}
|
||
}
|
||
```
|
||
|
||
**优点**:
|
||
- 零网络延迟
|
||
- 共享事务上下文
|
||
- 复用现有业务逻辑
|
||
- 统一的异常处理
|
||
|
||
**方式 2: HTTP API 调用（备选）**
|
||
|
||
如果 MCP Server 部署为独立服务：
|
||
|
||
```csharp
|
||
public class CreateIssueTool : IMcpTool
|
||
{
|
||
private readonly HttpClient _httpClient;
|
||
|
||
public async Task<McpToolResult> ExecuteAsync(...)
|
||
{
|
||
var response = await _httpClient.PostAsJsonAsync(
|
||
"/api/issues",
|
||
new { projectId, title, type });
|
||
|
||
response.EnsureSuccessStatusCode();
|
||
var issue = await response.Content.ReadFromJsonAsync<Issue>();
|
||
|
||
return new McpToolResult { ... };
|
||
}
|
||
}
|
||
```
|
||
|
||
**优点**:
|
||
- 服务解耦
|
||
- 独立扩展
|
||
- 可单独部署
|
||
|
||
**决策**: M2 阶段采用**方式 1（直接调用）**，M4 阶段考虑服务拆分时采用方式 2。
|
||
|
||
### 6.3 性能优化考虑
|
||
|
||
#### 6.3.1 缓存策略
|
||
|
||
**Redis 缓存层**:
|
||
|
||
```
|
||
查询请求 → 检查 Redis 缓存
|
||
↓
|
||
缓存命中 → 直接返回
|
||
↓
|
||
缓存未命中 → 查询数据库
|
||
↓
|
||
写入 Redis (TTL 5分钟)
|
||
↓
|
||
返回结果
|
||
```
|
||
|
||
**缓存的数据**:
|
||
- Projects List（高频访问）
|
||
- Current Sprint（高频访问）
|
||
- User List（高频访问）
|
||
- Issue Details（中频访问，TTL 2分钟）
|
||
|
||
**缓存失效策略**:
|
||
- 数据更新时主动失效（通过领域事件）
|
||
- TTL 自动过期（5分钟）
|
||
- 手动刷新接口（管理员操作）
|
||
|
||
#### 6.3.2 查询优化
|
||
|
||
**数据库索引**:
|
||
```sql
|
||
-- Issues 表优化
|
||
CREATE INDEX idx_issues_tenant_project ON issues(tenant_id, project_id);
|
||
CREATE INDEX idx_issues_tenant_status ON issues(tenant_id, status);
|
||
CREATE INDEX idx_issues_tenant_assignee ON issues(tenant_id, assignee_id);
|
||
CREATE INDEX idx_issues_tenant_sprint ON issues(tenant_id, sprint_id);
|
||
CREATE INDEX idx_issues_full_text ON issues USING gin(to_tsvector('english', title || ' ' || description));
|
||
|
||
-- PendingChanges 表优化
|
||
CREATE INDEX idx_pending_changes_tenant_status ON mcp_pending_changes(tenant_id, status);
|
||
CREATE INDEX idx_pending_changes_expires ON mcp_pending_changes(expires_at) WHERE status = 'PendingApproval';
|
||
```
|
||
|
||
**分页查询**:
|
||
- 默认 limit=50
|
||
- 最大 limit=100
|
||
- 使用 offset-based 分页（简单场景）
|
||
- 使用 cursor-based 分页（大数据集）
|
||
|
||
**只查询必要字段**:
|
||
```csharp
|
||
var issues = await _context.Issues
|
||
.Where(i => i.ProjectId == projectId)
|
||
.Select(i => new IssueDto
|
||
{
|
||
Id = i.Id,
|
||
Title = i.Title,
|
||
Status = i.Status
|
||
// 不加载 Description, Comments 等大字段
|
||
})
|
||
.ToListAsync();
|
||
```
|
||
|
||
#### 6.3.3 并发控制
|
||
|
||
**乐观并发控制**:
|
||
|
||
使用 EF Core 的 `RowVersion` / `Timestamp` 字段：
|
||
|
||
```csharp
|
||
public class Issue
|
||
{
|
||
[Timestamp]
|
||
public byte[] RowVersion { get; set; }
|
||
}
|
||
|
||
// 更新时检查版本
|
||
var issue = await _context.Issues.FindAsync(id);
|
||
issue.Title = newTitle;
|
||
|
||
try
|
||
{
|
||
await _context.SaveChangesAsync();
|
||
}
|
||
catch (DbUpdateConcurrencyException)
|
||
{
|
||
throw new ConcurrencyException("Issue has been modified by another user");
|
||
}
|
||
```
|
||
|
||
**分布式锁**:
|
||
|
||
使用 Redis 分布式锁防止并发冲突：
|
||
|
||
```csharp
|
||
await using var lock = await _distributedLock.AcquireAsync($"issue:{issueId}", TimeSpan.FromSeconds(10));
|
||
|
||
if (lock == null)
|
||
{
|
||
throw new ResourceLockedException("Issue is being modified by another operation");
|
||
}
|
||
|
||
// 执行更新操作
|
||
```
|
||
|
||
#### 6.3.4 异步处理
|
||
|
||
**后台任务**:
|
||
|
||
某些耗时操作通过后台队列异步处理：
|
||
|
||
- 审计日志写入（使用 Channel 队列）
|
||
- 邮件通知发送（使用 Hangfire）
|
||
- 数据统计计算（使用 BackgroundService）
|
||
|
||
**SignalR 实时推送**:
|
||
|
||
审批完成后通过 WebSocket 推送结果，无需 AI 轮询。
|
||
|
||
### 6.4 可扩展性设计
|
||
|
||
#### 6.4.1 插件化架构
|
||
|
||
MCP Resources/Tools/Prompts 采用插件化设计，便于扩展：
|
||
|
||
```csharp
|
||
public interface IMcpPlugin
|
||
{
|
||
string Name { get; }
|
||
string Version { get; }
|
||
void Register(IMcpRegistry registry);
|
||
}
|
||
|
||
public class CustomPlugin : IMcpPlugin
|
||
{
|
||
public string Name => "CustomIssueTools";
|
||
public string Version => "1.0.0";
|
||
|
||
public void Register(IMcpRegistry registry)
|
||
{
|
||
registry.RegisterResource(new CustomResource());
|
||
registry.RegisterTool(new CustomTool());
|
||
registry.RegisterPrompt(new CustomPrompt());
|
||
}
|
||
}
|
||
```
|
||
|
||
**插件加载方式**:
|
||
- 自动扫描程序集（Reflection）
|
||
- 配置文件指定（appsettings.json）
|
||
- 动态加载 DLL（高级场景）
|
||
|
||
#### 6.4.2 多租户扩展
|
||
|
||
**水平扩展**:
|
||
- MCP Server 无状态设计，可部署多个实例
|
||
- 负载均衡（Nginx / Azure Load Balancer）
|
||
- Session affinity（WebSocket 需要）
|
||
|
||
**数据库扩展**:
|
||
- 读写分离（主从复制）
|
||
- 按租户分片（大租户独立数据库）
|
||
- PostgreSQL 表分区（按租户 ID）
|
||
|
||
#### 6.4.3 版本控制
|
||
|
||
MCP 协议支持版本号：
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"method": "initialize",
|
||
"params": {
|
||
"protocolVersion": "2024-11-05",
|
||
"capabilities": {
|
||
"resources": {},
|
||
"tools": {},
|
||
"prompts": {}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**版本策略**:
|
||
- 向后兼容（old API Key 仍可使用）
|
||
- 废弃警告（Deprecated 字段）
|
||
- 强制升级（BREAKING CHANGE）
|
||
|
||
---
|
||
|
||
## 7. 实现路线图
|
||
|
||
### 7.1 MVP 阶段功能范围
|
||
|
||
**目标**: 验证技术可行性，实现核心功能
|
||
|
||
**功能范围**:
|
||
- ✅ 5 个核心 Resources（projects.list, issues.search, sprints.current, users.list, issues.get）
|
||
- ✅ 3 个核心 Tools（create_issue, update_status, add_comment）
|
||
- ✅ 2 个核心 Prompts（generate_prd, split_epic_to_stories）
|
||
- ✅ API Key 认证（创建、验证、撤销）
|
||
- ✅ Diff Preview 机制（生成、存储、审批）
|
||
- ✅ 基础审计日志
|
||
|
||
**不包含**:
|
||
- 高级查询工具
|
||
- 复杂权限配置
|
||
- IP 白名单
|
||
- 自动化审批规则
|
||
|
||
**预计时间**: 4 周
|
||
|
||
### 7.2 核心功能优先级
|
||
|
||
| 优先级 | 功能模块 | 工作量 | 依赖 |
|
||
|--------|---------|--------|------|
|
||
| **P0** | MCP Protocol Handler | 3天 | 无 |
|
||
| **P0** | API Key 管理（创建、验证） | 2天 | MCP Protocol Handler |
|
||
| **P0** | Resources 实现（5个） | 3天 | API Key |
|
||
| **P0** | Diff Preview Service | 2天 | Resources |
|
||
| **P0** | PendingChange 管理 | 2天 | Diff Preview |
|
||
| **P0** | Tools 实现（3个） | 3天 | PendingChange |
|
||
| **P0** | 审批流程（前端 UI） | 2天 | PendingChange |
|
||
| **P1** | Prompts 实现（2个） | 2天 | Tools |
|
||
| **P1** | 审计日志集成 | 1天 | 已有 Audit Log 系统 |
|
||
| **P1** | Claude Desktop 集成 PoC | 2天 | 所有核心功能 |
|
||
|
||
**总工时**: 22 天（约 4.5 周）
|
||
|
||
### 7.3 分阶段实现建议
|
||
|
||
#### Phase 1: Foundation（Week 1-2）
|
||
|
||
**目标**: 建立 MCP 基础设施
|
||
|
||
**交付物**:
|
||
- MCP Protocol Handler（JSON-RPC 2.0 解析和路由）
|
||
- API Key 聚合根和仓储
|
||
- API Key 认证中间件
|
||
- 基础的错误处理和日志记录
|
||
|
||
**验收标准**:
|
||
- [ ] MCP 协议 `initialize` 握手成功
|
||
- [ ] API Key 创建和验证通过
|
||
- [ ] 未授权请求返回 401
|
||
- [ ] 错误响应符合 MCP 规范
|
||
|
||
#### Phase 2: Resources（Week 3-4）
|
||
|
||
**目标**: 实现只读数据暴露
|
||
|
||
**交付物**:
|
||
- 5 个核心 Resources 实现
|
||
- Resource 注册和发现机制
|
||
- 租户隔离验证
|
||
- Redis 缓存集成
|
||
|
||
**验收标准**:
|
||
- [ ] 所有 5 个 Resources 返回正确数据
|
||
- [ ] 租户隔离 100% 生效
|
||
- [ ] 响应时间 < 200ms
|
||
- [ ] 缓存命中率 > 80%
|
||
|
||
#### Phase 3: Tools & Diff Preview（Week 5-6）
|
||
|
||
**目标**: 实现写操作和 Diff Preview
|
||
|
||
**交付物**:
|
||
- DiffPreviewService 实现
|
||
- PendingChange 聚合根和仓储
|
||
- 3 个核心 Tools 实现
|
||
- SignalR 实时通知集成
|
||
|
||
**验收标准**:
|
||
- [ ] Diff Preview 准确显示变更
|
||
- [ ] PendingChange 正确存储和查询
|
||
- [ ] SignalR 推送工作正常
|
||
- [ ] 24小时自动过期机制生效
|
||
|
||
#### Phase 4: Approval Workflow（Week 7-8）
|
||
|
||
**目标**: 实现审批流程
|
||
|
||
**交付物**:
|
||
- 审批 API 端点（approve/reject）
|
||
- 审批后自动执行逻辑
|
||
- 前端审批界面（Dashboard）
|
||
- 审计日志集成
|
||
|
||
**验收标准**:
|
||
- [ ] 审批通过后自动执行操作
|
||
- [ ] 审批拒绝后记录日志
|
||
- [ ] 前端界面清晰展示 Diff
|
||
- [ ] 审计日志完整记录
|
||
|
||
#### Phase 5: Prompts & Integration（Week 9-10）
|
||
|
||
**目标**: 实现提示词和 AI 集成
|
||
|
||
**交付物**:
|
||
- 2 个核心 Prompts 实现
|
||
- Claude Desktop 配置文件
|
||
- MCP 集成测试（端到端）
|
||
- 用户文档和使用指南
|
||
|
||
**验收标准**:
|
||
- [ ] Claude Desktop 成功连接
|
||
- [ ] AI 能够查询项目数据
|
||
- [ ] AI 能够创建任务（需审批）
|
||
- [ ] 完整的端到端流程测试通过
|
||
|
||
#### Phase 6: Testing & Hardening（Week 11-12）
|
||
|
||
**目标**: 质量保证和生产就绪
|
||
|
||
**交付物**:
|
||
- 单元测试覆盖率 > 80%
|
||
- 集成测试套件
|
||
- 性能测试和优化
|
||
- 安全审计和漏洞修复
|
||
|
||
**验收标准**:
|
||
- [ ] 所有测试通过
|
||
- [ ] 性能达标（API < 200ms）
|
||
- [ ] 无 CRITICAL 安全漏洞
|
||
- [ ] 文档完整且准确
|
||
|
||
#### Phase 7: Documentation & PoC（Week 13-16）
|
||
|
||
**目标**: 文档和概念验证
|
||
|
||
**交付物**:
|
||
- MCP API 完整文档
|
||
- AI 集成最佳实践指南
|
||
- 视频演示（Demo）
|
||
- 内部培训材料
|
||
|
||
**验收标准**:
|
||
- [ ] 外部开发者能根据文档集成
|
||
- [ ] 演示视频清晰展示价值
|
||
- [ ] 团队成员完成培训
|
||
|
||
---
|
||
|
||
## 8. 总结
|
||
|
||
### 8.1 核心设计原则
|
||
|
||
1. **安全优先**: 所有写操作需审批，完整审计追踪
|
||
2. **租户隔离**: 100% 数据隔离，无跨租户访问
|
||
3. **性能保证**: API < 200ms，缓存命中率 > 80%
|
||
4. **可扩展性**: 插件化设计，便于添加新 Resources/Tools
|
||
5. **向后兼容**: 版本控制，避免 Breaking Changes
|
||
|
||
### 8.2 技术亮点
|
||
|
||
- **自定义 MCP 实现**: 不依赖 Node.js，与 .NET 后端无缝集成
|
||
- **Diff Preview 机制**: 创新的"预览 → 审批 → 执行"流程
|
||
- **CQRS + DDD**: 清晰的架构分层，易于维护和测试
|
||
- **SignalR 实时通知**: 无需轮询，审批结果即时推送
|
||
- **多层缓存**: Redis + 应用层缓存，性能优化
|
||
|
||
### 8.3 风险与缓解
|
||
|
||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||
|------|------|------|---------|
|
||
| MCP 协议规范变更 | 高 | 中 | 版本控制，快速适配新规范 |
|
||
| AI 误操作导致数据损坏 | 高 | 低 | Diff Preview + 审批 + 审计 |
|
||
| 性能瓶颈（高并发） | 中 | 中 | Redis 缓存 + 水平扩展 |
|
||
| 安全漏洞（API Key 泄露） | 高 | 低 | BCrypt 哈希 + IP 白名单 + 速率限制 |
|
||
| 审批流程过于繁琐 | 中 | 中 | 可配置自动审批规则 |
|
||
|
||
### 8.4 后续演进方向
|
||
|
||
**M3 阶段（ChatGPT 集成）**:
|
||
- 支持 ChatGPT Plugin 协议
|
||
- 实现对话式项目管理
|
||
- AI 生成完整 PRD → Epic → Stories 闭环
|
||
|
||
**M4 阶段（外部系统集成）**:
|
||
- GitHub Actions 触发 ColaFlow 更新
|
||
- Slack 消息自动创建任务
|
||
- 日历同步 Sprint 时间线
|
||
|
||
**M5 阶段（企业级功能）**:
|
||
- 多 AI Agent 协作（PM AI + Dev AI + QA AI）
|
||
- AI 决策审批工作流
|
||
- 自定义 AI Prompt 市场
|
||
|
||
---
|
||
|
||
**文档结束**
|
||
|
||
如有疑问或需要更详细的技术设计，请联系架构师团队。
|