Penpal

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:

web → Next.js dev server on http://localhost:3000
mcp → FastMCP server on http://localhost:7337

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: GitAssets/Penpal_The_Write_Spot.md - 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

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

License

MIT

Support

For issues and questions:

GitHub Issues: github.com/NoManNayeem/Penpal/issues
Documentation: GitAssets/Penpal_The_Write_Spot.md