Ed Fi SDK

OpenSSF Scorecard

Tools for use with AI Assistants when developing client applications that interact with Ed-Fi APIs.

[!NOTE] At this time, there is a single tool available: an MCP server. Given that is about information discovery, but not data access, MCP might not be the right choice. We will also explore use of CLI tools and/or Skills for similar purposes.

Features

• Version Selection: Choose from Ed-Fi Data Standard versions 4.0, 5.0, 5.1, or 5.2
• Custom URL Support: Configure alternative URLs for custom Ed-Fi Data Standard instances
• OpenAPI Integration: Automatically fetches and parses OpenAPI specifications from Ed-Fi APIs
• Intelligent Caching: Caches OpenAPI specs locally to reduce network requests and improve response times
• Endpoint Discovery: Search and explore available API endpoints
• Schema Exploration: Browse and understand data models and schemas
• Detailed Documentation: Get comprehensive information about endpoints and data structures
• 🆕 Schema Visualization: Generate entity relationship diagrams in multiple formats (Mermaid, PlantUML, Graphviz)
• 🆕 Interactive Entity Analysis: Explore relationships between core entities (students, schools, assessments, etc.)
• 🆕 Domain Filtering: Filter diagrams by entity type or domain area
• 🆕 Multiple Export Formats: Export diagrams as text for use in various visualization tools
• 🆕 Prompt Documentation: Access comprehensive guides and best practices through AI prompts

Documentation & Prompts

The MCP server includes built-in prompt templates that provide detailed guidance on working with Ed-Fi APIs:

• ed-fi-authentication-guide: Complete OAuth 2.0 authentication guide with code examples
• ed-fi-api-quickstart: Quick start guide for common API operations (GET, POST, PUT, DELETE)
• ed-fi-data-validation: Data validation strategies and error handling techniques

These prompts can be accessed through any MCP-compatible AI assistant and provide contextual help for Ed-Fi development tasks.

For more information on using this server, see:

• Local Usage
• Schema Visualization Guide
• Requirements

AI Assistant Integration

[!WARNING] These installation instructions are not ready for usage yet.

1. Written by Copilot and not verified, other than the VS Code instructions.
2. They will only work once ed-fi-sdk-mcp has been published to npmjs.com.

This MCP server can be integrated with popular AI coding assistants to provide Ed-Fi Data Standard context during development.

Claude Desktop

Add the following to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ed-fi-data-standard": {
      "command": "npx",
      "args": ["ed-fi-sdk-mcp"],
      "env": {}
    }
  }
}

VS Code with Cline

1. Install the Cline extension in VS Code
2. Configure the MCP server in Cline's settings:
   • Command: npx ed-fi-sdk-mcp
   • Transport: stdio

Continue.dev

Add the following to your Continue configuration:

{
  "mcp": {
    "servers": {
      "ed-fi-data-standard": {
        "command": "npx",
        "args": ["ed-fi-sdk-mcp"]
      }
    }
  }
}

Cursor

Configure the MCP server in Cursor's MCP settings:

• Server name: ed-fi-data-standard
• Command: npx ed-fi-sdk-mcp

GitHub Copilot

VS Code

1. Ensure you have the GitHub Copilot and GitHub Copilot Chat extensions installed

2. Create or update your VS Code settings file (.vscode/mcp.json in your workspace or global settings):

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

3. Restart VS Code and use @ed-fi-data-standard in GitHub Copilot Chat to access Ed-Fi Data Standard tools

Visual Studio

1. Ensure you have the GitHub Copilot extension installed
2. See instructions in Use MCP servers.

Custom Installation

If you've installed the package globally or locally, you can also use:

# Global installation
npm install -g ed-fi-sdk-mcp

# Then reference it directly
ed-fi-mcp-server

Available Tools

The MCP server provides the following tools:

1. list_available_versions

Lists all supported Ed-Fi Data Standard versions and their corresponding OpenAPI specification URLs.

2. set_data_standard_version

Loads the OpenAPI specification for a specific Ed-Fi Data Standard version.

Parameters:

• version (required): One of "4.0", "5.0", "5.1", or "5.2"

3. set_custom_data_standard_url

Loads the OpenAPI specification from a custom URL (e.g., for custom Ed-Fi implementations).

Parameters:

• url (required): The URL to the custom OpenAPI specification
• name (required): A descriptive name for this custom data standard

4. search_endpoints

Searches for API endpoints that match a query term.

Parameters:

• query (required): Search term (e.g., "student", "school", "assessment")

5. get_endpoint_details

Gets detailed information about a specific API endpoint.

Parameters:

• path (required): The API endpoint path (e.g., "/ed-fi/students")
• method (optional): HTTP method (default: "GET")

6. search_schemas

Searches for data models/schemas that match a query term.

Parameters:

• query (required): Search term (e.g., "Student", "School", "Assessment")

7. get_schema_details

Gets detailed information about a specific data model/schema.

Parameters:

• schemaName (required): The name of the schema

🎨 Schema Visualization Tools

8. generate_entity_diagram

Generate entity relationship diagrams from the OpenAPI specification.

Parameters:

• format (optional): Diagram format - "mermaid", "plantuml", or "graphviz" (default: "mermaid")
• includeProperties (optional): Include entity properties in diagram (default: true)
• includeDescriptions (optional): Include entity descriptions (default: false)
• filterDomains (optional): Array of domain names to filter by (e.g., ["student", "school"])
• maxEntities (optional): Maximum number of entities to include (default: 20)

9. list_entity_relationships

List relationships between entities in the current specification.

Parameters:

• entityName (optional): Show relationships for a specific entity only
• relationshipType (optional): Filter by relationship type ("one-to-one", "one-to-many", "many-to-one", "many-to-many")

10. get_entities_by_domain

Get entities grouped by domain areas (Student, School, Staff, Assessment, etc.).

Parameters:

• domain (optional): Get entities for a specific domain only

11. export_diagram_as_text

Export a diagram as text that can be rendered by various visualization tools.

Parameters:

• format (required): Diagram format - "mermaid", "plantuml", or "graphviz"
• filename (optional): Filename to save the diagram text
• filterDomains (optional): Filter entities by domain areas
• maxEntities (optional): Maximum number of entities to include (default: 15)

Configuration

The MCP server supports the following environment variables for configuration:

Environment Variables

• ED_FI_CUSTOM_BASE_URL (optional): Set a custom base URL for Ed-Fi API instances. When set, standard version URLs will be rewritten to use this base instead of https://api.ed-fi.org.

  Example: ED_FI_CUSTOM_BASE_URL=https://my-ed-fi-instance.org/v7.3

• ED_FI_CACHE_DIR (optional): Specify a custom directory for caching OpenAPI specifications. Defaults to the system temporary directory.

  Example: ED_FI_CACHE_DIR=/home/user/.cache/ed-fi-mcp

Example Usage with Custom Configuration

# 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

Supported Ed-Fi Data Standard Versions

Version	OpenAPI Specification URL
4.0	https://api.ed-fi.org/v6.2/api/metadata/data/v3/resources/swagger.json
5.0	https://api.ed-fi.org/v7.1/api/metadata/data/v3/resources/swagger.json
5.1	https://api.ed-fi.org/v7.2/api/metadata/data/v3/resources/swagger.json
5.2	https://api.ed-fi.org/v7.3/api/metadata/data/v3/resources/swagger.json

Example Workflow

1. Start by listing available versions: Use list_available_versions to see all supported Ed-Fi Data Standard versions.

2. Select a version or custom URL:

   • Use set_data_standard_version with your desired version (e.g., "5.2") for standard Ed-Fi API.
   • Use set_custom_data_standard_url to load from a custom Ed-Fi implementation.

3. Explore endpoints: Use search_endpoints to find API endpoints related to your needs (e.g., search for "student").

4. Get endpoint details: Use get_endpoint_details to learn about request/response formats for specific endpoints.

5. Explore data models: Use search_schemas and get_schema_details to understand the data structures.

6. 🆕 Visualize entity relationships: Use generate_entity_diagram to create visual representations of the data model.

7. 🆕 Analyze entity domains: Use get_entities_by_domain to understand how entities are organized by functional areas.

8. 🆕 Export diagrams: Use export_diagram_as_text to save diagrams for documentation or further analysis.

Custom Ed-Fi Instance Example

If you're working with a custom Ed-Fi implementation, you can load specifications directly:

1. Use set_custom_data_standard_url with:

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

2. Continue with normal workflow (search_endpoints, etc.)

Running against saved swagger.json files (no ODS/API required)

When the Data Standard / API combination you need isn't hosted on api.ed-fi.org — for example DS 4.0 served by API v7.3.2 — you can capture the swagger.json files from a one-time local install and share them. Others can then point the MCP server at the saved files without standing up their own ODS/API instance.

1. Place both swagger files in a directory:

   swagger/resources-swagger_ODS7.3.2_DS4.0.0.json
   swagger/descriptors-swagger_ODS7.3.2_DS4.0.0.json
   

2. Start a static file server in that directory and leave the terminal open while using the MCP server:

   cd swagger
   npx serve -p 8000
   

   Verify in a browser: http://localhost:8000/resources-swagger_ODS7.3.2_DS4.0.0.json should return JSON.

3. In an MCP-aware chat (Agent mode), call:

   set_custom_data_standard_url
     url:  http://localhost:8000/resources-swagger_ODS7.3.2_DS4.0.0.json
     name: Ed-Fi 7.3.2 / DS 4.0 (from JSON file)
   

4. Use the normal tools — search_endpoints, get_schema_details edFi_student, generate_entity_diagram, etc.

[!NOTE] The MCP server fetches the spec over HTTP, so a file:// path or raw filesystem path will not work — the static server step is required. To switch from resources to descriptors, call set_custom_data_standard_url again with the other file's URL; the previous spec is replaced.

Visualization Workflow Example

For data architects working with Ed-Fi schemas:

1. Load the specification:

   set_data_standard_version("5.2")
   

2. Explore domain structure:

   get_entities_by_domain()
   

3. Generate a student-focused diagram:

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

4. Examine specific relationships:

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

5. Export for documentation:

   export_diagram_as_text({
     "format": "plantuml",
     "filename": "student-entities.puml",
     "filterDomains": ["student"]
   })
   

The generated diagrams can be used in:

• GitHub/GitLab documentation (Mermaid)
• Technical documentation (PlantUML)
• System architecture documents (Graphviz)
• Presentation materials (exported as images)

License

Copyright (c) 2025, Ed-Fi Alliance, LLC. All rights reserved.

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.