面向人工智能助理的Ed Fi软件开发工具包
在开发与Ed Fi API交互的客户端应用程序时与AI助手一起使用的工具。
\[！注意\] 目前，只有一个工具可用：MCP服务器。鉴于这是关于信息发现，而不是数据访问，MCP可能不是正确的选择。我们还将探索将CLI工具和/或技能用于类似目的。
特性
- 版本选择：从Ed Fi数据标准版本4.0、5.0、5.1或5.2中选择
- 自定义URL支持：为自定义Ed-Fi数据标准实例配置替代URL
- OpenAPI集成：自动从Ed Fi API获取和解析OpenAPI规范
- 智能高速缓存：在本地缓存OpenAPI规范，以减少网络请求并缩短响应时间
- 端点发现：搜索和探索可用的API端点
- 模式探索：浏览和理解数据模型和模式
- 详细文件：获取有关端点和数据结构的全面信息
- 🆕 架构可视化：生成多种格式的实体关系图（Mermaid、PlantUML、Graphviz）
- 🆕 交互式实体分析探索核心实体（学生、学校、评估等）之间的关系
- 🆕 域名筛选：按实体类型或域区域筛选图表
- 🆕 多种导出格式：将图表导出为文本，以便在各种可视化工具中使用
- 🆕 及时记录：通过人工智能提示访问全面的指南和最佳实践
文件和提示
MCP服务器包括内置的提示模板，提供有关使用Ed-Fi API的详细指导：
- ed-fi认证指南：使用代码示例完成OAuth 2.0身份验证指南
- ed-fiapi快速入门：常见API操作（GET、POST、PUT、DELETE）的快速入门指南
- ed-fi数据验证：数据验证策略和错误处理技术
这些提示可以通过任何兼容MCP的AI助手访问，并为Ed-Fi开发任务提供上下文帮助。
有关使用此服务器的更多信息，请参阅：
AI助手集成
\[！警告\] 这些安装说明尚未准备好使用。 1. 由Copilot编写，除VS代码说明外未经验证。 1. 它们只会工作一次 ed-fi-sdk-mcp 已发布到npmjs.com。此MCP服务器可以与流行的AI编码助手集成，在开发过程中提供Ed-Fi数据标准上下文。
克劳德桌面
将以下内容添加到您的Claude Desktop配置文件中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"ed-fi-data-standard": {
"command": "npx",
"args": ["ed-fi-sdk-mcp"],
"env": {}
}
}
}VS代码与Cline
- 在VS代码中安装Cline扩展
- 在Cline的设置中配置MCP服务器：
- 命令： npx ed-fi-sdk-mcp - 运输：stdio
Continue.dev
将以下内容添加到“继续”配置中：
{
"mcp": {
"servers": {
"ed-fi-data-standard": {
"command": "npx",
"args": ["ed-fi-sdk-mcp"]
}
}
}
}光标
在Cursor的MCP设置中配置MCP服务器：
- 服务器名称：ed-fi数据标准
- 命令：
npx ed-fi-sdk-mcp
GitHub Copilot
VS Code
- 确保您安装了GitHub Copilot和GitHub Copilot-Chat扩展
- 创建或更新您的VS Code设置文件(
.vscode/mcp.json在您的工作区或全局设置中）：
{
"servers": {
"ed-fi-sdk-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"ed-fi-sdk-mcp"
]
}
},
"inputs": []
}- 重新启动VS代码并使用
@ed-fi-data-standard在GitHub Copilot Chat中访问Ed Fi数据标准工具
Visual Studio
- 确保您已安装GitHub Copilot扩展
- 请参阅中的说明 使用MCP服务器.
自定义安装
如果您已在全局或本地安装了该软件包，您还可以使用：
# Global installation
npm install -g ed-fi-sdk-mcp
# Then reference it directly
ed-fi-mcp-server可用工具
MCP服务器提供以下工具：
1. list_available_versions
列出所有支持的Ed-Fi数据标准版本及其相应的OpenAPI规范URL。
2. set_data_standard_version
加载特定Ed-Fi数据标准版本的OpenAPI规范。
参数：
version（必填）：“4.0”、“5.0”、“5.1”或“5.2”中的一个
3. set_custom_data_standard_url
从自定义URL加载OpenAPI规范（例如，用于自定义Ed-Fi实现）。
参数：
url（必填）：自定义OpenAPI规范的URLname（必填）：此自定义数据标准的描述性名称
4. search_endpoints
搜索与查询项匹配的API终结点。
参数：
query（必填）：搜索词（例如，“学生”、“学校”、“评估”）
5. get_endpoint_details
获取有关特定API终结点的详细信息。
参数：
path（必需）：API端点路径（例如“/ed-fi/students”）method（可选）：HTTP方法（默认：“GET”）
6. search_schemas
搜索与查询词匹配的数据模型/模式。
参数：
query（必填）：搜索词（例如，“学生”、“学校”、“评估”）
7. get_schema_details
获取特定数据模型/架构的详细信息。
参数：
schemaName（必填）：架构的名称
🎨 架构可视化工具
8. generate_entity_diagram
根据OpenAPI规范生成实体关系图。
参数：
format（可选）：图表格式-“美人鱼”、“plantuml”或“graphviz”（默认：“美人鱼”）includeProperties（可选）：在图表中包含实体属性（默认值：true）includeDescriptions（可选）：包括实体描述（默认值：false）filterDomains（可选）：要过滤的域名数组（例如，\[“student”，“school”\]）maxEntities（可选）：要包含的最大实体数（默认值：20）
9. list_entity_relationships
列出当前规范中实体之间的关系。
参数：
entityName（可选）：仅显示特定实体的关系relationshipType（可选）：按关系类型筛选（“一对一”、“一对多”、“多对一”和“多对多”）
10. get_entities_by_domain
获取按域区域（学生、学校、员工、评估等）分组的实体。
参数：
domain（可选）：仅获取特定域的实体
11. export_diagram_as_text
将图表导出为可由各种可视化工具渲染的文本。
参数：
format（必填）：图表格式-“美人鱼”、“plantuml”或“graphviz”filename（可选）：用于保存图表文本的文件名filterDomains（可选）：按域区域筛选实体maxEntities（可选）：要包含的最大实体数（默认值：15）
配置
MCP服务器支持以下环境变量进行配置：
环境变量
ED_FI_CUSTOM_BASE_URL（可选）：为Ed-Fi API实例设置自定义基本URL。设置后，标准版本URL将被重写以使用此基，而不是https://api.ed-fi.org.
例子： ED_FI_CUSTOM_BASE_URL=https://my-ed-fi-instance.org/v7.3
ED_FI_CACHE_DIR（可选）：指定用于缓存OpenAPI规范的自定义目录。默认为系统临时目录。
例子： ED_FI_CACHE_DIR=/home/user/.cache/ed-fi-mcp
自定义配置的示例用法
# Using a custom Ed-Fi instance
ED_FI_CUSTOM_BASE_URL=https://my-ed-fi.org/v7.3 npx ed-fi-sdk-mcp
# Custom cache directory
ED_FI_CACHE_DIR=/opt/cache/ed-fi npx ed-fi-sdk-mcp
# Both options together
ED_FI_CUSTOM_BASE_URL=https://my-ed-fi.org/v7.3 ED_FI_CACHE_DIR=/opt/cache/ed-fi npx ed-fi-sdk-mcp支持的Ed Fi数据标准版本
| 版本 | OpenAPI规范URL |
|---|---|
| 4.0 | |
| 5.0 | |
| 5.1 | |
| 5.2 |
示例工作流程
- 首先列出可用版本：
使用 list_available_versions 查看所有支持的Ed Fi数据标准版本。
- 选择版本或自定义URL：
- 使用 set_data_standard_version 使用标准Ed-Fi API的所需版本（例如“5.2”）。 - 使用 set_custom_data_standard_url 从自定义Ed-Fi实现加载。
- 探索端点：
使用 search_endpoints 查找与您的需求相关的API端点（例如，搜索“学生”）。
- 获取端点详细信息：
使用 get_endpoint_details 了解特定端点的请求/响应格式。
- 探索数据模型：
使用 search_schemas 和 get_schema_details 了解数据结构。
- 🆕 可视化实体关系：
使用 generate_entity_diagram 以创建数据模型的可视化表示。
- 🆕 分析实体域：
使用 get_entities_by_domain 了解实体是如何按功能区域组织的。
- 🆕 导出图表：
使用 export_diagram_as_text 保存图表以供记录或进一步分析。
自定义Ed-Fi实例示例
如果您正在使用自定义Ed-Fi实现，则可以直接加载规范：
- 使用set_custom_data_standard_url：
- url: "https://your-ed-fi.org/api/metadata/data/v3/resources/swagger.json" - name: "My Custom Ed-Fi Instance"
- 继续正常的工作流程（search_endpoints等）
可视化工作流示例
对于使用Ed Fi模式的数据架构师：
- 加载规格：
set_data_standard_version("5.2")- 探索域结构：
get_entities_by_domain()- 生成以学生为中心的图表：
generate_entity_diagram({
"format": "mermaid",
"filterDomains": ["student", "school"],
"maxEntities": 15
})- 检查具体关系：
list_entity_relationships({
"entityName": "edfi_student"
})- 导出文件：
export_diagram_as_text({
"format": "plantuml",
"filename": "student-entities.puml",
"filterDomains": ["student"]
})生成的图表可用于：
- GitHub/GitLab文档（Mermaid）
- 技术文档（PlantUML）
- 系统架构文档（Graphviz）
- 演示材料（导出为图像）
许可证
版权所有（c）2025，Ed Fi Alliance，LLC。保留所有权利。
此项目根据Apache许可证2.0版获得许可-请参阅 许可证 文件以获取详细信息。