AI导哈

ESL学习管理平台

MyCastle是一个基于8-MCP领域驱动架构的ESL学校运营平台，提供课程表管理、CEFR驱动的课程规划、考勤跟踪、学生档案和AI辅助工作流等功能。

  • by jojopeligroso
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jojopeligroso/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）

🏗️ 技术栈

核心框架和语言

技术 版本 目的
TypeScript ^5 整个堆栈的类型安全开发
Next.js 16.0.1 带有API路由的完整React框架
Node.js ^20 MCP编排的服务器运行时

前端

技术 版本 目的
反应 19.2.0 UI组件库
React DOM 19.2.0 用于web的React渲染
Tailwind CSS ^4 实用程序优先的CSS框架

后端和API

技术 版本 目的
Next.js API路线 16.0.1 RESTful端点和MCP编排
MCP-SDK ^1.21.1 模型上下文协议实现
黄道带 ^4.1.12 运行时模式验证

数据库和ORM

技术 版本 目的
Supabase ^2.80.0 带RLS的主数据库平台
PostgreSQL - 基础关系数据库
淋ORM ^0.44.7 类型安全的SQL查询生成器
喷雾套件 ^0.31.6 架构迁移和管理
Postgres ^3.4.7 Node.js的PostgreSQL客户端

认证

技术 版本 目的
Supabase认证 ^2.80.0 基于JWT的身份验证
Supabase SSR ^0.7.0 服务器端渲染身份验证支持

AI&LLM

技术 版本 目的
OpenAI API ^6.8.1 LLM集成（模型无关设计）

测试

技术 版本 目的
玩笑 ^30.2.0 单元和集成测试
测试库 ^16.3.0 React组件测试
玩笑 ^6.9.1 Custom Jest matchers for DOM

代码质量和开发工具

技术 版本 目的
ESLint ^9 代码删除和质量检查
更漂亮 ^3.6.2 代码格式
多伦多证券交易所 ^4.20.6 脚本的TypeScript执行
执政官 - MCP开发检查员

运输和部署

图层 技术 注释
MCP协议 JSON-RPC 2.0通过标准输入/HTTPS 标准输入（开发），HTTPS（产品）
多租户技术 行级安全性（RLS） 数据库强制租户隔离

📐 建筑原理

  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

📚 关键文件

🔐 安全与合规

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

🎓 用例

对于管理员

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

教师（未来）

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

面向学生（未来）

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

🛠️ 开发流程

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

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

📖 文档状态

章节 状态 描述
1-8 ✅ 完成 概述、架构、MCP、管理员/教师/学生MCP、代理、数据库
9 ⏳ 详细信息 测试策略
10 ⏳ 整合 原始规范中的用户故事
11 ⏳ 详细信息 部署过程
12 ⏳ 创建 附录、术语表、API参考

🤝 贡献

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

  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

相关 MCP