Skip to main content
Glama
SoftwareOne Marketplace MCP Server

SoftwareOne Marketplace MCP Server

by marcserrat

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

⚑ 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

Guides

Reference


πŸ§ͺ 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:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests

  5. Submit a pull request


πŸ“„ License

[Add your license here]



πŸ“ž Support

For issues or questions:

  1. Check the Troubleshooting Guide

  2. Review Documentation

  3. Open an issue on GitHub


Made with ❀️ for SoftwareOne

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors