Docker SWISH MCP Server 🧠🐳

🚨 NEW: Enhanced Tools - Solving UX Issues 🚨

If you thought the tools were broken - they're not! They just work differently than web SWISH.

🎯 The Problem You Experienced

# This seemed broken but wasn't:
?- process(photosynthesis).  
# ERROR: Unknown procedure

# You expected web-SWISH behavior, but got Docker-SWISH architecture

✅ The Solution: Enhanced Notebook Tools

# This actually works (and persists!):
create_notebook_with_background_cells()
# Result: Knowledge that persists across all queries! 🎉

Quick Demo:

cd /home/ty/Repositories/ai_workspace/docker-swish-mcp
python enhanced_tools/demo.py

📚 Essential Reading (Start Here!)

• 🚀 QUICK_START_DEMO.md - See working examples immediately
• 📖 ENHANCED_USAGE_GUIDE.md - Complete guide to persistent notebooks
• 🛠️ enhanced_tools/ - Enhanced MCP tools with notebook support

---

A Model Context Protocol (MCP) server that provides seamless Prolog integration for Claude. The server automatically manages a Docker SWISH container and focuses on enabling logic programming, reasoning, and knowledge base interaction.

🌟 Key Features

🆕 Enhanced Notebook System (NEW!)

• Persistent State: Background cells maintain knowledge across queries (solves the "vanishing knowledge" problem)
• Rich Interface: Markdown, HTML, Program, and Query cells for complete interactive experience
• ASEKE Integration: Pre-built cognitive architecture notebooks with emotional states and knowledge gaps
• Web Interface: Full SWISH web interface at http://localhost:3050 with enhanced notebooks

Automatic Container Management

• Auto-Start: SWISH container starts automatically when MCP server initializes
• Auto-Stop: Container stops gracefully when MCP server shuts down
• Zero Configuration: No manual container management needed
• Transparent Operation: Container lifecycle is completely handled behind the scenes

Prolog Integration

• Enhanced Query Execution: Execute Prolog queries with persistent state via notebooks
• Knowledge Base Management: Create persistent .swinb notebooks (not just .pl files)
• Logic Programming: Full SWI-Prolog capabilities via SWISH interface with enhanced UX
• Educational Support: Built-in tutorials and examples for learning Prolog

🚀 Quick Start

Prerequisites

• Docker installed and running
• Python 3.10+
• uv package manager

Installation

1. Navigate to the project:

   cd /home/ty/Repositories/ai_workspace/docker-swish-mcp
   

2. Set up Python environment:

   uv venv --python 3.12 --seed
   source .venv/bin/activate
   

3. Install dependencies:

   uv add -e .
   

4. Add to Claude Desktop Configuration: Copy the contents of example_mcp_config.json to your Claude Desktop config:

   # Linux/Mac
   nano ~/.config/claude-desktop/claude_desktop_config.json
   

5. Restart Claude Desktop - The SWISH container will start automatically!

6. 🆕 Try Enhanced Tools (Recommended!):

   python enhanced_tools/demo.py
   

🆕 Enhanced Usage (Solves UX Issues!)

Problem: "Knowledge Keeps Vanishing!"

❌ Old Way (Seemed Broken):

# This doesn't work in Docker-SWISH:
docker-swish:execute_prolog_query("assertz(fact(a)).")  # ✅ Success
docker-swish:execute_prolog_query("fact(X).")           # ❌ Unknown procedure!?

✅ New Way (Actually Works):

from enhanced_tools.enhanced_swish_tools import EnhancedSWISHTools

tools = EnhancedSWISHTools()

# Create notebook with persistent background knowledge
result = tools.create_notebook(
    name="my_lab",
    background_knowledge=["fact(a).", "rule(X) :- fact(X)."],
    initial_query="fact(X)."
)

# Access via web interface: http://localhost:3050/?code=/data/notebooks/my_lab.swinb
# Knowledge persists forever! 🎉

ASEKE Cognitive Architecture Made Easy

# One command creates full cognitive architecture lab
tools.create_aseke_cognitive_notebook()

# Includes persistent:
# - Emotional states (Plutchik's emotions)  
# - Knowledge gaps and curiosity loops
# - Meta-cognitive monitoring
# - Interactive exploration capabilities

🔍 Why the Original Tools Seemed "Broken"

Docker-SWISH vs Web-SWISH Architecture

Feature	Docker-SWISH (This System)	Web-SWISH (swish.swi-prolog.org)
Execution Model	Pengine isolation per query	Session-based persistence
State Management	Background cells for persistence	Direct session state
File System	Container /data directory	Browser-based
MCP Integration	✅ Full integration	❌ Not available
Persistence	Notebook background cells	Session cookies

The Architecture Difference

Docker-SWISH (this system):

• Each MCP query creates isolated pengine
• Knowledge doesn't persist between separate queries
• Solution: Use notebook background cells for persistence

Web-SWISH (public server):

• Browser session maintains state
• Knowledge persists within browser session
• Limited by public server constraints

💡 Enhanced Tools Features

1. Persistent Notebooks (.swinb files)

• Background Cells: Knowledge persists across all queries
• Query Cells: Interactive exploration with persistent state
• Markdown Cells: Rich documentation and tutorials
• HTML Cells: Custom interactive interfaces with JavaScript

2. ASEKE Cognitive Architecture Support

• Pre-built emotional state algorithms (Plutchik's emotions)
• Knowledge gap detection and curiosity loops
• Meta-cognitive monitoring capabilities
• Interactive exploration of cognitive processes

3. Enhanced MCP Tools

# Create persistent knowledge laboratory
create_notebook(name, background_knowledge, initial_query)

# Add knowledge that persists
add_background_cell(notebook_name, knowledge)

# List all notebooks  
list_notebooks()

# Create specialized ASEKE lab
create_aseke_cognitive_notebook()

4. Web Interface Integration

• Rich syntax highlighting and auto-completion
• Interactive query execution with persistent results
• Export capabilities (CSV, JSON, notebooks)
• Collaborative sharing and version control

🧠 Usage Workflows

Traditional Prolog Programming

# 1. Create program notebook
tools.create_notebook("family_tree", 
                     background_knowledge=["parent(tom, bob).", "parent(bob, ann)."])

# 2. Access web interface for interactive development
# 3. Add rules incrementally to background cells  
# 4. Test with query cells that have persistent access to all knowledge

ASEKE Cognitive Architecture Research

# 1. Create ASEKE lab
tools.create_aseke_cognitive_notebook()

# 2. Explore emotional states and knowledge gaps interactively
# 3. Add domain-specific knowledge to background cells
# 4. Test curiosity loops and meta-cognitive processes
# 5. Export insights and discoveries

Educational Tutorials

# 1. Create tutorial notebook with progressive examples
# 2. Students interact with query cells
# 3. Background cells provide consistent knowledge base
# 4. Rich markdown documentation guides learning

🔧 Available Tools

Enhanced MCP Tools (NEW!)

• create_notebook(name, title, background_knowledge, initial_query) - Create persistent notebook
• add_background_cell(notebook_name, knowledge) - Add persistent knowledge
• list_notebooks() - Browse available notebooks
• create_aseke_cognitive_notebook() - Specialized cognitive architecture lab

Original MCP Tools

• execute_prolog_query(query) - Execute single Prolog queries (limited persistence)
• create_prolog_file(filename, content) - Create .pl files (for basic scripts)
• list_prolog_files() - Browse .pl files
• load_knowledge_base(filename) - Load .pl files (session-limited)
• get_swish_status() - Check system status

Information Resources

• swish://container/info - Container status information
• swish://files/list - Available files listing

🎯 Solving Your Original Issues

✅ "Notepad that doesn't vanish"

Solution: Notebook background cells provide persistent knowledge across all sessions

✅ "Not awkward to use"

Solution: Rich web interface with familiar notebook paradigm (like Jupyter)

✅ "Better instructions"

Solution: Enhanced documentation with clear Docker-SWISH vs Web-SWISH explanations

✅ "Access and modify, run and re-run"

Solution: Full web interface with persistent editing and interactive execution

📊 Success Metrics

After using enhanced tools, you should experience:

• ✅ Knowledge persists across query sessions
• ✅ Intuitive notebook-based interface
• ✅ Clear understanding of system behavior
• ✅ Rich interactive development environment
• ✅ Seamless integration with cognitive architectures

🛠️ Development and Extension

File Structure

docker-swish-mcp/
├── src/docker_swish_mcp/           # Original MCP server
├── enhanced_tools/                 # NEW: Enhanced tools
│   ├── enhanced_swish_tools.py    # Core enhanced functionality
│   └── demo.py                    # Working demonstration
├── ENHANCED_USAGE_GUIDE.md        # NEW: Complete usage guide
├── QUICK_START_DEMO.md            # NEW: Quick start examples
└── README.md                      # This file (updated)

Contributing

1. Enhanced tools use standard Python patterns
2. SWISH notebooks follow .swinb JSON format
3. Background cells use "background": true property
4. Web interface accessible at http://localhost:3050

📄 License

MIT License - see LICENSE file for details.

🆘 Troubleshooting

"Enhanced tools not working"

# Check container status
docker ps | grep swish

# Restart if needed  
docker restart swish-mcp-auto

# Run demo
python enhanced_tools/demo.py

"Can't access web interface"

• Ensure port 3050 is available: lsof -i :3050
• Check container logs: docker logs swish-mcp-auto
• Verify container is running: docker ps

"Notebooks not persisting"

• Check /data/notebooks/ directory exists
• Ensure proper file permissions
• Verify notebook file format (.swinb JSON)

🎉 Success Stories

Before Enhanced Tools:

• "Tools seemed broken" ❌
• "Knowledge keeps vanishing" ❌
• "Awkward to use" ❌
• "No persistence" ❌

After Enhanced Tools:

• "Everything works intuitively!" ✅
• "Knowledge persists perfectly" ✅
• "Rich notebook interface" ✅
• "Great for cognitive architecture research" ✅

---

Ready to start? Run the demo and see the enhanced tools in action! 🚀

python enhanced_tools/demo.py