npm package: @flyneko/mcp-market
Description: MCP market data server powered by APIs
Latest version: 0.1.31

# mcp-market

基于上游行情接口的 MCP Server。

包管理器：统一使用 `npm`（以 `package-lock.json` 为准）。

## 启动

```bash
npm install
npm run dev
```

默认是 `stdio` 模式（给 MCP 客户端本地拉起）。

如果要启用 HTTP 模式：

```bash
MCP_TRANSPORT=http MCP_HTTP_PORT=3100 npm run dev
```

生产构建后：

```bash
MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_PORT=3100 node dist/index.cjs
```

## 构建

```bash
# 先安装 dev 依赖（包含 esbuild）
npm install

# 单文件 bundle 到 dist/index.cjs（并混淆 + 产物校验）
npm run build

# 兼容旧脚本名
npm run build:legacy
```

## Docker

本仓库提供了 `Dockerfile`，容器默认以 HTTP 模式启动：

- `MCP_TRANSPORT=http`
- `MCP_HTTP_HOST=0.0.0.0`
- `MCP_HTTP_PORT=3100`
- `MCP_HTTP_PATH=/mcp`

本地构建与运行：

```bash
docker build -t mcp-market:local .
docker run --rm -p 3100:3100 mcp-market:local
```

GitHub Actions 自动发布镜像：

- workflow: `.github/workflows/docker-publish.yml`
- 触发条件：
  - push 到 `main`
  - push `v*` tag
  - 手动触发 `workflow_dispatch`
- 发布地址：`ghcr.io/<owner>/<repo>`

调试（Inspector）：

```bash
npm run inspector
# 等价于: npx @mcpjam/inspector@latest npx -y tsx "$PWD/src/index.ts"

# 如果没有安装 devDependencies（例如只装了生产依赖）：
npm run inspector:dist
# 等价于: npx @mcpjam/inspector@latest node "$PWD/dist/index.cjs"
```

默认环境变量：

- `MCP_TRANSPORT=stdio`：可选 `stdio` 或 `http`
- `MCP_HTTP_HOST=127.0.0.1`：仅 `http` 模式生效
- `MCP_HTTP_PORT=3100`：仅 `http` 模式生效
- `MCP_HTTP_PATH=/mcp`：仅 `http` 模式生效

## 发布到 npm

```bash
npm login
npm run release:check
npm publish
```

发布后可直接运行：

```bash
npx -y @flyneko/mcp-market
```

## 安装本地 skills

```bash
# 默认将仓库 skills/* 安装到 ~/.codex/skills
npm run install:skills

# 预览将执行的安装动作（不写入）
npm run install:skills -- --dry-run

# 已存在时覆盖
npm run install:skills -- --force

# 安装到自定义目录（支持 --dest 或 --path）
npm run install:skills -- --path ~/.codex/skills-custom
```

通过 npm 包安装 skills（给其他人用）：

```bash
# 从 npm 下载 @latest 并默认安装其中附带的 skills 到 ~/.codex/skills
npx -y --package @flyneko/mcp-market@latest mcp-market-install-skills

# 预览不写入
npx -y --package @flyneko/mcp-market@latest mcp-market-install-skills --dry-run

# 已存在时覆盖
npx -y --package @flyneko/mcp-market@latest mcp-market-install-skills --force

# 安装到自定义目录（支持 ~/... 路径）
npx -y --package @flyneko/mcp-market@latest mcp-market-install-skills --path ~/.codex/skills-custom
```

## MCP JSON 配置

```json
{
  "mcpServers": {
    "market-data-mcp": {
      "command": "npx",
      "args": ["-y", "@flyneko/mcp-market"]
    }
  }
}
```

以上配置默认通过 `stdio` 传输启动 MCP server；只有在你明确需要 HTTP 部署时，才设置 `MCP_TRANSPORT=http`。

## Tools

### `search_symbol`

- 上游：`GET /api/searchBox/v3?keyword={query}&count={count}&page={page}`
- 入参：

```json
{
  "query": "00700",
  "count": 3,
  "page": 1
}
```

- 返回：`result.searchStock.list`

### `get_quote`

- 上游：`GET /hq/{market}/quote-info/{stockCode}/v2`
- 入参：

```json
{
  "market": "HK",
  "stockCode": "00700"
}
```

- `market` 支持：`US | HK | SH | SZ`
- 返回：`result`

### `get_kline`

- 上游：`GET /hq/{market}/kline/{interval}/{stockCode}/v4`
- 入参：

```json
{
  "market": "SH",
  "interval": "day",
  "stockCode": "600410",
  "timestamp": 1518364800,
  "count": 300,
  "rightsType": "preRights"
}
```

- `market` 支持：`HK | SH | SZ`
- `interval` 支持：`day | week | month | quarter | year | min1 | min5 | min15 | min30 | min60 | min120`
- `rightsType` 支持：`exRights | preRights | afterRights`
- 返回：`result`

### `get_shsz_change_counts`

- 上游：`GET /hq/market/shsz/change-counts/v1`
- 入参：

```json
{}
```

- 返回：`result`

### `get_minute_line`

- 上游：`GET /hq/{market}/minute-line/{stockCode}/v3`
- 入参：

```json
{
  "market": "HK",
  "stockCode": "00700"
}
```

- `market` 支持：`US | HK | SH | SZ`
- 返回：`result`

### `get_stocks_base_data`

- 上游：`GET /hq/stocks/base-data-with-us/v1`
- 入参：

```json
{
  "stockCodes": "HK00700,SH000001"
}
```

- `stockCodes` 必填，支持：
  - 逗号分隔字符串，如 `"HK00700,SH000001"`
  - 数组，如 `["HK00700", "SH000001"]`
- 返回：`result`