CSE MCP

CSE MCP 服务

@gajarthan/cse-mcp 是一个面向 Colombo Stock Exchange 的 TypeScript Model Context Protocol 服务。它为兼容 MCP 的客户端提供了一种简洁的方式，可用于搜索上市公司、获取标准化的单只股票报价，以及检索市场整体快照，例如市场状态、市场摘要、涨幅榜、跌幅榜和指数数据。它面向开发者、分析师和 AI 工具构建者，帮助他们通过稳定的 MCP 工具接口快速访问 CSE 数据，而不必在提示词中抓取原始网站响应。

主要功能

• 使用本地 CSV 目录，按代码或公司名称搜索 CSE 上市公司
• 从 companyInfoSummery 获取标准化的股票报价数据
• 从 marketStatus、marketSummery、topGainers、topLooses、aspiData 和 snpData 获取市场整体数据
• 在发起上游请求前验证工具输入
• 将未公开文档的 CSE 负载标准化为便于 AI 使用的 JSON
• 使用专用服务层处理 CSE HTTP 调用，并采用精简的 MCP 处理程序
• 对暂时性上游故障应用请求超时和基本重试处理
• 仅向 stderr 写入日志，确保 stdout 不受影响，供 MCP 传输使用
• 兼容 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 在 ~/.codex/config.toml 中提供 MCP 配置文档，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 版本中确认确切的配置路径和界面操作流程。

VS Code / Copilot

VS Code 和 GitHub Copilot 对 MCP 的支持取决于版本。在支持本地 MCP 服务的版本中，常见做法是使用 workspace 或用户级 mcp.json 风格的配置，并设置 command 和 args：

{
  "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 文档或扩展程序界面中确认当前的配置文件名和位置。

Continue

Continue 对 MCP 的支持取决于版本，可能通过 YAML 或基于界面的 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，实际可行的方式是连接 GitHub 仓库，让 Smithery 从仓库、分支和根目录构建，而不是要求提供公共 MCP URL。

此仓库推荐使用以下 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
5. 打开由 Actions 创建的 GitHub 草稿发布版本，检查生成的说明并发布

此工作流会先在 Ubuntu 和 Windows 上验证发布，然后再创建 GitHub 草稿发布版本。

工具参考

search_company

按公司名称或股票代码搜索本地 CSV 目录。

输入：

{
  "query": "john keells"
}

返回：

• 规范化的查询
• 排序后的匹配结果
• 股票代码、公司名称和匹配分数

get_stock_quote

获取有效 CSE 股票代码对应的规范化报价。

输入：

{
  "symbol": "JKH.N0000"
}

返回：

• 最新价格和前收盘价
• 价格变动和百分比变动
• 当日区间和 52 周区间
• 成交量、成交额、市值和 Beta 值
• 来源元数据和获取时间戳

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

获取一个或两个受支持的指数摘要。

输入：

{
  "index": "all"
}

允许的值：

• aspi
• snp
• all

配置、标志和环境变量

当前运行时配置

• 传输方式：仅支持 stdio
• 必需的环境变量：无
• 必需的 API 密钥：无
• 上游默认超时时间：10000ms
• 瞬时故障的默认重试次数：2

CLI 标志

此项目目前不提供自定义 CLI 标志。使用以下命令运行：

node dist/index.js

环境变量

此项目目前不需要或记录自定义环境变量。

TODO

如果超时时间、重试次数、基础 URL 覆盖或 CSV 路径覆盖需要支持用户配置，应明确添加并在此处记录，而不是从源代码中推断。

已知限制

• 此服务仅支持 stdio 传输方式
• 上游 CSE API 为非官方 API，可能会在不另行通知的情况下发生变化
• 市场数据的准确性和可用性取决于 CSE 网站
• 尚未实现托管式 HTTP/SSE 部署
• 此处的 Smithery GitHub 发布说明与文档保持一致，但仍应在 Smithery 项目界面和部署日志中验证最终构建行为

故障排除

客户端未显示任何工具

• 确认客户端支持本地 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 存在
• 客户端配置使用了适用于你所用操作系统的正确路径分隔符和引号

无法查询某个代码的报价

• 先使用 search_company 确认 CSE 代码的准确名称
• 查询报价前，会根据捆绑的 CSV 目录验证代码
• 如果 CSE 中存在该代码，但 CSV 中没有，请更新 cse_companies.csv

上游超时或出现意外的响应错误

• CSE API 为非官方 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 pack 验证

推荐的本地工作流：

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. Fork 此仓库
2. 创建功能分支
3. 运行 npm install
4. 运行 npm run typecheck
5. 运行 npm run build
6. 使用 MCP Inspector 进行测试
7. 提交拉取请求，并附上清晰的摘要

高价值贡献方向：

• 新增工具，例如 chartData、allSectors 和公告
• 增强针对规范化和错误处理的自动化测试
• 更好地处理 CSE 响应结构的变化
• 随着 MCP 客户端支持不断发展，完善客户端配置文档

如果发现 CSE 响应结构发生变化，请尽可能在 issue 或 PR 中附上经过脱敏的示例负载。