🧠 PAELLADOC: The AI-First Development Framework

⚠️ Historical — preserved for reference This repository is PaellaDoc v0.x (340+ ⭐, 2024–2025), the original MCP-based framework. The current product is a desktop orchestrator at paelladoc.com with native Claude Code, Codex and Gemini integration, Playwright-verified Golden Gate, and a community at forum.paelladoc.com. This repo is preserved as historical reference and is no longer actively maintained.

Visit the Official Website

⭐ If you find PAELLADOC useful, please consider starring the repo! ⭐ </

=======

Version 0.3.7: Hotfix release restoring core project CRUD tools inadvertently omitted in v0.3.6 build. Check the CHANGELOG for details!

"In the AI era, context isn't supplementary to code—it's the primary creation."

PAELLADOC is an AI-First Development framework that implements the 5 Philosophical Principles of AI-First Development, transforming how we create software in the age of AI.

🎯 PAELLADOC and the Model Context Protocol (MCP)

PAELLADOC implements Anthropic's Model Context Protocol (MCP) (see Anthropic's news). This protocol provides a structured way for Large Language Models (LLMs) to interact with external tools and context, enabling more sophisticated capabilities.

By implementing MCP, PAELLADOC allows LLMs to leverage its specific AI-First development tools and workflows directly through this standard. This approach facilitates functionalities similar to Tool Use or Function Calling seen in other platforms, but specifically utilizes the Anthropic MCP standard for interaction.

🎯 The AI-First Philosophy

Traditional development treats documentation as an afterthought. AI-First Development inverts this paradigm:

• Context becomes the primary artifact
• Code becomes its manifestation
• Knowledge evolves alongside systems
• Decisions preserve their philosophical context
• Human-AI collaboration is seamless

🧠 The Five Principles in Action

1. Context as Primary Creation

# Traditional Way
write_code() -> document()

# PAELLADOC Way
create_context() -> manifest_as_code()

• Every artifact has a UUID for perfect traceability
• Context is versioned alongside code
• Knowledge graphs capture relationships
• Intent is preserved at every step

2. Intent-Driven Architecture

graph TD
    A[Business Intent] --> B[Context Creation]
    B --> C[Architecture Manifestation]
    C --> D[Code Generation]
    D --> E[Living Documentation]

• Architecture flows from intent, not implementation
• Every decision captures its philosophical context
• Systems adapt to evolving purpose

3. Knowledge as Living Entity

# Knowledge evolves with your system
paella continue my-project

• Project memory tracks evolution of understanding
• Documentation updates automatically with changes
• Context remains fresh and relevant
• Knowledge graphs show relationships

4. Human-AI Collaborative Consciousness

# Not just code generation, but true collaboration
with paelladoc.context() as ctx:
    ctx.understand_intent()
    ctx.propose_solutions()
    ctx.implement_with_human()

• Natural language conversations
• Intent preservation
• Contextual awareness
• Seamless collaboration

5. Contextual Decision Architecture

decision:
  id: uuid-123
  intent: "Why we chose this path"
  context: "What we knew at the time"
  alternatives: "What we considered"
  implications: "Future impact"

• Every decision preserves its context
• Future developers understand the "why"
• Changes respect historical context
• Intent remains clear

🚀 Installation & Integration

PAELLADOC is a Python application and should be installed in its own dedicated Python virtual environment. This keeps its dependencies separate and avoids conflicts. You'll need one PAELLADOC environment, regardless of how many different projects (Python, JS, Ruby, etc.) you plan to document.

(Requires Python 3.12 or later)

Installing via Smithery

To install PAELLADOC for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @jlcases/paelladoc --client claude

1. Create and Activate the Dedicated Environment

First, choose a permanent location for this environment. Your home directory is often a good choice.

# Navigate to where you want to store the environment (e.g., your home directory)
# cd ~  # Uncomment and run if you want it in your home directory

# Create the virtual environment (using python3.12 or your installed 3.12+ version)
# We'll name the folder '.paelladoc_venv' (starting with a dot makes it hidden)
python3.12 -m venv .paelladoc_venv

# Activate the environment 
# (The command depends on your shell. Use ONE of the following)

# For Bash/Zsh:
source .paelladoc_venv/bin/activate

# For Fish:
# source .paelladoc_venv/bin/activate.fish

# For Powershell (Windows):
# .\.paelladoc_venv\Scripts\activate.ps1 

(You should see (.paelladoc_venv) at the beginning of your terminal prompt now)

2. Install PAELLADOC in the Activated Environment

# Make sure your (.paelladoc_venv) prompt is visible before running pip
pip install paelladoc

3. Configure Database Path

PAELLADOC needs to know where to store its memory database (memory.db). There are two main ways to configure this:

Option 1: Environment Variable (Less Reliable for LLM Integration)

You can set the PAELLADOC_DB_PATH environment variable. This works well if you run PAELLADOC directly from your terminal.

# Example: Set the variable in your current terminal session
export PAELLADOC_DB_PATH="$HOME/.paelladoc/memory.db"

# Optional: Add the export line to your shell's startup file 
# (.bashrc, .zshrc, etc.) for it to persist across sessions.

Important: When PAELLADOC is run by an LLM tool (like Cursor via MCP), it might not inherit environment variables set this way. Therefore, this method is less reliable for LLM integration.

Option 2: MCP Configuration (Recommended for LLM Integration)

The most reliable way to ensure your LLM tool uses the correct database path is to configure it directly within the tool's MCP JSON file (.cursor/mcp.json for Cursor). This injects the variable directly into the server process launched by the LLM.

See the examples in the next section.

4. Configure Your LLM (MCP Setup)

Now, tell your LLM tool (like Cursor) how to find and run PAELLADOC.

Key Information Needed:

• Full Path to Python Executable: Absolute path to python inside your .paelladoc_venv.

#### Cursor IDE Example

Edit your .cursor/mcp.json file. Add a server configuration for PAELLADOC. Here's a typical example:

{
  "mcpServers": {
    "Paelladoc": {
      "command": "/absolute/path/to/.paelladoc_venv/bin/python", 
      "args": [
        "-m",
        "paelladoc.ports.input.mcp_server_adapter",
        "--stdio"
      ],
      "cwd": "/path/to/your/project/directory", // Optional: Set working directory
      "env": {
        // Recommended for local dev: Use a DB in your project folder
        "PAELLADOC_DB_PATH": "/path/to/your/project/directory/paelladoc_memory.db",
        // Optional: Add src to PYTHONPATH if needed for local development imports
        "PYTHONPATH": "/path/to/your/project/directory/src:/path/to/your/project/directory" 
      },
      "disabled": false
    }
  },
  "mcp.timeout": 120000
}

Important Notes:

• The command path must be the absolute path to the Python executable inside your .paelladoc_venv (created in Step 1). Replace /absolute/path/to/ with the actual path on your system (e.g., /Users/your_username/).
• Database Path:
• By default (if PAELLADOC_DB_PATH is not set in env), PAELLADOC uses ~/.paelladoc/memory.db.
• For local development where you might want the database alongside your project code, setting PAELLADOC_DB_PATH in the env section (as shown in the example) is the recommended and most reliable approach. Replace /path/to/your/project/directory/ with the actual path to your project.
• Working Directory (cwd): Setting this to your project directory can be helpful but is often optional.
• PYTHONPATH: Setting this in env might be necessary if you are doing local development on PAELLADOC itself and need the server to find your source code.