mcp-twfood: Instructions file for Claude Code

MCP TWFood

Overview

MCP server for twfood.cc — Taiwan agricultural wholesale market price data. 6 AI-callable tools over stdio JSON-RPC 2.0. Public API, no authentication required.

Setup

uv venv && source .venv/bin/activate
uv pip install -e .

Run

python mcp_server.py

Test

# Test connection
python scripts/auth/test_connection.py

# Run all tool tests
python tests/test_all_tools.py

Architecture

stdio (JSON-RPC 2.0)
  → mcp_server.py (entry point, side-effect import triggers tool registration)
    → 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, URL builder)

Key Patterns

• Singleton: app.py creates the FastMCP instance, imported everywhere
• Decorator registration: @mcp.tool() with Pydantic Field() for typed parameters
• Side-effect imports: mcp_server.py imports tool module to trigger registration
• LoopBack filters: Trade APIs use JSON-encoded filter query parameter
• No auth: Public API — auth/none.py returns empty headers

Tools

1. search_products — Search products by name or item code
2. get_daily_trades — Daily trade data (volume, avg/high/low price)
3. get_weekly_trades — Weekly trade summaries
4. get_monthly_trades — Monthly trade summaries
5. get_yearly_trades — Yearly trade summaries (back to 1996)
6. get_market_history — Cross-market volume & price comparison

Code Conventions

• English for all code, docstrings, and tool descriptions
• Use connector helpers — don't call requests directly in tools
• All tools return dict
• Use Pydantic Field() for parameter descriptions and defaults