fairyfly

Don't Wait for Walldorf.

SAP's enterprise backbone runs on a predictable release cycle. AI moves at the speed of thought.

fairyfly bridges that gap.

Modern C++ automation for SAP GUI today. Natural language control via LLMs tomorrow.

The Problem We're Solving

SAP professionals know the drill: manual transactions, repetitive workflows, fragile GUI scripts that break on each quarterly upgrade. Meanwhile, AI agents can automate virtually everything—except SAP. Until now.

AI enthusiasts face the opposite challenge: modern agent frameworks (Claude AI, Anthropic's ADK, LangChain) can chain together APIs and web services effortlessly, but enterprise SAP systems? They're still the black box that requires specialized scripting knowledge.

fairyfly solves both problems:

For SAP experts: Stop writing brittle scripts. Get AI assistance without waiting for SAP's roadmap.
For AI builders: Make SAP accessible to modern agent frameworks through standard protocols.

The Vision: Natural Language SAP Automation

What's Coming (Phase 3)

Imagine this conversation with Claude Desktop:

You: "Create a purchase order in SAP for 100 units of material 100-100-001 
     from vendor 12345, delivered to warehouse 001, plant 1000"

Claude: *interacts with SAP through fairyfly*
       "I've created purchase order #4500123456. The document is saved and 
        awaiting approval. Would you like me to display it?"

Or use it with Cline in VS Code, agent frameworks like the Anthropic Agent Development Kit, or any MCP-compatible client. fairyfly speaks the Model Context Protocol, making SAP a first-class citizen in the modern AI ecosystem.

Why This Matters

Traditional RPA approach:

Record 50 clicks → Hard-code element IDs → Break on SAP upgrade → Debug for hours

LLM-powered approach:

Describe what you need → AI understands context → Executes via fairyfly → Handles errors gracefully

fairyfly provides the reliable COM foundation (SAP's battle-tested API since 2002) with the modern MCP interface that LLMs understand. You get the best of both worlds: SAP's stability meets AI's flexibility.

What Works Today

While we build toward the LLM vision, fairyfly already automates SAP through a powerful CLI. Production-ready today, agent-ready tomorrow.

Quick Demo: Extracting SAP Screen Data

# Attach to running SAP window (click when prompted)
fairyfly attach

# Navigate to SM59 (RFC connections)
fairyfly tcode SM59

# Read the entire screen structure as JSON
fairyfly screen read --output json

# Or view it in human-readable Markdown
fairyfly screen read --output markdown

# Fill a field with a value
fairyfly fill "wnd[0]/usr/txtRFCDEST" "MY_RFC_CONN"

# Click a button
fairyfly click "wnd[0]/tbar[0]/btn[3]"

Real workflow example:

# PowerShell script automating SAP transaction
$conn_id = (fairyfly attach --output json | ConvertFrom-Json).data.connection_file_id

# Execute transaction SM59
fairyfly --connection $conn_id tcode SM59

# Extract screen data to analyze
$screen = fairyfly --connection $conn_id screen read --output json | ConvertFrom-Json

# Process with Python, then write back
python process_sap_data.py $screen | Out-String | ForEach-Object {
    fairyfly --connection $conn_id fill "wnd[0]/usr/txtFIELD" $_
}

Example Scenarios

Scenario A: Using fairyfly with Claude Desktop (Coming in Phase 3)

Configure fairyfly as an MCP server in Claude Desktop:

{
  "mcpServers": {
    "fairyfly": {
      "command": "C:\\path\\to\\fairyfly.exe",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Then have natural language conversations with Claude about your SAP system:

You: "Show me all purchase orders created today"
Claude: *executes SAP transaction via fairyfly, extracts table data*
       "I found 47 purchase orders created today. Here are the top 10 by value..."

Scenario B: Integration with Agent Frameworks (Design Ready)

fairyfly's JSON-native output is perfect for agent frameworks like the Anthropic Agent Development Kit. The agent reads screen context, reasons about the next action, and executes via fairyfly:

# Example agent workflow (high-level design)
agent = AnthropicAgent(tools=[fairyfly_connect, fairyfly_tcode, fairyfly_fill, ...])

# Agent chain for complex workflow
result = agent.execute(
    "Create vendor 12345 with address in SAP",
    tools=fairyfly_tools,
    context=last_screen_state  # Maintained automatically
)

Scenario C: CLI Automation Today

The CLI is fully functional right now. Use it in PowerShell, Bash, or Python:

#!/bin/bash
# Automated report generation
fairyfly attach
fairyfly tcode SE16
fairyfly fill "wnd[0]/usr/txtTABLENAME" "MATERIALS"
fairyfly click "wnd[0]/usr/btn[0]"
fairyfly screen read --output json > report.json

Current Status & Roadmap

✅ Phase 1: Core Automation (COMPLETE)

Foundation that makes everything else possible:

Windows COM integration with SAP GUI Scripting API (20+ years of stability)
Core automation actions: transactions, clicks, field filling, reading
Smart retry logic with progressive backoff
Robust error handling with actionable suggestions
Session management with persistence across invocations

Tests: 16/16 passing | Production-ready

✅ Phase 2A: Command-Line Interface (COMPLETE)

Full-featured CLI for immediate use:

14+ commands for complete SAP workflow automation
Profile management: store multiple SAP system connections
Multiple output formats: JSON (machine-readable), Markdown (human-friendly), PlainText (scripting)
Attach to running SAP windows (no credentials in code)
Launch programmatic connections
Comprehensive diagnostics and troubleshooting

CLI commands implemented:

attach - Click-to-attach to running SAP window
launch - Open SAP Logon connection programmatically
tcode - Execute SAP transaction codes
click / fill / get - Element manipulation
screen read / capture - Extract screen data or screenshots
connections - Manage SAP connection files
diagnose - Check SAP GUI status and configuration

⏳ Phase 2B: Advanced Workflows (IN PROGRESS)

Next up: make complex workflows effortless:

Batch operations (fill multiple fields in one round-trip)
Intelligent element caching (TTL-based, invalidated on screen changes)
Table extraction and export (CSV, Excel formats)
Advanced error recovery (automatic fallback strategies)
Windows Credential Manager integration (secure password storage)

📅 Phase 3: LLM Integration (THE VISION)

Where fairyfly transforms from tool to infrastructure:

MCP Server: JSON-RPC 2.0 over stdio and HTTP
Tool Schemas: OpenAI function calling format for LLM consumption
Multimodal Support: Screenshot capture for vision-language models
Claude Desktop Integration: Native support for Anthropic's desktop app
Agent Framework Support: Seamless integration with ADK, LangChain, etc.
Natural Language Workflows: Describe intent, get execution

Expected: Q2 2025

📅 Phase 4: Enterprise Scale

Production hardening:

Cross-platform support (SAP GUI for Java on Mac/Linux)
Parallel session management (handle multiple users concurrently)
Advanced performance optimization
Enterprise deployment patterns and documentation
Audit logging and compliance features

Architecture: Reliability Meets Modern AI

┌─────────────────────────────────────┐
│   Claude Desktop / Cline / Agents   │  ← Natural language interface
├─────────────────────────────────────┤
│   MCP Server (Phase 3)              │  ← Standards-compliant protocol
├─────────────────────────────────────┤
│   CLI Interface (Today)              │  ← Direct automation
├─────────────────────────────────────┤
│   SAP GUI Automation Engine         │  ← Smart retry, error handling
│   - Session Management               │
│   - Element Caching                 │
│   - Screen Extraction               │
├─────────────────────────────────────┤
│   SAP GUI Scripting API (COM)       │  ← Battle-tested since 2002
└─────────────────────────────────────┘

Design Philosophy

1. Reliability over features

Uses SAP's proven COM API, not screen scraping
Respects SAP's timing model (handles busy states correctly)
Handles all failure modes: connection loss, timeouts, element changes

2. Security-first

Credentials never stored in plain text
Windows Credential Manager integration (Phase 2B)
Audit logging of all automation actions
Respects SAP's authorization model (no privilege escalation)

3. AI-ready by design

JSON-native output format
Structured error responses with suggestions for LLM recovery
MCP protocol implementation for standard LLM integration
Multimodal support (structured data + screenshots)

Why C++?

Cross-platform portability (Windows COM today, Java on Mac/Linux later)
Native performance (no runtime overhead, single binary deployment)
No garbage collection pauses (critical for time-sensitive SAP operations)
Type safety catches bugs at compile-time
Minimal dependencies: ~15MB executable, runs anywhere

Getting Started in 5 Minutes

Prerequisites

Required:

Windows 10/11 (x64)
SAP GUI for Windows 7.60+ with Scripting enabled
CMake 3.20+ and Visual Studio 2019+ (or equivalent)

SAP GUI Configuration:

Open SAP Logon → Options → Accessibility & Scripting → Scripting
Check "Enable scripting"
Check "Open scripting API when SAP GUI starts"
(Server-side): Set sapgui/user_scripting = TRUE via transaction RZ11 (admin required)

Build from Source

# 1. Install vcpkg (if not already installed)
cd C:\dev
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

# Set environment variable
setx VCPKG_ROOT "C:\dev\vcpkg"

# 2. Clone fairyfly
git clone https://github.com/yourusername/fairyfly.git
cd fairyfly

# 3. Configure and build
cmake -B build -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

# 4. Run
.\build\Release\fairyfly.exe --help

vcpkg will automatically download and compile dependencies (CLI11, nlohmann-json, spdlog, catch2).

Your First Automation

# 1. Open SAP Logon and connect to your system manually
# 2. Navigate to any transaction (e.g., SM59)
# 3. Run fairyfly attach
.\build\Release\fairyfly.exe attach
# Click on the SAP window when prompted

# 4. Extract screen structure
.\build\Release\fairyfly.exe screen read --output markdown

# 5. Try interacting
.\build\Release\fairyfly.exe tcode SE38
.\build\Release\fairyfly.exe screen read --output json

Output Formats

fairyfly supports multiple output formats for different use cases:

# JSON (default) - Machine-readable, perfect for scripting and LLMs
fairyfly screen read --output json

{
  "status": "success",
  "data": {
    "window": {
      "title": "Create Purchase Order",
      "elements": [...]
    }
  },
  "metadata": {
    "timestamp": "2025-01-15T12:00:00Z",
    "duration_ms": 123
  }
}

# Markdown - Human-friendly formatting
fairyfly screen read --output markdown

# Screen: Create Purchase Order (wnd[0])

## Toolbar
- Save (btn[11])
- Back (btn[3])

## Fields
**Vendor**: [TextField] ""
**Quantity**: [TextField] ""

# PlainText - Minimal for scripts
fairyfly profile list --output text

production  abc123
dev         xyz789

Technology Stack

Language: Modern C++ (C++20 standard)
Build System: CMake 3.20+ with vcpkg dependency management
CLI Framework: CLI11 for argument parsing
JSON Processing: nlohmann/json (header-only, fast)
Logging: spdlog for structured, performant logging
Testing: Catch2 for unit tests
Future: Asio for async I/O (MCP server implementation)

Dependencies are minimal and well-maintained. The final binary is a single ~15MB executable with no runtime dependencies.

Development & Contributing

Running Tests

# Build tests
cmake --build build --config Release --target unit_tests

# Run tests
cd build
ctest -C Release --output-on-failure

Project Structure

fairyfly/
├── src/
│   ├── main.cpp                    # Entry point, CLI parsing
│   ├── cli_handler.cpp             # Command implementation
│   ├── com_automation_engine.cpp  # SAP COM integration
│   ├── com_wrapper.cpp             # COM abstractions
│   ├── connection_manager.cpp      # Session persistence
│   └── include/                    # Public headers
├── tests/
│   ├── unit/                       # C++ unit tests (Catch2)
│   └── integration/                # PowerShell integration tests
├── docs/
│   ├── ideas.md                    # Technical design document
│   ├── CLAUDE.md                   # Development guide
│   └── *.md                        # API documentation
├── CMakeLists.txt                  # Build configuration
└── vcpkg.json                      # Dependencies

Contributing

This project welcomes contributions! Areas of particular interest:

Phase 2B: Batch operations, element caching, table extraction
Phase 3: MCP server implementation, tool schema design
Testing: More integration tests with real SAP systems
Documentation: Usage examples, troubleshooting guides

See CLAUDE.md for development guidelines and ideas.md for the comprehensive technical design.

Security Considerations

Credentials: Never stored in code or config files. Use OS credential managers (Windows Credential Manager support coming in Phase 2B)
Audit Logging: All automation actions logged with user context and timestamps
Authorization: Runs with user's SAP permissions (no privilege escalation)
Network: Supports SAP's SNC (Secure Network Communications)
Scripting: Requires SAP GUI scripting to be enabled (controlled via RZ11 on server side)

Call to Action

Don't wait for Walldorf to deliver AI-powered SAP automation.

SAP professionals: Join us in building tools that respect SAP's complexity while bringing modern AI capabilities
AI enthusiasts: Help us make SAP a first-class citizen in the agent ecosystem
Contributors: Phase 2B is in active development - check the roadmap and pick a feature

Get Involved

🌟 Star the repo to follow development
💬 Join Discussions to share ideas
🐛 Report Issues with detailed diagnostics
📖 Read Technical Design for architecture details
🛠️ Read Development Guide to start contributing

Acknowledgments

Built on foundations that have stood the test of time:

SAP GUI Scripting API: Stable since 2002, used by all major RPA vendors
Model Context Protocol: Anthropic's vision for standardized LLM tool use
RPA Best Practices: Lessons learned from UiPath, Blue Prism, Power Automate

fairyfly doesn't replace what works—it adds what's missing.

License

MIT License - see LICENSE file for details

Ready to bridge the gap between SAP's enterprise stability and AI's transformative potential?

Install now → | Read the vision → | See the roadmap →

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CMakeLists.txt		CMakeLists.txt
Makefile		Makefile
README.md		README.md
vcpkg.json		vcpkg.json

Folders and files

Latest commit

History

Repository files navigation