Esl MCP Spec

MyCastle–ESL学习平台规范

版本： 3.0.0 批准 | 最后更新时间： 2025-11-11

此存储库包含 完整的规格 MyCastle是一个基于 8-MCP域驱动架构 具有未来域MCP的可扩展性。它涵盖了时间表管理、CEFR驱动的课程规划、出勤跟踪、学生档案以及通过特定角色的MCP服务器进行的人工智能辅助工作流程。

______________________________________________________________________

✅ MVP准备真实来源

准备就绪层次结构（SSOT）：

• MVP_SPEC_REVIEW.md=权限（准备就绪）
• STATUS.md=信号（导出）
• ROADMAP.md=意图（未来）
• project-review.md=学习（临时）

MVP政策决策：

• **/api/admin/* 路由仅限管理员*\*
• 管理员出勤不要求MVP遵守哈希链

______________________________________________________________________

📋 核心规范文件（Spine）

这三份文件构成 权威脊柱 项目的状态，并随着每次提交而更新：

1. 需求.md --需求规格说明

系统必须做什么以及为什么。

• 目标（MoSCoW）、利益相关者、用户故事
• 功能和非功能要求
• 数据要求、合规性、验收标准
• 成功指标和可追溯性

2. 设计.md --设计说明书

系统如何满足要求。

• 架构（MCP、Next.js、Supabase）
• 域模型、数据流、API
• 安全（RLS、JWT、加密）
• 性能策略、可观察性

3. TASKS.md --任务规范

如何执行工作以实现设计。

• Epic的工作分解结构（WBS）
• 具有验收标准的可操作任务
• 测试策略，CI/CD管道
• 可追溯性（REQ→ 设计→ TASK)

这些文件是活的，必须与实施保持一致。

______________________________________________________________________

🗂️ 仓库结构

更新： 2026-01-02-从27合并→ 12 核心文件

MyCastle/
├── README.md                       # This file - Navigation hub
│
├── Core Specification ("The Spine")
├── REQ.md                          # ✅ Requirements Specification (v3.0.0)
├── DESIGN.md                       # ✅ Design Specification (v3.0.0)
├── TASKS.md                        # ✅ Task Specification (v3.0.0)
│
├── Living Documents (Updated Weekly)
├── STATUS.md                       # ⭐ Current sprint tasks with 20-min subtasks
├── ROADMAP.md                      # Phases 1-4 (105 tasks)
│
├── Operational Guides
├── GETTING-STARTED.md              # Quick start + detailed setup + overview
├── TESTING.md                      # All testing procedures (unit, E2E, RLS)
├── DEPLOYMENT.md                   # Production deployment guide
│
├── Reference Documents
├── docs/
│   ├── reference/
│   │   ├── 8-MCP-IMPLEMENTATION-PLAN.md
│   │   ├── BUSINESS_VALUE_PRIORITIES.md
│   │   └── FLEXIBLE_ENROLLMENTS.md
│   │
│   ├── archive/                    # Historical documents
│   │   ├── sprints/                # Sprint retrospectives
│   │   ├── analyses/               # Gap analyses and reviews
│   │   ├── PROGRESS.md             # Old progress tracking
│   │   └── NEXT_STEPS_GUIDE.md     # Old setup guide
│   │
│   └── migration/
│       └── MIGRATION_GUIDE.md
│
├── Technical Specifications
├── spec/                           # Detailed MCP architecture specs
│   ├── 01-overview.md              # Project objectives, stakeholders
│   ├── 02-system-architecture.md   # System architecture details
│   ├── 03-mcp.md                   # MCP protocol implementation
│   ├── 04-admin-mcp.md             # Admin MCP specification
│   ├── 05-teacher-mcp.md           # Teacher MCP specification
│   ├── 06-student-mcp.md           # Student MCP specification
│   ├── 07-agents.md                # Host orchestration patterns
│   ├── 08-database.md              # Complete database schema
│   ├── 09-mcp-interaction-patterns.md
│   └── table-of-contents.md
│
└── Implementation
    └── app/                        # Next.js application code

______________________________________________________________________

🚀 快速开始

产品/业务

1. 开始.md -项目概况及现状
2. 状态.md -当前冲刺进度（每周更新）
3. 需求.md -完整的需求规格说明

对于新开发人员

1. 开始.md -5分钟快速启动或详细设置
2. 状态.md -查看当前包含20分钟子任务的冲刺任务
3. 测试.md -运行测试并验证设置

工程类

1. 设计.md -技术架构和模式
2. TASKS.md -工作分解结构（42项任务）
3. 规格/ -详细的MCP架构规范

用于实施

1. 检查 状态.md 用于当前的sprint任务
2. 每个任务都有20分钟的子任务，便于跟踪
3. 链接到中的要求 需求.md
4. 审查设计 设计.md
5. 实施可追溯性意见
6. 跑 npm run check 在承诺之前
7. 更新STATUS.md的进度

🎯 8-MCP架构（v3.0已批准）

核心MCP（全部≤10个工具）：

1. ✅ 身份和访问MCP （6个工具）-用户身份验证、角色、权限
2. ✅ 学术运营MCP （10个工具）-程序、课程、日程安排
3. ✅ 出勤与合规MCP （8个工具）-登记簿、签证跟踪
4. ✅ 金融MCP （9个工具）-发票、付款、对账
5. ✅ 学生服务MCP （9个工具）-住宿、信件、证书
6. ✅ 运营与质量MCP （8个工具）-备份、QA、CPD
7. ✅ MCP老师 （10个工具）-课程规划、评分、出勤
8. ✅ 学生MCP （10个工具）-时间表、人工智能导师、进度跟踪

未来扩展性：

• ⏭️ 家长MCP -父门户（≤10个工具）
• ⏭️ 合作伙伴MCP -学校合作伙伴关系（≤10个工具）
• ⏭️ 分析MCP -BI和报告（≤10个工具）
• ⏭️ 营销MCP -CRM和活动（≤10个工具）
• ⏭️ 自定义域MCP -易于添加，无需修改现有MCP

迁移策略： 4阶段推出（见TASKS.md§4.3.1）

🏗️ 技术栈

核心框架和语言

前端

后端和API

数据库和ORM

认证

AI&LLM

测试

代码质量和开发工具

运输和部署

📐 建筑原理

1. 领域驱动设计：8个聚焦MCP（全部≤10个工具）与臃肿的3-MCP设计
2. 主机中介通信：所有MCP服务器都通过主机通信（MCP与MCP之间没有直接通信）
3. 基于范围的路由：细粒度授权（身份：*，财务：*、学术：\*等）
4. 租户隔离：多租户就绪 tenant_id RLS政策
5. 设计可扩展性：添加新域MCP而不修改现有域MCP
6. 规范优先开发：实施前记录所有变更
7. 设计安全：JWT验证、RLS、审计日志记录贯穿始终
8. 演出：分布式负载、特定于域的缓存、每个MCP更简单的RLS

📚 关键文件

• 目录 -完整导航
• 系统架构 -详细的架构图和组件描述
• 管理员MCP -MVP MCP服务器的完整规范（资源、工具、提示）
• 数据库模式 -带有ERD、RLS策略和视图的完整Drizzle架构
• 智能体编排 -多MCP协调的主机模式

🔐 安全与合规

• GDPR对齐：数据最小化、目的限制、访问控制
• RLS（行级安全）：在数据库级别强制执行租户隔离
• JWT身份验证：支持JWKS验证的身份验证
• 审计日志：所有重要操作都被永久记录
• 上下文隔离：MCP服务器不能直接访问彼此的数据

🎓 用例

对于管理员

• 管理用户（添加、修改、删除）
• 创建和管理类
• 跟踪出勤和预订情况
• 从模板生成Excel/CSV导出
• 查看付款摘要并创建发票
• 系统备份和审计日志

教师（未来）

• 制定课程计划和测验
• 自动评分作业
• 分析学生表现
• 记录出勤率和成绩
• 发送班级公告

面向学生（未来）

• 获得个性化辅导和家庭作业帮助
• 参加练习测验
• 跟踪学习进度
• 访问课程材料
• 接受学习指导

🛠️ 开发流程

该项目遵循 规格优先 方法：

1. 规格 → 实施前记录设计
2. 架构定义 → 使用Drizzle定义的数据库表
3. MCP 服务器 → 工具、资源、提示已实施
4. 主机集成 → 将MCP连接到主机服务
5. 测试 → 拱门检查+单元/集成测试
6. 部署 → 本地开发（stdio），生产（HTTPS）

📖 文档状态

🤝 贡献

这是一个活生生的规范。更改应遵循以下过程：

1. 讨论拟议的变更
2. 更新相关规范文件
3. 如果结构发生变化，请更新目录
4. 增量版本处于文档状态
5. 以清晰的描述承诺

📊 可追溯性

每一项任务 TASKS.md 链接到：

• 用户故事 通过REQ-T在REQ.md（§5）中-*，REQ-A-*，REQ-S-\*ID
• 设计部分 通过§引用在DESIGN.md中
• 验收标准 （文-衡格式）

可追溯性链示例:

User Story (REQ-T-001): Generate CEFR-aligned lesson plan
    ↓
Design (DESIGN §6): Lesson Planning Flow (AI-Assisted)
    ↓
Tasks: T-031 (API), T-032 (Schema), T-033 (Cache)
    ↓
Implementation: Code with comments linking back to REQ-T-001
    ↓
Tests: E2E test named "REQ-T-001: Generate lesson plan"

这确保了 双向追踪性：从需求到实现，从代码到需求。

______________________________________________________________________

📝 版本历史

v3.0.0 批准 （2025-11-11）-8-MCP领域驱动架构

状态： ✅ 架构决策最终确定并批准实施

核心变化：

• ✅ 将管理MCP拆分为6个域MCP（身份、学术、出勤、财务、学生服务、运营）
• ✅ 优化教师MCP（12→10个工具）
• ✅ 优化学生MCP（14→10个工具）
• ✅ 所有8个MCP现在≤10个工具（符合架构约束）
• ✅ 增加了34个迁移任务（T-110至T-143），并制定了4阶段部署计划
• ✅ 更新了基于范围的路由的C4架构图
• ✅ 细粒度授权范围（标识：*，财务：*、学术：\*等）
• ✅ 总计：76项任务（42项核心+34项迁移）

可扩展性：

• ✅ 添加未来域MCP（母公司、合作伙伴、分析、营销）的清晰模式
• ✅ 具有maxTools=10约束的标准MCP接口
• ✅ 独立部署模型（无级联更改）
• ✅ 记录扩展指南和技术要求
• ✅ 提供示例实现（父MCP，带10个工具）

优点：

• ✅ 更好的安全性：最小权限，每个MCP的攻击面更小
• ✅ 更好的性能：分布式负载、特定域缓存
• ✅ 更容易维护：明确的领域界限，集中的责任
• ✅ 面向未来：无需重构现有MCP即可无缝添加新域

v2.1.0（2025-11-07）——Spine集成规范

• ✅ 添加REQ.md、DESIGN.md、TASKS.md作为项目主干
• ✅ 使MCP架构与传统需求相协调
• ✅ 在所有规格之间建立可追溯性
• ✅ 用户故事映射到详细任务
• ✅ 在11部史诗中定义了42项任务
• ✅ 4个具有明确退出标准的里程碑

v2.0.0（2025-10-31）——MCP架构重构

• 完整的MCP架构规范（管理员、教师、学生MCP）
• 交互模式和编排细节
• 共享服务架构

v1.0.0（2025-10-30）——初始合并

• 合并了原始规范.md和esl-mcp规范内容
• 已完成第1-8节
• 确定MVP优先级（管理MCP+主机）

______________________________________________________________________

👤 作者

Eoin Malone （带克劳德密码）

📄 许可证

\[待定\]

______________________________________________________________________

规范状态: ✅ v3.0.0已批准-完成并对齐（要求↔ 设计↔ 任务） 建筑决策: ✅ 具有可扩展性的8-MCP域驱动架构于2025-11年获得批准 最后更新: 2025-11-11 版本: 3.0.0