README.md•4.18 kB
# Turbify Store MCP Server
A Model Context Protocol (MCP) server for managing Turbify Store catalogs. This server provides tools to create, update, delete, and search catalog items through the Turbify Store Catalog API.
## Features
- **Item Management**: Create, update, and delete catalog items
- **Search**: Search through your catalog using keywords
- **Configuration**: View and manage store settings
- **Error Handling**: Comprehensive error handling and reporting
- **Documentation**: Built-in API documentation via MCP resources
## Installation
1. Clone this repository:
```bash
git clone <your-repo-url>
cd turbify-mcp
```
2. Initialize with uv (recommended):
```bash
uv init .
uv add fastmcp pydantic requests urllib3
```
Or install with pip:
```bash
pip install -e .
```
## Configuration
Set the following environment variables:
```bash
export TURBIFY_STORE_ID="your_store_id"
export TURBIFY_CONTRACT_TOKEN="your_contract_token"
```
Or create a `.env` file:
```env
TURBIFY_STORE_ID=your_store_id
TURBIFY_CONTRACT_TOKEN=your_contract_token
```
## Usage
### Running the Server
```bash
python src/turbify_mcp/server.py
```
Or if installed:
```bash
turbify-mcp
```
Using MCP Inspector
```bash
mcp-inspector "python run_server.py"
```
### Available Tools
#### create_catalog_item
Create a new item in your catalog:
```python
create_catalog_item(
item_id="ITEM123",
name="Sample Product",
table_id="TABLE1",
price=29.99,
sale_price=24.99,
orderable="yes",
taxable="yes"
)
```
#### update_catalog_item
Update an existing item:
```python
update_catalog_item(
item_id="ITEM123",
name="Updated Product Name",
price=34.99
)
```
#### delete_catalog_item
Delete an item:
```python
delete_catalog_item(item_id="ITEM123")
```
#### search_catalog_items
Search for items:
```python
search_catalog_items(
keyword="shirt",
start_index=1,
end_index=50
)
```
#### get_store_config
Get current configuration:
```python
get_store_config()
```
## MCP Integration
This server can be used with any MCP-compatible client, such as:
- Claude Desktop
- Custom MCP clients
- Development tools that support MCP
### Claude Desktop Configuration
Add to your Claude Desktop config:
```json
{
"mcpServers": {
"turbify-store": {
"command": "python",
"args": ["path/to/turbify-store-mcp/src/turbify_store_mcp/server.py"],
"env": {
"TURBIFY_STORE_ID": "your_store_id",
"TURBIFY_CONTRACT_TOKEN": "your_contract_token"
}
}
}
}
```
## API Response Format
All tools return JSON responses with the following structure:
### Success Response
```json
{
"status": "success",
"messages": [
{
"code": "SUCCESS",
"message": "Operation completed successfully"
}
],
"items": [...], // For search operations
"item_ids": [...] // For some operations
}
```
### Error Response
```json
{
"status": "error",
"errors": [
{
"code": "ERROR_CODE",
"message": "Error description"
}
]
}
```
## Development
### Setting up for development:
```bash
# Install with development dependencies
uv add --dev pytest pytest-asyncio black mypy
# Run tests
uv run pytest
# Format code
uv run black .
# Type checking
uv run mypy src/
```
### Project Structure
```
turbify-mcp/
├── src/
│ └── turbify_mcp/
│ ├── __init__.py
│ └── server.py
├── tests/
├── pyproject.toml
├── README.md
└── .env
```
## Requirements
- Python 3.8+
- Turbify Store API credentials
- FastMCP
- Pydantic v2
- Requests
## Limitations
- Maximum 1000 items per search query (Turbify API limit)
- Rate limiting as per Turbify Store API terms
- XML-based API (handled internally)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
[Add your license information here]
## Support
For issues related to:
- This MCP server: Create an issue in this repository
- Turbify Store API: Consult Turbify Store API documentation
- MCP protocol: Check the Model Context Protocol specification