OA-Y MCP Service

MCP for managing courses via HTTP API at oa-y.com.

---

Integration as MCP Server

This service supports two transport protocols for MCP integration: STDIO and StreamableHTTP.

Mode 1: STDIO (Local/Command Line)

For local integration with Cursor, Claude Desktop, or other MCP clients:

{
  "mcpServers": {
    "oa-y-mcp-service": {
      "command": "npx",
      "args": ["-y", "github:AdminRHS/oa-y-mcp-service"],
      "env": {
        "APP_ENV": "prod",
        "API_TOKEN": "your_token",
        "API_TOKEN_LIBS": "your_libs_token"
      }
    }
  }
}

Mode 2: StreamableHTTP (Remote/HTTP)

For remote integration via StreamableHTTP:

{
  "mcpServers": {
    "oa-y-remote": {
      "url": "http://your-server:3000/mcp?API_TOKEN=your_token&API_TOKEN_LIBS=your_libs_token&APP_ENV=prod"
    }
  }
}

When to use each transport:

• STDIO (stdin/stdout, Desktop‑first): Ideal for Desktop apps and local IDE integrations (Cursor, Claude Desktop).
• StreamableHTTP (/mcp, Browser/Agents‑first): Best for AI agents and browser/cloud clients (including proxies/tunnels).

API_TOKEN

How to get your API_TOKEN:

1. Go to https://oa-y.com and log in as an admin.
2. Open the Admin Panel and go to the API Tokens tab.
3. Click Create Token, enter a name, and create the token.
4. Copy the generated token and use it as the API_TOKEN environment variable.

API_TOKEN_LIBS

How to get your API_TOKEN_LIBS:

1. Go to https://libs.anyemp.com and log in as an admin.
2. Open the Admin Panel and go to the API Tokens tab.
3. Click Create Token, enter a name (e.g., "Libs API"), and create the token.
4. Copy the generated token and use it as the API_TOKEN_LIBS environment variable.

APP_ENV

Environment setting:

• prod - Production environment (default, uses oa-y.com and libs.anyemp.com)
• dev - Development/testing (uses lrn.oa-y.com and libdev.anyemp.com)

---

Available MCP Tools

This section describes all available tools for managing courses, lessons, modules, tests, and professions.

Course Management

• get_courses — get a list of courses (with filters and pagination, supports profession filtering)
• get_course — get a course by id
• create_course — create a course (requires module IDs from create_module)
• update_course — update a course (requires module IDs from create_module)

Lesson Management

• get_lessons — get a list of lessons
• get_lesson — get a lesson by id
• create_lesson — create a lesson (use this first to get lesson IDs)
• update_lesson — update a lesson

Module Management

• get_modules — get a list of modules
• get_module — get a module by id
• create_module — create a module (requires lesson IDs from create_lesson)
• update_module — update a module (requires lesson IDs from create_lesson)

Test Management

• get_tests — get a list of tests
• get_test — get a test by id
• create_test — create a test (requires lesson ID from create_lesson, tests are attached to lessons)
• update_test — update a test (requires lesson ID from create_lesson, tests are attached to lessons)

Profession Management

• get_professions — get all professions (returns array with name and ID)
• get_skills — get all skills (returns array with name and ID)
• get_tools — get all tools (returns array with name and ID)

Creation Order

IMPORTANT: Follow the correct sequential creation order for courses, modules, lessons, and tests.

Sequential workflow:

1. CREATE COURSE:

   • Use create_course to create the course structure
   • Can start with empty modules array, will be updated later

2. CREATE MODULE (at least one module required):

   • Use create_module to create a module
   • Can start with empty lessons array
   • Get module ID from the response

3. CREATE FIRST LESSON (at least one lesson per module required):

   • Use create_lesson to create a lesson
   • Get lesson ID from the response

4. CREATE TEST FOR LESSON (optional):

   • Use create_test with the lesson ID to attach test to this lesson
   • IMPORTANT: Tests are attached to lessons, not modules
   • Get test ID from the response

5. UPDATE LESSON WITH TEST (if test was created):

   • Use update_lesson to add test IDs to the lesson's tests array

6. CREATE NEXT LESSON (repeat steps 3-5):

   • Create another lesson for the same module
   • Create tests for it
   • Update lesson with test IDs
   • Repeat until all lessons for this module are created

7. UPDATE MODULE WITH ALL LESSON IDS:

   • Use update_module to add all created lesson IDs to the module
   • Example: lessons: ["lesson_id_1", "lesson_id_2", "lesson_id_3"]

8. CREATE NEXT MODULE (repeat steps 2-7):

   • Create next module
   • Create lessons for it
   • Create tests for lessons
   • Update lessons and module
   • Repeat until all modules are created

9. UPDATE COURSE WITH ALL MODULE IDS:

   • Use update_course to add all module IDs with their order
   • Example: modules: [{ module: "module_id_1", order: 1 }, { module: "module_id_2", order: 2 }]

Required structure:

• Course must contain at least one module
• Module must contain at least one lesson
• Tests are optional but attached to lessons (not modules)
• Each module has ordered lessons
• Each course has ordered modules

Data flow:

Course
  └─ Module 1 (order: 1)
      ├─ Lesson 1
      │   └─ Test 1 (optional)
      ├─ Lesson 2
      │   └─ Test 2 (optional)
      └─ ...
  └─ Module 2 (order: 2)
      ├─ Lesson 1
      └─ ...

Example Requests

Get Courses:

{
  "name": "get_courses",
  "arguments": { "page": 1, "limit": 10 }
}

Get Courses by Professions:

{
  "name": "get_courses",
  "arguments": {
    "professions": [68, 69],
    "difficulty": "beginner"
  }
}

Create Lesson (first):

{
  "name": "create_lesson",
  "arguments": {
    "title": "Lesson Title",
    "description": "Lesson description (optional)",
    "type": "text",
    "contentType": "standard",
    "content": "Lesson content here",
    "image": "https://example.com/lesson-image.jpg",
    "duration": 30,
    "professions": [],
    "skills": [],
    "tests": []
  }
}

Create Module (with lesson IDs):

{
  "name": "create_module",
  "arguments": {
    "title": "Module Title",
    "content": "Module description (plain text)",
    "description": "Optional detailed description",
    "videoUrl": "https://example.com/video.mp4",
    "previewImage": "https://example.com/preview.jpg",
    "lessons": ["lesson_id_from_create_lesson"]
  }
}

Note: Modules don't contain tests directly. Tests are attached to lessons.

Create Course (with module IDs):

{
  "name": "create_course",
  "arguments": {
    "title": "Course Title",
    "description": "Course description",
    "difficulty": "beginner",
    "modules": [
      {
        "module": "module_id_from_create_module",
        "order": 1
      }
    ],
    "professions": [],
    "image": "",
    "duration": 60
  }
}

Get Professions:

{
  "name": "get_professions",
  "arguments": {}
}

Get Skills:

{
  "name": "get_skills",
  "arguments": {}
}

Get Tools:

{
  "name": "get_tools",
  "arguments": {}
}

Create Test (with lesson ID):

{
  "name": "create_test",
  "arguments": {
    "title": "Test Title",
    "description": "Test description",
    "lesson": "lesson_id_from_create_lesson",
    "questions": [
      {
        "question": "What is HTML?",
        "type": "single-choice",
        "options": [
          { "text": "HyperText Markup Language", "isCorrect": true },
          { "text": "High Tech Modern Language", "isCorrect": false }
        ],
        "points": 10
      }
    ],
    "passingScore": 70,
    "timeLimit": 30
  }
}

IMPORTANT: Tests are attached to lessons, not modules. Use lesson ID from create_lesson.

Update Course (with module IDs):

{
  "name": "update_course",
  "arguments": {
    "courseId": "course_id_here",
    "title": "Updated Course Title",
    "description": "Updated course description",
    "difficulty": "intermediate",
    "modules": [
      {
        "module": "existing_module_id",
        "order": 1
      },
      {
        "module": "new_module_id_from_create_module",
        "order": 2
      }
    ]
  }
}

Course Filtering by Professions

The get_courses tool supports filtering courses by profession IDs:

Workflow:

1. Call get_professions to get all available professions with their IDs
2. Use profession IDs in get_courses with the professions parameter

Parameters:

• professions - Array of profession IDs (numbers)
• difficulty - Filter by difficulty: "beginner", "intermediate", "advanced"
• search - Search by course name or description
• page - Page number for pagination
• limit - Number of courses per page
• all - Get all courses without pagination

---

Testing

This section describes how to test the MCP service in different modes.

Testing Mode 1: STDIO (Local/Command Line)

Prerequisites:

• Node.js installed
• API tokens configured (see API_TOKEN and API_TOKEN_LIBS sections)

Steps:

1. Install dependencies:

   npm install
   

2. Build the bundled version:

   npm run build
   

   This creates oa-y-mcp-service.cjs file that will be used by MCP clients.

3. Configure your MCP client (Cursor/Claude Desktop):

   Add to your MCP settings file:

   {
     "mcpServers": {
       "oa-y-local": {
         "command": "node",
         "args": ["c:/Projects/RH/oa-y-mcp-service/oa-y-mcp-service.cjs"],
         "env": {
           "APP_ENV": "prod",
           "API_TOKEN": "your_token",
           "API_TOKEN_LIBS": "your_libs_token"
         }
       }
     }
   }
   

4. Restart your MCP client (Cursor/Claude Desktop)

5. Test the tools:

   • Try calling get_professions to verify connection
   • Try creating a lesson with create_lesson
   • Verify that all tools are available and working

For development/debugging:

npm run dev          # Run in STDIO mode
npm run dev:inspect  # Run with Node Inspector

Testing Mode 2: StreamableHTTP (Remote/HTTP)

Prerequisites:

• Node.js installed
• API tokens configured (see API_TOKEN and API_TOKEN_LIBS sections)

Steps:

1. Install dependencies:

   npm install
   

2. Start the HTTP server:

   npm start
   # or
   npm run http
   

3. Test health endpoint:

   curl http://localhost:3000/health
   

4. Configure your MCP client (Cursor/Claude Desktop):

   Add to your MCP settings file:

   {
     "mcpServers": {
       "oa-y-http": {
         "url": "http://localhost:3000/mcp?API_TOKEN=your_token&API_TOKEN_LIBS=your_libs_token&APP_ENV=prod"
       }
     }
   }
   

5. Restart your MCP client (Cursor/Claude Desktop)

6. Test the tools:

   • Try calling get_professions to verify connection
   • Try creating a lesson with create_lesson
   • Verify that all tools are available and working

For development/debugging:

npm run http:inspect  # Run HTTP server with Node Inspector

Available HTTP endpoints:

• GET /mcp — StreamableHTTP handshake/stream
• POST /mcp — MCP protocol endpoint
• GET /health — health check
• GET / — service information

Testing with public URL (localtunnel):

For testing with remote access:

1. Install localtunnel:

   npm install -g localtunnel
   

2. Start your local server:

   npm start
   

3. Create a public tunnel:

   lt --port 3000 --local-host localhost
   

4. Use the provided URL in your MCP client:

   {
     "mcpServers": {
       "oa-y-remote": {
         "url": "https://random-subdomain.loca.lt/mcp?API_TOKEN=your_token&API_TOKEN_LIBS=your_libs_token&APP_ENV=prod"
       }
     }
   }
   

---

Deployment

This section describes how to deploy the MCP service for production use.

Deployment Mode 1: STDIO (NPM Package via GitHub)

This mode allows users to install your MCP service directly from GitHub using npx.

Requirements:

• Repository pushed to GitHub
• Built oa-y-mcp-service.cjs file committed to repository

Deployment Steps:

1. Build the bundled version:

   npm run build
   

   This creates oa-y-mcp-service.cjs — the bundled file that includes all dependencies.

2. Commit and push to GitHub:

   git add oa-y-mcp-service.cjs
   git commit -m "Build MCP service for distribution"
   git push origin main
   

3. Users can now install via npx:

   {
     "mcpServers": {
       "oa-y-mcp-service": {
         "command": "npx",
         "args": ["github:AdminRHS/oa-y-mcp-service"],
         "env": {
           "APP_ENV": "prod",
           "API_TOKEN": "user_token",
           "API_TOKEN_LIBS": "user_libs_token"
         }
       }
     }
   }
   

Important:

• Always build before pushing: npm run build
• The built file oa-y-mcp-service.cjs must be committed to the repository
• Users will download and run this file via npx

Deployment Mode 2: StreamableHTTP (Docker on Server)

This mode deploys the MCP service as an HTTP server using Docker.

Requirements:

• Docker and Docker Compose installed on server
• Server with public IP or domain name

Deployment Steps:

1. On your server, clone the repository:

   git clone https://github.com/AdminRHS/oa-y-mcp-service.git
   cd oa-y-mcp-service
   

2. Create .env file (optional, for custom port):

   PORT=3000
   

3. Start the service with Docker Compose:

   docker-compose up -d
   

4. Verify the service is running:

   curl http://localhost:3000/health
   

5. Users can now connect via HTTP:

   {
     "mcpServers": {
       "oa-y-remote": {
         "url": "http://your-server-ip:3000/mcp?API_TOKEN=user_token&API_TOKEN_LIBS=user_libs_token&APP_ENV=prod"
       }
     }
   }
   

Docker Compose Configuration:

The service uses docker-compose.yml and Dockerfile:

• Builds image from Node.js Alpine
• Installs dependencies
• Exposes port 3000 (configurable via .env)
• Auto-restarts on failure

Updating the Deployment:

To update the service on the server:

git pull origin main
docker-compose down
docker-compose up -d --build

Monitoring:

View logs:

docker-compose logs -f

Check container status:

docker-compose ps

Production Recommendations:

• Use a reverse proxy (nginx/traefik) for HTTPS
• Set up proper firewall rules
• Use environment-specific API tokens
• Configure monitoring and alerts
• Set up automated backups

---

Response Format

All responses follow the MCP (Model Context Protocol) JSON-RPC 2.0 format. See MCP documentation for details.

---

Available Scripts

• npm run dev - Run STDIO mode (local development)
• npm run dev:inspect - Run STDIO mode with Inspector
• npm run http - Run HTTP server mode
• npm run http:inspect - Run HTTP server with Inspector
• npm start - Start HTTP server (default)
• npm run build - Build bundled version (oa-y-mcp-service.cjs)