体育数据可视化服务

test-mcp-server/
├── server/                      # Python FastMCP server (Modularized!)
│   ├── main.py                 # Entry point (32 lines!)
│   ├── config.py               # Configuration (Pydantic BaseSettings)
│   ├── errors.py               # Error definitions
│   ├── logging_config.py       # Logging setup
│   ├── models/                 # Domain models
│   │   ├── widget.py          # Widget dataclass
│   │   ├── tool.py            # ToolDefinition (has_widget property)
│   │   └── schemas.py         # Pydantic schemas
│   ├── services/               # Business logic
│   │   ├── asset_loader.py    # HTML asset loading
│   │   ├── widget_registry.py # Widget registry
│   │   ├── tool_registry.py   # Tool registry
│   │   ├── cache.py           # TTL cache for API responses
│   │   └── sports/            # Modular Sports API (Phase 6)
│   │       ├── __init__.py    # SportsClientFactory
│   │       ├── base/          # Base classes
│   │       │   ├── client.py  # BaseSportsClient
│   │       │   ├── endpoints.py # Common endpoints
│   │       │   └── mapper.py  # BaseResponseMapper
│   │       ├── basketball/    # Basketball module
│   │       ├── soccer/        # Soccer module
│   │       ├── volleyball/    # Volleyball module
│   │       └── football/      # Football module
│   ├── handlers/               # Tool handlers
│   │   └── sports.py          # Sports data handlers
│   ├── factory/                # MCP server factory
│   │   ├── safe_wrapper.py    # SafeFastMCPWrapper (Phase 2)
│   │   ├── server_factory.py  # MCP server creation
│   │   └── metadata_builder.py # OpenAI metadata
│   ├── tests/                  # Integration tests
│   │   ├── test_mcp.py        # MCP integration tests
│   │   ├── test_sports_api_integration.py  # Sports API tests
│   │   ├── test_sports_tools.py  # Sports tools tests
│   │   ├── test_environment.py   # Environment tests
│   │   └── unit/              # Unit tests
│   │       ├── test_endpoints.py
│   │       └── test_client_endpoints.py
│   └── requirements.txt
├── components/                  # React UI components
│   ├── src/                    # React source code
│   │   ├── example/           # Example widget (테스트용)
│   │   ├── game-result-viewer/ # Game results viewer
│   │   └── index.css          # Shared styles
│   ├── assets/                 # Built HTML/JS/CSS (generated)
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   └── build.ts                # Build script
├── tests/                       # Additional tests
│   └── test_cache.py           # Cache module tests (18 tests)
├── .env.development            # Development environment
├── .env.production             # Production environment
├── package.json                 # Root build scripts
├── API_INTEGRATION.md          # API integration guide
├── ARCHITECTURE.md             # Architecture documentation
├── CUSTOMIZATION_GUIDE.md      # Customization guide
├── REFACTORING_PLAN.md         # Refactoring plan (Phase 1-8 ✅)
└── README.md

React (TSX) → Build → HTML → MCP Server → ChatGPT (Render)
                              ↓
                        structuredContent (props)

# Install all dependencies (Python + Node)
npm run install:all

# Or install separately
npm run install:components  # Install React dependencies
npm run install:server      # Install Python dependencies

npm run build

# The .env.development file is used automatically
npm run server        # or npm run server:dev

# Create/edit .env.production file
vi .env.production

# Set required values:
# - SPORTS_API_KEY=your_actual_api_key
# - USE_MOCK_SPORTS_DATA=false
# - LOG_LEVEL=INFO

# Run in production mode
ENV=production npm run server:prod
# or
npm run start:prod

# Development (default)
npm run server

# Development (explicit)
npm run server:dev

# Production
npm run server:prod

npm run build

components/assets/
├── example.js
├── example.css
├── example.html
├── game-result-viewer.js
├── game-result-viewer.css
├── game-result-viewer.html
└── manifest.json

# Build and verify (recommended)
npm run build

# Build without verification
npm run build:only

# Verify existing build
npm run build:verify

Verifying widget builds...
============================================================
Widget: example
  HTML: ✅ example.html
  JS:   ✅ example.js
  CSS:  ✅ example.css

Widget: game-result-viewer
  HTML: ✅ game-result-viewer.html
  JS:   ✅ game-result-viewer.js
  CSS:  ✅ game-result-viewer.css

============================================================
✅ All widget builds verified successfully!

Verified 2 widget(s):
  - example
  - game-result-viewer

npm run install:all  # First time only
npm run dev          # Build + Start server

# Terminal 1: Watch and rebuild on changes
npm run build:watch

# Terminal 2: Run server with auto-reload
npm run server

mkdir -p components/src/my-widget

import { createRoot } from 'react-dom/client';

interface MyWidgetProps {
  data?: string;
}

function MyWidget({ data = "default" }: MyWidgetProps) {
  return (
    <div>
      <h1>My Widget</h1>
      <p>{data}</p>
    </div>
  );
}

const rootElement = document.getElementById('my-widget-root');
if (rootElement) {
  const root = createRoot(rootElement);
  root.render(<MyWidget />);
}

export default MyWidget;

npm run build

widgets: List[Widget] = [
    Widget(
        identifier="my-widget",
        title="My Widget",
        template_uri="ui://widget/my-widget.html",
        invoking="Loading my widget",
        invoked="My widget loaded",
        html=_load_widget_html("my-widget"),
        response_text="Rendered my widget!",
    ),
]

npm run server

return types.ServerResult(
    types.CallToolResult(
        content=[...],
        structuredContent={"data": "Hello from MCP!"},  # ← Props
        _meta={
            "openai.com/widget": widget_resource.model_dump(mode="json"),
        }
    )
)

cd components
npm run serve

BASE_URL=http://your-domain.com:4444 npm run build

EXTERNAL_API_BASE_URL=https://api.example.com
EXTERNAL_API_KEY=your-api-key-here
EXTERNAL_API_TIMEOUT_S=10.0           # Optional, default: 10.0
EXTERNAL_API_AUTH_HEADER=Authorization # Optional, default: Authorization
EXTERNAL_API_AUTH_SCHEME=Bearer        # Optional, default: Bearer

SportsClientFactory.create_client("basketball")  # Returns BasketballClient
SportsClientFactory.create_client("soccer")      # Returns SoccerClient
SportsClientFactory.create_client("volleyball")  # Returns VolleyballClient
SportsClientFactory.create_client("football")    # Returns FootballClient

# Via MCP tool call
{
  "name": "get_games_by_sport",
  "arguments": {
    "date": "20251118",
    "sport": "basketball"
  }
}

# Via MCP tool call
{
  "name": "get_game_details",
  "arguments": {
    "game_id": "OT2025313104237"
  }
}

.venv/bin/python test_sports_tools.py

npm run build

source .venv/bin/activate  # Activate virtual environment
npm run install:server     # Install dependencies

uvicorn.run("main:app", host="0.0.0.0", port=8001)

# Activate virtual environment
source .venv/bin/activate

# Run cache module tests
pytest tests/test_cache.py -v

# Run endpoint unit tests
pytest server/tests/unit/ -v

# Run MCP server integration tests
.venv/bin/python server/tests/test_mcp.py

# Run sports tools tests
.venv/bin/python server/tests/test_sports_tools.py

# Run sports API integration tests
.venv/bin/python server/tests/test_sports_api_integration.py

# Install cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o /tmp/cloudflared.deb
sudo dpkg -i /tmp/cloudflared.deb

# Login and create tunnel
cloudflared tunnel login
cloudflared tunnel create mcpapps

# Configure tunnel (/etc/cloudflared/config.yml)
tunnel: <UUID>
credentials-file: /etc/cloudflared/<UUID>.json

ingress:
  - hostname: mcpapps.yourdomain.com
    service: http://localhost:8000
  - service: http_status:404

# Route DNS and start
cloudflared tunnel route dns mcpapps mcpapps.yourdomain.com
sudo cloudflared service install
sudo systemctl start cloudflared