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.

Related MCP server: Claude-LMStudio-Bridge

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:

   cd c:\Users\koppa\Desktop\EdgeMind-MCP-Story

2. Create a virtual environment:

   python -m venv .venv

3. Activate the virtual environment:

   • On Windows (Command Prompt):

     .venv\Scripts\activate

   • On Windows (PowerShell):

     .venv\Scripts\Activate.ps1

4. Install the required packages:

   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:

  set LM_STUDIO_BASE_URL=http://localhost:1234/v1
  set LM_STUDIO_MODEL=<your-copied-model-identifier>

• 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:

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:

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:

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:

{
  "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.