内容
# 普泰拉 MCP 服务器
普泰拉 MCP（模型上下文协议）服务器，为 AI 代理提供直接访问普泰拉 GraphQL API 和本地项目简介数据的能力。连接 Cursor、Claude Desktop 或任何 MCP 客户端，以创建学习程序、管理评估、提交作品作为学习者、进行评审，并在普泰拉 monorepo 中运行测试套件。
## 为什么选择普泰拉 MCP？
使用此 MCP 服务器，代理可以：
- 分析和重组现有项目，以适应不同受众或年级水平
- 自动生成评估蓝图和创建问题
- 在机构或 LMS 数据格式之间导入/导出程序
- 提交评估和管理评审工作流程
- 按技能搜索 5400+ 个体验式学习项目简介
- 直接从 Cursor 运行测试套件，跨所有普泰拉存储库
## 快速入门（Cursor — 本地开发）
1. 克隆此存储库与其他普泰拉存储库一起。
2. 安装依赖项：`npm install`
3. 将 `.cursor/mcp.json` 添加到任何普泰拉存储库（参见 [Cursor 配置](#cursor-配置)）。
4. 重新加载 Cursor MCP 面板 — `practera` 服务器将出现。
不需要单独的服务器进程。Cursor 通过 stdio 自动启动 MCP 服务器。
## 传输
### stdio（Cursor 本地 — 推荐）
Cursor 将服务器作为子进程启动。不需要单独的 `npm run dev`。
```bash
# 用于手动测试/调试
npm run dev:stdio
```
### SSE（远程/共享）
具有服务器发送事件的 HTTP 服务器 — 在多个客户端共享一个实例时使用。
```bash
npm run dev # → http://localhost:3000/sse
```
将 MCP 客户端连接到 `http://localhost:3000/sse`。
## Cursor 配置
在您的存储库中创建 `.cursor/mcp.json`（或将其添加到 `~/.cursor/mcp.json` 以适用于所有工作区）：
```json
{
"mcpServers": {
"practera": {
"command": "node",
"args": [
"/absolute/path/to/practera-mcp-server/dist/stdio.js"
],
"env": {
"PRACTERA_REGION": "local",
"AUTH_EMAIL": "your@email.com",
"GRAPHQL_URL": "http://localhost:8000",
"WORKSPACE_ROOT": "/absolute/path/to/practera-workspace"
}
}
}
}
```
> 在源代码更改后，在 `practera-mcp-server` 中运行 `npm run build` 以重建 `dist/stdio.js`。
对于生产区域，省略 `AUTH_EMAIL`/`GRAPHQL_URL` 并在每个工具调用中传递 `apikey`。
## 身份验证
### API 密钥（生产）
在每个工具调用中传递 `apikey`。密钥作为 `apikey` HTTP 头转发到 GraphQL API。
### devLogin（本地/阶段）
省略 `apikey` 并设置 `AUTH_EMAIL`（或每个工具调用传递 `email`）。服务器调用 `devLogin` GraphQL 突变以自动获取 JWT。仅适用于 `region=local` 或 `region=stage`。
## 可用工具
### 通用/只读
| 工具 | 描述 |
|------|-------------|
| `mcp_practera_get_project` | 完整的项目树：里程碑、活动、任务 |
| `mcp_practera_get_assessment` | 具有问题和答案选择的评估详细信息 |
| `mcp_practera_search_project_briefs` | 按技能关键词搜索本地简介目录 |
### 作者（需要管理员/协调员角色）
| 工具 | GraphQL 操作 | 描述 |
|------|------------------|-------------|
| `create_experience` | `createExperience` | 在机构内创建新程序 |
| `create_milestone` | `createMilestone` | 向体验添加里程碑 |
| `create_activity` | `createActivity` | 向里程碑添加活动 |
| `create_assessment` | `createAssessment` | 在活动上创建评估 |
| `add_question` | `createAssessmentQuestion` | 向评估添加问题 |
| `add_task_to_activity` | `addTaskToActivity` | 向活动添加任务（资源/链接） |
| `enroll_user` | `enrollUser` | 在体验中注册用户 |
| `import_experience` | `importExperienceData` | 从 JSON 导出批量导入体验内容 |
| `export_experience` | `exportExperience` | 将体验结构导出为 JSON |
### 学生（学习者）
| 工具 | GraphQL 操作 | 描述 |
|------|------------------|-------------|
| `list_experiences` | `experiences` | 列出当前用户的所有体验 |
| `get_milestones` | `project.milestones` | 获取项目的里程碑和活动 |
| `get_tasks` | `tasks(activityId:)` | 获取活动的任务 |
| `submit_assessment` | `submitAssessment` | 提交评估 |
| `get_feedback` | `submission(id:)` | 获取提交详情，包括评审反馈 |
### 评审者
| 工具 | GraphQL 操作 | 描述 |
|------|------------------|-------------|
| `list_pending_reviews` | `reviews(status: "pending")` | 列出待评审的评估 |
| `submit_review` | `submitReview` | 提交已完成的评审 |
### 测试
| 工具 | 描述 |
|------|-------------|
| `run_tests` | 在任何普泰拉存储库中运行测试套件 — 调用 npm/cargo/docker |
#### `run_tests` 参数
| 参数 | 必需 | 描述 |
|-----------|----------|-------------|
| `repo` | 是 | 哪个存储库：`core-graphql-api`、`login-api`、`app-v2`、`practera`、`practera-mcp-server`、`practera-devops-center` |
| `suite` | 是 | 哪个套件（参见下表） |
| `pattern` | 否 | 测试文件/名称过滤器（作为 `--testPathPattern` 传递给 Jest 目标） |
| `workspaceRoot` | 否 | 工作区根目录的绝对路径。默认为 `WORKSPACE_ROOT` 环境变量。 |
#### 可用测试套件
| 存储库 | 套件 | 命令 |
|------|-------|---------|
| `core-graphql-api` | `unit` | `npm test`（Jest，带覆盖率） |
| `core-graphql-api` | `integration` | `npm run test:integration` |
| `core-graphql-api` | `parity` | `npm run test:parity` |
| `login-api` | `unit` | `npx vitest run tests/unit` |
| `login-api` | `integration` | `npx vitest run tests/integration` |
| `login-api` | `full` | `npm run test:coverage` |
| `app-v2` | `unit` | `npm test -- --watch=false` |
| `practera` | `phpunit` | `docker exec practera-core ./vendor/bin/phpunit` |
| `practera-mcp-server` | `typecheck` | `npm run typecheck` |
| `practera-devops-center` | `cargo` | `cargo test` |
## MCP 资源
| 资源 URI | 描述 |
|-------------|-------------|
| `practera://project/current` | 当前项目数据（GraphQL） |
| `practera://assessments/{assessmentId}` | 按 ID 获取评估 |
| `practera://briefs/{briefId}` | 来自本地目录的项目简介 |
## MCP 提示
| 提示 | 目的 |
|--------|---------|
| `project-analysis` | 分析项目结构和学习设计质量 |
| `assessment-analysis` | 评估评估结构和问题质量 |
| `skill-brief-selection` | 从目录中查找与技能匹配的简介 |
| `complex-brief-finder` | 按技能、复杂性和时间范围匹配简介 |
## 环境变量
| 变量 | 描述 |
|----------|-------------|
| `PORT` | HTTP 端口（默认 3000 开发/80 生产） |
| `NODE_ENV` | 环境（`development`、`production`） |
| `GRAPHQL_URL` | 重写本地 GraphQL 端点 |
| `PRACTERA_REGION` | 默认区域：`local`、`stage`、`usa`、`aus`、`euk` |
| `AUTH_EMAIL` | 用于 devLogin 的默认电子邮件（本地/阶段） |
| `WORKSPACE_ROOT` | 工作区根目录的绝对路径 — 由 `run_tests` 使用 |
## GraphQL 区域
| 区域 | 端点 |
|--------|---------|
| `local` | `http://localhost:8000`（或 `GRAPHQL_URL`） |
| `stage` | `https://core-graphql-api.p2-stage.practera.com/` |
| `usa` | `https://core-graphql-api.usa.practera.com/` |
| `aus` | `https://core-graphql-api.aus.practera.com/` |
| `euk` | `https://core-graphql-api.euk.practera.com/` |
## 构建和部署
```bash
# 构建
npm run build # 编译 TS + 复制 src/data → dist/
# 运行 SSE 服务器（编译）
npm start
# 运行 stdio（编译 — 在生产 Cursor 配置中使用）
npm run start:stdio
```
### AWS App Runner
`apprunner.yaml` 配置了一个 App Runner 服务，在 80 端口运行 SSE 服务器。
### AWS Lambda（过时）
`serverless.yml` 存在，但 Lambda 处理程序导出当前未连接。使用 App Runner 进行生产部署。
## 路线图
- [x] GraphQL 读取访问（项目、评估）
- [x] 作者 CRUD 工具（创建体验、里程碑、活动、评估、问题、任务、注册）
- [x] 体验 JSON 导入/导出
- [x] 学生工具（列表、提交、反馈）
- [x] 评审者工具（列表待处理、提交评审）
- [x] 项目简介搜索（5400+ 简介，基于技能）
- [x] 用于 Cursor 集成的 stdio 传输
- [x] `run_tests` 工具，用于跨存储库测试执行
- [ ] 指标 API（从 `calculateMetrics` 生成 LLM 可读报告）
- [ ] OAuth 2.1（当前已搭建，但未激活）
- [ ] 将身份验证上下文传递到 MCP 资源
- [ ] `assign_reviewer`、`handle_review` 工具，用于评审者工作流程管理
- [ ] 媒体资产生成
## 许可证
MIT
