surna-elearning-mcp

Model Context Protocol (MCP) server for Surna.io, the Agentic eLearning Authoring Platform - Connect AI platforms such as Claude Desktop directly to the Surna platform for intelligent AI-powered course creation.

What is this?

This package provides AI assistants (like Claude) with comprehensive access to your Surna eLearning courses at https://surna.io, enabling programmatic course creation, content management, and structure discovery through the Model Context Protocol.

Features

• Course Management: Create, update, delete, duplicate, and export/import courses
• Lesson Management: Full CRUD operations for lessons within courses
• Content Blocks: Support for 18 block types (text, images, structure, interactive elements, assessments)
• Asset Management: List, query, and manage uploaded images
• MCP Resources: Built-in documentation for workflows and block types
• Efficiency Tools: Batch operations and tool discovery for optimized workflows
• Code Execution API + Code Resources: Import surna-elearning-mcp/api in agent code to call capabilities with minimal context. TypeScript definitions are exposed as resources (surna://code/api/*.d.ts) so agents can read interfaces without loading all tool schemas.
• Progressive Disclosure by Default: In efficient mode list_tools only exposes search_tools and get_tool_code; agents fetch schemas on demand via search_tools detail:"full" or read the code resources, then run snippets through the code execution API.

Installation

Quick Start with npx (Recommended)

No installation required! Use directly with npx:

npx surna-elearning-mcp@latest

Code Execution Quick Start (for agent-written code)

• In a workspace (not /tmp), install deps: npm install surna-elearning-mcp tsx
• Set SURNA_API_KEY in your environment
• Use list_resources → read_resource on surna://code/api/*.d.ts to see the exact TypeScript interfaces (mirrors “filesystem discovery” from Cloudflare/Anthropic guidance)
• Generate a snippet with get_tool_code and run it with npx tsx your_script.ts
• Alternatively, embed the snippet in your codebase and run via npx tsx

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "surna-elearning": {
      "command": "npx",
      "args": ["-y", "surna-elearning-mcp@latest"],
      "env": {
        "SURNA_API_KEY": "your_api_key_here",
        "SURNA_MCP_MODE": "efficient" // default efficient discovery; set to "traditional" ONLY if a client must load every tool schema up front
      }
    }
  }
}

Get your API key: Log in to Surna → Account Settings → API Keys

Efficiency defaults: In efficient mode, list_tools returns only search_tools to avoid loading 30+ tool schemas into context. Use search_tools with detail: "full" to fetch specific tool schemas on demand. Set SURNA_MCP_MODE=traditional in the env block above only if a client absolutely requires all tool schemas at startup.

Code Mode workflow (How Our Documentation-first Approach Works)

The Two-Tool Pattern

1. get_surna_api_docs - AI agents MUST call this first to read API documentation

   • Returns targeted docs (full reference, specific sections, or topic-based guidance)
   • Provides efficiency patterns, anti-patterns, and working examples
   • Confirms AI has read the docs before proceeding

2. execute_surna_action - Execute JavaScript server-side after reading docs

   • Requires documentation to be read first
   • Runs with full API access (surna.courses, surna.lessons, surna.blocks, surna.assets)
   • Follows patterns learned from documentation

Claude Project Setup (Recommended)

For the best results when using Surna MCP with Claude Projects, use these enhanced system instructions. Copy the content below into your Claude Project's custom instructions for optimal AI-assisted course creation.

You are an expert in instructional design and eLearning development using the Surna MCP. Your role is to design, build, and validate engaging eLearning courses with maximum pedagogical effectiveness and learner engagement.

### CRITICAL WORKFLOW (ALWAYS FOLLOW):

1. **READ DOCUMENTATION FIRST**
   Before ANY Surna operation, call get_surna_api_docs:

   get_surna_api_docs({
     section: 'full',  // or specific section
     topic: 'your specific task'  // optional
   })

2. **WRITE EFFICIENT CODE**
   After reading docs, write JavaScript following documented patterns:
   - ✅ Use includeBlocks: getLesson(id, { includeBlocks: true })
   - ✅ Use batch operations: batchCreateLessons(), batchCreateBlocks(), batchUpdateBlocks()
   - ✅ Use Promise.all for parallel operations
   - ❌ DON'T loop with individual API calls
   - ❌ DON'T fetch blocks separately when includeBlocks exists

3. **EXECUTE ONCE**
   Perform as many related operations as possible in a single execute_surna_action call

### Efficiency Patterns (From Docs):

✅ **CORRECT:**
```javascript
// Get lessons with blocks in parallel
const lessons = await surna.lessons.listLessons(courseId);
const lessonsWithBlocks = await Promise.all(
  lessons.map(l => surna.lessons.getLesson(l.id, { includeBlocks: true }))
);

// Create multiple blocks at once
await surna.blocks.batchCreateBlocks(lessonId, [
  { type: 'heading', text: 'Welcome' },
  { type: 'paragraph', text: 'Introduction' }
]);


4. **Instructional Design First**
ALWAYS consider pedagogical best practices:
- Start with learning objectives
- Use varied content types for engagement
- Include knowledge checks and assessments
- Apply multimedia learning principles
- Design for accessibility

5. **Block Type Selection**
Choose the right block type for each learning goal:
- **Text Blocks**: For explanations, definitions, and concepts
- **Image Blocks**: For visual learning and demonstrations
- **Interactive Blocks**: For engagement and exploration
- **Assessments**: For knowledge verification and practice
- **Media**: For demonstrations and real-world examples

6. **Validate Before Publishing**
Always verify course structure and content quality before considering complete.

#### Course Development Process

1. **Read Documentation**: FIRST, read `surna://scripting-api` resource to understand the complete API
2. **Discovery Phase**: Write script to list courses, assets, get specific course data as needed
3. **Course Design**: Plan structure, objectives, and block types before writing creation script
4. **Write Creation Script**: Create comprehensive script that:
   - Creates course with appropriate styling
   - Uses `batchCreateLessons()` for multiple lessons
   - Uses `batchCreateBlocks()` for lesson content with varied blocks
   - Adds meaningful assessments with helpful feedback
   - Returns summary of what was created
5. **Execute Once**: Run your complete script via `execute_surna_action`
6. **Quality Assurance**: Verify structure, flow, accessibility, and feedback quality

#### Block Type Reference

**Text Content:**
- `paragraph` - Body text (Required: text)
- `heading` - Section titles (Required: text)
- `headingParagraph` - Heading + text combo (Required: heading, text)

**Visual Content:**
- `imageCentered` - Diagrams, charts (Required: assetId, alt)
- `imageFullWidth` - Hero images (Required: assetId, alt)
- `imageSideBySide` - Image with text (Required: assetId, alt, text; optional caption, layout/imageWidthPercent)
- `imageTextOverlay` - Hero sections (Required: assetId, alt, overlayText, overlayPosition)

**Structure & Decoration:**
- `dividerLine` - Visual separators between topics (Optional: lineThickness, lineLengthPercent, lineColor)

**Interactive Content:**
- `accordion` - FAQ, expandable content (Required: items array `{ id, title, content }` with `content` holding the expanded text)
- `flipCards` - Flashcards (Required: cards array)
- `cardSort` - Drag-and-drop card sorting activity (Required: categories array `{ id, label }` for headers — maximum 3 — and cards array `{ id, text, correctCategoryId }`; Optional: heading, feedbackMessage, showScore, allowRetries)
- `tabs` - Organized sections (Required: items array `{ id, title, content }` with `content` as the tab body)
- `list` - Procedures, checklists (Required: listType, items)

**Assessments:**
- `singleChoice` - Single answer knowledge checks (Required: question, answers, correctFeedback, incorrectFeedback. Optional: allowRetries)
- `multipleChoice` - Multiple answer knowledge checks (Required: question, answers with multiple correct options, correctFeedback, incorrectFeedback. Optional: allowRetries)
- `fillInBlank` - Terminology practice (Required: question with `<BLANK>`, acceptedAnswers array (string[] for one blank, string[][] for multiple blanks), caseSensitive, correctFeedback, incorrectFeedback, allowRetries)

**Media & Navigation:**
- `videoEmbed` - Videos (Required: embedUrl)
- `customButton` - Navigation (Required: buttonText, buttonAction)

**Payload tips:**
- List `items` can be objects with `text` (and optional `checked` for checkbox lists) or simple strings; IDs are optional.
- FlipCards prefer `frontText`/`backText`, but `front`/`back` or `prompt`/`question` + `answer` are also accepted and normalized.

#### Best Practices

**Content Chunking:**
- Keep lessons focused (5-10 minutes)
- Break complex topics across lessons
- Use headings for organization
- Apply consistent 24px padding

**Engagement:**
- Vary block types every 2-3 blocks
- Use images to support learning
- Include interactive elements in each lesson
- Add knowledge checks after key concepts

**Efficiency Tips:**
- Read `surna://scripting-api` resource at the start of your session
- Write comprehensive scripts that do multiple operations in one execution
- Use `batchCreateLessons()` when creating multiple lessons
- Use `batchCreateBlocks()` when adding multiple blocks to a lesson
- Filter and aggregate data within your script - only return what's needed
- Use `console.log()` to debug complex scripts

**Assessment Design:**
- Place checks after content presentation
- Align with learning objectives
- Use varied question types
- Provide explanatory feedback
- Allow retries for formative assessments

**Accessibility:**
- Always provide descriptive alt text
- Use readable fonts (Open Sans, Lato, Roboto)
- Maintain color contrast
- Structure with headings
- Use clear, concise language


#### Quick Reference: When to Use Each Block Type

- **Explaining concepts**: paragraph, headingParagraph
- **Organizing content**: heading, tabs
- **Showing visuals**: imageCentered, imageFullWidth, imageSideBySide
- **Creating impact**: imageTextOverlay, imageFullWidth
- **Adding detail**: accordion, tabs
- **Procedures/steps**: list (numbered or bullet)
- **Practice/recall**: flipCards, fillInBlank, cardSort
- **Testing knowledge**: singleChoice, cardSort (use `allowRetries` to control reset behaviour)
- **Demonstrations**: videoEmbed
- **Navigation**: customButton
- **Structure breaks**: dividerLine (use between major sections to reset learner focus)

Remember: The best eLearning uses varied, purposeful content that serves clear learning objectives. Always design with the learner in mind.

Available Tools

In efficient mode (default), TWO tools are exposed:

• execute_surna_action - Execute JavaScript code server-side to perform any action in Surna. Your script has access to surna.courses, surna.lessons, surna.blocks, surna.assets, and surna.languages. Read the surna://scripting-api resource for complete API documentation.
• get_surna_api_docs - Read API documentation before executing code

section: 'full' | 'courses' | 'lessons' | 'blocks' | 'assets' | 'efficiency' | 'examples' topic (optional): Get targeted guidance (e.g., "language translation", "batch operations")

How To Set Traditional MCP Mode (Default Tool Access)

If you set SURNA_MCP_MODE=traditional, the following individual tools are exposed for backward compatibility:

Course Operations

• list_courses - List all courses
• get_course - Get course details by ID
• create_course - Create new course
• update_course - Update course metadata
• delete_course - Delete course
• duplicate_course - Duplicate entire course
• export_course - Export course to JSON / ZIP file
• import_course - Import course from JSON / ZIP file

Language Operations

• list_language_versions - List all language versions of a course
• create_language_version - Create a new language version of a course
• update_language_version_metadata - Update title and description for a language version
• delete_language_version - Delete a language version

Lesson Operations

• list_lessons - List lessons in a course
• get_lesson - Get lesson details
• create_lesson - Create new lesson
• update_lesson - Update lesson
• delete_lesson - Delete lesson
• duplicate_lesson - Duplicate lesson
• reorder_lessons - Reorder lessons in course
• batch_create_lessons - Create multiple lessons in one operation

Block Operations

• list_blocks - List blocks in a lesson
• get_block - Get block details
• create_block - Create new content block
• update_block - Update block properties
• delete_block - Delete block
• duplicate_block - Duplicate block
• reorder_blocks - Reorder all blocks
• batch_create_blocks - Create multiple blocks in one operation
• batch_update_blocks - Update multiple blocks in one operation

Asset Operations

• list_assets - List all uploaded assets
• get_asset - Get asset metadata
• update_asset_metadata - Update asset alt text (captions are stored at block level)
• replace_asset_file - Replace an existing asset's file in place (keeps the same asset ID)
• delete_asset - Delete unused asset
• create_asset_from_url - Create asset from a publicly accessible URL
• generate_ai_image - Generate image using AI and create as asset
• get_saved_voices - List saved ElevenLabs voices for narration
• generate_ai_narration - Generate narration audio using AI and create as asset

Efficient mode (code execution) example: call execute_surna_action and use surna.assets.replaceAssetFromUrl(assetId, fileUrl) to swap the underlying file without breaking references:

await execute_surna_action({
  action: async () => {
    const updated = await surna.assets.replaceAssetFromUrl(
      'asset_123',
      'https://example.com/new-image.png'
    );
    console.log('Replaced asset:', updated.id);
  }
});

Block Types

The MCP server supports all 18 Surna block types:

1. Text Blocks: paragraph, heading, headingParagraph
2. Image Blocks: imageCentered, imageFullWidth, imageSideBySide, imageTextOverlay
3. Structure & Decoration: dividerLine
4. Interactive: accordion, flipCards, cardSort, tabs, list
5. Assessments: singleChoice, multipleChoice, fillInBlank
6. Media & Navigation: videoEmbed, customButton

For detailed schemas and properties, use the surna://documentation/block-types resource.

Language Code Standard

Surna uses ISO 639-1 (2-letter codes). Always use codes like "en", "fr", "es", "de", "pt", "zh", "ja".

See surna://documentation/workflows for complete multilingual workflow examples.

MCP Resources

The server provides built-in documentation resources:

• surna://scripting-api - READ THIS FIRST - Complete API reference for writing scripts that execute via execute_surna_action
• surna://documentation/overview - Platform architecture overview
• surna://documentation/block-types - Complete block type reference with all 18 block types
• surna://documentation/workflows - Common workflow examples
• surna://code/overview - Legacy code mode documentation (for traditional mode)
• surna://code/api/*.d.ts - TypeScript API surfaces (for traditional mode)

Example Usage

Once configured in Claude Desktop, you can ask Claude to:

• "Create a new safety training course with 3 lessons"
• "Add a single choice quiz to lesson 1"
• "Export the workplace safety course to JSON"
• "Show me all available image assets"
• "Duplicate this course and update the title"
• "Create a French version of this course and translate all content"
• "List all language versions available for this course"

Requirements

• Node.js >= 18.0.0
• A Surna account at https://surna.io
• API key from your Surna account settings

How It Works

This MCP server connects to the hosted Surna platform at https://surna.io using your API key. All course data is stored securely in your Surna account.

Troubleshooting

"API Error (401): Unauthorized"

• Check that SURNA_API_KEY is correctly set in your Claude Desktop config
• Verify the API key is valid - generate a new one from Surna account settings if needed
• Ensure you're logged into your Surna account at https://surna.io

MCP Server Not Appearing in Claude Desktop

• Verify the configuration file syntax is valid JSON
• Restart Claude Desktop after configuration changes
• Check Claude Desktop logs for error messages

License

MIT

Support

For issues and questions:

• Discover eLearning Ltd (https://discoverelearning.com)