# EdgeMind-MCP-Story

This project is part of the Day 2 task in the course "LLMs in Edge Computing". It provides a beginner-friendly Model Context Protocol (MCP) server that connects an LLM client to a local instance of LM Studio to generate and save creative writing stories.

---

## 1. Project Overview

**EdgeMind-MCP-Story** is a Python-based MCP server that exposes a custom tool, `generate_story`. When called by an MCP-compatible client, this tool takes a story topic and optional filename, constructs a creative writing prompt, sends it to a locally running model inside **LM Studio**, and automatically saves the generated story as a `.txt` file inside a local `stories/` directory.

This allows you to leverage powerful, offline language models running on edge devices (like your local PC) directly within MCP-compatible developer tools, assistants, and IDE integrations.

---

## 2. Architecture

Below is the execution flow of how the model context protocol, the client, and the local server interact:

```
User (Input Topic & Filename)
↓
MCP Client (e.g., Claude Desktop, Inspector, Cursor)
↓
MCP Server (server.py via stdio)
↓
LM Studio Local API (http://localhost:1234/v1/chat/completions)
↓
Local Language Model (running on your PC)
↓
Generated Story (returned to Server)
↓
stories/story.txt (written locally in UTF-8)
```

---

## 3. Requirements

To run this project, make sure you have:
*   **Operating System**: Windows 10/11
*   **Python**: Python 3.10 or higher installed (with `pip` and virtual environment support)
*   **LM Studio**: A local installer downloaded and configured on your PC
*   **Local Language Model**: A downloaded GGUF chat or instruct model inside LM Studio (e.g., `Llama-3-8B-Instruct`, `Qwen-2.5-7B-Instruct`, `Phi-3-mini`, etc.)
*   **MCP Host/Client**: An MCP-compatible client (such as Claude Desktop, Cursor, or the MCP Inspector tool)

---

## 4. Installing Dependencies

Follow these steps to set up a clean Python virtual environment and install the required dependencies:

1.  Open **PowerShell** or **Command Prompt** in the project directory:
    ```cmd
    cd c:\Users\koppa\Desktop\EdgeMind-MCP-Story
    ```

2.  Create a virtual environment:
    ```cmd
    python -m venv .venv
    ```

3.  Activate the virtual environment:
    *   On **Windows (Command Prompt)**:
        ```cmd
        .venv\Scripts\activate
        ```
    *   On **Windows (PowerShell)**:
        ```powershell
        .venv\Scripts\Activate.ps1
        ```

4.  Install the required packages:
    ```cmd
    pip install -r requirements.txt
    ```

---

## 5. Setting Up LM Studio

Ensure your local model server is running before attempting to use the MCP tool:

1.  Open **LM Studio** on your Windows PC.
2.  Go to the **Search / Discover** tab (magnifying glass) and download a suitable local chat/instruct model (e.g., Qwen-2.5-7B-Instruct, Llama-3-8B-Instruct).
3.  Go to the **Developer / Local Server** tab (the double-arrows icon `<->` or server icon on the left sidebar).
4.  Load your downloaded model using the drop-down menu at the top.
5.  Check the **Port** configuration (default is `1234`).
6.  Click the **Start Server** button.
7.  Verify that the console logs show `Local server listening on port 1234`.
8.  **Important**: Look at the top of the screen or in the server logs and copy the exact **model identifier** (e.g. `lmstudio-community/Meta-Llama-3-8B-Instruct-GGUF` or `qwen2.5-7b-instruct`). You will need this for configuration.

---

## 6. Configure Environment Variables

Before starting the server, you must specify which model the server should instruct LM Studio to run.

### Option A: System Environment Variables (Windows)
Run these commands in your terminal before running the server:

*   **Command Prompt**:
    ```cmd
    set LM_STUDIO_BASE_URL=http://localhost:1234/v1
    set LM_STUDIO_MODEL=<your-copied-model-identifier>
    ```

*   **PowerShell**:
    ```powershell
    $env:LM_STUDIO_BASE_URL="http://localhost:1234/v1"
    $env:LM_STUDIO_MODEL="<your-copied-model-identifier>"
    ```

### Option B: Local `.env` File (Easiest)
Create a file named `.env` in the project root directory (`c:\Users\koppa\Desktop\EdgeMind-MCP-Story\.env`) and add the following content:
```env
LM_STUDIO_BASE_URL=http://localhost:1234/v1
LM_STUDIO_MODEL=your-copied-model-identifier
```
Replace `your-copied-model-identifier` with the exact name you copied in Section 5.

---

## 7. Running the MCP Server

You can start the MCP server directly using:
```cmd
python server.py
```
*Note: Because MCP servers use standard input/output (`stdio`) transport for communication with clients, running it directly in the terminal will not show a web UI or accept keyboard commands. It will wait silently for JSON-RPC messages from a client.*

To stop the server, press `Ctrl + C`.

### 7.1 Running Offline Tests

To verify the logic of the server (such as filename sanitization, error responses, and mock LM Studio integration) offline, run:
```cmd
python test_server.py
```
This runs the automated unit tests in `test_server.py` and ensures everything is functioning properly without needing a live LM Studio connection.

---

## 8. Connecting the MCP Server to an MCP Client

To use the tool with an actual LLM, you need to configure an MCP client to launch the server.

### Example: Claude Desktop
To add this server to the Claude Desktop application, open your Claude configuration file (located at `%APPDATA%\Claude\claude_desktop_config.json`) and add this configuration:

```json
{
  "mcpServers": {
    "edgemind-story-writer": {
      "command": "python",
      "args": [
        "c:/Users/koppa/Desktop/EdgeMind-MCP-Story/server.py"
      ],
      "env": {
        "LM_STUDIO_BASE_URL": "http://localhost:1234/v1",
        "LM_STUDIO_MODEL": "<your-model-identifier-here>"
      }
    }
  }
}
```
*Note: If you configured environment variables via a `.env` file inside the directory, you do not need to add the `"env"` block in the JSON file. Be sure to restart Claude Desktop after modifying this configuration.*

---

## 9. Using the Tool

When connected, the MCP client gains access to the tool `generate_story`.

### Arguments:
*   `topic` (string, required): The core concept or prompt for your story.
*   `filename` (string, optional): A custom filename for the output file (e.g. `mysterious_device.txt`). If left blank, a safe filename will be automatically created based on the topic.

### Example Prompt:
> *"Write a story about: A student discovers a mysterious device inside his college laboratory."*

The client will automatically route this to the `generate_story` tool.

---

## 10. Output

All successfully written stories are stored inside the `stories/` directory:
```
stories/
  └── mysterious_device.txt
```
The server saves files using `UTF-8` encoding. The output response returned to your MCP client will contain:
1.  A confirmation that the story was generated by your local model.
2.  The exact relative path where it was saved.
3.  The topic of the story.
4.  The file size and word count details.

---

## 11. Troubleshooting

### 1. "Error: Could not reach LM Studio at..."
*   **Cause**: LM Studio is not running, or the Local Server has not been started.
*   **Solution**: Open LM Studio, go to the Local Server tab, and verify that the server is started and listening on the port configured in `LM_STUDIO_BASE_URL` (usually `1234`).

### 2. "Error: The environment variable 'LM_STUDIO_MODEL' is not set"
*   **Cause**: The server doesn't know which model to query.
*   **Solution**: Ensure you have defined `LM_STUDIO_MODEL` in your terminal environment, or created a `.env` file with the model name in the project directory.

### 3. "Error: LM Studio returned HTTP status 400 (or other api error)"
*   **Cause**: The model name defined in `LM_STUDIO_MODEL` does not match the model currently loaded in LM Studio.
*   **Solution**: Double-check the spelling of the model identifier at the top of the LM Studio window. Set it exactly as shown.

### 4. "Error: Cannot create or access the 'stories' folder"
*   **Cause**: Python does not have write permissions to the project directory.
*   **Solution**: Run terminal as Administrator or verify folder permissions in Windows.

---

## 12. Project Architecture

The project contains only the files required to run, keeping it simple and easy to demonstrate:

*   **`server.py`**: The core application file. Contains the MCP server instantiation, configuration validation, the `generate_story` tool, filename security sanitization, HTTP request payload creation, and local file storage logic.
*   **`test_server.py`**: Automated unit tests for verifying filename sanitization, input validation, and mocked API interaction offline.
*   **`requirements.txt`**: List of Python external dependencies required to run the server.
*   **`stories/`**: Directory where all generated story text files will be written.
*   **`.gitignore`**: Tells Git to track the project files while ignoring local environment variables, Python cache directories, and generated story txt outputs.
*   **`README.md`**: This guide.