OA-Y MCP Service

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

1. 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

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

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

1. 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

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

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

1. 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

1. 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"]

1. 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

1. 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: ``json { "name": "get_courses", "arguments": { "page": 1, "limit": 10 } } ``

Get Courses by Professions: ``json { "name": "get_courses", "arguments": { "professions": [68, 69], "difficulty": "beginner" } } ``

Create Lesson (first): ``json { "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): ``json { "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): ``json { "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: ``json { "name": "get_professions", "arguments": {} } ``

Get Skills: ``json { "name": "get_skills", "arguments": {} } ``

Get Tools: ``json { "name": "get_tools", "arguments": {} } ``

Create Test (with lesson ID): ``json { "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): ``json { "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

1. Build the bundled version:

   npm run build

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

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

Add to your MCP settings file: ``json { "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" } } } } ``

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

1. 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: ``bash 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

1. Start the HTTP server:

   npm start
   # or
   npm run http

1. Test health endpoint:

   curl http://localhost:3000/health

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

Add to your MCP settings file: ``json { "mcpServers": { "oa-y-http": { "url": "http://localhost:3000/mcp?API_TOKEN=your_token&API_TOKEN_LIBS=your_libs_token&APP_ENV=prod" } } } ``

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

1. 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: ``bash 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

1. Start your local server:

   npm start

1. Create a public tunnel:

   lt --port 3000 --local-host localhost

1. 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.

1. Commit and push to GitHub:

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

1. 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

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

   PORT=3000

1. Start the service with Docker Compose:

   docker-compose up -d

1. Verify the service is running:

   curl http://localhost:3000/health

1. 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: ``bash git pull origin main docker-compose down docker-compose up -d --build ``

Monitoring:

View logs: ``bash docker-compose logs -f ``

Check container status: ``bash 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)