1.0.6 • Published 8 months ago

@cactus-digital-sa/mcp-softone-erp v1.0.6

Weekly downloads
-
License
SEE LICENSE IN LI...
Repository
github
Last release
8 months ago

MCP SoftOne ERP Server (@cactus-digital-sa/mcp-softone-erp)

A Model Context Protocol (MCP) server for integrating with SoftOne ERP API, providing comprehensive ERP data access and analysis capabilities.

Features

  • Authentication: Secure login and session management with SoftOne ERP
  • Character Encoding: Automatic Windows-1253 to UTF-8 conversion for Greek text
  • Data Discovery: Explore ERP objects, tables, and fields structure
  • Data Retrieval: Get records, browse data lists, and generate reports
  • Data Operations: Insert, update, delete, and calculate ERP records
  • Business Intelligence: Built-in prompts for customer, sales, inventory, and financial analysis
  • Resources: Access to API documentation and database schema

Installation MCP SoftOne

Claude Desktop

To use this with Claude Desktop, add the following to your claude_desktop_config.json. The full path on MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json, on Windows: %APPDATA%/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "softone-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@cactus-digital-sa/mcp-softone-erp"
      ]
    }
  }
}

VS Code

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

{
  "servers": {
    "softone-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cactus-digital-sa/mcp-softone-erp"]
    }
  }
}

Cursor

Install in Cursor Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

{
  "mcpServers": {
    "softone-mcp": {
      "command": "npx",
      "args": ["-y", "@cactus-digital-sa/mcp-softone-erp"]
    }
  }
}

Usage

Authentication

First, authenticate with your SoftOne ERP system using the login tool:

{
  "registeredName": "your-company",
  "username": "your-username", 
  "password": "your-password",
  "appId": "your-app-id"
}

Available Tools

Authentication

  • login - Authenticate with SoftOne ERP system

Data Discovery

  • getObjects - Get all available ERP objects
  • getObjectTables - Get tables for a specific object
  • getTableFields - Get fields for a table

Data Retrieval

  • getData - Get specific record data by primary key
  • getBrowserInfo - Initialize browser query for data lists
  • getBrowserData - Get browser query results with pagination

Data Operations

  • calculate - Calculate field values and business logic
  • setData - Insert or update records (not implemented in current version)
  • delData - Delete records (not implemented in current version)

Convenience Tools

  • lookupCustomer - Search customers by code, name, or tax ID
  • lookupSales - Search sales documents by date range and optional customer

Debug Tools

  • debugEncoding - Test character encoding conversion (Windows-1253 → UTF-8)

Character Encoding

The server automatically converts responses from Windows-1253 (Greek encoding) to UTF-8, similar to PHP's:

iconv('Windows-1253', "UTF-8//TRANSLIT//IGNORE", $text)

This ensures proper display of Greek characters in customer names, addresses, product descriptions, and other text fields from SoftOne ERP.

Testing Encoding

You can test the encoding conversion with:

# Basic encoding test
npm run test-encoding

# Real-world SoftOne ERP encoding test  
npm run test-encoding-real

# Or run directly
node encoding-test.js
node real-world-encoding-test.js

Or use the debug tool:

await debugEncoding({ testString: "Test Greek text from SoftOne" });

Available Resources

  • blackbook://api-documentation - Complete SoftOne API documentation
  • s1schema://database-schema - Database schema and structure

Business Analysis Prompts

  • analyze-customers - Comprehensive customer data analysis
  • analyze-sales - Sales performance and trends analysis
  • analyze-inventory - Inventory optimization analysis
  • analyze-financials - Financial performance analysis

Configuration

The server connects to SoftOne ERP systems hosted at https://{registeredName}.oncloud.gr.

Authentication Parameters

  • registeredName: Your company's registered name in SoftOne Cloud
  • username: Your SoftOne Web Accounts username
  • password: Your SoftOne Web Accounts password
  • appId: Service ID defined in SoftOne Web Accounts

Requirements

  • Node.js 18+
  • Valid SoftOne ERP credentials
  • Network access to SoftOne cloud services

Error Handling

The server provides comprehensive error handling for:

  • Authentication failures
  • API connectivity issues
  • Data validation errors
  • Permission restrictions

API Reference

SoftOne ERP Integration

This server integrates with the SoftOne ERP Web Services API, providing access to:

  • Customer management and CRM data
  • Sales document processing and reporting
  • Inventory management and stock control
  • Financial reporting and analysis
  • Custom object manipulation and calculations

Filter Syntax

When using browser queries, you can apply filters using SoftOne's filter syntax:

  • FIELD=value - Exact match
  • FIELD=value* - Starts with match
  • FIELD1=value1&FIELD2=value2 - Multiple conditions (AND)
  • FIELD1=value1|FIELD2=value2 - Alternative conditions (OR)

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Privacy & Analytics

This software includes optional, anonymous usage analytics to help identify potential commercial usage patterns for license compliance.

What is collected:

  • Anonymous session ID (machine fingerprint)
  • Platform information (OS, architecture)
  • Environment indicators (production/development)
  • Session duration

What is NOT collected:

  • Personal information
  • Business data or ERP content
  • IP addresses or location data
  • Specific usage patterns or data

Opt-out:

export DISABLE_ANALYTICS=true
# or
DISABLE_ANALYTICS=true npx @mcp-servers/softone-erp

All analytics help us understand usage patterns while maintaining your privacy and helping ensure license compliance.

Licensing

This software is available under a dual-license model:

🆓 Non-Commercial Use (Free)

  • ✅ Personal projects and learning
  • ✅ Open source projects
  • ✅ Academic research and education
  • ✅ Non-profit organizations
  • ✅ Evaluation and testing

💼 Commercial Use (Paid License Required)

  • ❌ For-profit companies and organizations
  • ❌ Production use in business environments
  • ❌ Revenue-generating applications
  • ❌ Organizations with more than 5 employees
  • ❌ Commercial products and services

License Compliance Checker

Not sure if you need a commercial license? Use our compliance checker:

# After installing the package
npx softone-erp-license-check

# Or if installed globally
softone-erp-license-check

This interactive tool will help you determine if your usage requires a commercial license.

Support

For issues and questions:

  • Create an issue on GitHub
  • Check the API documentation resource
  • Review the database schema resource
  • Consult the SoftOne ERP documentation

Changelog

1.0.6

  • Initial release
  • Authentication and session management
  • Data discovery and retrieval tools
  • Customer and sales lookup functions
  • Business analysis prompts
  • Resource access for documentation and schema
mcpmodel-context-protocolsoftoneerpapiintegrationbusinessaccounting
@modelcontextprotocol/sdkaxioszodiconv-lite
1.0.6

8 months ago

1.0.5

8 months ago

1.0.4

8 months ago

1.0.3

8 months ago

1.0.2

8 months ago

1.0.1

8 months ago

1.0.0

8 months ago