<div align="center">

# 🎭 LM Studio Creative Story Writer
### *Model Context Protocol (MCP) Server for Local LLMs*

[![MCP Protocol](https://img.shields.io/badge/Protocol-MCP%20v1.0-blue?style=for-the-badge)](https://modelcontextprotocol.io)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![LM Studio](https://img.shields.io/badge/LM%20Studio-Local%20LLM-6B46C1?style=for-the-badge)](https://lmstudio.ai)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)

<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](https://www.python.org/).
2. **LM Studio**: Download from [lmstudio.ai](https://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**:
   ```bash
   git clone https://github.com/KVS-Manvith/VTU25374-MCP.git
   cd VTU25374-MCP
   ```

2. **Create and Activate a Virtual Environment (Optional but Recommended)**:
   ```bash
   # On Windows:
   python -m venv venv
   .\venv\Scripts\activate

   # On macOS/Linux:
   python3 -m venv venv
   source venv/bin/activate
   ```

3. **Install Dependencies**:
   ```bash
   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:
```bash
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`:
   ```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](LICENSE).