Ed Fi Data Standard MCP Server

面向人工智能助理的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

1. 在VS代码中安装Cline扩展
2. 在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

1. 确保您安装了GitHub Copilot和GitHub Copilot-Chat扩展

1. 创建或更新您的VS Code设置文件(.vscode/mcp.json 在您的工作区或全局设置中）：

   {
    "servers": {
     "ed-fi-sdk-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
       "ed-fi-sdk-mcp"
      ]
     }
    },
    "inputs": []
   }

1. 重新启动VS代码并使用 @ed-fi-data-standard 在GitHub Copilot Chat中访问Ed Fi数据标准工具

Visual Studio

1. 确保您已安装GitHub Copilot扩展
2. 请参阅中的说明 使用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规范的URL
• name （必填）：此自定义数据标准的描述性名称

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数据标准版本

示例工作流程

1. 首先列出可用版本：

使用 list_available_versions 查看所有支持的Ed Fi数据标准版本。

1. 选择版本或自定义URL：

- 使用 set_data_standard_version 使用标准Ed-Fi API的所需版本（例如“5.2”）。 - 使用 set_custom_data_standard_url 从自定义Ed-Fi实现加载。

1. 探索端点：

使用 search_endpoints 查找与您的需求相关的API端点（例如，搜索“学生”）。

1. 获取端点详细信息：

使用 get_endpoint_details 了解特定端点的请求/响应格式。

1. 探索数据模型：

使用 search_schemas 和 get_schema_details 了解数据结构。

1. 🆕 可视化实体关系：

使用 generate_entity_diagram 以创建数据模型的可视化表示。

1. 🆕 分析实体域：

使用 get_entities_by_domain 了解实体是如何按功能区域组织的。

1. 🆕 导出图表：

使用 export_diagram_as_text 保存图表以供记录或进一步分析。

自定义Ed-Fi实例示例

如果您正在使用自定义Ed-Fi实现，则可以直接加载规范：

1. 使用set_custom_data_standard_url：

- url: "https://your-ed-fi.org/api/metadata/data/v3/resources/swagger.json" - name: "My Custom Ed-Fi Instance"

1. 继续正常的工作流程（search_endpoints等）

可视化工作流示例

对于使用Ed Fi模式的数据架构师：

1. 加载规格：

   set_data_standard_version("5.2")

1. 探索域结构：

   get_entities_by_domain()

1. 生成以学生为中心的图表：

   generate_entity_diagram({
     "format": "mermaid",
     "filterDomains": ["student", "school"],
     "maxEntities": 15
   })

1. 检查具体关系：

   list_entity_relationships({
     "entityName": "edfi_student"
   })

1. 导出文件：

   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版获得许可-请参阅 许可证 文件以获取详细信息。