@edubase/mcp 1.0.23 → 1.1.1

package/README.md

@@ -83,7 +83,28 @@ Add the following to your `claude_desktop_config.json`:
 
 #### Using Node.js
 
-Before running the MCP server, make sure you have **Node.js installed**. You can download it from [nodejs.org](https://nodejs.org/) or use a package manager like `brew`. Download EduBase MCP server release or clone the repository and run `npm run build` to build the server. Do not forget to adjust `/path/to/dist` to the actual directory and **configure the environmental variables**!
+Before running the MCP server, make sure you have **Node.js installed**. You can download it from [nodejs.org](https://nodejs.org/) or use a package manager like `brew`.
+
+```json
+{
+  "mcpServers": {
+    "edubase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@edubase/mcp"
+      ],
+      "env": {
+        "EDUBASE_API_URL": "https://domain.edubase.net/api",
+        "EDUBASE_API_APP": "your_integration_app_id",
+        "EDUBASE_API_KEY": "your_integration_secret_key"
+      }
+    }
+  }
+}
+```
+
+Or download EduBase MCP server release or clone the repository and run `npm run build` to build the server. Do not forget to adjust `/path/to/dist` to the actual directory and **configure the environmental variables**!
 
 ```json
 {

package/dist/helpers.js

@@ -2,3 +2,12 @@
 export function getClientIp(req) {
     return (req.get('x-forwarded-for')?.split(',')[0] || req.get('x-real-ip') || req.ip || req.socket.remoteAddress || null);
 }
+/* Get header value */
+export function getHeaderValue(req, name) {
+    const raw = req.headers?.[name.toLowerCase()];
+    if (typeof raw === "string" && raw.length > 0)
+        return raw;
+    if (Array.isArray(raw) && raw.length > 0 && typeof raw[0] === "string")
+        return raw[0];
+    return null;
+}

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "node:crypto";
 import queryString from "query-string";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
@@ -9,7 +9,11 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { InMemoryEventStore } from '@modelcontextprotocol/sdk/examples/shared/inMemoryEventStore.js';
 import express from "express";
 import bodyParser from "body-parser";
-import { getClientIp } from "./helpers.js";
+import { getClientIp, getHeaderValue } from "./helpers.js";
+import packageJson from '../package.json' with { type: "json" };
+import * as z from 'zod/v4';
+/* Version */
+const VERSION = packageJson.version;
 /* Enable SSE or Streamable HTTP mode */
 const SSE = ((process.env.EDUBASE_SSE_MODE || 'false') == 'true');
 const STREAMABLE_HTTP = ((process.env.EDUBASE_STREAMABLE_HTTP_MODE || 'false') == 'true');
@@ -30,18 +34,141 @@ if (!SSE && !STREAMABLE_HTTP && EDUBASE_API_KEY.length == 0) {
     process.exit(1);
 }
 /* Supported tools and prompts */
-import { EDUBASE_API_TOOLS, EDUBASE_API_TOOLS_OUTPUT_SCHEMA } from "./tools.js";
-import { EDUBASE_API_PROMPTS, EDUBASE_API_PROMPTS_HANDLERS } from "./prompts.js";
-/* Create MCP server */
-const server = new Server({
-    name: '@edubase/mcp',
-    version: '1.0.23',
-}, {
-    capabilities: {
-        prompts: {},
-        tools: {},
-    },
-});
+import { EDUBASE_API_TOOLS } from "./tools.js";
+import { EDUBASE_API_PROMPTS } from "./prompts.js";
+/* Create MCP server with appropriate EduBase configuration */
+function getEduBaseApiUrl(req) {
+    if (req.query?.config && typeof req.query.config == 'string') {
+        /* Use URL from Smithery configuration */
+        const smitheryConfig = JSON.parse(Buffer.from(req.query.config, 'base64').toString());
+        if (smitheryConfig.edubaseApiUrl && typeof smitheryConfig.edubaseApiUrl == 'string' && smitheryConfig.edubaseApiUrl.length > 0) {
+            return smitheryConfig.edubaseApiUrl;
+        }
+    }
+    return null;
+}
+function getEduBaseAuthentication(req) {
+    let EDUBASE_API_APP = null;
+    let EDUBASE_API_KEY = null;
+    if (req.query?.config && typeof req.query.config == 'string') {
+        /* Use authentication from Smithery configuration */
+        const smitheryConfig = JSON.parse(Buffer.from(req.query.config, 'base64').toString());
+        if (smitheryConfig.edubaseApiApp && typeof smitheryConfig.edubaseApiApp == 'string' && smitheryConfig.edubaseApiApp.length > 0) {
+            EDUBASE_API_APP = smitheryConfig.edubaseApiApp;
+        }
+        if (smitheryConfig.edubaseApiKey && typeof smitheryConfig.edubaseApiKey == 'string' && smitheryConfig.edubaseApiKey.length > 0) {
+            EDUBASE_API_KEY = smitheryConfig.edubaseApiKey;
+        }
+    }
+    else if (getHeaderValue(req, 'edubase-api-app') && getHeaderValue(req, 'edubase-api-secret')) {
+        /* Use authentication from request headers */
+        EDUBASE_API_APP = getHeaderValue(req, 'edubase-api-app');
+        EDUBASE_API_KEY = getHeaderValue(req, 'edubase-api-secret');
+    }
+    else if (getHeaderValue(req, 'authorization') && getHeaderValue(req, 'authorization').startsWith('Bearer ')) {
+        /* Use authentication from Bearer token */
+        try {
+            /* Decode Bearer token */
+            const [app, secret] = atob(getHeaderValue(req, 'authorization').split(' ')[1]).split(':');
+            if (app && app.length > 0 && secret && secret.length > 0) {
+                EDUBASE_API_APP = app;
+                EDUBASE_API_KEY = secret;
+            }
+        }
+        catch (error) {
+            /* Probably not encoded as base64 */
+            const [app, secret] = getHeaderValue(req, 'authorization').split(' ')[1].split(':');
+            if (app && app.length > 0 && secret && secret.length > 0) {
+                EDUBASE_API_APP = app;
+                EDUBASE_API_KEY = secret;
+            }
+        }
+    }
+    if (EDUBASE_API_APP && EDUBASE_API_KEY) {
+        return { app: EDUBASE_API_APP, secret: EDUBASE_API_KEY };
+    }
+    return null;
+}
+function createMcpServer(apiUrl = null, authentication = null) {
+    /* Create MCP server instance */
+    const server = new McpServer({
+        name: '@edubase/mcp',
+        version: VERSION,
+    }, {
+        capabilities: {
+            prompts: {},
+            tools: {},
+        },
+    });
+    /* Configure request handlers */
+    Object.values(EDUBASE_API_PROMPTS).forEach((prompt) => {
+        /* Register prompts */
+        server.registerPrompt(prompt.name, { description: prompt.description, argsSchema: prompt.argsSchema }, prompt.handler);
+    });
+    server.registerTool('edubase_mcp_server_version', { description: 'Get the MCP server version (only use for debugging)' }, async () => {
+        /* Static response with server version, useful for testing connectivity and authentication */
+        return {
+            content: [{ type: 'text', text: VERSION }],
+            isError: false,
+        };
+    });
+    server.registerTool('edubase_mcp_server_api', { description: 'Get the MCP server API URL (only use for debugging)' }, async () => {
+        /* Static response with server API URL, useful for testing connectivity and authentication */
+        return {
+            content: [{ type: 'text', text: apiUrl || EDUBASE_API_URL }],
+            isError: false,
+        };
+    });
+    Object.values(EDUBASE_API_TOOLS).forEach((tool) => {
+        /* Register tools */
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema, outputSchema: tool.outputSchema }, async (args, ctx) => {
+            try {
+                const name = tool.name;
+                /* Decompose request and check arguments */
+                if (!name.match(/^edubase_(get|post|delete)/)) {
+                    throw new Error('Invalid tool configuration');
+                }
+                if (!args) {
+                    throw new Error('No arguments provided');
+                }
+                /* Prepare and send API request */
+                const [, method, ...endpoint] = name.split('_');
+                const response = await sendEduBaseApiRequest(method, (apiUrl || EDUBASE_API_URL) + '/' + endpoint.join(':'), args, authentication);
+                /* Return response */
+                if (response.length == 0 || tool.outputSchema === z.object({}).optional()) {
+                    /* Endpoint without response */
+                    return {
+                        content: [{ type: 'text', text: 'Success.' }],
+                        isError: false,
+                    };
+                }
+                else if (typeof response != 'object') {
+                    /* Response should be an object at this point */
+                    throw new Error('Invalid response');
+                }
+                else {
+                    /* Return response with schema */
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(response) }],
+                        structuredContent: response,
+                        isError: false,
+                    };
+                }
+            }
+            catch (error) {
+                /* Request failed */
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `${error instanceof Error ? error.message : String(error)}`,
+                        }],
+                    isError: true,
+                };
+            }
+        });
+    });
+    return server;
+}
 /* EduBase API rate limits (via environment variables or configured defaults) */
 const EDUBASE_API_MAXRATE_DEFAULT = {
     second: 10,
@@ -132,107 +259,6 @@ async function sendEduBaseApiRequest(method, endpoint, data, authentication) {
         return await clonedResponse.text();
     }
 }
-server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-    prompts: Object.values(EDUBASE_API_PROMPTS),
-}));
-server.setRequestHandler(GetPromptRequestSchema, (request) => {
-    try {
-        /* Decompose request and check arguments */
-        const { name, arguments: args } = request.params;
-        const promptHandler = EDUBASE_API_PROMPTS_HANDLERS[name];
-        if (!promptHandler) {
-            throw new Error('Prompt not found');
-        }
-        /* Return prompt response */
-        return promptHandler;
-    }
-    catch (error) {
-        /* Request failed */
-        return {};
-    }
-});
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: EDUBASE_API_TOOLS,
-}));
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    try {
-        /* Decompose request and check arguments */
-        const { name, arguments: args } = request.params;
-        if (!name.match(/^edubase_(get|post|delete)/)) {
-            throw new Error('Invalid tool configuration');
-        }
-        if (!args) {
-            throw new Error('No arguments provided');
-        }
-        const meta = request.params._meta || {};
-        /* Prepare authentication */
-        let authentication = null;
-        if (meta && meta.override && meta.override.EDUBASE_API_APP && meta.override.EDUBASE_API_KEY) {
-            /* Use authentication from custom configuration */
-            authentication = {
-                app: meta.override.EDUBASE_API_APP,
-                secret: meta.override.EDUBASE_API_KEY
-            };
-        }
-        else if (meta && meta.headers && meta.headers['edubase-api-app'] && meta.headers['edubase-api-secret']) {
-            /* Use authentication from request headers */
-            authentication = {
-                app: meta.headers['edubase-api-app'],
-                secret: meta.headers['edubase-api-secret']
-            };
-        }
-        else if (meta && meta.headers && meta.headers['authorization'] && meta.headers['authorization'].startsWith('Bearer ')) {
-            /* Use authentication from Bearer token */
-            try {
-                /* Decode Bearer token */
-                const [app, secret] = atob(meta.headers['authorization'].split(' ')[1]).split(':');
-                if (app && app.length > 0 && secret && secret.length > 0) {
-                    authentication = { app, secret };
-                }
-            }
-            catch (error) {
-                /* Probably not encoded as base64 */
-                const [app, secret] = meta.headers['authorization'].split(' ')[1].split(':');
-                if (app && app.length > 0 && secret && secret.length > 0) {
-                    authentication = { app, secret };
-                }
-            }
-        }
-        /* Prepare and send API request */
-        const [, method, ...endpoint] = name.split('_');
-        const response = await sendEduBaseApiRequest(method, (meta?.override?.EDUBASE_API_URL || EDUBASE_API_URL) + '/' + endpoint.join(':'), args, authentication);
-        /* Return response */
-        const outputSchemaKey = name;
-        if (typeof EDUBASE_API_TOOLS_OUTPUT_SCHEMA[outputSchemaKey] == 'object' && Object.keys(EDUBASE_API_TOOLS_OUTPUT_SCHEMA[outputSchemaKey]).length == 0 && typeof response == 'string' && response.length == 0) {
-            /* Endpoint without response */
-            return {
-                content: [{ type: 'text', text: 'Success.' }],
-                isError: false,
-            };
-        }
-        else if (typeof response != 'object') {
-            /* Response should be an object at this point */
-            throw new Error('Invalid response');
-        }
-        else {
-            /* Return response with optional schema */
-            return {
-                content: [{ type: 'text', text: "Response: " + JSON.stringify(response) + (Object.keys(EDUBASE_API_TOOLS_OUTPUT_SCHEMA[outputSchemaKey]).length > 0 ? "\nResponse schema: " + JSON.stringify(EDUBASE_API_TOOLS_OUTPUT_SCHEMA[outputSchemaKey]) : '') }],
-                isError: false,
-            };
-        }
-    }
-    catch (error) {
-        /* Request failed */
-        return {
-            content: [{
-                    type: 'text',
-                    text: `${error instanceof Error ? error.message : String(error)}`,
-                }],
-            isError: true,
-        };
-    }
-});
 /* Start MCP server */
 if (STREAMABLE_HTTP) {
     /* Using HTTP with Streamable HTTP transport */
@@ -263,6 +289,7 @@ if (STREAMABLE_HTTP) {
                     delete transports[transport.sessionId];
                 }
             };
+            const server = createMcpServer(getEduBaseApiUrl(req), getEduBaseAuthentication(req));
             await server.connect(transport);
         }
         else {
@@ -341,7 +368,6 @@ if (STREAMABLE_HTTP) {
     process.on('SIGTERM', () => {
         /* Graceful shutdown */
         console.error("Received SIGTERM, shutting down EduBase MCP server...");
-        server.close();
     });
 }
 else if (SSE) {
@@ -350,14 +376,15 @@ else if (SSE) {
     app.use(bodyParser.json());
     app.disable('x-powered-by');
     const transports = {};
-    app.get('/sse', async (_, res) => {
-        /* Handle SSE sessions */
+    app.get('/sse', async (req, res) => {
+        /* Handle SSE sessions (but prefer Streamable HTTP) */
         const transport = new SSEServerTransport('/messages', res);
         transports[transport.sessionId] = transport;
         res.on('close', () => {
             delete transports[transport.sessionId];
         });
         try {
+            const server = createMcpServer(getEduBaseApiUrl(req), getEduBaseAuthentication(req));
             await server.connect(transport);
         }
         catch (error) {
@@ -413,13 +440,13 @@ else if (SSE) {
     process.on('SIGTERM', () => {
         /* Graceful shutdown */
         console.error("Received SIGTERM, shutting down EduBase MCP server...");
-        server.close();
     });
 }
 else {
     /* Using stdio transport */
     async function runMcpServer() {
         const transport = new StdioServerTransport();
+        const server = createMcpServer();
         await server.connect(transport);
         console.error("EduBase MCP server is now listening on standard input/output");
     }

package/dist/prompts/questions.js

@@ -0,0 +1,24 @@
+import * as z from 'zod/v4';
+/* Prompts definitions */
+export const EDUBASE_API_PROMPTS_QUESTIONS = [
+    // Create a new question
+    {
+        name: 'edubase_prompt_create_question',
+        description: 'Create a new question with the given subject and content.',
+        argsSchema: z.object({
+            type: z.string().describe('The type of the question, use the EduBase question types!'),
+            subject: z.string().describe('The subject of the question, e.g. "Mathematics", "History", etc.')
+        }),
+        handler: async (args) => {
+            return {
+                messages: [{
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: `Create a new question of type ${args.type} about ${args.subject}. Please provide the question in a clear and concise manner, suitable for educational purposes.`
+                        }
+                    }]
+            };
+        }
+    }
+];

package/dist/prompts.js

@@ -1,4 +1,5 @@
+import { EDUBASE_API_PROMPTS_QUESTIONS } from "./prompts/questions.js";
 /* Prompt definitions */
-export const EDUBASE_API_PROMPTS = {};
-/* Prompt handler definitions */
-export const EDUBASE_API_PROMPTS_HANDLERS = {};
+export const EDUBASE_API_PROMPTS = {
+    ...EDUBASE_API_PROMPTS_QUESTIONS,
+};