Practera MCP Server

Practera MCP 服务

一个 MCP（模型上下文协议）服务，可让 AI Agent 直接访问 Practera 的 GraphQL API 和本地项目简介数据。连接 Cursor、Claude Desktop 或任何 MCP 客户端，即可在 Practera 单体仓库中编写学习项目、管理评估、以学习者身份提交作业、开展评审并运行测试套件。

为什么选择 Practera MCP？

借助此 MCP 服务，Agent 可以：

• 分析并重构现有项目，以适应不同受众或年级
• 自动生成评估蓝图并创建问题
• 在不同机构或 LMS 数据格式之间导入/导出项目
• 提交评估并管理评审工作流
• 按技能搜索包含 5400 多个体验式学习项目简介的资料库
• 直接通过 Cursor 在所有 Practera 仓库中运行测试套件

快速开始（Cursor — 本地开发）

1. 将此仓库克隆到其他 Practera 仓库旁边。
2. 安装依赖：npm install
3. 在任意 Practera 仓库中添加 .cursor/mcp.json（参见Cursor 配置）。
4. 重新加载 Cursor MCP 面板 — practera 服务将会出现。

无需单独启动服务进程。Cursor 会自动通过 stdio 启动 MCP 服务。

传输方式

stdio（Cursor 本地 — 推荐）

Cursor 会将服务作为子进程启动。无需单独运行 npm run dev。

# For manual testing / debugging
npm run dev:stdio

SSE（远程 / 共享）

通过 Server-Sent Events 提供的 HTTP 服务 — 适用于多个客户端共享同一实例的情况。

npm run dev        # → http://localhost:3000/sse

将 MCP 客户端连接到 http://localhost:3000/sse。

Cursor 配置

在仓库中创建 .cursor/mcp.json（或添加到 ~/.cursor/mcp.json，以应用于所有工作区）：

{
  "mcpServers": {
    "practera": {
      "command": "node",
      "args": [
        "/absolute/path/to/practera-mcp-server/dist/stdio.js"
      ],
      "env": {
        "PRACTERA_REGION": "local",
        "AUTH_EMAIL": "[email protected]",
        "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 Key（生产环境）

在每次工具调用中传入 apikey。此密钥会作为 apikey HTTP 标头转发到 GraphQL API。

devLogin（仅限本地/预发布环境）

省略 apikey 并设置 AUTH_EMAIL（或在每次工具调用中传入 email）。服务会调用 devLogin GraphQL mutation 自动获取 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	在任意 Practera 仓库中运行测试套件 — 调用 npm/cargo/docker

run_tests 参数

参数	必填	描述
repo	是	仓库名称：core-graphql-api、login-api、app-v2、practera、practera-mcp-server、practera-devops-center
suite	是	测试套件（见下表）
pattern	否	测试文件/名称筛选条件（对于 Jest 目标，会作为 --testPathPattern 传入）
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 的默认邮箱（local/stage）
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/

构建和部署

# Build
npm run build       # compiles TS + copies src/data → dist/

# Run SSE server (compiled)
npm start

# Run stdio (compiled — use in production Cursor config)
npm run start:stdio

AWS App Runner

apprunner.yaml 配置了一个在端口 80 上运行 SSE 服务的 App Runner 服务。

AWS Lambda（已过时）

serverless.yml 文件仍然存在，但目前尚未接通 Lambda 处理程序导出。生产环境部署请使用 App Runner。

路线图

• GraphQL 读取访问权限（项目、评估）
• 作者 CRUD 工具（创建体验、里程碑、活动、评估、问题、任务、注册）
• 导入/导出体验 JSON
• 学生工具（列表、提交、反馈）
• 评审者工具（列出待处理项、提交评审）
• 项目简介搜索（5400+ 份简介，基于技能）
• 用于 Cursor 集成的 stdio 传输
• 用于跨仓库测试执行的 run_tests 工具
• Metrics API（根据 calculateMetrics 生成大模型可读的报告）
• OAuth 2.1（目前已搭建框架，但尚未启用）
• 在 MCP 资源中传递身份验证上下文
• 用于评审者工作流管理的 assign_reviewer、handle_review 工具
• 媒体资源生成

许可证

MIT