# MCP TWFood

[![PyPI version](https://img.shields.io/pypi/v/mcp-twfood)](https://pypi.org/project/mcp-twfood/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-twfood)](https://pypi.org/project/mcp-twfood/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)
[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-twfood)](https://github.com/asgard-ai-platform/mcp-twfood/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-twfood)](https://github.com/asgard-ai-platform/mcp-twfood/issues)
[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-twfood)](https://github.com/asgard-ai-platform/mcp-twfood/commits/main)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for **twfood.cc** — Taiwan's agricultural wholesale market real-time price data platform. Provides 6 AI-callable tools to search products and query daily, weekly, monthly, yearly trade data and cross-market price comparisons.

[繁體中文](README.zh-TW.md)

## Features

- **6 MCP tools** — Search products, query trade data at 4 time granularities, cross-market comparison
- **No authentication** — Uses public twfood.cc APIs, no credentials needed
- **Historical data** — Yearly summaries back to 1996
- **16+ wholesale markets** — Cross-market volume and price comparison
- **2,000+ products** — Vegetables, fruits, flowers, imported items

## Prerequisites

- Python 3.10+
- No API credentials required (public data)

## Installation

### From PyPI

```bash
pip install mcp-twfood
```

### Using uvx (no install)

```bash
uvx mcp-twfood
```

### From source

```bash
git clone https://github.com/asgard-ai-platform/mcp-twfood.git
cd mcp-twfood
uv venv && source .venv/bin/activate
uv pip install -e .
```

## Quick Start

```bash
# Test connection
python scripts/auth/test_connection.py

# Run all tool tests
python tests/test_all_tools.py

# Start MCP server
python mcp_server.py
```

## Usage

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "twfood": {
      "command": "python",
      "args": ["/path/to/mcp-twfood/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-twfood"
      }
    }
  }
}
```

### Claude Code

The `.mcp.json` file is auto-discovered when you open the project directory.

### Cursor

Add to Cursor MCP settings:

```json
{
  "mcpServers": {
    "twfood": {
      "command": "python",
      "args": ["/path/to/mcp-twfood/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-twfood"
      }
    }
  }
}
```

## Usage Examples

### "What was last week's cabbage price?"

> **You:** 我想知道上週高麗菜的批發價格

**AI calls:**

```
search_products(keyword="高麗菜")
```

Found item code `LA1`. Then:

```
get_weekly_trades(item_code="LA1", start_date="2026/03/24")
```

**Result:** `SUCCESS` — Last week (week 14) cabbage averaged **6.47 TWD/kg**, total volume 4,041,510 kg. Price has been gradually rising from 5.76 in early March.

---

### "Compare cabbage prices across all wholesale markets"

> **You:** 全台各批發市場的高麗菜行情比較

**AI calls:**

```
get_market_history(item_code="LA1")
```

**Result:** `SUCCESS` — Returns volume and price time series for 17 markets. For example, 台北二 averages 7.2 TWD/kg while 西螺鎮 averages 5.1 TWD/kg — regional price differences clearly visible.

---

### "Daily pineapple prices for March"

> **You:** 三月份金鑽鳳梨每天的批發價多少？

**AI calls:**

```
get_daily_trades(item_code="B2", start_date="2026/03/01")
```

**Result:** `SUCCESS` — 33 daily records. March 1: avg 28.02, high 36.75, low 20.02 TWD/kg with volume 126,913 kg. Prices fluctuated between 20–37 TWD/kg range throughout the month.

---

### "How have strawberry prices changed over the years?"

> **You:** 草莓歷年來的價格變化？

**AI calls:**

```
get_yearly_trades(item_code="N1")
```

**Result:** `SUCCESS` — 31 years of data since 1996. Prices rose from ~40 TWD/kg in the early 2000s to 80–98 TWD/kg in recent years (2022: 97.8, 2023: 80.73, 2024: 81.86, 2025: 94.23 TWD/kg).

---

### "Monthly banana market trends"

> **You:** 香蕉近一年的月度走勢

**AI calls:**

```
get_monthly_trades(item_code="A1", start_date="2025/04/01")
```

**Result:** `SUCCESS` — 12 monthly summaries showing seasonal price and volume patterns. Useful for understanding supply cycles and planning purchasing.

---

### "What pineapple varieties are available?"

> **You:** 有哪些鳳梨品種？

**AI calls:**

```
search_products(keyword="鳳梨")
```

**Result:** `SUCCESS` — Found 7 varieties: 鳳梨-開英 (B1), **鳳梨-金鑽鳳梨 (B2)**, 鳳梨-香水鳳梨 (B3), 鳳梨-鳳梨花 (B4), 鳳梨-蜜鳳梨 (B5), 鳳梨-其他 (B9), plus 釋迦-鳳梨釋迦 (32).

---

### "Is garlic expensive right now?"

> **You:** 最近蒜頭貴不貴？幫我查一下

**AI calls:**

```
search_products(keyword="蒜頭")
```

Found 大蒜-蒜頭 with code `SG5`. Then:

```
get_daily_trades(item_code="SG5", start_date="2026/03/01")
```

**Result:** `SUCCESS` — Returns daily prices so you can compare current prices against recent trends and decide whether to buy now or wait.

---

### "Which market has cheapest cabbage?"

> **You:** 哪個批發市場的高麗菜最便宜？

**AI calls:**

```
get_market_history(item_code="LA1")
```

**Result:** `SUCCESS` — AI analyzes the price time series across 17 markets and identifies the markets with consistently lower prices. Southern and central markets (e.g., 西螺鎮, 溪湖鎮) tend to have lower prices than 台北二.

## Tools Reference

| Tool | Description | Parameters |
|------|-------------|------------|
| `search_products` | Search 2,000+ products by name or code | `keyword` |
| `get_daily_trades` | Daily trade data (volume, avg/high/low price) | `item_code`, `start_date` |
| `get_weekly_trades` | Weekly trade summaries | `item_code`, `start_date` |
| `get_monthly_trades` | Monthly trade summaries | `item_code`, `start_date` |
| `get_yearly_trades` | Yearly trade summaries (back to 1996) | `item_code` |
| `get_market_history` | Cross-market volume & price comparison (~17 markets) | `item_code` |

## ItemCode Reference

| Category | Prefix | Example |
|----------|--------|---------|
| Leafy vegetables | `LA` | LA1 (Cabbage/高麗菜) |
| Legumes | `FB` | FB1 |
| Seasonings | `SA` | SA3 |
| Vegetable fruits | `FJ` | FJ3 |
| Stem vegetables | `SB` | SB2 |
| Fruits | Various | A1 (Banana), B2 (Pineapple), P1 (Guava), N1 (Strawberry) |
| Roses | `FR` | FR102 |
| Imported roses | `IR` | IR101 |

Use `search_products` to find the exact item code for any product.

## Architecture

```
stdio (JSON-RPC 2.0)
  → mcp_server.py (entry point)
    → app.py (FastMCP singleton)
      → tools/twfood_tools.py (@mcp.tool() — 6 tools)
        → connectors/rest_client.py (HTTP GET with retry)
          → auth/none.py (no auth — public API)
            → config/settings.py (twfood.cc endpoints)
```

## Publishing to PyPI

This project uses GitHub Actions for automated PyPI publishing.

### Setup (one-time)

1. **PyPI Trusted Publisher** — Go to [pypi.org/manage/account/publishing](https://pypi.org/manage/account/publishing/) and add:
   - PyPI project name: `mcp-twfood`
   - Owner: `asgard-ai-platform`
   - Repository: `mcp-twfood`
   - Workflow name: `publish.yml`
   - Environment name: `pypi`

2. **GitHub Environment** — Repo Settings > Environments > New environment named `pypi`

### Release

```bash
# Tag and create release — triggers publish workflow
gh release create v0.1.0 --title "v0.1.0 - Initial Release" --notes "Initial release with 6 tools for Taiwan agricultural wholesale market data"
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Data Source & Acknowledgements

This MCP server retrieves data from [**twfood.cc (當季好蔬果)**](https://www.twfood.cc/), a Taiwan agricultural wholesale market real-time price data platform that combines big data and data visualization technologies.

- **Website:** https://www.twfood.cc/
- **Data license:** Price-related charts are licensed under [Creative Commons BY-NC-ND 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/)
- **Data source:** Taiwan wholesale market transaction records (vegetables, fruits, flowers)

We sincerely thank the **twfood.cc** team for making this valuable agricultural market data publicly accessible. Their work enables transparency in Taiwan's agricultural wholesale market and benefits farmers, traders, researchers, and consumers.

> **Note:** This project is an independent open-source MCP server and is not officially affiliated with or endorsed by twfood.cc. Please respect the data license terms when using the data retrieved through this server.

## License

MIT License — see [LICENSE](LICENSE) for details.

The MIT license applies to the source code of this MCP server only. The agricultural market data accessed through twfood.cc is subject to its own [CC BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/) license terms.

## Part of the Asgard Ecosystem

This server is part of the [Asgard AI Platform](https://github.com/asgard-ai-platform) open-source ecosystem, connecting AI to real-world services across e-commerce, finance, government data, IoT, social media, and more.