@manamurah/mcp-server/README.md

MCP Server for ManaMurah Data API - Malaysian price data integration for Claude Desktop and AI tools

# ManaMurah MCP Server

A Model Context Protocol (MCP) server for Malaysian price data from KPDN Pricecatcher. This server enables direct integration with Claude Desktop and other MCP-compatible AI tools for querying Malaysian consumer goods prices.

## Features

🇲🇾 **Daily Malaysian Price Data** - KPDN Pricecatcher data via OpenDOSM  
🤖 **AI-Optimized** - Natural language queries with intelligent parsing  
⚡ **Serverless** - Deployed on Cloudflare Workers for global performance  
🔒 **Rate Limited** - Built-in abuse protection and fair usage  
📊 **Rich Analytics** - Price comparisons, trends, and market insights  

### Settings

```json
{
  "manamurah": {
    "command": "npx",
    "args": ["-y", "@manamurah/mcp-server@latest"]
  }
}
```


## Available Tools

### 🔍 get_malaysian_prices
Search for current prices with natural language queries.

**Examples:**
- "rice prices in Kuala Lumpur"
- "cheapest chicken in Penang hypermarkets"
- "cooking oil under RM20 in Selangor"

### 📊 compare_prices
Compare prices across different regions or retail chains.

**Examples:**
- Harga betik di Selangor
- Compare rice prices between KL and Penang
- Find price differences across retail chains
- Regional price analysis for specific items

### 📈 analyze_price_trends
Analyze price trends and market patterns over time.

**Examples:**
- Price volatility analysis
- Seasonal price patterns
- Regional market trends

### 💡 get_market_insights
Get market intelligence and insights about price anomalies.

**Examples:**
- Recent price changes
- Market anomaly detection
- Regional price differences

## Example Usage

### Basic Price Search
```
User: "What are rice prices in Kuala Lumpur?"

MCP Response:
📊 Summary: Rice prices in Kuala Lumpur range from RM15.20-RM25.80 per 5kg

💡 Key Insights:
• Hypermarkets offer 18% lower prices than convenience stores
• Significant price variation exists across different retailers

📈 Price Statistics:
• Average: RM18.50
• Range: RM15.20 - RM25.80
• Price Variation: 32%

[Detailed price listings follow...]
```

### Price Comparison
```
User: "Compare chicken prices between Penang and Johor"

MCP Response:
📊 Summary: Penang has lower average chicken prices (RM8.20) compared to Johor (RM9.10)

## Regional Comparison

### 1. Penang
• Average Price: RM8.20
• Price Range: RM7.50 - RM9.80
• Sample Size: 15 price points

### 2. Johor
• Average Price: RM9.10
• Price Range: RM8.20 - RM11.50
• Sample Size: 12 price points

💡 Comparison Insights:
• Most Affordable: Penang (RM8.20 average)
• Potential Savings: RM0.90 (9.9%) by choosing Penang
```


## Rate Limits

- **Per Minute**: 10 requests
- **Per Hour**: 100 requests
- **Automatic Cleanup**: Old request data is cleaned up automatically

Rate limits help ensure fair usage and prevent abuse while allowing genuine research and analysis.

## Features

### Natural Language Processing
- Intelligent extraction of items, locations, and price constraints
- Support for Malaysian terms (e.g., "beras" for rice, "ayam" for chicken)
- Price range detection ("under RM20", "between RM10 and RM15")
- Location recognition for all Malaysian states and major cities

### Rich Response Formatting
- Markdown-formatted responses optimized for Claude Desktop
- Statistical analysis with averages, ranges, and insights
- Suggested follow-up questions for continued exploration
- Data source attribution and freshness indicators

### Error Handling
- User-friendly error messages with helpful suggestions
- Graceful degradation when data is unavailable
- Query improvement recommendations
- Comprehensive error logging for debugging

## Data Source

**Official Government Data**: KPDN Pricecatcher program via [OpenDOSM](https://open.dosm.gov.my)

- Daily data updates (subject to government publication schedules)
- Comprehensive coverage of Malaysian retail prices
- Data includes hypermarkets, supermarkets, convenience stores, and grocery shops
- Covers all Malaysian states and major urban centers

## Support

### Getting Help
- **Documentation**: [api.manamurah.com/docs](https://api.manamurah.com/docs)
- **AI Integration Guide**: [Complete guide for AI developers](../docs/ai-integration-guide.md)
- **Issues**: [GitHub Issues](https://github.com/manamurah/mcp-server/issues)

### Contact
- **General Support**: support@manamurah.com
- **AI Integration**: ai-support@manamurah.com
- **Enterprise**: enterprise@manamurah.com

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests for any improvements.

---

**Built with ❤️ for the Malaysian data community**

Making Malaysian price data accessible to AI tools and researchers worldwide.