mcp-tdcc: Instructions file for Claude Code

MCP TDCC Server

Overview

MCP Server for TDCC (Taiwan Depository & Clearing Corporation) OpenData. Provides 8 AI-callable tools for querying Taiwan securities custody open data via stdio JSON-RPC 2.0.

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, imports tools/tdcc_tools)
    → app.py (FastMCP singleton)
      → tools/tdcc_tools.py (@mcp.tool() — 8 tools with client-side filtering)
        → connectors/rest_client.py (GET requests + BOM stripping + retry)
          → auth/none.py (no auth — public API)
            → config/settings.py (100+ TDCC endpoint paths)

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 tools.tdcc_tools to trigger registration
• No auth: TDCC OpenData is public — uses auth/none.py
• BOM stripping: Connector strips \ufeff from API response field names
• Client-side filtering: Tools fetch full datasets and filter locally by stock code/name
• _val() helper: Handles FieldInfo defaults when tools are called directly (not via MCP)

Adding a New Tool

1. Add the tool function in tools/tdcc_tools.py with @mcp.tool() decorator
2. Use api_get("endpoint-id") from connectors/rest_client.py
3. Add client-side filtering with _filter_by_code() / _filter_by_name()
4. Add a test in tests/test_all_tools.py

Code Conventions

• English for all code, docstrings, and tool descriptions
• Use api_get() from connector — don't call requests directly in tools
• All tools return dict with total and data keys
• Use _val() helper for optional parameters with Field(default=None)
• Use Pydantic Field() for parameter descriptions