Penpal

NoManNayeem/Penpal

3.2

If you are the rightful owner of Penpal and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Penpal MCP server is a Python-based server designed to facilitate content creation with a pen-pal inspired experience, integrating with various platforms and providing tools for document management and export.

Tools
4
Resources
0
Prompts
0

Penpal: The Write Spot

A hybrid content creation platform with a warm, pen-pal inspired experience. This monorepo hosts the Next.js 15 web client, Tauri 2 desktop shell, and Python-based MCP server.

Project layout

apps/
  web/        # Next.js 15 + shadcn/ui brand experience & workspace UI
  desktop/    # Tauri 2 wrapper for the static web build
packages/
  python-mcp/ # FastMCP server with async SQLite + LiteLLM pipeline

Prerequisites

  • Node.js 18+ (Node 23 tested)
  • pnpm 10+ (v10.17.1 recommended)
  • Rust + Cargo (for Tauri desktop builds - latest stable)
  • Python 3.10+ (3.10, 3.11, or 3.12 recommended)

Quick Start

1. Clone and Install:

git clone https://github.com/NoManNayeem/Penpal.git
cd "Penpal - The Write Spot"
pnpm install

2. Start the MCP Server:

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

pip install -e .[dev]
cp .env.example .env
python -m penpal_mcp.server

3. Start the Web App (in a new terminal):

pnpm --filter web dev

4. Open http://localhost:3000 in your browser

5. Access the Workspace: Navigate to http://localhost:3000/workspace to start writing!

Common scripts

pnpm install                 # install workspace deps
pnpm dev                     # run all dev scripts via Turborepo
pnpm --filter web dev        # start Next.js app only (http://localhost:3000)
pnpm --filter desktop dev    # launch Tauri desktop (spawns Next dev server)

MCP server

cd packages/python-mcp
python -m venv .venv
. .venv/Scripts/Activate.ps1  # Windows example
pip install -e .[dev]
cp .env.example .env
python -m penpal_mcp.server

The MCP server exposes tools for outline generation, document storage, listing, and export. API keys for OpenAI/Anthropic/Google/xAI are optional—without them the server responds with deterministic sample data so the UI can run end-to-end during development.

MCP Environment Variables

The MCP server reads configuration from .env or environment variables with the PENPAL_ prefix:

  • PENPAL_DATABASE_URL - SQLite database path (default: sqlite+aiosqlite:///./penpal_write_spot.db)
  • PENPAL_MCP_PORT - HTTP server port (default: 7337)
  • PENPAL_LLM_DEFAULT_MODEL - Default LLM model (default: openai/gpt-4o-mini)
  • OPENAI_API_KEY - Optional: OpenAI API key for live AI features
  • ANTHROPIC_API_KEY - Optional: Anthropic Claude API key
  • GOOGLE_API_KEY - Optional: Google Gemini API key
  • XAI_API_KEY - Optional: xAI Grok API key

Docker workflow

Spin up the web client and MCP server together via Docker Compose:

docker compose up --build

Services:

The compose configuration mounts the repository so code edits hot-reload inside the containers. Named volumes cache the pnpm store and node modules to keep rebuilds fast.

Note: The Tauri desktop shell is not part of the Docker stack because it requires a native windowing environment. Build it locally with Rust/Cargo once the web app is exported.

Accessing the workspace UI

Once the stack is running, open http://localhost:3000/workspace to launch the Penpal editor experience:

  • Left sidebar lists documents stored through the MCP server.
  • Center stage hosts the rich-text editor (TipTap) and save actions.
  • Right rail surfaces outline suggestions generated via MCP tools.

The web client talks to the MCP transport through /api/mcp, proxying requests to the configured NEXT_PUBLIC_MCP_URL (defaults to http://127.0.0.1:7337).

Building the desktop app

pnpm --filter web build
pnpm exec tauri build --target x86_64-pc-windows-msvc

Prerequisites: the Rust toolchain (rustup), Windows C++ build tools, and pnpm enabled via corepack. The installer and binary output live in apps/desktop/src-tauri/target/release/bundle (for example bundle/msi/penpal-desktop_*.msi). Link the “Download desktop build” CTA to that release artifact once you publish it.

Features

✨ Rich Text Editor - TipTap-powered editor with full formatting support 📝 AI-Powered Outlines - Generate content outlines using multiple LLM providers 💾 Document Management - Save, list, and version your documents 📤 Multi-Format Export - Export to PDF, DOCX, PPTX, HTML, and Markdown 🌓 Dark Mode - System-aware theme switching 🖥️ Desktop App - Tauri-based native desktop application 🐳 Docker Support - Containerized development workflow

Technology Stack

Frontend

  • Next.js 15 - React framework with App Router
  • React 19 - Latest React with concurrent features
  • TipTap - Extensible rich text editor
  • shadcn/ui - Accessible component library
  • Tailwind CSS v4 - Utility-first styling
  • Zustand - State management
  • next-themes - Dark mode support

Backend

  • FastMCP - Model Context Protocol server framework
  • SQLAlchemy 2.0 - Async ORM with SQLite
  • LiteLLM - Multi-provider LLM integration
  • WeasyPrint - PDF generation
  • python-docx - Word document generation
  • python-pptx - PowerPoint generation

Desktop

  • Tauri 2.0 - Native desktop wrapper
  • Rust - High-performance backend

Documentation

📚 Complete Architecture Guide: - Brand system, technical architecture, and implementation details for the entire platform.

GitHub Pages Landing

A separate static landing page that mirrors the Penpal brand lives under GitAssets/. Deploy it directly to GitHub Pages by pointing the Pages build folder to /GitAssets. Preview locally with:

cd GitAssets
python -m http.server 4100
# Visit http://localhost:4100

Troubleshooting

MCP Server Connection Issues

  • Ensure the MCP server is running on port 7337
  • Check NEXT_PUBLIC_MCP_URL in apps/web/.env.local
  • Verify no firewall is blocking port 7337

Build Errors

  • Clear node_modules: rm -rf node_modules apps/*/node_modules && pnpm install
  • Clear Next.js cache: rm -rf apps/web/.next
  • Ensure Python 3.10+ is in your PATH

Desktop App Won't Start

  • Ensure Rust toolchain is installed: rustup --version
  • Build web app first: pnpm --filter web build
  • Check Tauri dependencies are installed

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

MIT

Support

For issues and questions: