<div align="center">

🎭 LM Studio Creative Story Writer

Model Context Protocol (MCP) Server for Local LLMs

<p align="center"> <b>An official MCP Server that turns local LM Studio models into imaginative storytellers, automatically generating and saving creative stories as text files.</b> </p>

</div>

---

🌟 Key Features

• 🤖 LM Studio Integration: Uses LM Studio's local OpenAI-compatible API server (http://localhost:1234/v1).
• ✍️ Creative Prompt Engineering: System prompts specifically optimized for rich sensory descriptions, immersive pacing, and engaging narratives.
• 💾 Automatic File Saving: Generates formatted .txt files complete with topic headers, genre, and generation timestamps.
• 🎭 Genre Customization: Easily specify genres such as Sci-Fi, Fantasy, Mystery, Cyberpunk, or Horror.
• ⚡ FastMCP Protocol: Built with the official lightweight FastMCP library for seamless integration with MCP clients (LM Studio, Claude Desktop, Cursor, etc.).

---

🏗️ Architecture Flowchart

┌─────────────────┐        MCP Protocol       ┌──────────────────┐
│  MCP Client     │  ◄─────────────────────►  │   story_server   │
│ (LM Studio Host │                           │   (FastMCP)      │
│ / Claude / CLI) │                           └────────┬─────────┘
└─────────────────┘                                    │
                                                       │ OpenAI API
                                                       ▼
┌──────────────────┐      Writes File         ┌──────────────────┐
│  Local Disk      │  ◄─────────────────────  │    LM Studio     │
│ (story_file.txt) │                          │  (Local Server)  │
└──────────────────┘                          └──────────────────┘

---

📋 Prerequisites

Before running the server, ensure you have:

1. Python 3.10+: Download from python.org.
2. LM Studio: Download from lmstudio.ai.
3. Local LLM Model: Download a model in LM Studio (e.g., Llama 3, Mistral 7B, or Qwen 2.5).

---

⚙️ Installation & Setup

1. Clone the Repository:

   git clone https://github.com/KVS-Manvith/VTU25374-MCP.git
   cd VTU25374-MCP
   

2. Create and Activate a Virtual Environment (Optional but Recommended):

   # On Windows:
   python -m venv venv
   .\venv\Scripts\activate
   
   # On macOS/Linux:
   python3 -m venv venv
   source venv/bin/activate
   

3. Install Dependencies:

   pip install -r requirements.txt
   

---

🚀 How to Run

Step 1: Start LM Studio Local Server

1. Launch LM Studio.
2. Select and load your model at the top dropdown.
3. Open the Local Server tab (< / > icon on the left sidebar).
4. Click Start Server (Server will start on http://localhost:1234).

Step 2: Test via FastMCP Dev Inspector

You can test the tool interactively in your browser:

mcp dev story_server.py

This opens an interactive dashboard where you can call the write_and_save_story tool with custom parameters!

Step 3: Register in LM Studio MCP Client

1. In LM Studio, navigate to Settings -> MCP / Tools.
2. Add the server configuration to your mcp.json:

   {
     "mcpServers": {
       "creative-story-writer": {
         "command": "python",
         "args": ["C:/path/to/VTU25374-MCP/story_server.py"]
       }
     }
   }
   

3. Save the config. In your LM Studio chat, you can now instruct the assistant:

   "Write a sci-fi story about a forgotten space station and save it as space_station.txt using the story writer tool."

---

🛠️ Tool Definition

write_and_save_story

Parameter	Type	Default	Description
topic	string	(Required)	The main idea, theme, or prompt for the story.
filename	string	"creative_story.txt"	The name of the file to save the story into.
genre	string	"general fiction"	Target genre (e.g. sci-fi, fantasy, mystery, horror).

---

📂 Project Structure

VTU25374-MCP/
├── story_server.py     # Main MCP server script
├── requirements.txt    # Python dependencies
├── README.md           # Documentation
├── LICENSE             # MIT License
├── .gitignore          # Git ignore rules
└── sample_story.txt    # Example generated story output

---

📝 License

This project is licensed under the MIT License.