ishswar/story_mcp_server

📚 Story MCP Server

This is a lightweight MCP (Multi-Channel Processor) server powered by the fastmcp module. It provides a creative storytelling platform with character management and story storage capabilities using HTTP Streaming transport.

📦 Features

• FastAPI-based HTTP Streaming server using fastmcp
• Character management with backstories and superpowers
• Story creation and storage in markdown format
• Comprehensive logging system
• Dockerized for portability and ease of use

🚀 Getting Started

🔧 Prerequisites

• Docker & Docker Compose installed
• Python 3.x (for local runs)
• fastmcp Python package

🐳 Run via Docker

1. Clone the repository

git clone <your-repo-url>
cd story_mcp_server

2. Build and run

docker compose up --build

🟢 MCP server will be available at http://localhost:8082/mcp

🛠 Local Run (for development)

Recommended: Using Dedicated Virtual Environment

To avoid dependency conflicts with other projects, use the dedicated virtual environment:

# 1. Create virtual environment (first time only)
python3 -m venv venv

# 2. Install dependencies
./venv/bin/pip install -r requirements.txt

# 3. Run the server using the startup script
./start_server.sh

Or run directly with:

./venv/bin/python story_mcp_server.py

Quick Install (system-wide or existing environment)

pip install fastmcp
python story_mcp_server.py

Note: This project requires uvicorn<0.38.0 due to a compatibility issue with FastMCP. The requirements.txt file includes this constraint.

🔧 Troubleshooting

Server won't start - KeyError: 'websockets-sansio'

This error occurs with uvicorn 0.38.0+. Solutions:

1. Use the dedicated venv (recommended):

   ./venv/bin/python story_mcp_server.py
   

2. Check uvicorn version:

   pip list | grep uvicorn
   # Should show: uvicorn 0.37.0 or earlier
   

3. Reinstall with correct version:

   pip install "uvicorn[standard]<0.38.0" --force-reinstall
   

Using the wrong Python environment

Always use the venv Python to ensure correct dependencies:

./venv/bin/python story_mcp_server.py  # ✅ Correct
python story_mcp_server.py              # ❌ May use wrong environment

⚙️ Project Structure

.
├── Dockerfile                # Container setup
├── docker-compose.yml        # Compose file for container orchestration
├── story_mcp_server.py      # Main MCP server implementation
├── requirements.txt         # Python dependencies
├── start_server.sh          # Startup script for local development
├── story_server.log        # Server logs
├── venv/                   # Virtual environment (created locally)
└── README.md

🌐 Networking (Docker Compose)

The server is configured to run on port 8082 by default and uses HTTP Streaming transport:

networks:
  app_network_pyd:
    driver: bridge

🧰 Exposed MCP Tools

This MCP server registers six tools, each providing specific storytelling and character management functionality:

1. get_characters()

🔍 Description:
Returns a list of all available character names.

📤 Output:

• List of character names (e.g., ["Jack", "Ram", "Robert"])

2. get_backstory(character: str)

📄 Description:
Retrieves the backstory for a specified character.

📥 Input:

• character (str): Name of the character

📤 Output:

• Character's backstory as a string

3. get_superpower(character: str)

💪 Description:
Gets the superpower of a specified character.

📥 Input:

• character (str): Name of the character

📤 Output:

• Character's superpower as a string

4. save_story(title: str, content: str)

💾 Description:
Saves a story to a markdown file with title and creation date.

📥 Inputs:

• title (str): Story title
• content (str): Story content

📤 Output:

• Confirmation message with file path

5. list_stories(reason: str)

📚 Description:
Lists all saved story files in markdown format.

📥 Input:

• reason (str): Reason for listing stories (for logging)

📤 Output:

• List of story filenames

6. get_story(filename: str)

📖 Description:
Reads and returns the content of a specific story file.

📥 Input:

• filename (str): Name of the story file to read

📤 Output:

• Story content in markdown format

✅ Example Flow

1. Get available characters: get_characters()
2. Get character details: get_backstory("Jack") and get_superpower("Jack")
3. Create and save a story: save_story("Jack's Adventure", "...")
4. List available stories: list_stories("checking available stories")
5. Read a story: get_story("jacks_adventure.md")

🎨 Writing Style Prompts

This MCP server also exposes three educational prompts that act as writing instructors, teaching different storytelling styles with specific techniques and assignments.

1. adventure-writing-master

🎯 Description:
An Adventure Writing Instructor that teaches action-packed storytelling techniques.

📥 Input:

• story_theme (str, optional): Theme for the adventure story (default: "heroic quest")

📤 Output:

• Complete masterclass content with 10 essential adventure writing techniques
• Specific writing assignment based on the provided theme
• Teaching guidance for creating thrilling, fast-paced narratives

2. mystery-writing-master

🔍 Description:
A Mystery Writing Instructor that teaches suspenseful, puzzle-driven storytelling.

📥 Input:

• mystery_type (str, optional): Type of mystery story (default: "whodunit")

📤 Output:

• Complete masterclass content with 10 essential mystery writing techniques
• Specific writing assignment based on the mystery type
• Teaching guidance for creating engaging, suspenseful narratives

3. character-driven-master

💭 Description:
A Character-Driven Writing Instructor that teaches emotional, relationship-focused storytelling.

📥 Input:

• emotional_theme (str, optional): Emotional theme to explore (default: "personal growth")

📤 Output:

• Complete masterclass content with 10 essential character-driven writing techniques
• Specific writing assignment based on the emotional theme
• Teaching guidance for creating deep, emotionally resonant narratives

🎓 How to Use Writing Prompts

These prompts are designed to be used with AI language models to get structured writing guidance:

1. Choose a writing style that matches your story goals
2. Specify parameters (theme, mystery type, or emotional focus)
3. Receive comprehensive teaching content with techniques and assignments
4. Apply the techniques to create stories using the character tools

Example Usage:

• Request adventure-writing-master with theme "space exploration"
• Use the teaching content to write an adventure story featuring Jack's invisibility powers
• Save the completed story using save_story()

📝 Demo Characters

The server comes with three pre-configured characters:

1. Jack: A former spy with invisibility and telepathy powers
2. Ram: An ancient warrior with invincible body and immense strength
3. Robert: A scientist-turned-cyborg with advanced technological powers

These characters can be used to create engaging stories using their unique backstories and abilities.