Global MCP Stock Server

글로벌 주식 시장 데이터 및 분석을 위한 Model Context Protocol(MCP) 서버

개요

이 프로젝트는 주식 시장 데이터에 액세스하는 MCP 서버를 제공합니다. AI 어시스턴트가 주가, 차트 데이터, 기업 정보 등에 실시간으로 액세스할 수 있도록 합니다.

MCP(Model Context Protocol)란?

Model Context Protocol(MCP)은 응용 프로그램이 대규모 언어 모델(LLM)에 컨텍스트를 제공하는 표준화된 방법입니다. 자세한 내용은 Model Context Protocol 웹 사이트 를 참조하십시오.

기능

실시간 주가 정보 취득
주가 이력 데이터 및 차트
주요 주식 지표 지원
기업 정보 및 재무 데이터
TypeScript에 의한 구현과 엄격한 타입 체크

사용자 가이드

전제 조건

Node.js 18 이상
npm 또는 yarn

설치 방법

리포지토리 복제:
git clone https://github.com/sakura-ku/grobal_mcp_stock_server.git cd grobal_mcp_stock_server
종속성 설치:
npm install
서버 빌드 및 실행:
npm run build npm start

이용방법

1. 환경 변수 설정

먼저 필요한 환경 변수를 설정합니다. .env 파일을 만들거나 기존 .env.example 파일을 복사하여 사용합니다.

# Windows PowerShellの場合
Copy-Item .env.example .env

# UNIX系システムの場合
cp .env.example .env

.env 파일을 편집하여 필요한 API 키를 설정합니다.

# 基本設定
PORT=3000
HOST=localhost
NODE_ENV=development

# Polygon.io APIキー (株価データ取得用)
POLYGON_API_KEY=your_polygon_api_key_here

# その他のAPIキー...

2. 서버 실행

개발 모드에서 서버를 시작하려면:

npm run dev

프로덕션 모드에서 서버를 시작하려면:

npm run build
npm run start:prod

3. API 사용 방법

브라우저에서 직접 액세스

서버가 시작되면 브라우저에서 다음 URL로 주가 데이터에 액세스할 수 있습니다.

http://localhost:3000/api/stock/price?symbol=AAPL

cURL을 사용한 예

명령줄에서 cURL을 사용하여 데이터를 검색할 수 있습니다.

# 株価データの取得
curl "http://localhost:3000/api/stock/price?symbol=AAPL"

# 株価履歴データの取得（過去30日間）
curl "http://localhost:3000/api/stock/history?symbol=AAPL&days=30"

프로그램의 사용 예

Node.js 애플리케이션에서 사용하는 예 :

// 株価データを取得する関数
async function getStockPrice(symbol) {
  const response = await fetch(`http://localhost:3000/api/stock/price?symbol=${symbol}`);
  const data = await response.json();
  return data;
}

// 使用例
getStockPrice('AAPL').then(data => {
  console.log(`現在の${data.symbol}の株価: ${data.price} ${data.currency}`);
});

4. AI 어시스턴트와의 통합

Claude, GPT-4와 같은 AI 어시스턴트와 통합하는 방법에 대한 자세한 내용은 MCP 클라이언트와의 연동 섹션을 참조하십시오.

Claude에서의 사용 예

Claude 프롬프트의 예:

株価を調べてください。
テスラ（TSLA）の現在の株価と、過去1週間の動向を教えてください。

AI 어시스턴트의 응답 예

テスラ（TSLA）の株価情報は以下の通りです：

現在の株価: $248.42 USD
前日比: +$5.21 (+2.14%)
取引量: 3,421,532株

過去1週間の動向:
- 7日前: $230.15
- 6日前: $232.05
- 5日前: $235.87
- 4日前: $239.14
- 3日前: $242.33
- 2日前: $243.21
- 1日前: $248.42

過去1週間で約8%の上昇トレンドを示しています。特に直近3日間で価格の上昇が加速しています。

사용 가능한 도구

주가 정보 얻기 (get_stock_price)

지정된 유명 상표의 현재 주가 및 관련 정보를 가져옵니다.

매개변수:

symbol (string): 주식의 주식 코드(예: AAPL, MSFT, GOOGL)

반환값:

주가정보(가격, 변동, 통화 등)

MCP 클라이언트와의 협력

이 MCP 서버를 클라이언트 (Claude, Claude Desktop, 기타 MCP 지원 응용 프로그램)에서 사용하려면 mcp.json 파일을 만들고 MCP 서버를 정의합니다.

mcp.json 정의 예

다음은 이 서버를 사용하기 위한 mcp.json 정의 예제입니다. 이 설정을 MCP 클라이언트에 추가하면 주가 정보에 액세스할 수 있습니다.

{
  "servers": [
    {
      "id": "global-stock-server",
      "url": "http://localhost:3000",
      "description": "株式市場データと分析のためのMCPサーバー",
      "tools": [
        {
          "name": "get_stock_price",
          "description": "指定された株式銘柄の現在の株価と関連情報を取得します",
          "parameters": {
            "type": "object",
            "required": ["symbol"],
            "properties": {
              "symbol": {
                "type": "string",
                "description": "株式銘柄コード（例: AAPL, MSFT, GOOGL）"
              }
            }
          }
        }
      ]
    }
  ]
}

MCP 클라이언트에서 설정하는 방법

위의 mcp.json 정의를 원하는 곳에 저장합니다.
MCP 클라이언트(예: Claude Desktop)의 설정 화면을 엽니다.
MCP 설정 섹션에서 서버 추가 또는 가져오기 옵션을 선택합니다.
저장된 mcp.json 파일을 선택하거나 내용을 복사하여 붙여넣습니다.
설정을 저장하고 클라이언트를 다시 시작합니다.

이제 MCP 클라이언트의 프롬프트와 채팅 내에서 주가 정보 도구를 사용할 수 있습니다.

Cursor IDE에서 설정하는 방법

Cursor IDE에서 settings.json 파일에 MCP 서버 설정을 추가하면 AI 어시스턴트가 도구를 사용할 수 있습니다.

설정 절차

커서 설정을 엽니다.
- Windows/Linux: Ctrl+,
- macOS: Cmd+,
"Cursor Settings"를 선택하고 settings.json 파일을 편집합니다.
mcpServers 섹션에 다음 설정을 추가합니다.

로컬 프로젝트로 실행하는 경우(권장)

이 프로젝트는 로컬 개발 및 실행을 전제로 합니다. npm 스크립트를 사용하여 실행하는 것이 가장 확실한 방법입니다.

{
  "mcpServers": {
    "global-stock-server": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/grobal_mcp_stock_server",
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "NODE_ENV": "production",
        "STOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

개발 모드에서 실행하는 경우 :

{
  "mcpServers": {
    "global-stock-server": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/grobal_mcp_stock_server",
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "NODE_ENV": "development",
        "STOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

GitHub Packages에서 설치하는 방법

이 MCP 서버는 GitHub Packages를 사용하여 개인 npm 레지스트리로 게시됩니다. 다음과 같이 설치할 수 있습니다.

.npmrc 파일을 만들거나 편집하여 인증 설정을 수행합니다.

@sakura-ku:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

환경 변수 NPM_TOKEN 에 GitHub의 개인 액세스 토큰을 설정합니다.

# Windowsの場合
$env:NPM_TOKEN="your_github_token"

# macOS/Linuxの場合
export NPM_TOKEN="your_github_token"

패키지 설치:

npm install @sakura-ku/grobal-mcp-stock-server

Cursor IDE의 설정 예:

{
  "mcpServers": {
    "global-stock-server": {
      "command": "npx",
      "args": ["@sakura-ku/grobal-mcp-stock-server"],
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "STOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

자세한 설정 방법은 개인 npm 레지스트리 관리 방법을 참조하십시오.

문제해결

서버가 시작되지 않는 경우 :
- 프로젝트 디렉토리로 이동하여 수동으로 명령을 실행하여 오류 확인
- 종속성이 올바르게 npm install 실행)
- TypeScript 버전이 맞는지 확인
도구를 찾을 수 없는 경우 :
- 서버가 성공적으로 시작되었는지 확인
- 로그 출력에 등록된 툴명을 확인
- 필요한 경우 npm run dev 로 서버를 디버그 모드로 부팅

개발자 가이드

프로젝트 구성

grobal_mcp_stock_server/
├── build/                # コンパイルされたJavaScriptファイル
├── src/
│   ├── __tests__/        # 統合テストとテストユーティリティ
│   ├── config/           # 設定ファイル
│   ├── data/             # データモデルとストレージ
│   ├── errors/           # カスタムエラークラス
│   ├── services/         # 外部APIとの連携サービス
│   ├── tools/            # MCPツール実装
│   │   └── __tests__/    # ツールユニットテスト
│   ├── types/            # TypeScript型定義
│   └── index.ts          # メインサーバーエントリーポイント
├── package.json          # プロジェクト設定
├── tsconfig.json         # TypeScript設定
└── README.md             # プロジェクトドキュメント

개발 환경 설정

개발 종속성 설치:
npm install
개발 모드에서 서버 시작:
npm run dev

개발 워크플로우

TypeScript 컴파일러를 시계 모드로 시작: npm run dev
코드 정적 분석: npm run lint
정적 분석 문제 자동 수정: npm run lint:fix
npm test test

사용 가능한 스크립트

package.json에 정의 된 스크립트에 대한 자세한 설명 :

빌드 스크립트

build : TypeScript 코드를 컴파일하고 dist 디렉토리에 출력합니다.
build:dev : 개발 환경용 소스 맵으로 빌드합니다.
build:prod : 프로덕션용 소스 맵 없이 빌드
clean : dist 디렉토리를 삭제하고 청소합니다.
prebuild : 빌드 전에 자동으로 clean 스크립트를 실행합니다.

서버 시작 스크립트

start : 컴파일된 서버를 시작합니다.
start:dev : 개발 환경 설정으로 서버를 시작합니다.
start:prod : 프로덕션 환경에서 서버를 시작합니다.
dev : 소스 코드 변경을 모니터링하고 자동으로 빌드 및 재부팅을 수행하는 개발 모드입니다.

코드 품질 관리 스크립트

lint : ESLint를 사용하여 TypeScript 코드를 정적 구문 분석합니다.
lint:fix : ESLint를 사용하여 코드 문제를 자동 수정합니다.

테스트 스크립트

test : Jest를 사용하여 모든 테스트를 실행합니다.
test:watch : 테스트를 워치 모드로 실행하고 변경 시 재실행
test:coverage : 테스트 커버리지 보고서를 생성합니다.
test:ci : CI 환경에 대한 테스트 설정으로 실행
test:unit : 단위 테스트만 실행
test:integration integration : 통합 테스트만 실행
test:services 테스트만 실행
test:debug : 디버그 모드에서 테스트를 실행합니다.

배포 및 패키징

deploy:staging staging : 스테이징 환경에 배포
deploy:production : 프로덕션 환경에 배포
publish:package : npm 레지스트리에 패키지를 게시합니다.
prepare:package : 패키징 전에 프로덕션 빌드를 실행하여 tarball을 만듭니다.
prepublishOnly : 패키지를 게시하기 전에 프로덕션 빌드를 실행합니다.

라이센스

ISC

기여

이 프로젝트에 기여하는 데 관심이 있는 경우 풀 요청을 제출하세요.

Integrations