Financial Modeling Prep MCP Server

Financial Modeling Prep MCP 服务

一个使用 Financial Modeling Prep API 进行金融分析的 Model Context Protocol（MCP）服务，提供工具、资源和提示词。

功能

• 公司信息：获取详细的公司概况和同业比较
• 财务报表：检索并分析利润表、资产负债表和现金流量表
• 财务指标：获取投资分析所需的关键财务比率和指标
• 市场数据：获取市场快照、指数和新闻
• 股票报价：获取当前股票报价、盘后报价和简化的价格信息
• 股票图表：获取历史价格数据并计算价格变动
• 分析师评级：获取分析师建议和评级详情
• 市场指数：获取市场指数数据和报价
• 市场表现：获取涨幅最大、跌幅最大和交易最活跃的股票
• 市场交易时间：查询主要交易所的交易时间和节假日
• ETF 分析：分析 ETF 的行业权重、国家/地区敞口和持仓
• 大宗商品：获取大宗商品列表、当前价格和历史价格数据
• 加密货币：获取加密货币列表和当前报价
• 外汇：获取外汇货币对列表和汇率
• 技术指标：计算并解读指数移动平均线（EMA）
• 分析提示词：使用预定义的提示词模板生成投资分析
• 聊天 Agent：用于与 FMP MCP 服务交互的命令行聊天界面
• 多种传输选项：支持 stdio、SSE 和 Streamable HTTP 传输方式
• 有状态和无状态模式：为不同使用场景提供灵活的部署选项
• Docker 支持：支持配置传输模式的容器化部署
• 运行状况检查端点：内置 /health 端点，用于负载均衡器运行状况检查

代码组织

代码库按照 FMP API 文档中的结构组织。每个模块对应 API 的特定部分：

• analyst.py：分析师建议和目标价
• charts.py：股票图表和历史价格数据
• commodities.py：大宗商品列表、价格数据和历史价格数据
• company.py：公司概况和相关信息
• crypto.py：加密货币列表和报价
• etf.py：ETF 行业权重、国家/地区敞口和持仓
• forex.py：外汇货币对列表和汇率
• indices.py：市场指数列表和报价
• market.py：市场数据和新闻
• market_hours.py：主要交易所的交易时间和节假日
• market_performers.py：涨幅最大、跌幅最大和交易最活跃的股票
• quote.py：股票报价数据、盘后报价和价格变动
• search.py：用于搜索股票代码和公司的 API
• statements.py：财务报表（利润表、资产负债表、现金流量表、比率）
• technical_indicators.py：技术指标和分析

API 端点标准化

代码库采用标准化方式检索不同资产类型的报价：

• 使用统一的 quote 端点检索所有资产类型的报价，包括：

  • 股票
  • 外汇货币对
  • 加密货币
  • 大宗商品
  • 市场指数

• 每个模块都会针对相应的资产类型提供专门的格式化处理：

  • get_quote：标准股票报价
  • get_aftermarket_quote：包含买价/卖价数据的盘后交易报价
  • get_forex_quotes：货币汇率
  • get_crypto_quote：加密货币价格
  • get_commodities_prices：大宗商品价格
  • get_historical_price_eod_light：大宗商品历史价格数据
  • get_index_quote：市场指数值

这种标准化提高了代码的可维护性，并为整个应用中资产价格的检索提供了一致的方式。

其他近期变更

• get_aftermarket_quote：新增用于获取盘后交易数据的函数

  • 使用 "aftermarket-quote" 端点获取买入价／卖出价及数量
  • 包含交易量和时间戳信息
  • 将毫秒时间戳格式化为便于阅读的格式
  • 提供带有表情符号标记的结构化 Markdown 输出

• get_historical_price_eod_light：新增用于获取历史商品价格数据的函数

  • 使用 "historical-price-eod/light" 端点高效获取数据
  • 支持通过 from_date 和 to_date 参数筛选日期范围
  • 包含 limit 参数，用于控制结果数量
  • 计算连续两天之间的每日价格变动和百分比变化
  • 在格式整齐的 Markdown 表格中显示数据，并使用表情符号标记（🔺、🔻、➖）表示价格走势

早期变更

• get_quote_change：更新为使用 "stock-price-change" 端点，而非 "quote-change" 端点

  • 现在可通过单次请求返回所有时间段（1D、5D、1M、3M、6M、YTD、1Y、3Y、5Y、10Y、max）的价格变动
  • 改进表格格式，提升可读性
  • 使用表情符号标记（🔺、🔻、➖），更清晰地展示趋势

• get_financial_estimates：更新为匹配实际的 "analyst-estimates" 端点结构

  • 新增对 API 响应中所有字段的支持（revenueAvg、revenueHigh、revenueLow 等）
  • 新增分页支持，加入 page 参数
  • 改进展示方式，加入分析师数量信息
  • 增强所有指标的高／低／平均值展示

• get_price_target_news：改进为使用 "price-target-news" 端点

  • 新增按 symbol 筛选的支持
  • 包含调整后的目标价信息
  • 改进日期格式，提升可读性
  • 支持 API 响应中的所有字段

• get_key_metrics：增强全面财务指标工具

  • 改进对 key-metrics 端点中所有指标的支持
  • 新增指标的详细分类（估值、盈利能力、流动性等）
  • 改进财务数据的格式和组织方式
  • 支持财年和货币信息

测试也采用类似的组织方式，每个模块对应一个测试文件，并遵循统一模式，确保覆盖全面。

安装

1. 克隆代码仓库：

   git clone https://github.com/cdtait/fmp-mcp-server.git
   cd fmp-mcp-server
   

2. 使用 pip 或 uv 设置环境：

   选项 1：使用 pip（标准方式）

   # Create and activate a virtual environment
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install pip if not available (rare but possible in some environments)
   # curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && python get-pip.py
   
   # Install dependencies
   python -m pip install -r requirements.txt
   
   # For development (includes testing dependencies)
   python -m pip install -e ".[dev]"
   

   选项 2：使用 uv（更快）

   # Install uv if you don't have it yet
   curl -LsSf https://astral.sh/uv/install.sh | sh
   export PATH=~/.local/bin/:${PATH}
   
   # Create and activate the environment
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install dependencies
   uv pip install -r requirements.txt
   
   # For development (includes testing dependencies)
   uv pip install -e ".[dev]"
   

3. 设置你的 Financial Modeling Prep API 密钥：

   # Copy the template
   cp .env.template .env
   
   # Edit the .env file to add your API key
   # Replace 'your_api_key_here' with your actual API key from FMP
   

   你可以在 Financial Modeling Prep 注册并获取 API 密钥。

4. 设置你的 OpenAI API 密钥（如果使用聊天 Agent）：

   # Add your OpenAI API key to the .env file
   echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env
   

5. 运行测试以验证安装：

   # Run unit tests
   python -m pytest tests/ -v
   
   # Run acceptance tests with mock data
   TEST_MODE=true python -m pytest tests/acceptance_tests.py -v
   

开发

本项目采用测试驱动开发（TDD）方法。测试套件位于 tests/ 目录中。

测试策略

项目采用全面的测试策略，包含三种不同的测试类型：

1. 单元测试（test_company.py、test_quotes.py 等）

   • 专注于隔离测试单个函数
   • 按模块组织，与代码结构保持一致
   • 模拟所有外部依赖
   • 验证正常运行、边缘情况和错误处理时的行为是否正确
   • 执行速度快，且无外部依赖
   • 采用一致的模式，使用 @patch 装饰器进行模拟
   • 在打补丁后导入函数，以确保正确隔离模拟

2. 集成测试（test_server.py、test_resources.py）

   • 测试各组件如何协同工作
   • 验证服务设置、工具注册和资源处理是否正确
   • 使用模拟的外部 API 测试端到端流程
   • 确保系统组件正确集成
   • 验证组件之间的错误处理是否正确

3. 验收测试（acceptance_tests.py）

   • 验证与真实 FMP API 的集成
   • 验证 API 连接和响应格式
   • 使用无效输入测试错误处理
   • 关注数据结构，而非具体值
   • 可使用真实 API 运行，也可通过设置 TEST_MODE=true 使用模拟数据运行
   • 仅在明确触发或提供 API 密钥时，才使用真实 API 运行

这种多层级方法既能确保单个组件正常工作，也能验证整个系统的可靠性，并确保应用程序在隔离运行及与真实 API 集成时都能正常工作。

运行测试

# Run all unit and integration tests
python -m pytest

# Run with coverage report
python -m pytest --cov=src tests/

# Run specific test file
python -m pytest tests/test_company.py

# Run tests with specific marker
python -m pytest -m acceptance

验收测试

项目包含用于验证与真实 FMP API 集成的验收测试。这些测试需要有效的 API 密钥，也可以使用模拟数据运行。

运行验收测试：

# Option 1: Run with the real API
# Set your API key
export FMP_API_KEY=your_api_key_here

# Run the acceptance tests with real API
python -m pytest tests/acceptance_tests.py -v

# Option 2: Run with mock data
# This doesn't require an API key and uses mock responses
TEST_MODE=true python -m pytest tests/acceptance_tests.py -v

这些测试会验证：

• API 连接
• 数据格式和结构
• 使用无效输入时的错误处理
• 使用真实数据时的工具格式

验收测试旨在检查格式和结构，而不对可能随时间变化的具体值（如股价）作出断言。因此，在提供有效 API 密钥密文的 CI/CD 流水线中也适合运行这些测试。

设置 TEST_MODE=true 后，可在 CI 环境中运行验收测试，而无需真实 API 密钥；测试将使用 conftest.py 中定义的模拟响应。

项目结构

fmp-mcp-server/
├── src/                      # Source code
│   ├── api/                  # API client functionality 
│   │   ├── client.py         # FMP API client
│   ├── tools/                # MCP tools implementation
│   │   ├── analyst.py        # Analyst ratings tools
│   │   ├── charts.py         # Stock chart tools
│   │   ├── commodities.py    # Commodities tools
│   │   ├── company.py        # Company profile tools
│   │   ├── crypto.py         # Cryptocurrency tools
│   │   ├── etf.py            # ETF analysis tools
│   │   ├── forex.py          # Forex tools
│   │   ├── indices.py        # Market indices tools
│   │   ├── market.py         # Market data tools
│   │   ├── market_hours.py   # Market hours tools 
│   │   ├── market_performers.py # Market performers tools
│   │   ├── quote.py          # Stock quote tools
│   │   ├── search.py         # Search tools
│   │   ├── statements.py     # Financial statements tools
│   │   └── technical_indicators.py # Technical analysis tools
│   ├── resources/            # MCP resources implementation
│   │   ├── company.py
│   │   └── market.py
│   ├── prompts/              # MCP prompts implementation
│   │   └── templates.py
│   └── agent_chat_client.py  # OpenAI Agent-based chat client
├── scripts/                  # Deployment and automation scripts
│   └── mcp-aws-ecs-setup.sh  # AWS ECS deployment script
├── tests/                    # Test suite
│   ├── conftest.py           # Pytest fixtures
│   ├── acceptance_tests.py   # API integration tests
│   ├── test_analyst.py       # Tests for analyst tools
│   ├── test_api_client.py    # Tests for API functionality
│   ├── test_calendar.py      # Tests for calendar tools
│   ├── test_charts.py        # Tests for chart tools
│   ├── test_commodities.py   # Tests for commodities tools
│   ├── test_company.py       # Tests for company profile tools
│   ├── test_crypto.py        # Tests for cryptocurrency tools
│   ├── test_etf.py           # Tests for ETF tools
│   ├── test_forex.py         # Tests for forex tools
│   ├── test_indices.py       # Tests for indices tools
│   ├── test_market.py        # Tests for market tools
│   ├── test_market_hours.py  # Tests for market hours tools
│   ├── test_market_performers.py # Tests for market performers tools
│   ├── test_prompts.py       # Tests for prompts
│   ├── test_quotes.py        # Tests for quote tools
│   ├── test_resources.py     # Tests for resources
│   ├── test_search.py        # Tests for search tools
│   ├── test_server.py        # Integration tests
│   ├── test_statements.py    # Tests for financial statements tools
│   └── test_technical_indicators.py # Tests for technical indicators tools
├── Dockerfile                # Docker configuration
├── docker-compose.yml        # Docker Compose configuration
└── server.py                 # Main server implementation

使用方法

运行服务

你可以通过不同方式运行服务：

本地开发（stdio）

# Run the server directly (stdio mode)
python -m src.server

# Or use the MCP CLI for development
mcp dev src/server.py

# Install in Claude Desktop
mcp install src/server.py

SSE 服务模式

# Run as an SSE server
python -m src.server --sse --port 8000

Streamable HTTP 服务模式

注意：Streamable HTTP 传输是生产部署的推荐传输方式，取代 SSE 传输。

服务支持 Streamable HTTP 传输，并提供有状态和无状态两种运行模式：

# Stateful Streamable HTTP (maintains session state)
python -m src.server --streamable-http --port 8000

# Stateless Streamable HTTP (no session persistence)
python -m src.server --streamable-http --stateless --port 8000

# Stateless with JSON responses (instead of SSE streams)
python -m src.server --streamable-http --stateless --json-response --port 8000

传输模式：

• 有状态（默认）：维护会话状态，支持事件续传，适合交互式客户端
• 无状态：不持久化会话，适合多节点部署和负载均衡
• JSON 响应：返回 JSON，而非 SSE 流，适用于更简单的 HTTP 客户端

端点：

• Streamable HTTP 端点：http://localhost:8000/mcp
• 健康检查端点：http://localhost:8000/health
• 所有 MCP 操作（工具、资源、提示词）均可通过 HTTP POST/GET 使用

Docker 支持：

# Default SSE mode
docker run -p 8000:8000 -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

# Streamable HTTP stateful mode
docker run -p 8000:8000 -e TRANSPORT=streamable-http -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

# Streamable HTTP stateless mode
docker run -p 8000:8000 -e TRANSPORT=streamable-http -e STATELESS=true -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

# Streamable HTTP stateless JSON mode
docker run -p 8000:8000 -e TRANSPORT=streamable-http -e STATELESS=true -e JSON_RESPONSE=true -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

故障排除

如果运行服务时遇到导入错误，请确认：

1. 已激活虚拟环境：

   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

2. 已正确安装所有依赖项：

   python -m pip install -r requirements.txt
   

这会以 SSE（服务器发送事件）模式启动服务，从而允许 MCP Inspector 或其他 MCP 客户端通过 HTTP 连接。

使用聊天 Agent

项目包含一个聊天 Agent，它通过 SSE 连接到 FMP MCP 服务，并提供用于查询金融数据的交互式 CLI 界面。

前置条件

• OpenAI API 密钥（设置在环境变量或 .env 文件中）
• 正在以 SSE 模式运行的 FMP MCP 服务

运行聊天 Agent

1. 以 SSE 模式启动 FMP MCP 服务：

# In one terminal window
python -m src.server --sse

2. 在另一个终端窗口中运行聊天 Agent：

# Ensure you have the OpenAI API key set
export OPENAI_API_KEY=your_openai_api_key_here

# Run the chat agent
python -m src.agent_chat_client

3. 开始与财务顾问 Agent 聊天：

View trace: https://platform.openai.com/traces/trace?trace_id=trace_abc123...

You: What is the current price of Apple?
Running: What is the current price of Apple?
The current price of Apple Inc. (AAPL) is $202.52.

You: Compare AAPL and MSFT's financial performance
Running: Compare AAPL and MSFT's financial performance
...

聊天 Agent 功能

• 交互式 FMP 金融数据聊天界面
• 通过自然语言访问所有 FMP 数据工具
• 基于 OpenAI Agent 的实现，可处理复杂查询
• 跟踪视图，便于调试并了解 Agent 的操作

输入 exit 或 quit 结束聊天会话。

使用 Docker

使用 Docker 运行服务有几种方式：

选项 1：在本地构建并运行

# Build and run with Docker (includes health check endpoint)
docker build -t fmp-mcp-server .
docker run -p 8000:8000 -e FMP_API_KEY=your_api_key_here fmp-mcp-server

# Or use docker-compose with default port (8000)
# Method 1: Export environment variables (less secure)
export FMP_API_KEY=your_api_key_here
docker-compose up

# Method 2 (PREFERRED): Use a .env file (more secure)
# First, create a .env file in the project root with your API key
echo "FMP_API_KEY=your_api_key_here" > .env
docker-compose up

# Use docker-compose with a custom port
# Using environment variable
PORT=9000 docker-compose up

# Using both .env file and custom port
echo "FMP_API_KEY=your_api_key_here" > .env
PORT=9000 docker-compose up

选项 2：使用 GitHub Container Registry 中预构建的镜像

# Pull the latest image
docker pull ghcr.io/cdtait/fmp-mcp-server:latest

# Run with environment variable for API key
docker run -p 8000:8000 -e FMP_API_KEY=your_api_key_here ghcr.io/cdtait/fmp-mcp-server:latest

# Run with custom port
docker run -p 9000:8000 -e FMP_API_KEY=your_api_key_here ghcr.io/cdtait/fmp-mcp-server:latest

# Run with a mounted .env file (PREFERRED)
# First create your .env file with your API key
echo "FMP_API_KEY=your_api_key_here" > .env

# Then mount it when running the container
docker run -p 8000:8000 -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

服务在容器内始终监听端口 8000，但 Docker 会将其映射到指定的主机端口（默认为 8000，或 PORT 环境变量的值）。

**注意：**建议使用 .env 文件来存储 API 密钥，而不是在 shell 中导出密钥，因为这样可以降低密钥意外泄露到命令历史记录或环境变量中的风险。

使用 MCP Inspector

MCP Inspector 是一个用于测试 MCP 服务的实用工具。你可以用它浏览可用的工具、资源和提示词，并进行交互式测试。

使用 Node.js 运行 MCP Inspector

运行 MCP Inspector 最简单的方式是使用 Node.js：

# Using npx (no installation required)
npx @modelcontextprotocol/inspector

# Or if you have the package installed globally
mcp-inspector

MCP Inspector 运行后：

1. 在 Transport 下拉菜单中选择“HTTP/SSE”
2. 输入服务 URL：http://localhost:8000/sse
   • 如果你使用自定义端口启动了服务（例如 PORT=9000），则使用该端口：http://localhost:9000/sse
3. 点击“Connect”以建立与服务的连接
4. 在对应的标签页中浏览可用的工具、资源和提示词

测试健康检查

服务运行后，你可以测试健康检查端点：

# Test the dedicated health endpoint (ALB-compatible GET request)
curl http://localhost:8000/health

# Expected response:
# {"status":"healthy","service":"fmp-mcp-server"}

# Test MCP redirect endpoint (ALB-compatible GET request)
curl http://localhost:8000/mcp/

# Expected response: HTTP 307 redirect (indicates service is running)

# Test full MCP functionality (JSON-RPC POST request)
curl -L -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping",
    "params": {}
  }' \
  http://localhost:8000/mcp

# Expected response:
# event: message
# data: {"jsonrpc":"2.0","id":1,"result":{}}

# Test with ALB (after deployment)
curl http://your-alb-dns-name.region.elb.amazonaws.com/health

# Test full MCP functionality via ALB
curl -L -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping",
    "params": {}
  }' \
  http://your-alb-dns-name.region.elb.amazonaws.com/mcp

示例查询

服务运行并连接到 Claude Desktop 或 MCP Inspector 等 MCP 客户端后，你可以：

1. 获取公司简介：

   • “使用公司简介工具介绍 Apple 的财务状况”
   • “TSLA 的关键财务指标有哪些？”

2. 获取财务报表：

   • “显示 AAPL 最近一年的损益表”
   • “TSLA 的资产负债表是什么样的？”
   • “获取 MSFT 的现金流量表并进行分析”

3. 获取股票报价和价格信息：

   • “MSFT 股票当前价格是多少？”
   • “显示 GOOGL 最近的价格变动”
   • “比较 AAPL、AMZN 和 META 的当前报价”
   • “获取 AAPL 的盘后报价”
   • “显示 TSLA 盘后的买卖价差”

4. 获取分析师评级：

   • “分析师如何看待 AMZN 股票？”
   • “获取 NVDA 的分析师评级概览”
   • “显示 MSFT 最新的目标价”

5. 获取市场指数和表现最佳的股票：

   • “显示当前主要市场指数”
   • “今天涨幅最大的股票有哪些？”
   • “今天市场上交易最活跃的股票有哪些？”

6. 查看市场状态：

   • “现在市场开盘了吗？”
   • “下一个市场假期是什么时候？”
   • “NYSE 的交易时间是什么？”

7. 分析 ETF：

   • “SPY 的主要持仓有哪些？”
   • “显示 QQQ 的行业分布”
   • “VEU 投资了哪些国家？”

8. 获取大宗商品、加密货币和外汇信息：

   • “黄金当前价格是多少？”
   • “显示过去一个月的黄金历史价格数据”
   • “显示当前 Bitcoin 价格”
   • “EURUSD 的汇率是多少？”

9. 获取技术分析：

   • “计算 AAPL 的 RSI”
   • “提供 TSLA 的技术分析摘要”
   • “AMZN 的 20 日 SMA 能说明什么？”

10. 使用分析提示词：

    • “使用股票比较提示词比较 AAPL、MSFT 和 GOOGL”
    • “使用财务报表分析提示词分析 TSLA 的财务报表”

配置

服务使用以下环境变量：

• FMP_API_KEY：你的 Financial Modeling Prep API 密钥（必需）
  • 你可以在 Financial Modeling Prep 注册以获取 API 密钥
  • 可通过命令行、环境变量或 .env 文件传入
• OPENAI_API_KEY：你的 OpenAI API 密钥（使用聊天 Agent 时必需）
  • 从 OpenAI 获取 API 密钥
• PORT：使用 Docker Compose 运行时要使用的主机端口（默认为 8000）
  • 仅影响主机端口映射；容器内部始终在 8000 端口运行
• TEST_MODE：设为 "true" 可在验收测试中使用模拟数据
  • 适用于 CI/CD 环境，或在没有有效 API 密钥时进行测试
  • 使用在 tests/conftest.py 中定义的模拟响应
  • 包含多种资产类型的全面模拟数据：
    • 股票（AAPL、MSFT 等）
    • 外汇货币对（EURUSD、GBPUSD、USDJPY）
    • 加密货币（BTCUSD、ETHUSD）
    • 大宗商品（黄金对应 GCUSD、原油对应 CLUSD、布伦特原油对应 BZUSD）
    • 市场指数（标普 500 对应 ^GSPC、道琼斯指数对应 ^DJI）

你可以在项目根目录的 .env 文件中设置这些变量：

# Example .env file contents
FMP_API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
PORT=9000
TEST_MODE=true  # For testing with mock data

贡献

1. 创建功能分支
2. 为你的功能编写测试
3. 实现你的功能，并确保测试通过
4. 提交拉取请求

CI/CD 流水线

本项目实现了一个包含多个阶段的全面 CI/CD 流水线：

1. 持续集成（ci.yml）

每个拉取请求以及对 main 的每次推送都会自动触发：

• 单元测试：使用 pytest 测试各个组件

  • 在多个 Python 版本（3.11、3.12）上运行
  • 排除验收测试
  • 向 Codecov 报告覆盖率

• 集成测试：验证组件之间的交互

  • 使用 TEST_MODE=true 运行验收测试
  • 使用模拟数据以避免 API 费用
  • 单独报告覆盖率指标

• 部署（合并到 main 时）：

  • 使用最新代码构建 Docker 镜像
  • 发布到 GitHub Container Registry
  • 创建部署标记以便跟踪

工作流配置位于 .github/workflows/ci.yml。

2. 验收测试（acceptance-tests.yml）

使用真实 FMP API 的测试会按以下方式运行：

• 定期运行：每周一 UTC 时间凌晨 5 点自动运行
• 按需运行：可手动触发，并指定特定提交
• 验证：确认与真实 API 的兼容性
• 状态更新：记录部署的成功或失败状态

此独立工作流有助于确保与外部 API 的兼容性，同时保持主 CI 流水线的快速运行，并避免不必要的 API 费用。

手动运行验收测试工作流：

1. 前往 GitHub 仓库
2. 点击 "Actions" 选项卡
3. 在工作流列表中选择 "API Acceptance Tests"
4. 点击 "Run workflow"（可选择指定提交 SHA）

验收测试工作流配置位于 .github/workflows/acceptance-tests.yml。

3. 发布流程（release.yml）

准备好发布稳定版本时：

• 手动触发：提供版本号和提交 SHA
• 验证：确保该提交已通过验收测试
• 打标签：创建 Git 标签和 GitHub Release
• 生产镜像：发布带版本号的 Docker 镜像和稳定版 Docker 镜像

创建新版本：

1. 前往 GitHub 仓库
2. 点击 "Actions" 选项卡
3. 在工作流列表中选择 "Release"
4. 点击 "Run workflow"
5. 输入要发布的版本号和提交 SHA

发布工作流配置位于 .github/workflows/release.yml。

容器注册表

Docker 镜像会以多个标签发布到 GitHub Container Registry：

# Development (from CI pipeline)
docker pull ghcr.io/cdtait/fmp-mcp-server:latest           # Latest build from main branch
docker pull ghcr.io/cdtait/fmp-mcp-server:a7f33fe2ce0265e0 # Specific commit

# Production releases (from release workflow)
docker pull ghcr.io/cdtait/fmp-mcp-server:stable           # Latest stable release
docker pull ghcr.io/cdtait/fmp-mcp-server:v1.2.3           # Specific version

有关运行容器的详细说明，请参阅 使用 Docker 部分。

AWS ECS 部署

该项目包含全面的 AWS ECS 部署自动化功能，提供生产环境就绪特性，包括负载均衡、服务发现和重复检测。

可用的部署脚本

scripts/ 目录中提供了以下脚本：

• mcp-aws-ecs-setup.sh - ECS 主部署脚本，支持重复检测
• add-load-balancer.sh - 添加 Application Load Balancer，以实现稳定的外部访问
• add-service-discovery.sh - 添加 AWS Cloud Map 服务发现，以支持内部通信
• cleanup-duplicates.sh - 查找并移除重复服务

前置条件

• 已安装并配置 AWS CLI v2
• 拥有全面权限的 AWS IAM 用户：
  • AmazonECS_FullAccess
  • AmazonEC2ReadOnlyAccess
  • IAMFullAccess（或 CloudWatchLogsFullAccess + SecretsManagerReadWrite）
  • CloudWatchReadOnlyAccess
• FMP API 密钥
• 容器镜像（来自 GitHub Container Registry 或自定义构建）

快速设置

步骤 1：基本 ECS 部署

# Make scripts executable
chmod +x scripts/*.sh

# Run the main setup script
./scripts/mcp-aws-ecs-setup.sh

脚本会提示你输入：

• AWS 区域（例如 eu-west-2、us-east-1）
• ECS 集群名称（例如 mcp-cluster）
• 任务定义名称（例如 mcp-task-stream）
• 容器镜像（例如 ghcr.io/cdtait/fmp-mcp-server:latest）
• 端口号（例如 8000、8001）
• FMP API 密钥（安全存储在 AWS Secrets Manager 中）

步骤 2：添加负载均衡器（推荐）

# Add Application Load Balancer for stable external access
./scripts/add-load-balancer.sh

这会提供稳定的 DNS 名称，例如 mcp-alb-123456789.eu-west-2.elb.amazonaws.com，而不是不断变化的 IP 地址。

步骤 3：添加服务发现（可选）

# Add AWS Cloud Map for internal service discovery
./scripts/add-service-discovery.sh

这样，服务便可在 VPC 内使用类似 mcp-streamable.fmp-mcp-services 的 DNS 名称相互发现。

重复检测与预防

所有脚本都包含智能重复检测功能：

ECS 设置脚本功能：

• 检测使用相同任务定义的现有服务
• 创建新服务前警告存在功能重复的服务
• 提供三个选项：
  1. 更新现有服务（推荐）
  2. 仍然创建新服务（可能导致重复）
  3. 退出并手动清理

重复检测输出示例：

🔄 DUPLICATE DETECTED: Service 'mcp-streamable-service-a1a90073' already uses task family 'mcp-task-stream'

🚨 DUPLICATE SERVICE DETECTED! 🚨
Service 'mcp-streamable-service-a1a90073' already runs the same task definition family 'mcp-task-stream'

Recommended actions:
1. Update existing service 'mcp-streamable-service-a1a90073' (RECOMMENDED)
2. Create new service anyway (will cause duplicates and extra costs)
3. Exit and cleanup manually

清理重复服务：

# Check for and remove duplicate services
./scripts/cleanup-duplicates.sh

此脚本会：

• 查找使用相同任务定义的服务
• 显示哪些服务配置了负载均衡器（建议保留）
• 提供自动清理重复服务的功能
• 提供手动清理命令

环境变量

你可以通过设置环境变量预先配置部署：

# Create deployment configuration
cat > .env << EOF
REGION=eu-west-2
CLUSTER_NAME=mcp-cluster
TASK_FAMILY=mcp-task-stream
CONTAINER_IMAGE=ghcr.io/cdtait/fmp-mcp-server:latest
PORT=8001
FMP_API_KEY=your_api_key_here
EOF

# Source the environment
source .env

# Run scripts without prompts
./scripts/mcp-aws-ecs-setup.sh
./scripts/add-load-balancer.sh

脚本创建的内容

基本 ECS 设置（mcp-aws-ecs-setup.sh）：

1. AWS CLI v2 安装（如有需要）
2. 使用 Fargate 容量提供程序的 ECS 集群
3. 具有 CloudWatch Logs 和 Secrets Manager 权限的 IAM 角色
4. 可配置端口访问权限的 安全组
5. 用于安全存储 API 密钥的 Secrets Manager 集成
6. 使用可流式 HTTP 传输的 ECS 服务
7. 用于直接访问的 公共 IP 端点

负载均衡器设置（add-load-balancer.sh）：

1. 面向互联网的 Application Load Balancer
2. 配置运行状况检查的 目标组（检测 HTTP 307 重定向）
3. 用于 ALB ↔ ECS 通信的 安全组规则
4. 用于外部访问的 稳定 DNS 端点
5. 自动运行状况监控和故障转移

服务发现设置（add-service-discovery.sh）：

1. AWS Cloud Map 私有 DNS 命名空间
2. 用于自动发现的 服务注册
3. 用于服务间通信的 内部 DNS 名称
4. 运行状况检查以及自动注册和注销

部署后

基本部署输出：

=== SETUP COMPLETE ===

Cluster: mcp-cluster
Region: eu-west-2

Service: mcp-streamable-service-abc123
- Endpoint: http://3.10.53.254:8001/mcp/
- Transport: streamable-http (stateless)
- Task Definition: mcp-task-stream:1

Test command:
curl http://3.10.53.254:8001/mcp/meta

MCP Inspector Connection URL:
http://3.10.53.254:8001/mcp/

使用负载均衡器：

=== APPLICATION LOAD BALANCER SETUP COMPLETE ===

Load Balancer: mcp-alb
DNS Name: mcp-alb-689612947.eu-west-2.elb.amazonaws.com

Your service is now accessible at:
http://mcp-alb-689612947.eu-west-2.elb.amazonaws.com/mcp/meta

Test commands:
curl http://mcp-alb-689612947.eu-west-2.elb.amazonaws.com/mcp/meta
curl http://mcp-alb-689612947.eu-west-2.elb.amazonaws.com/mcp/

使用服务发现：

=== SERVICE DISCOVERY SETUP COMPLETE ===

Namespace: fmp-mcp-services
Service: mcp-streamable
DNS Name: mcp-streamable.fmp-mcp-services

Your service can now be reached at:
- Internal DNS: mcp-streamable.fmp-mcp-services
- From within the VPC: http://mcp-streamable.fmp-mcp-services:8001

扩缩容与管理

# Scale service to 2 instances for high availability
aws ecs update-service --region eu-west-2 --cluster mcp-cluster --service SERVICE_NAME --desired-count 2

# Force new deployment (useful for updates)
aws ecs update-service --region eu-west-2 --cluster mcp-cluster --service SERVICE_NAME --force-new-deployment

# View service status
aws ecs describe-services --region eu-west-2 --cluster mcp-cluster --services SERVICE_NAME

# Check load balancer health
aws elbv2 describe-target-health --region eu-west-2 --target-group-arn TARGET_GROUP_ARN

# View logs
aws logs tail /ecs/mcp-task-stream --region eu-west-2 --follow

运行状况检查

服务器提供多种运行状况检查方式：

选项 1：专用健康检查端点（推荐）

• 健康检查路径：/health
• 方法：GET（简单的 HTTP 请求）
• 预期响应：HTTP 200，JSON 正文为 {"status": "healthy", "service": "fmp-mcp-server"}
• 优点：专为负载均衡器健康检查设计的简单、快速、轻量级端点

选项 2：MCP 重定向端点（旧版）

• 健康检查路径：/mcp/
• 方法：GET（ALB 健康检查仅支持 GET）
• 预期响应：HTTP 307 重定向（表示 MCP 服务正在响应）
• 用途：兼容要求 MCP 协议可用的现有配置

负载均衡器功能：

• 自动故障转移：自动替换不健康的实例
• 跨可用区分布：实例分布在多个可用区

安全功能

• API 密钥存储在 AWS Secrets Manager 中（而非环境变量）
• 安全组仅开放所需的最少访问权限
• IAM 角色遵循最小权限原则
• VPC 隔离用于内部服务通信
• 支持 HTTPS 的负载均衡器配置

最佳实践

1. 生产环境的外部访问始终使用负载均衡器
2. 至少扩展到 2 个实例以实现高可用性
3. 在多服务架构中使用服务发现
4. 重新部署前运行清理脚本以避免重复
5. 监控 CloudWatch 日志以检查应用健康状况
6. 使用 Secrets Manager存储敏感配置

Terraform 基础设施

本项目包含可用于生产环境的 Terraform 配置，可将 FMP MCP 服务部署到 AWS，并提供企业级功能和成本优化。

基础设施功能

• 🏗️ 单区域架构：简化部署，并支持可选的多区域配置
• 🐳 ECS Fargate：支持自动扩缩的无服务器容器平台
• ⚖️ 应用程序负载均衡器：提供高可用性和健康检查
• 🔒 安全最佳实践：VPC 隔离、IAM 角色、安全组
• 🗺️ 服务发现：通过 AWS Cloud Map 实现内部服务通信
• 📊 监控：CloudWatch 日志和健康监控
• 💰 成本优化：仅在周末运行，每周可节省 69-83% 的成本
• 🌐 多区域支持：基于延迟的 Route53 路由
• 🔐 密钥管理：使用 AWS Secrets Manager 管理 API 密钥

快速开始

# Navigate to terraform directory
cd terraform/fmp-mcp-modular

# Copy and configure variables
cp terraform.tfvars.example terraform-my-region.tfvars
# Edit with your values (region, domain, etc.)

# Deploy infrastructure
terraform init
terraform plan -var-file="terraform-my-region.tfvars" -out="my-region.tfplan"
terraform apply my-region.tfplan

# Set API key in AWS Secrets Manager
SECRET_ARN=$(terraform output -raw secret_arn)
aws secretsmanager put-secret-value \
  --secret-id $SECRET_ARN \
  --secret-string '{"API_KEY":"your-fmp-api-key-here"}'

# Get application URL
terraform output application_url

多区域部署

要进行全球部署并实现自动故障转移：

# Deploy to multiple regions with separate state files
terraform apply -var-file="terraform-eu-west-1.tfvars" \
  -state="terraform-eu-west-1.tfstate" \
  -state-out="terraform-eu-west-1.tfstate"

terraform apply -var-file="terraform-eu-west-2.tfvars" \
  -state="terraform-eu-west-2.tfstate" \
  -state-out="terraform-eu-west-2.tfstate"

# Route53 automatically provides latency-based routing

成本优化

基础设施包含智能的仅周末运行调度：

# Enable weekend-only mode (69-83% cost savings)
terraform apply -var-file="terraform-my-region.tfvars" \
  -var="enable_weekend_only=true" \
  -var="destroy_albs_when_scaled_down=false"

# Manual scaling operations
aws ecs update-service \
  --cluster $(terraform output -raw ecs_cluster_name) \
  --service $(terraform output -raw ecs_service_name) \
  --desired-count 0  # Scale down

架构

Terraform 配置会创建：

• 支持多可用区的 VPC 公有子网
• 包含 Fargate 任务的 ECS 集群
• 带健康检查的 应用程序负载均衡器
• 配置基于延迟路由的 Route53 DNS（多区域）
• 遵循最小权限原则的 IAM 角色
• 用于安全存储 API 密钥的 Secrets Manager
• CloudWatch 日志记录和监控

详细架构图、配置选项和管理命令，请参阅完整文档 terraform/fmp-mcp-modular/README.md。

覆盖率报告

代码覆盖率按不同测试阶段进行跟踪：

• 单元测试：基本代码路径覆盖率
• 集成测试：使用模拟数据的覆盖率
• 验收测试：使用真实 API 调用的覆盖率

项目使用 Codecov 汇总并可视化覆盖率指标，并为每个测试阶段设置单独的标记。