# SoftwareOne Marketplace MCP Server

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)
[![RQL Compliant](https://img.shields.io/badge/RQL-compliant-success.svg)](https://docs.platform.softwareone.com/developer-resources/rest-api/resource-query-language)

A **Model Context Protocol (MCP)** server that provides AI assistants with access to the [SoftwareOne Marketplace API](https://docs.platform.softwareone.com/). Features full RQL (Resource Query Language) support, intelligent caching, and streamlined tool interface.

---

## 🚀 Quick Start

```bash
# 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](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](https://docs.platform.softwareone.com/developer-resources/rest-api/resource-query-language)
- Filtering: `eq()`, `ilike()`, `and()`, `or()`, `not()`, `in()`, `out()`
- Field selection, sorting, pagination
- See **[docs/guides/RQL_GUIDE.md](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](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](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

```python
# 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

```python
# List all available resources
marketplace_resources()

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

### Cache Management

```python
# Check cache status
marketplace_cache_info()

# Force refresh
marketplace_refresh_cache()
```

---

## 📖 Documentation

### Getting Started
- **[Quick Start Guide](docs/QUICKSTART.md)** - Get up and running in minutes
- **[Setup Guide](docs/setup/SETUP.md)** - Detailed setup instructions
- **[Cursor Integration](docs/setup/CURSOR_SETUP.md)** - Use with Cursor AI

### Guides
- **[RQL Guide](docs/guides/RQL_GUIDE.md)** - Complete RQL usage guide
- **[RQL Reference](docs/guides/RQL_REFERENCE.md)** - Quick operator reference
- **[RQL Implementation](docs/guides/RQL_IMPLEMENTATION.md)** - Implementation details
- **[Caching Guide](docs/guides/CACHING.md)** - How caching works
- **[SSE Deployment](docs/guides/SSE_DEPLOYMENT.md)** - Cloud deployment guide ☁️
- **[Multi-Tenant Guide](docs/guides/MULTITENANT_GUIDE.md)** - Multiple clients with own credentials 👥

### Reference
- **[Architecture](docs/reference/ARCHITECTURE.md)** - System architecture
- **[Features](docs/reference/FEATURES.md)** - Complete feature list
- **[Setup Scripts](docs/SETUP_SCRIPTS.md)** - Script reference guide

---

## 🧪 Testing

```bash
# 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:
```python
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:

```bash
# 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](docs/setup/SETUP.md)** for details.

---

## 🐛 Troubleshooting

### Server won't start
```bash
# 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
```bash
# View logs
./scripts/utils/view_logs.sh

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

See **[docs/setup/TROUBLESHOOTING.md](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]

---

## 🔗 Links

- **[SoftwareOne Marketplace](https://www.softwareone.com/)**
- **[SoftwareOne API Docs](https://docs.platform.softwareone.com/)**
- **[Model Context Protocol](https://modelcontextprotocol.io/)**
- **[RQL Documentation](https://docs.platform.softwareone.com/developer-resources/rest-api/resource-query-language)**

---

## 📞 Support

For issues or questions:

1. Check the **[Troubleshooting Guide](docs/setup/TROUBLESHOOTING.md)**
2. Review **[Documentation](docs/)**
3. Open an issue on GitHub

---

**Made with ❤️ for SoftwareOne**