Mopsfin 대만 주식 MCP Server

공개, 읽기 전용, 데이터베이스가 없는 대만 기업 재무 데이터 MCP Server입니다. 서비스는 Next.js 16 App Router와 MCP TypeScript SDK v2로 구현되었으며, Stateless Streamable HTTP /api/mcp를 통해 7개의 도구를 노출합니다. 모든 재무 조회는 공개정보관측소－재무비교 E點通에 직접 접근합니다.

이것은 대만증권거래소 공식 MCP Server가 아니며, 투자 조언을 구성하지 않습니다.

아키텍처

LLM / MCP client
       │ Streamable HTTP
       ▼
Next.js /api/mcp on Vercel
       │ 固定 allowlist endpoint、form-urlencoded、無 cookie
       ▼
mopsfin.twse.com.tw
       │
       ├─ JSON → periods + series
       └─ HTML → 展開 rowspan/colspan 的二維 tables

• 데이터베이스, Redis 또는 폐기된 HTTP+SSE transport를 사용하지 않습니다.

• 재무 데이터는 캐시하지 않습니다. 홈페이지에서 파싱한 동적 카탈로그만 단일 Vercel instance 메모리에 5분간 캐시합니다.

• 업스트림 URL은 완전히 고정되어 있으며, 도구 파라미터는 URL을 제공할 수 없으므로 임의 proxy/SSRF가 형성되지 않습니다.

• 업스트림 timeout 20초. 네트워크 오류, 429, 5xx는 한 번만 재시도하며, 다른 4xx는 재시도하지 않습니다.

• Mopsfin 쿠키를 보존하거나 전달하지 않습니다.

• 보고서의 latest는 이전 완료 분기부터 최대 12분기를 역방향으로 탐색하고, 응답 기간을 대조하여 원래 사이트가 조용히 다른 분기로 되돌아가지 않도록 합니다.

• Vercel은 Node.js 24.x, 도쿄 hnd1, 60초 function duration 및 Fluid Compute를 사용합니다.

Related MCP server: polygon-mcp

MCP 도구

각 도구는 엄격한 Zod input/output schema를 가지며, 짧은 content 요약과 완전한 structuredContent를 반환합니다. 도구 annotations는 읽기 전용, 비파괴, 멱등, 개방형 세계 부작용 없음으로 표시됩니다.

LLM은 세 가지 계층에서 해석 데이터를 얻을 수 있습니다. MCP initialize의 server instructions는 전체 데이터 범위와 호출 순서를 설명합니다. tools/list는 7개 도구와 각 input/output 필드에 대한 용도와 기준을 제공합니다. list_catalog의 officialGuidance와 각 metric의 guidance는 공식, 수치 기반, 적용 업종 및 주의사항을 제공합니다. 실제 조회 결과의 warnings는 이번 조회와 직접 관련된 신고 빈도, 단일 분기／누적, 결측값, 평균 또는 페이지네이션 경고를 추가로 포함합니다.

코드를 모를 때는 먼저 find_companies 또는 list_catalog를 호출하세요. list_catalog의 family는 다음과 같이 대응됩니다:

추세는 기본적으로 최근 12분기를 반환하며, start_period, end_period 또는 history: "all"을 사용할 수 있습니다. 대형 HTML 테이블은 offset, limit으로 페이지네이션하며, 기본 100행, 상한 500행입니다. 기간 형식은 YYYYQn입니다.

기업 지표는 include_industry_average, include_company_average로 산업 평균 및 선택 기업 단순 평균을 추가할 수 있습니다. 금융기관 지표는 include_industry_average, include_institution_average로 해당 금융 업종 평균 및 선택 기관 단순 평균을 추가할 수 있습니다. 이러한 평균은 모두 Mopsfin이 계산하며, 시가총액 가중이 아닙니다.

데이터 질문에 답할 때는 최소한 unit, 실제 periods／period, 조회 basis 및 warnings를 유지해야 합니다. null, NO_DATA 또는 특정 분기가 없는 것은 해당 없음, 아직 신고되지 않음 또는 해당 시장에서 원래 신고할 필요가 없음을 의미할 수 있으며, 0으로 바꿔 쓸 수 없습니다.

로컬 개발

요구 사항: Node.js 24, npm 11.

npm install
npm run dev

서비스:

• 홈페이지: http://localhost:3000/

• MCP: http://localhost:3000/api/mcp

• 헬스 체크: http://localhost:3000/api/health

헬스 체크는 Mopsfin을 호출하지 않아 모니터링 트래픽이 원래 사이트에 대한 고정 조회가 되지 않도록 합니다.

공식 MCP Inspector 또는 포함된 client로 검증할 수 있습니다:

npm run test:client
# 或指定 Preview URL
npm run test:client -- https://your-preview.vercel.app/api/mcp

MCP client 설정 예시:

{
  "mcpServers": {
    "mopsfin": {
      "url": "https://your-domain.example/api/mcp"
    }
  }
}

ChatGPT에서 사용

ChatGPT는 연결 가능한 공개 HTTPS /api/mcp URL이 필요합니다. 로컬의 localhost는 원격 ChatGPT에 직접 제공할 수 없습니다.

1. 먼저 Vercel에 배포하여 https://<당신의 도메인>/api/mcp를 획득합니다.

2. ChatGPT에서 Settings → Security and login → Developer mode를 엽니다.

3. ChatGPT Plugins로 이동하여 더하기 버튼으로 새 연결을 추가합니다.

4. 이름(예: Mopsfin 대만 주식)을 입력하고 Connection URL을 전체 https://<당신의 도메인>/api/mcp로 설정합니다.

5. 생성 후 ChatGPT가 7개 도구를 인식하는지 확인합니다.

6. 새 대화를 시작하고 도구 메뉴에서 이 MCP connection을 추가한 다음 자연어로 대만 주식을 직접 질문합니다.

Developer mode 사용 가능 여부는 계정 요금제와 workspace policy에 따라 다릅니다. 자세한 절차는 OpenAI 공식 연결 설명을 참조하세요.

예시 질문:

• "TSMC 최근 12분기 영업수익을 조회하여 표로 정리하고 추세를 지적해 줘."

• "TSMC와 MediaTek의 최근 8분기 ROE를 비교해 줘."

• "TSMC 2025Q4 대차대조표의 주요 항목을 나열해 줘."

• "반도체 업종 최근 12분기 매출 추세를 비교해 줘."

• "대만은행의 최근 사용 가능한 은행업 자본적정성을 조회해 줘."

검증

npm run lint
npm run type-check
npm test
npm run build

일반 테스트는 고정 fixtures만 사용하며, 53개 compareItem 분류, 6개 endpoint family, 결측값, 음수, 백분율, 다중 기업, HTML 병합 셀, 페이지네이션, timeout, 429, 5xx, 잘못된 분기 및 MCP initialize/tools/list/tools/call을 포함합니다.

Live contract tests는 기본적으로 건너뛰며, 명시적으로 설정할 때만 원래 사이트를 조회합니다:

npm run test:live

Mopsfin에 고정 트래픽을 발생시키지 않도록 live tests를 정기 CI로 설정하지 마세요.

Vercel에 배포

1. repository를 Vercel로 가져옵니다.

2. Build command는 npm run build를 사용합니다. Vercel은 package-lock.json에 따라 npm 설치를 실행합니다.

3. package.json은 Node.js 24.x로 고정되어 있습니다. vercel.json은 Fluid Compute를 활성화합니다.

4. 배포 후 npm run test:client -- https://<preview>/api/mcp로 검증합니다.

5. 공개 트래픽에 따라 Vercel Firewall에 적절한 규칙을 설정합니다. 애플리케이션 자체는 cross-instance rate-limit 데이터베이스를 생성하지 않습니다.

Preview 검증 권장 사항: TSMC 최근 12분기 매출, TSMC와 MediaTek ROE, 지정 분기 대차대조표, 반도체 산업 추세, 대만은행 자본적정성 및 TSMC 재무보고서 주석.

오류 코드

• INVALID_ARGUMENT

• NOT_FOUND

• NO_DATA

• UPSTREAM_TIMEOUT

• UPSTREAM_RATE_LIMITED

• UPSTREAM_BAD_RESPONSE

시장별 신고 분기가 다릅니다. 상장／상장(櫃) 기업은 일반적으로 Q1–Q4가 있고, 흥궤(興櫃) 및 공개발행 기업은 Q2/Q4만 있을 수 있으며, 일부 기업은 연간만 신고합니다. NO_DATA가 반드시 기업이 존재하지 않음을 의미하지는 않습니다.

데이터 출처, 업데이트 및 사용 조건

데이터의 유일한 출처는 Mopsfin입니다. 사이트 사용 설명에 따르면 사이트 데이터는 하루에 한 번 업데이트되며 신고보다 약 하루 늦을 수 있습니다. 본 서비스는 테스트 fixtures를 공식 데이터 또는 fallback으로 사용하지 않습니다.

공개 출시 전에 프로젝트 소유자는 TWSE/Mopsfin의 공개 프록시, 재배포 및 사용 빈도에 대한 승인을 직접 확인해야 합니다. 사이트 사용 설명의 데이터 범위와 업데이트 빈도에 대한 설명은 재배포 권한의 명시적 부여와 동일하지 않습니다. 사용자도 공개정보관측소의 원본 신고를 최종 확인으로 사용해야 합니다.

주요 참고 자료

• OpenAI: Build an MCP server

• Vercel: MCP for Next.js

• Next.js 16 upgrade guide

• Vercel Node.js versions

• Vercel Fluid Compute