CSE MCP

CSE MCP Server

@gajarthan/cse-mcp は、コロンボ証券取引所向けの TypeScript 製 Model Context Protocol サーバーです。MCP 互換クライアントが、上場企業を検索し、正規化された個別銘柄の株価情報を取得し、市場状況、概要、値上がり銘柄、値下がり銘柄、指数データなどの市場全体のスナップショットを取得できる、使いやすい方法を提供します。プロンプト内で生のウェブサイトのレスポンスをスクレイピングする代わりに、安定した MCP ツールを通じて CSE データにすばやくアクセスしたい開発者、アナリスト、AI ツール開発者向けに構築されています。

主な機能

• ローカルの CSV カタログを使用して、シンボルまたは企業名で CSE の上場企業を検索
• companyInfoSummery から正規化された株価データを取得
• marketStatus、marketSummery、topGainers、topLooses、aspiData、snpData から市場全体のデータを取得
• 上流へのリクエストを行う前にツールの入力を検証
• 文書化されていない CSE のペイロードを AI 向けの JSON に正規化
• CSE への HTTP 呼び出しには専用のサービスレイヤーを使用し、MCP ハンドラーは薄く保つ
• リクエストのタイムアウトと、一時的な上流障害に対する基本的な再試行処理を適用
• MCP トランスポート用に stdout をクリーンに保つため、stderr にのみログを出力
• MCP Inspector およびローカルの stdio ベースの MCP クライアントとの互換性を維持

免責事項、セキュリティ、プライバシー

• このプロジェクトでは、https://www.cse.lk/api/ が公開する非公式のリバースエンジニアリング済みエンドポイントを使用しています。レスポンスの形式は予告なく変更される場合があります。
• 市場データには遅延、不完全、一時的な利用不可が生じる場合があります。財務上の判断を行う前に、重要な数値を公式情報源と照合してください。
• このサーバーは CSE のウェブサイトに外部リクエストを送信します。ツール経由で送信されたシンボルとリクエストペイロードは、その外部サービスに送信されます。
• このサーバーでは API キーは不要で、テレメトリーや分析機能も組み込まれていません。
• ツールの出力は、接続先の MCP クライアントに返されます。クライアントのログ、トランスクリプト、ツールの承認履歴は機密情報として扱ってください。
• このサーバーは現在、ローカルの stdio トランスポートのみをサポートしています。リモートの HTTP または SSE MCP エンドポイントはまだ提供していません。

必要条件

• Node.js 20 以降
• npm 10 以降
• https://www.cse.lk へのインターネットアクセス
• ローカルの stdio サーバーをサポートする MCP クライアント

はじめに

ローカルビルドを使用する

ローカルでビルドします。

npm install
npm run build

ローカル MCP 設定の最小例：

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

ローカルで開発している場合、MCP Inspector が最も手早く動作確認できます。

npm run inspector

公開済み npm パッケージを使用する

パッケージが npm に公開されている場合、最も手早いインストール方法は次のとおりです。

{
  "mcpServers": {
    "cse": {
      "command": "npx",
      "args": ["-y", "@gajarthan/cse-mcp"]
    }
  }
}

最初のテスト用プロンプト

Use search_company to find John Keells Holdings, then call get_stock_quote for the correct symbol.

MCP クライアントの設定

このサーバーはローカルの stdio のみをサポートしています。ほとんどのクライアントでは、次のいずれかの方法で設定できます。

• ローカル開発モード：node C:/absolute/path/to/cse-mcp/dist/index.js
• 公開済みパッケージモード：npx -y @gajarthan/cse-mcp

ローカルの stdio とリモート HTTP の違い

• 現在サポート：command と args を指定してプロセスを起動するローカルの stdio MCP クライアント
• まだサポートされていないもの：SSE またはストリーミング HTTP トランスポートを必要とする、リモート専用の MCP クライアント

Claude Code

Claude Code は MCP のサポートを公開しており、ローカルの stdio サーバーで問題なく動作します。

サーバーを直接追加します。

claude mcp add-json cse "{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"C:/absolute/path/to/cse-mcp/dist/index.js\"]}"

公開済みパッケージを使用する場合：

claude mcp add-json cse "{\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"@gajarthan/cse-mcp\"]}"

または、.mcp.json を使用します。

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Claude Desktop の設定が済んでいる場合は、その MCP エントリーを Claude Code にインポートすることもできます。

claude mcp add-from-claude-desktop

Codex

OpenAI の MCP 設定は ~/.codex/config.toml で行い、Codex CLI と IDE 拡張機能で共有されます。

CLI の設定：

codex mcp add cse -- node C:/absolute/path/to/cse-mcp/dist/index.js

公開済みパッケージを使用する場合の CLI の設定：

codex mcp add cse -- npx -y @gajarthan/cse-mcp

config.toml の設定：

[mcp_servers.cse]
command = "node"
args = ["C:/absolute/path/to/cse-mcp/dist/index.js"]

公開済みパッケージを使用する場合の config.toml の設定：

[mcp_servers.cse]
command = "npx"
args = ["-y", "@gajarthan/cse-mcp"]

Cursor

Cursor の MCP サポートはバージョンによって異なります。ローカル MCP サーバーに対応しているバージョンでは、次の設定に相当するものを使用します。

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

クライアントが npx に対応している場合は、通常、コマンドを次のように置き換えられます。

{
  "mcpServers": {
    "cse": {
      "command": "npx",
      "args": ["-y", "@gajarthan/cse-mcp"]
    }
  }
}

インストール済みの Cursor のバージョンで、正確な設定ファイルのパスと UI 操作の流れを確認してください。

VS Code / Copilot

VS Code と GitHub Copilot の MCP サポートはバージョンによって異なります。ローカル MCP サーバーに対応しているビルドでは、一般的に、command と args を使用するワークスペースまたはユーザー用の mcp.json 形式の設定を行います。

{
  "servers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

この例を使用する前に、お使いの VS Code または Copilot のバージョンで、正確なファイルの場所とスキーマを確認してください。

Cline

Cline の MCP サポートはバージョンによって異なります。ローカル MCP stdio サーバーに対応しているバージョンでは、同じプロセス起動パターンを使用します。

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Cline のドキュメントまたは拡張機能の UI で、現在の設定ファイル名と場所を確認してください。

Continue

Continue のサポートはバージョンによって異なり、YAML または UI ベースの MCP 設定を通じて構成する場合があります。実際のローカル設定は次のとおりです。

mcpServers:
  cse:
    command: node
    args:
      - C:/absolute/path/to/cse-mcp/dist/index.js

インストール済みのバージョンで、現在の Continue 設定形式を確認してください。

Roo Code

Roo Code の MCP サポートはバージョンによって異なります。バージョン固有の MCP 設定で、同じローカル stdio コマンドパターンを使用します。

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

TODO：現在の Roo Code の正確な設定パスを確認し、記載してください。

Gemini CLI

Gemini CLI の MCP サポートはバージョンによって異なります。ローカル MCP サーバーに対応しているバージョンでは、このサーバーをローカル stdio プロセスとして設定します。

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

使用しているバージョンで、現在の Gemini CLI の設定パスとスキーマを確認してください。

Smithery への公開

このプロジェクトは、GitHub リポジトリ連携を通じて Smithery に公開することを想定しています。

確認済みの内容：

• サーバーはローカルの stdio MCP サーバーです
• npm パッケージは @gajarthan/cse-mcp として公開されています
• リポジトリは GitHub 上で公開されています

現時点で意図的にサポートしていない内容：

• 公開 HTTPS MCP デプロイ
• SSE トランスポート
• ホスト型リモート MCP URL の公開

Smithery では、公開 MCP URL を用意するのではなく、GitHub リポジトリを連携し、リポジトリ、ブランチ、ベースディレクトリから Smithery にビルドさせる方法が実用的です。

このリポジトリで推奨される Smithery 設定：

• リポジトリ：Gajarthan/cse-mcp
• ブランチ：master
• ベースディレクトリ：.
• 自動デプロイ：初回の公開が成功してから有効にしてください

GitHub から Smithery へのワークフロー、チェックリスト、よくある失敗の原因について詳しくは、SMITHERY.md を参照してください。

リリース

このリポジトリには、 .github/workflows/release.yml にタグ駆動のリリース自動化がすでに含まれています。

GitHub リリースを作成するには：

1. package.json、src/index.ts、server.json、glama.json を目的のバージョンに更新します
2. CHANGELOG.md にリリースノートを追加します
3. npm run release:check を実行します
4. v2.0.1 のような semver タグを作成してプッシュします
5. Actions が作成した GitHub リリースのドラフトを開き、生成されたノートを確認して公開します

このワークフローは、GitHub リリースのドラフトを作成する前に、Ubuntu と Windows の両方でリリースを検証します。

ツールリファレンス

search_company

会社名またはティッカーシンボルで、ローカルの CSV カタログを検索します。

入力：

{
  "query": "john keells"
}

戻り値：

• 正規化されたクエリ
• ランク付けされた一致候補
• シンボル、会社名、一致スコア

get_stock_quote

有効な CSE シンボルの正規化された株価情報を取得します。

入力：

{
  "symbol": "JKH.N0000"
}

戻り値：

• 最終価格と前日終値
• 価格変動と変動率
• 日中レンジと52週間レンジ
• 出来高、売買代金、時価総額、ベータ値
• ソースのメタデータと取得日時

get_market_status

CSE から現在の取引セッション文字列を取得し、ステータスと推定された市場の開閉シグナルに正規化します。

入力：

{}

get_market_summary

市場全体の売買代金、株式出来高、取引件数、取引日を取得します。

入力：

{}

get_top_gainers

市場の値上がり上位銘柄を取得します。

入力：

{
  "limit": 10
}

注：

• デフォルトの limit は 10 です
• limit の最大値は 25 です

get_top_losers

値下がり率上位の銘柄を取得します。

入力：

{
  "limit": 10
}

注意事項：

• limit のデフォルト値は 10 です
• limit の最大値は 25 です

get_index_summary

対応している指数のサマリーを1つまたは両方取得します。

入力：

{
  "index": "all"
}

指定できる値：

• aspi
• snp
• all

設定、フラグ、環境変数

現在のランタイム設定

• トランスポート：stdio のみ
• 必須の環境変数：なし
• 必須の API キー：なし
• デフォルトの上流タイムアウト：10000ms
• 一時的な障害に対するデフォルトの再試行回数：2

CLI フラグ

このプロジェクトでは、現在、カスタム CLI フラグを公開していません。次のように実行してください：

node dist/index.js

環境変数

このプロジェクトでは、現在、カスタム環境変数は必要としておらず、説明もしていません。

TODO

タイムアウト、再試行回数、ベース URL の上書き、または CSV パスの上書きをユーザーが設定できるようにする場合は、ソースコードから推測させるのではなく、明示的に追加してここで説明してください。

既知の制限事項

• このサーバーは stdio トランスポートのみをサポートしています
• 上流の CSE API は非公式であり、予告なく変更される場合があります
• 市場データの正確性と可用性は CSE のウェブサイトに依存します
• ホスト型 HTTP/SSE デプロイメントはまだ実装されていません
• ここでは Smithery の GitHub 公開に関する説明を整合させていますが、最終的なビルド動作は Smithery プロジェクトの UI とデプロイログで引き続き確認してください

トラブルシューティング

クライアントにツールが表示されない

• クライアントがローカルの stdio MCP サーバーをサポートしていることを確認してください
• args のパスが絶対パスであることを確認してください
• クライアントから dist/index.js を指定する前に、npm run build を実行してください
• 設定を変更した後は、MCP クライアントを再起動してください
• npm パッケージのパスを使用している場合は、ターミナルから npx @gajarthan/cse-mcp が実行できることを確認してください

サーバーを起動できない

サーバーを直接実行して、stderr を確認してください：

node dist/index.js

次を確認してください：

• Node.js のバージョンが 20 以降である
• 依存関係がインストールされている
• dist/index.js が存在する
• クライアント設定で、お使いの OS に適したパス区切り文字と引用符が使われている

銘柄コードの株価取得に失敗する

• まず search_company を使用して、正確な CSE 銘柄コードを確認してください
• 株価取得の呼び出し前に、同梱の CSV カタログで銘柄コードが検証されます
• 銘柄コードが CSE に存在するのに CSV にない場合は、cse_companies.csv を更新してください

上流のタイムアウトまたは予期しないレスポンスエラー

• CSE API は非公式であり、レスポンスの形式が変更される場合があります
• 一時的な問題かどうかを確認するため、数分後に再試行してください
• MCP Inspector またはローカルでの直接実行を再度行い、stderr のログを確認してください
• レスポンスの形式が変更された場合は、src/services/cseApi.ts の Zod パース処理と正規化ロジックを更新してください

ChatGPT がこのサーバーに接続できない

現時点では想定どおりです。このサーバーは stdio のみですが、ChatGPT がドキュメントで説明しているリモート MCP フローでは、SSE またはストリーミング HTTP が必要です。

Windows のパスに関する問題

可能な場合は、JSON 設定で絶対パスとスラッシュを使用してください：

{
  "command": "node",
  "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
}

ローカルパスを扱いたくない場合は、公開済みパッケージ形式を使用してください：

{
  "command": "npx",
  "args": ["-y", "@gajarthan/cse-mcp"]
}

クライアントからパッケージを直接起動できない場合は、npm パッケージを明示する形式を使用してください：

{
  "command": "npx",
  "args": ["-y", "-p", "@gajarthan/cse-mcp", "cse-mcp"]
}

開発

インストールとビルド：

npm install
npm run build

便利なスクリプト：

• npm run dev - tsx を使ったウォッチモードでの開発
• npm run build - TypeScript を dist/ にコンパイル
• npm run typecheck - ファイルを出力せずに TypeScript のチェックを実行
• npm run start - コンパイル済みサーバーを起動
• npm run inspector - ローカルビルドに対して MCP Inspector を起動
• npm run pack:check - 公開せずに npm パッケージの内容を検証
• npm run release:check - 型チェック、ビルド、テスト、npm パッケージの検証を実行

推奨するローカルでの作業手順：

1. npm install を実行します
2. npm run typecheck を実行します
3. npm run build を実行します
4. npm run inspector を実行します
5. 少なくとも以下をテストします：
   • search_company
   • get_stock_quote
   • get_market_summary
   • get_index_summary

プロジェクトの構成：

• src/index.ts - MCP サーバーの起動処理と stdio トランスポート
• src/services/companyLookup.ts - CSV を使ったシンボルおよび企業の検索
• src/services/cseApi.ts - CSE API の HTTP 呼び出し、検証、再試行、正規化
• src/tools/*.ts - 個々の MCP ツール定義
• src/utils/errors.ts - 安全なエラー処理と stderr へのログ出力
• src/utils/formatters.ts - 出力形式の整備と正規化のヘルパー

変更履歴

CHANGELOG.md を参照してください。

コントリビューション

これはオープンソースプロジェクトであり、コントリビューションを歓迎します。

ローカル環境のセットアップ、検証手順、プルリクエストに関する要件については、CONTRIBUTING.md を参照してください。

推奨するコントリビューションの流れ：

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. npm install を実行します
4. npm run typecheck を実行します
5. npm run build を実行します
6. MCP Inspector でテストします
7. 明確な概要を添えてプルリクエストを作成します

特に価値の高いコントリビューション分野：

• chartData、allSectors、お知らせなどの新しいツール
• 正規化とエラー処理に関する、より充実した自動テスト
• CSE のレスポンス形式の変化への対応強化
• MCP クライアントのサポートの進展に合わせた、より明確なクライアント設定のドキュメント

CSE のレスポンス形式の変更に気付いた場合は、可能であれば、サニタイズしたペイロードの例を Issue または PR に含めてください。