docs: add readme

Author: Henrrypg

backend/openedx_ai_extensions/mcp/README.md

@@ -0,0 +1,135 @@
+# Model Context Protocol (MCP) - Proof of Concept
+
+This directory contains a **proof of concept (MVP)** demonstrating how Model Context Protocol (MCP) works. This is **NOT** the full OpenEdx AI Extensions integration yet, but rather a working example to understand MCP concepts and test the infrastructure.
+
+## Overview
+
+This MVP demonstrates the MCP architecture and workflow using a simple dice-rolling example. The implementation consists of three main components:
+
+1. **`server.py`** - A FastMCP server with an example tool (`roll_dice`)
+2. **`run_server.py`** - Script to run the MCP server in HTTP mode
+3. **`client_example.py`** - Example client showing how to interact with the MCP server
+
+**Note:** The actual OpenEdx-specific tools and integration will be implemented in future iterations. This MVP focuses on validating the MCP infrastructure and communication patterns.
+
+## Architecture
+
+The current implementation uses:
+- **FastMCP** - A framework for building MCP servers
+- **Streamable HTTP** transport - Allows the server to be exposed via HTTP
+- **LiteLLM** - For integrating the MCP server with language models
+
+### Example Tool: `roll_dice`
+
+The server currently implements a simple example tool that rolls dice. **This is a demonstration tool only** to show how MCP tools work. This pattern will later be extended to implement OpenEdx-specific operations like course management, user administration, content creation, etc.
+
+## Setup
+
+### Prerequisites
+
+Install the required dependencies:
+
+```bash
+pip install fastmcp litellm openai
+```
+
+### Environment Variables
+
+Set your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY="your_openai_api_key_here"
+```
+
+Or update it directly in `client_example.py`.
+
+## Running the Server
+
+### Step 1: Start the MCP Server
+
+Run the server locally on port 9001:
+
+```bash
+python run_server.py
+```
+
+The server will start and listen on `http://127.0.0.1:9001/mcp`.
+
+### Step 2: Expose the Server with ngrok
+
+Since the MCP protocol requires a publicly accessible endpoint for certain use cases, you need to expose your local server using ngrok:
+
+```bash
+# Install ngrok if you haven't already
+# Visit https://ngrok.com/ to download and set up
+
+# Expose port 9001
+ngrok http 9001
+```
+
+ngrok will provide you with a public URL like:
+```
+https://abc123.ngrok-free.app
+```
+
+**Important**: Copy the ngrok URL (including the subdomain) as you'll need it for the client configuration.
+
+### Step 3: Update the Client Configuration
+
+Edit `client_example.py` and update the `server_url` with your ngrok URL:
+
+```python
+tools=[
+    {
+        "type": "mcp",
+        "server_label": "dice_server",
+        "server_url": "https://<your_ngrok_subdomain>.ngrok-free.app/mcp/",
+        "require_approval": "never",
+    },
+],
+```
+
+Replace `<your_ngrok_subdomain>` with your actual ngrok subdomain (e.g., `abc123.ngrok-free.app`).
+
+### Step 4: Run the Client Example
+
+In a new terminal (while the server and ngrok are still running):
+
+```bash
+python client_example.py
+```
+
+## Testing Workflow
+
+Here's the complete workflow for testing:
+
+1. **Terminal 1** - Start the MCP server:
+   ```bash
+   cd backend/openedx_ai_extensions/mcp
+   python run_server.py
+   ```
+
+2. **Terminal 2** - Expose with ngrok:
+   ```bash
+   ngrok http 9001
+   ```
+   Copy the ngrok URL from the output.
+
+3. **Terminal 3** - Run the client:
+   ```bash
+   # Update client_example.py with your ngrok URL first
+   python client_example.py
+   ```
+
+## Expected Output
+
+When running the client, you should see:
+
+1. List of available tools from the MCP server
+2. The AI model response after using the `roll_dice` tool
+
+Example:
+```
+Available resources: ['roll_dice']
+Response: <LiteLLM response object with dice roll results>
+```

backend/openedx_ai_extensions/mcp/__init__.py

@@ -0,0 +1,3 @@
+"""
+Model Context Protocol (MCP) integration for OpenEdx AI Extensions
+"""

backend/openedx_ai_extensions/mcp/client_example.py

@@ -0,0 +1,40 @@
+# client_litellm.py
+import asyncio
+from fastmcp import Client, tools
+from litellm import completion, responses
+import openai
+
+
+import os 
+os.environ["OPENAI_API_KEY"] = "your_openai_api_key_here"
+
+
+openai_client = openai.OpenAI()
+
+async def main():
+    # Connect to the MCP server
+    async with Client("http://127.0.0.1:9001/mcp") as client:
+
+        # List resources (optional, just to show it works)
+        resources = await client.list_tools()
+        print("Available resources:", [r.name for r in resources])
+
+    response = responses(
+        model="gpt-4.1-nano",
+        reasoning=None,
+        tools=[
+            {
+                "type": "mcp",
+                "server_label": "dice_server",
+                "server_url": "https://<your_ngrok_subdomain>.ngrok-free.app/mcp/",
+                "require_approval": "never",
+            },
+        ],
+        input="Roll a dice for me.",
+    )
+
+    print("Response:", response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/openedx_ai_extensions/mcp/run_server.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python
+"""
+Run the FastMCP server in stdio mode
+"""
+from server import mcp
+
+
+if __name__ == "__main__":
+
+    mcp.run(transport="streamable-http")

backend/openedx_ai_extensions/mcp/server.py

@@ -0,0 +1,21 @@
+"""
+MCP Server implementation using FastMCP for OpenEdx AI Extensions
+
+This module provides a Model Context Protocol (MCP) server that exposes
+tools and resources for AI assistants to interact with the OpenEdx system.
+"""
+import logging
+from typing import Any
+from mcp.server.fastmcp import FastMCP
+from starlette.responses import PlainTextResponse
+from starlette.requests import Request
+import random
+
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP("dice_server", port=9001)
+
+@mcp.tool()
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]