README.mdā¢6.59 kB
# 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
š²š¾ **Official 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
šÆ **Claude Desktop Ready** - One-click setup for Claude Desktop integration
## Live Demo
The MCP server is deployed and accessible at:
- **Production**: https://mcp.manamurah.com
- **API Endpoint**: https://mcp.manamurah.com/mcp
- **Status**: https://mcp.manamurah.com/ (returns server info)
## Quick Start
### Deploy to Cloudflare Workers
```bash
# Clone or create from template
npm create cloudflare@latest manamurah-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless
# Replace src/ contents with ManaMurah implementation
# (Copy files from this directory)
# Install dependencies
npm install
# Deploy to Cloudflare Workers
npm run deploy
```
### Connect to Claude Desktop
1. Get your deployed Workers URL (e.g., `https://mcp.manamurah.com`)
2. Add to Claude Desktop MCP configuration:
```json
{
"manamurah": {
"command": "node",
"args": ["/path/to/mcp-client.js"],
"env": {
"MCP_SERVER_URL": "https://mcp.manamurah.com/sse"
}
}
}
```
3. Restart Claude Desktop
4. Start asking about Malaysian prices!
## 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:**
- 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
```
## Development
### Local Development
```bash
# Install dependencies
npm install
# Start development server
npm run dev
# Type checking
npm run type-check
# Linting
npm run lint
```
### Project Structure
```
src/
āāā index.ts # Main MCP server implementation
āāā utils/
ā āāā api-client.ts # ManaMurah API client
ā āāā query-parser.ts # Natural language query parsing
ā āāā response-formatter.ts # MCP response formatting
ā āāā rate-limiter.ts # Rate limiting implementation
āāā types/
āāā manamurah.ts # TypeScript type definitions
```
### Configuration
Environment variables in `wrangler.toml`:
```toml
[vars]
MANAMURAH_API_BASE = "https://api.manamurah.com"
RATE_LIMIT_ENABLED = "true"
CACHE_TTL = "300"
MAX_QUERIES_PER_MINUTE = "10"
MAX_QUERIES_PER_HOUR = "100"
```
## 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/api/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.