mcp-tw-company: Instructions file for Claude Code

MCP Taiwan Company Registry

Overview

MCP server for Taiwan company registry open data (GCIS). Exposes AI-callable tools over stdio JSON-RPC 2.0. Part of the Asgard open-source ecosystem.

Setup

# Prerequisite: Python 3.14.x
uv sync

Run

uv run python mcp_server.py

Test

# Test connection
uv run python scripts/auth/test_connection.py

# Run all tool tests
uv run python tests/test_all_tools.py

Architecture

stdio (JSON-RPC 2.0)
  → mcp_server.py (entry point, side-effect imports trigger tool registration)
    → app.py (FastMCP singleton)
      → tools/company_registry_tools.py (@mcp.tool() decorated functions)
        → connectors/rest_client.py (HTTP REST with retry + pagination)
          → auth/none.py (no auth — public API)
            → config/settings.py (GCIS 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 modules to trigger registration
• REST connector: connectors/rest_client.py — retry, pagination, TLS workaround for GCIS
• No-auth: auth/none.py — GCIS is a public open data API

Adding a New Tool

1. Choose the appropriate tool module in tools/ (or create a new one)
2. Import your connector: from connectors.rest_client import api_get
3. Write the tool function with @mcp.tool() decorator
4. Add the module import in mcp_server.py (if new module)
5. Add a test in tests/test_all_tools.py

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