Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
504 lines (352 loc) · 15.6 KB

GETTING_STARTED.md

File metadata and controls

504 lines (352 loc) · 15.6 KB

Getting Started with Frappe Assistant Core

Welcome to Frappe Assistant Core! This guide will walk you through everything you need to know to start using AI with your ERPNext system.

📋 What You'll Learn

  • How to install and configure Frappe Assistant Core
  • Connect with Claude Desktop or other AI tools
  • Basic usage patterns and commands
  • Advanced features and customization
  • Troubleshooting common issues

🎯 Prerequisites

Before we begin, make sure you have:

  • ERPNext/Frappe: Version 15+ installed and running
  • Python: Version 3.11+
  • Database: MariaDB or MySQL properly configured
  • Admin Access: Ability to install apps and modify configurations
  • AI Tool: Claude Desktop, Claude API access, or other MCP-compatible AI

🚀 Step 1: Installation

Quick Installation

The fastest way to get started:

# Navigate to your Frappe bench directory
cd /path/to/your/frappe-bench

# Download the app
bench get-app https://github.com/buildswithpaul/Frappe_Assistant_Core

# Install on your site (replace 'yoursite' with your actual site name)
bench --site yoursite install-app frappe_assistant_core

# Run database migrations
bench --site yoursite migrate

Verify Installation

Check that everything installed correctly:

# Check if app is installed
bench --site yoursite list-apps

# Start your site
bench start

You should see frappe_assistant_core in the list of installed apps.

⚙️ Step 2: Configuration

Enable the Assistant

# Enable the assistant system
bench --site yoursite set-config assistant_enabled 1

# Restart your site to apply changes
bench restart

Set Up User Permissions

  1. Login to ERPNext as Administrator
  2. Go to User Management: Desk → Users → [Your User]
  3. Add Roles: Assign "Assistant User" or "Assistant Admin" role
  4. Enable Assistant: Check the "Assistant Enabled" field for the user
  5. Save the user record

Generate API Credentials

For secure authentication, generate API keys:

  1. Go to your User Profile
  2. API Access section
  3. Generate Keys - Note down the API Key and API Secret
  4. Keep these secure - You'll need them for AI integration

🤖 Step 3: Connect with AI

Choose the AI tool that works best for your workflow:

Option Best For Setup Difficulty OAuth Support
Claude Desktop Desktop users, developers ⭐ Easy (UI-based) ✅ Full OAuth 2.0
ChatGPT Web users, team collaboration ⭐ Easy (UI-based) ✅ Full OAuth 2.0
MCP Inspector Testing, debugging ⭐⭐ Moderate ✅ Full OAuth 2.0
Custom App Embedded integration ⭐⭐⭐ Advanced ✅ Full OAuth 2.0

Option A: Claude Desktop with OAuth (Recommended for Desktop)

Connect Claude Desktop using modern OAuth 2.0 authentication:

1. Enable OAuth in Assistant Core Settings

  • Login to ERPNext as Administrator
  • Go to: Setup → Integrations → Assistant Core Settings
  • OAuth Tab:
    • ✅ Check "Show Authorization Server Metadata"
    • ✅ Check "Enable Dynamic Client Registration"
    • ✅ Check "Show Protected Resource Metadata"
  • Save

2. Configure Claude Desktop

Option A: Using Claude Desktop UI (Recommended - Easiest)

The easiest way to connect is through Claude Desktop's built-in connector interface:

  1. Open Claude Desktop
  2. Click on the integrations/settings icon
  3. Navigate to: Custom Connectors or MCP Servers section
  4. Click: "Add Custom Connector" or "+" button
  5. Fill in the connection details:
    • Name: Frappe Assistant (or any name you prefer)
    • Transport Type: Select StreamableHTTP
    • Server URL: https://your-site.com/api/method/frappe_assistant_core.api.fac_endpoint.handle_mcp
    • Authentication: Select OAuth 2.0
    • OAuth Discovery URL: https://your-site.com/.well-known/openid-configuration
  6. Save the connector
  7. Authorize when prompted (Claude will open your browser)

Replace your-site.com with your actual Frappe site URL.

💡 Tip: This UI-based approach is much easier than editing configuration files manually and is available in recent versions of Claude Desktop.

Option B: Manual Configuration File

If you prefer manual configuration or your Claude Desktop version doesn't have the UI:

File Locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "frappe-assistant": {
      "url": "https://your-site.com/api/method/frappe_assistant_core.api.fac_endpoint.handle_mcp",
      "transport": "streamablehttp",
      "oauth": {
        "discoveryUrl": "https://your-site.com/.well-known/openid-configuration",
        "clientName": "Claude Desktop"
      }
    }
  }
}

Replace your-site.com with your actual Frappe site URL.

3. Authorize Claude Desktop (if not done in UI)

  1. Restart Claude Desktop
  2. Start a new conversation
  3. When prompted, Claude will open your browser
  4. Login to Frappe and authorize Claude Desktop
  5. Return to Claude Desktop - you're connected!

What Happens Behind the Scenes:

  • Claude discovers your OAuth configuration automatically
  • Registers as an OAuth client (if dynamic registration enabled)
  • Requests your authorization
  • Stores and manages access tokens
  • Automatically refreshes tokens when they expire

📖 See detailed OAuth flow documentation

Option B: MCP Inspector for Testing

Test your setup with the MCP Inspector tool:

1. Enable Browser-Based Clients

  • Go to: Assistant Core Settings → OAuth Tab
  • Add to "Allowed Public Client Origins": http://localhost:6274
  • Save

2. Use MCP Inspector

  1. Open: http://localhost:6274/
  2. Select: "Streamable HTTP" transport
  3. Enter URL: https://your-site.com/api/method/frappe_assistant_core.api.fac_endpoint.handle_mcp
  4. Click: "Open Auth Settings"
  5. Click: "Quick OAuth Flow"
  6. Authorize when prompted

You can now test tools and see MCP requests/responses!

Option C: ChatGPT Integration

ChatGPT also supports custom MCP connectors with OAuth authentication:

1. Enable OAuth (Same as Claude Desktop)

Make sure OAuth is enabled in Assistant Core Settings (see Step 1 above).

2. Add Custom Action in ChatGPT

Using ChatGPT UI:

  1. Open ChatGPT (chatgpt.com)
  2. Go to: Settings → Custom Actions (or GPT Builder)
  3. Click: "Create Custom Action" or "Add Action"
  4. Select: MCP Protocol / Custom Connector
  5. Fill in the connection details:
    • Name: Frappe Assistant (or any name you prefer)
    • Transport: StreamableHTTP or HTTP
    • Endpoint URL: https://your-site.com/api/method/frappe_assistant_core.api.fac_endpoint.handle_mcp
    • Authentication: Select OAuth 2.0
    • OAuth Discovery URL: https://your-site.com/.well-known/openid-configuration
  6. Save and Authorize when prompted

Replace your-site.com with your actual Frappe site URL.

💡 Note: ChatGPT's MCP support may vary by subscription tier. Custom actions are typically available for ChatGPT Plus, Team, and Enterprise users.

3. Test the Connection

Once authorized, you can use ChatGPT to interact with your Frappe data:

  • "List my customers in Frappe"
  • "Create a sales order for customer ABC"
  • "Show me this month's sales report"

📖 See ChatGPT integration details (coming soon)

Option D: Custom Application Integration

For custom applications or other MCP clients, see the complete OAuth integration example in our MCP StreamableHTTP Guide.

Quick Example:

import requests

# 1. Discover OAuth endpoints
config = requests.get(
    "https://your-site.com/.well-known/openid-configuration"
).json()

# 2. Perform OAuth flow (see full example in guide)
# ... authorization code flow with PKCE ...

# 3. Make authenticated MCP requests
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

response = requests.post(
    config["mcp_endpoint"],
    headers=headers,
    json={
        "jsonrpc": "2.0",
        "method": "tools/list",
        "params": {},
        "id": 1
    }
)
print(response.json())

🔄 Migrating from STDIO Bridge?

If you're upgrading from an older version that used the STDIO bridge, see our Migration Guide for step-by-step instructions.

🎉 Step 4: Test Your Setup

Basic Test Commands

Once connected, try these commands with your AI:

1. Check Connection

"Can you connect to my ERPNext system? Show me the server status."

2. Simple Document Query

"How many customers do I have in the system?"

3. Create a Test Document

"Create a test customer called 'AI Test Customer' with email 'test@ai.com'"

4. Data Analysis

"Show me a summary of sales invoices from this month"

Expected Responses

If everything is working, you should see:

✅ Connection Successful: AI responds with system information
✅ Data Access: AI can read your ERPNext data
✅ Document Creation: AI can create and modify documents
✅ Analysis Capabilities: AI can analyze and report on your data

📄 Step 5: Configure OCR (Optional)

Frappe Assistant Core includes built-in OCR for extracting text from scanned documents and images. Two backends are available:

Option A: PaddleOCR (Default - No Extra Setup)

PaddleOCR works out of the box. It runs locally and supports 80+ languages. No configuration needed — it's the default backend.

Option B: Ollama Vision (AI-Powered OCR)

For better document understanding and complex layouts, you can use an Ollama vision model:

1. Install Ollama

# Install Ollama (Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Pull a vision model for OCR
ollama pull deepseek-ocr

2. Configure in Assistant Core Settings

  1. Login to ERPNext as Administrator
  2. Go to: Setup → Integrations → Assistant Core Settings
  3. OCR Tab:
    • OCR Backend: Select ollama
    • Ollama API URL: http://localhost:11434 (default)
    • Ollama Vision Model: deepseek-ocr:latest
    • Request Timeout: 120 seconds
  4. Save

3. Test OCR

Try extracting text from a scanned document:

"Extract the text from the uploaded invoice PDF" "OCR this scanned document image"

How it works: When Ollama is selected, the system sends document images to the Ollama vision model for text extraction. If Ollama fails or returns empty results, it automatically falls back to PaddleOCR.

OCR Language Support

Set the default OCR language in Assistant Core Settings. Common language codes:

  • en - English (default)
  • fr - French
  • de - German
  • es - Spanish
  • ch - Chinese (Simplified)
  • japan - Japanese

You can also specify the language per-request when calling the extract_file_content tool.

🎯 Understanding Core Capabilities

Document Operations

📝 CREATE: "Create a new customer named Acme Corp"
📖 READ: "Show me customer details for CUST-00001"
✏️ UPDATE: "Update the customer's phone number to +1234567890"
🗑️ DELETE: "Delete the test customer record"
📋 LIST: "List all customers created this week"

Search & Discovery

🔍 GLOBAL SEARCH: "Find all documents mentioning 'bulk order'"
🎯 TARGETED SEARCH: "Search for sales orders above $10,000"
📊 FILTERED SEARCH: "Show me pending purchase orders from this month"

Analytics & Reporting

📊 CHARTS: "Create a bar chart of monthly sales"
📈 ANALYSIS: "Analyze our top 10 customers by revenue"
📋 REPORTS: "Run the Sales Analytics report for Q4"
🔢 CALCULATIONS: "Calculate total revenue for this year"

Advanced Features

🐍 PYTHON CODE: "Execute Python code to analyze inventory trends"
📊 DASHBOARDS: "Create a dashboard showing key sales metrics"
🔄 WORKFLOWS: "Submit all pending sales orders for approval"

🔧 Customization Options

Plugin Management

Access the admin interface to manage plugins:

URL: https://yoursite.com/desk#/fac-admin

Available plugins:

  • Core (always enabled): Document operations, search, reports
  • Data Science: Python execution, statistical analysis
  • Visualization: Charts, dashboards, KPIs
  • Batch Processing: Bulk operations

Custom Tools

Create your own tools for specific business needs:

  1. External App Tools (Recommended): Add tools to your existing Frappe apps
  2. Plugin Development: Create internal plugins within the core system

See Development Guide for details.

🚨 Troubleshooting

Common Issues

Connection Problems

Problem: AI can't connect to ERPNext Solution:

  • Check API credentials are correct
  • Verify site URL is accessible
  • Ensure assistant_enabled = 1 in configuration
  • Check firewall settings

Permission Errors

Problem: "Access denied" or "Permission denied" Solution:

  • Add "Assistant User" role to your user
  • Enable "Assistant Enabled" field on user record
  • Check DocType permissions are properly configured

Tool Not Found Errors

Problem: "Tool 'xyz' not found" Solution:

  • Check which plugins are enabled
  • Verify plugin contains the required tool
  • Restart system after enabling plugins

Performance Issues

Problem: Slow responses or timeouts Solution:

  • Check database performance
  • Enable caching in Frappe configuration
  • Consider upgrading server resources
  • Review plugin configurations

Getting Help

If you're still having issues:

  1. Check Documentation: Review Technical Documentation
  2. Community Support: Post in GitHub Discussions
  3. Report Bugs: Use GitHub Issues
  4. Enterprise Support: Contact jypaulclinton@gmail.com for priority support

🎓 Next Steps

Now that you're up and running:

  1. Explore Tools: Try different commands and see what the AI can do
  2. Learn Advanced Features: Check out Tool Reference
  3. Customize: Create custom tools for your specific business needs
  4. Monitor: Set up audit logging and monitoring
  5. Scale: Consider performance optimization as you grow

💡 Tips for Success

Best Practices

  • Start Simple: Begin with basic document operations before complex analytics
  • Use Specific Commands: Clear, specific requests get better results
  • Test Thoroughly: Always verify AI-generated data and operations
  • Monitor Usage: Keep an eye on audit logs and system performance
  • Stay Updated: Regular updates bring new features and improvements

Common Use Cases

  • Sales Team: Customer management, opportunity tracking, quote generation
  • Finance: Invoice processing, payment tracking, financial reporting
  • Operations: Inventory management, purchase order automation
  • Management: Dashboard creation, KPI monitoring, executive reporting
  • IT: Custom workflows, data integration, system monitoring

🎉 Congratulations! You're now ready to transform your ERP operations with AI assistance.

Questions? Check our comprehensive documentation or reach out to the community.

Happy AI-powered ERPing! 🚀
⚡