How do I use SoftwareOne Marketplace MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SoftwareOne Marketplace MCP Server show me the top 10 Microsoft products by price" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

SoftwareOne Marketplace MCP Server

Python 3.12+ MCP Protocol RQL Compliant

A Model Context Protocol (MCP) server that provides AI assistants with access to the SoftwareOne Marketplace API. Features full RQL (Resource Query Language) support, intelligent caching, and streamlined tool interface.

🚀 Quick Start

# 1. Clone and setup
git clone <repository-url>
cd mpt-mcp

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp config/env.example .env
# Edit .env with your API credentials

# 5. Start the server
./scripts/start/start_server.sh

See docs/QUICKSTART.md for detailed instructions.

✨ Features

🎯 Streamlined Tool Interface

Single marketplace_query tool instead of 200+ individual tools
Supports all 263 GET endpoints from the SoftwareOne API
Simple resource-based access: catalog.products, commerce.orders, etc.

📊 Full RQL Support

Complete implementation of Resource Query Language
Filtering: eq(), ilike(), and(), or(), not(), in(), out()
Field selection, sorting, pagination
See docs/guides/RQL_GUIDE.md

⚡ Intelligent Caching

24-hour TTL for OpenAPI spec
Fast startup (uses cached spec when available)
Automatic cache refresh
Offline mode support

🔌 Dual Transport Modes

Stdio - Local Cursor integration (single-user) 🏠
SSE - Cloud deployment (multi-tenant capable) ☁️👥
- Intelligent credential handling: client or server credentials
- Case-insensitive header support (X-MPT-Authorization, X-MPT-Endpoint)
See docs/guides/SSE_DEPLOYMENT.md

🚀 Cloud-Ready (SSE Mode)

Docker support with provided Dockerfile
Docker Compose for easy deployment
Multi-tenant capable - Each client uses their own credentials
Flexible fallback - Server credentials when client doesn't provide
CORS configuration for secure remote access
Cloud platform examples (AWS, GCP, Azure, Heroku)
See docs/guides/MULTITENANT_GUIDE.md

📊 Current Stats

9,582 products available in marketplace
263 API endpoints supported
5 tools (vs 200+ with old approach)
24-hour cache TTL

📁 Project Structure

mpt-mcp/
├── README.md                    # You are here
├── requirements.txt             # Python dependencies
├── .env                         # Your configuration (create from config/env.example)
│
├── src/                         # 🔧 Source code
│   ├── server_stdio.py         # Stdio MCP server (local)
│   ├── api_client.py           # API client with RQL support
│   ├── config.py               # Configuration management
│   ├── cache_manager.py        # Caching system
│   └── openapi_parser.py       # OpenAPI spec parser
│
├── scripts/                     # 🛠️ Utility scripts
│   ├── setup/                  # Setup scripts
│   ├── start/                  # Server startup
│   └── utils/                  # Utilities
│
├── tests/                       # 🧪 Tests
│   ├── test_rql.py             # RQL implementation tests
│   ├── test_mcp_json.py        # MCP protocol tests
│   └── test_stdio_server.py    # Server tests
│
├── docs/                        # 📚 Documentation
│   ├── QUICKSTART.md           # Quick start guide
│   ├── setup/                  # Setup guides
│   ├── guides/                 # User guides (RQL, caching, etc.)
│   └── reference/              # Technical reference
│
└── config/                      # ⚙️  Configuration examples
    ├── cursor_mcp_config.json  # Cursor MCP configuration
    └── env.example             # Environment template

🔧 Usage

Query Products

# Get product count
marketplace_query(resource="catalog.products", limit=1)
# Returns: 9,582 products

# Search for Microsoft products
marketplace_query(
    resource="catalog.products",
    rql="ilike(name,*Microsoft*)",
    limit=50
)

# Filter by status
marketplace_query(
    resource="catalog.products",
    rql="eq(status,Published)",
    select="+id,+name,+vendor",
    limit=100
)

Available Resources

# List all available resources
marketplace_resources()

# Get details about a specific resource
marketplace_resource_info(resource="catalog.products")

Cache Management

# Check cache status
marketplace_cache_info()

# Force refresh
marketplace_refresh_cache()

📖 Documentation

Getting Started

Quick Start Guide - Get up and running in minutes
Setup Guide - Detailed setup instructions
Cursor Integration - Use with Cursor AI

Guides

RQL Guide - Complete RQL usage guide
RQL Reference - Quick operator reference
RQL Implementation - Implementation details
Caching Guide - How caching works
SSE Deployment - Cloud deployment guide ☁️
Multi-Tenant Guide - Multiple clients with own credentials 👥

Reference

Architecture - System architecture
Features - Complete feature list
Setup Scripts - Script reference guide

🧪 Testing

# Run all tests
cd /path/to/mpt-mcp

# Test RQL implementation
./venv/bin/python tests/test_rql.py

# Test MCP protocol
./venv/bin/python tests/test_mcp_json.py

# Test server initialization
pytest tests/test_stdio_server.py

# Get current product count
./venv/bin/python scripts/utils/get_product_count.py

🎯 Use Cases

For AI Assistants (via Cursor)

Ask natural language questions:

"How many products are in the SoftwareOne marketplace?"
"Find all Microsoft Office products"
"Show me active orders from the last week"
"Get invoices for customer X"

For Developers

Query the API programmatically:

from src.api_client import APIClient
from src.config import config

client = APIClient(
    base_url=config.marketplace_api_base_url,
    token=config.marketplace_api_token
)

# Query with RQL
result = await client.get(
    "/public/v1/catalog/products",
    params={"rql": "ilike(name,*Microsoft*)", "limit": 50}
)

🔐 Configuration

Create a .env file in the project root:

# Copy the example
cp config/env.example .env

# Edit with your credentials
MARKETPLACE_API_BASE_URL=https://api.s1.show
MARKETPLACE_API_TOKEN=your_token_here
OPENAPI_SPEC_URL=https://api.s1.show/public/v1/openapi.json

See docs/setup/SETUP.md for details.

🐛 Troubleshooting

Server won't start

# Verify setup
./scripts/utils/verify_cursor_setup.sh

# Check environment
source venv/bin/activate
python -c "from src.config import config; config.validate()"

Cursor can't connect

# View logs
./scripts/utils/view_logs.sh

# Or in Cursor: Cmd+Shift+U → Select "MCP: softwareone-marketplace"

See docs/setup/TROUBLESHOOTING.md for more help.

📦 Requirements

Python 3.12+
httpx - Async HTTP client
fastmcp - MCP server framework
pydantic - Data validation
python-dotenv - Environment management

See requirements.txt for complete list.

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

[Add your license here]

🔗 Links

📞 Support

For issues or questions:

Check the Troubleshooting Guide
Review Documentation
Open an issue on GitHub

Made with ❤️ for SoftwareOne

SoftwareOne Marketplace MCP Server

SoftwareOne Marketplace MCP Server

🚀 Quick Start

✨ Features

🎯 Streamlined Tool Interface

📊 Full RQL Support

⚡ Intelligent Caching

🔌 Dual Transport Modes

🚀 Cloud-Ready (SSE Mode)

📊 Current Stats

📁 Project Structure

🔧 Usage

Query Products

Available Resources

Cache Management

📖 Documentation

Getting Started

Guides

Reference

🧪 Testing

🎯 Use Cases

For AI Assistants (via Cursor)

For Developers

🔐 Configuration

🐛 Troubleshooting

Server won't start

Cursor can't connect

📦 Requirements

🤝 Contributing

📄 License

🔗 Links

📞 Support

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API