内容
# Umbraco Commerce MCP Server
> **⚠️ Work in Progress**
> This project is currently a proof of concept and under active development. Features and APIs may change significantly before the first stable release.
A Model Context Protocol (MCP) server that provides AI tools for interacting with Umbraco Commerce APIs. This server acts as a bridge between AI assistants and Umbraco Commerce functionality, enabling operations like order management, analytics, discount management, and user administration.
## Getting Started
### Prerequisites
- Node.js >= 22.0.0
- Running Umbraco instance with Commerce
- OAuth2 client credentials for Umbraco back-office API access
### Installation
```bash
npm install
```
### Authentication Setup
The server uses OAuth2 client credentials flow with automatic token refresh:
1. Create an API user in your Umbraco back-office following the [Umbraco API Users documentation](https://docs.umbraco.com/umbraco-cms/fundamentals/data/users/api-users)
2. Ensure the API user has access to the Commerce/Settings sections
3. Note the client ID and secret for configuration
### Configuration
1. Create `.env` file:
```bash
cp .env.example .env
```
2. Configure environment variables:
```env
UMBRACO_CLIENT_ID=your_oauth_client_id
UMBRACO_CLIENT_SECRET=your_oauth_client_secret
UMBRACO_BASE_URL=https://your-umbraco-site.com
```
3. Build the server:
```bash
npm run build
```
## Using with Claude Desktop
This MCP server is designed to work with Claude Desktop and other MCP-compatible clients.
### Claude Desktop Configuration
1. **Add to Claude Desktop config**:
Open your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
2. **Add the MCP server configuration**:
```json
{
"mcpServers": {
"umbraco-commerce": {
"command": "node",
"args": ["/path/to/Umbraco.Commerce.Mcp/build/index.js"],
"env": {
"UMBRACO_CLIENT_ID": "your_oauth_client_id",
"UMBRACO_CLIENT_SECRET": "your_oauth_client_secret",
"UMBRACO_BASE_URL": "https://your-umbraco-site.com"
}
}
}
}
```
3. **Restart Claude Desktop** to load the MCP server
### Example Conversations
Once configured, you can interact with your Umbraco Commerce store through Claude:
- *"Show me recent orders from the last week"*
- *"What products are running low on stock?"*
- *"Create a 20% discount for everything in September"*
- *"How many orders did we get yesterday?"*
- *"Find orders from customers with email containing '@company.com'"*
### Troubleshooting
- Ensure your Umbraco instance is accessible from Claude Desktop
- Verify your OAuth2 credentials have Commerce section access
- Check the Claude Desktop logs for connection errors
- Use `npm run inspect` for debugging the MCP server
## Development
### Project Structure
```
src/
├── features/ # Domain-organized features
│ ├── analytics/ # Analytics and reporting tools
│ ├── discounts/ # Discount management tools
│ ├── orders/ # Order management tools
│ ├── stores/ # Store statistics and management
│ ├── ... # Other features to come
│ └── umbraco/users/ # User session management
├── common/ # Shared utilities and types
│ ├── mcp/tools/ # MCP tool framework
│ ├── session/ # Session management
│ └── types/ # Common type definitions
└── infrastructure/ # External integrations
└── umbraco-commerce/ # Auto-generated API client
```
### Available Commands
```bash
# Development
npm run build # Build TypeScript
npm run start # Build and start server
npm run inspect # Start with MCP inspector
# API Generation
npm run generate:api # Generate API client from OpenAPI spec
# Testing
npm run test:tools # Test tools using YAML files
npm run test:compliance # Run MCP compliance tests
```
### API Integration
The project uses an auto-generated API client from Umbraco Commerce's Management API specification. To regenerate the client:
```bash
npm run generate:api
```
This requires a running Umbraco instance.
### Creating New Tools
1. Create a tool file in the appropriate feature directory:
```typescript
// src/features/example/tools/my-tool.ts
import { z } from "zod";
import type { ToolDefinition } from "../../../common/mcp/tools/tool-definition.js";
const paramsSchema = z.object({
param1: z.string().describe("Description of parameter")
});
export default {
name: "my_tool",
description: "Tool description with usage examples",
paramsSchema: paramsSchema.shape,
canAccess: (session) => session.hasAccessToSection("commerce"),
execute: async (args, context) => {
// Tool implementation
return createJsonResult({ success: true });
}
} satisfies ToolDefinition<typeof paramsSchema.shape>;
```
2. Tools are automatically discovered from `src/features/*/tools/*{.,-}tool.{js,ts}` files
### Testing
Testing is done using [mcp-server-tester](https://github.com/steviec/mcp-server-tester). Create YAML test files in the `tests/` directory:
```yaml
tools:
expected_tool_list: ['search_orders', 'get_order']
tests:
- name: 'Search orders test'
tool: 'search_orders'
params:
storeId: 'default'
take: 10
expect:
success: true
```
Run tests with:
```bash
npm run test:tools
```
See the [mcp-server-tester documentation](https://github.com/steviec/mcp-server-tester) for more details on test configuration and options.
### Development & Planning
This project is guided by real-world use cases and requirements. Development documentation includes:
- **[Use Cases](docs/use-cases.md)** - Store owner scenarios and essential MCP endpoints
- **[Commerce API Improvements](docs/commerce-api-improvements.md)** - Proposed enhancements to Umbraco Commerce APIs for better AI integration
- **[Project Considerations](docs/project-considerations.md)** - Strategic decisions and long-term project viability
These documents help guide feature development and identify areas where Umbraco Commerce APIs may need enhancement to better support AI-driven interactions.
## License
This MCP server is MIT licensed. However, it requires Umbraco Commerce, which is a commercially licensed product by Umbraco A/S. You will need a valid Umbraco Commerce license to use this tool with a production Umbraco instance.
