SSI Stock Data MCP

Sumário

• Sumário
• 1. Introdução
• 2. Recursos
• 3. Início Rápido
  • 3.1. Pré-requisitos
  • 3.2. Execução Local
  • 3.3. Execução com Docker
• 4. Ferramentas
• 5. Desenvolvimento
• 6. Licença

1. Introdução

SSI Stock Data MCP é um servidor Model Context Protocol (MCP) para obter dados intradiários de ações do Vietnã. Ele permite que assistentes de IA e ferramentas consultem dados intradiários usando a SSI FastConnect API de forma programática e segura.

2. Recursos

• Lista de códigos de ações por bolsa
• Recuperar informações detalhadas de um código de ação
• Recuperar a lista de códigos de ações em uma cesta de índice
• Recuperar a lista de códigos de índices
• Recuperar as informações de abertura, máxima, mínima, fechamento, volume e valor de um código de ação por cada tick de dados
• Recuperar as informações de abertura, máxima, mínima, fechamento, volume e valor de um código de ação por dia
• Recuperar os resultados diários de negociação do índice composto
• Recuperar as informações diárias de negociação de um código de ação
• Suporte a conteinerização com Docker
• Suporte para obter dados em tempo real via adaptador de streaming (planejado)
• Suporte para gerenciamento de ordens e negociação via MCP (consideração futura)

3. Início Rápido

3.1. Pré-requisitos

• Python 3.12+
• uv (para gerenciamento rápido de dependências).
• Docker (opcional, para implantação conteinerizada).
• Certifique-se de se registrar no serviço SSI FastConnect antes de executar este servidor MCP. Você pode se registrar em SSI FastConnect para obter seu consumer ID e secret.

Instalação via Smithery

Para instalar o SSI Stock MCP Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @archiephan78/ssi-stock-mcp-server --client claude

3.2. Execução Local

• Clone o repositório:

# Clone the repository
$ git clone https://github.com/archiephan78/ssi-stock-mcp-server.git

• Configure as variáveis de ambiente

# Set environment variables (see .env.sample)
FC_DATA_URL=https://fc-data.ssi.com.vn/ #optional
FC_DATA_AUTH_TYPE=Bearer #optional
FC_DATA_CONSUMER_ID=your_consumer_id 
FC_DATA_CONSUMER_SECRET=your_consumer_secret  

• Adicione a configuração do servidor ao seu arquivo de configuração do cliente. Por exemplo, para Claude Desktop:

{
  "mcpServers": {
    "SSIStockMCPServer": {
      "command": "uv",
      "args": ["--directory", "full-path", "run", "ssi-stock-mcp-server"],
      "env": {
        "FC_DATA_CONSUMER_ID": "id",
        "FC_DATA_CONSUMER_SECRET": "id",
        "FC_DATA_URL": "https://fc-data.ssi.com.vn/",
        "FC_DATA_AUTH_TYPE": "Bearer"
      }
    }
  }
}

• Reinicie o Claude Desktop para carregar a nova configuração.
• Agora você pode pedir ao Claude para interagir com os dados usando linguagem natural:
  • "chỉ số VN30 hôm nay có gì hot không"
  • "get volume room ngoại đã bán của SSI hôm nay"
  • "so sánh vol của SSI với VND trong ngày hôm nay"
  • "total matchvol của SSI trong 1 tuần trở lại đây"

3.3. Execução com Docker

• Execute com a imagem pré-construída (ou você pode construir a sua própria):

$ docker run -p 8000:8000 
             -e FC_DATA_CONSUMER_ID=id 
             -e FC_DATA_CONSUMER_SECRET=id ghcr.io/archiephan78/ssi-stock-mcp-server

• Executando com Docker no Claude Desktop:

{
  "mcpServers": {
    "SSIStockMCPServer": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "FC_DATA_CONSUMER_ID",
        "-e", "FC_DATA_CONSUMER_SECRET",
        "ghcr.io/archiephan78/ssi-stock-mcp-server:latest"
      ],
      "env": {
        "FC_DATA_CONSUMER_ID": "your_username",
        "FC_DATA_CONSUMER_SECRET": "your_password"
      }
    }
  }
}

Esta configuração passa as variáveis de ambiente do Claude Desktop para o contêiner Docker usando a flag -e apenas com o nome da variável, e fornecendo os valores reais no objeto env.

4. Ferramentas

O servidor MCP expõe ferramentas:

• Obter lista de valores mobiliários: get_securities_list()
• Obter detalhes do valor mobiliário: get_securities_details()
• Obter índice: get_index_components()
• Obter lista de índices: get_index_list()
• Obter abertura, máxima, mínima, fechamento diários: get_daily_ohlc()
• Obter abertura, máxima, mínima, fechamento intradiários: get_intraday_ohlc()
• Obter índice diário: get_daily_index()
• Obter preço da ação: get_stock_price()

Consulte src/ssi_stock_mcp_server/server.py para obter detalhes completos da API.

5. Desenvolvimento

Contribuições são bem-vindas! Abra uma issue ou envie um pull request se tiver sugestões ou melhorias.

Este projeto usa uv para gerenciar dependências. Instale o uv seguindo as instruções para sua plataforma.

# Clone the repository
$ git clone https://github.com/archiephan78/ssi-stock-mcp-server.git
$ uv venv
$ source .venv/bin/activate  # On Unix/macOS
$ .venv\Scripts\activate     # On Windows
$ uv pip install -e .
# run test
$ pytest

6. Licença

Apache 2.0

Contato / Suporte

• Abra uma issue no GitHub se encontrar problemas ou precisar de suporte.
• E-mail: n/a