# https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server 项目说明书

生成时间：2026-05-31 18:25:37 UTC

## 目录

- [项目概述](#project-overview)
- [快速开始](#quick-start)
- [系统架构](#system-architecture)
- [API 客户端层](#api-clients)
- [安装部署](#installation)
- [配置指南](#configuration)
- [服务器模式](#server-modes)
- [工具目录](#tools-catalog)
- [工具使用指南](#tools-usage)
- [常见问题与故障排除](#troubleshooting)

<a id='project-overview'></a>

## 项目概述

### 相关页面

相关主题：[快速开始](#quick-start), [系统架构](#system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/README.md)
- [package.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/package.json)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [CONTRIBUTING.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CONTRIBUTING.md)
- [CHANGELOG.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CHANGELOG.md)
- [server.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/server.json)
</details>

# 项目概述

## 项目简介

Financial-Modeling-Prep-MCP-Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 助手提供访问 Financial Modeling Prep (FMP) 金融数据 API 的能力。该项目通过 MCP 协议将 FMP 的丰富金融数据（包括股票报价、财务报表、新闻、SEC 文件等）封装为一组可被 AI 客户端调用的工具。资料来源：[README.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/README.md)

该项目采用 TypeScript 开发，支持动态工具发现和静态工具集两种运行模式，可通过 npm 全局安装或通过 MCP 注册表进行集成。最新版本为 v2.6.10，已发布至 NPM Registry 和 MCP Registry。资料来源：[package.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/package.json)

## 核心架构

### 系统组件

```mermaid
graph TD
    A[MCP 客户端] --> B[MCP 服务器]
    B --> C[工具发现层]
    C --> D[工具集目录]
    D --> E[模块加载器]
    E --> F[API 客户端]
    F --> G[FMP API]
    
    H[会话配置] --> B
    I[环境变量] --> B
    J[命令行参数] --> B
```

### 技术栈

| 组件 | 技术选型 | 说明 |
|------|----------|------|
| 开发语言 | TypeScript | 类型安全保证 |
| 运行时 | Node.js >= 25.3.0 | 最低版本要求 |
| 包管理器 | npm >= 11.11.0 | 依赖管理 |
| MCP SDK | @modelcontextprotocol/sdk ^1.27.1 | MCP 协议实现 |
| 工具框架 | toolception | 动态工具管理 |
| 状态管理 | Smithery SDK | 有状态会话管理 |
| HTTP 服务 | 内置 JSON-RPC 端点 | 远程调用支持 |
| 测试框架 | Vitest | 单元测试 |
| 代码检查 | oxlint, knip | 代码质量 |

资料来源：[package.json:测试依赖](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/package.json)

## 服务器运行模式

该项目支持三种服务器运行模式，通过 `ServerMode` 类型定义：

| 模式 | 描述 | 使用场景 |
|------|------|----------|
| `DYNAMIC_TOOL_DISCOVERY` | 动态工具发现模式 | 客户端按需加载工具 |
| `STATIC_TOOL_SETS` | 静态工具集模式 | 预定义工具集启动 |
| `ALL_TOOLS` | 全量工具模式 | 加载所有可用工具 |

资料来源：[src/types/index.ts:ServerMode](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)

### 配置映射机制

`ModeConfigMapper` 类负责将 FMP 的服务器模式转换为 toolception 框架的配置格式：

```mermaid
graph LR
    A[ServerMode] --> B[ModeConfigMapper]
    B --> C[ToolceptionConfig]
    C --> D[startup.mode]
    C --> E[catalog]
    C --> F[moduleLoaders]
```

## 工具集分类

项目将功能划分为 24 个工具集，涵盖金融数据的各个领域：

| 工具集 | 名称 | 核心功能 |
|--------|------|----------|
| `search` | 搜索 | 股票符号搜索 |
| `company` | 公司信息 | 公司基本信息和详情 |
| `quotes` | 报价数据 | 实时和历史价格 |
| `statements` | 财务报表 | 资产负债表、利润表等 |
| `calendar` | 日历 | 财报发布时间 |
| `charts` | 图表 | K 线图数据 |
| `news` | 新闻 | 金融新闻和公告 |
| `analyst` | 分析师 | 分析师评级和建议 |
| `market-performance` | 市场表现 | 指数和板块表现 |
| `insider-trades` | 内部交易 | 高管和内部人交易 |
| `institutional` | 机构持仓 | 13F 机构持仓 |
| `indexes` | 指数 | 市场指数数据 |
| `economics` | 经济数据 | 宏观经济指标 |
| `crypto` | 加密货币 | 加密货币数据 |
| `forex` | 外汇 | 汇率数据 |
| `commodities` | 大宗商品 | 商品期货价格 |
| `etf-funds` | ETF 基金 | ETF 持仓和净值 |
| `esg` | ESG 评分 | 环境社会治理评分 |
| `technical-indicators` | 技术指标 | RSI、MA 等指标 |
| `senate` | 政府交易 | 国会交易披露 |
| `sec-filings` | SEC 文件 | 监管文件 |
| `earnings` | 财报会议 | 财报电话会议记录 |
| `dcf` | DCF 估值 | 现金流折现模型 |
| `bulk` | 批量数据 | 批量数据导出 |

资料来源：[src/types/index.ts:ToolSet](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)

### 工具集定义结构

每个工具集在 `src/constants/toolSets.ts` 中定义为 `ToolSetDefinition`：

```typescript
interface ToolSetDefinition {
  name: string;           // 工具集显示名称
  description: string;    // 功能描述
  decisionCriteria: string; // 决策帮助文本
  modules: string[];      // 关联的模块列表
}
```

## 项目目录结构

| 目录 | 内容 | 说明 |
|------|------|------|
| `src/api` | HTTP 客户端 | 封装 FMP API 调用 |
| `src/tools` | MCP 工具注册 | 工具定义和实现 |
| `src/toolception-adapters` | 框架适配器 | toolception 集成 |
| `src/server-mode-enforcer` | 模式强制执行 | 服务器配置控制 |
| `src/constants` | 常量定义 | 工具集和默认值 |
| `src/endpoints` | HTTP 端点 | JSON-RPC 接口 |
| `src/prompts` | MCP 提示词 | 提示词模板 |
| `src/types` | 类型定义 | TypeScript 类型 |
| `__tests__` | 测试文件 | Vitest 单元测试 |
| `docs` | 文档目录 | 配置和使用指南 |

资料来源：[CONTRIBUTING.md:项目结构](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CONTRIBUTING.md)

## 配置方式

### 环境变量配置

| 变量名 | 类型 | 描述 | 必需 |
|--------|------|------|------|
| `FMP_ACCESS_TOKEN` | string | FMP API 访问令牌 | 是 |
| `DYNAMIC_TOOL_DISCOVERY` | boolean | 启用动态工具发现 | 否 |
| `FMP_TOOL_SETS` | string | 逗号分隔的工具集列表 | 否 |
| `PORT` | number | HTTP 服务端口 | 否 |

### 命令行参数

| 参数 | 描述 |
|------|------|
| `--fmp-token` | 设置 FMP API 令牌 |
| `--port` | 设置 HTTP 服务端口 |
| `--dynamic-tool-discovery` | 启用动态工具发现模式 |
| `--fmp-tool-sets` | 指定加载的工具集 |

资料来源：[server.json:Arguments](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/server.json)

## 已知问题与限制

### 社区反馈的问题

根据社区 issue 反馈，以下问题需要关注：

| Issue | 问题描述 | 影响范围 |
|-------|----------|----------|
| #100 | batch-quote 端点对 Ultimate 计划用户错误拦截 | 计划验证逻辑 |
| #93 | 工具参数名使用 Python 保留字导致客户端兼容性问题 | Python MCP 客户端 |
| #81 | FMP API KEY 配置困难 | 新用户入门 |

资料来源：[GitHub Issues](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues)

### 版本兼容性要求

- **Node.js**: >= 25.3.0
- **npm**: >= 11.11.0

低于上述版本的运行环境可能导致兼容性问题。

## 安装与部署

### NPM 全局安装

```bash
npm install -g financial-modeling-prep-mcp-server
```

### MCP 注册表安装

该项目已注册至多个 MCP 注册表：

- [Smithery.ai](https://smithery.ai/server/@imbenrabi/financial-modeling-prep-mcp-server)
- [Glama.ai](https://glama.ai/mcp/servers/@imbenrabi/financial-modeling-prep-mcp-server)
- [MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.imbenrabi/financial-modeling-prep-mcp-server)

### Docker 部署

从源码构建 Docker 镜像：

```bash
docker build -t fmp-mcp-server .
docker run -e FMP_ACCESS_TOKEN=<your-token> fmp-mcp-server
```

## 版本历史

| 版本 | 发布日期 | 主要变更 |
|------|----------|----------|
| v2.6.10 | 2026-04-30 | 最新版本 |
| v2.6.9 | 2026-04-24 | 修复 Python 保留字参数名 (`from` → `from_date`) |
| v2.6.8 | 2026-02-03 | 代码库组织优化 |
| v2.6.7 | 2026-02-02 | 文档刷新，Docker 改进 |
| v2.5.0 | 2024-12-16 | 引入 GitHub Actions 自动化发布 |
| v2.4.0 | 2024-12-09 | 完整重写，引入会话管理 |

资料来源：[CHANGELOG.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CHANGELOG.md)

## 许可证

项目采用 Apache-2.0 许可证开源。资料来源：[LICENSE](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/LICENSE)

---

<a id='quick-start'></a>

## 快速开始

### 相关页面

相关主题：[项目概述](#project-overview), [安装部署](#installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/package.json)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [server.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/server.json)
</details>

# 快速开始

本文档帮助用户在 5 分钟内完成 Financial Modeling Prep MCP Server 的安装、配置和首次使用。

## 系统要求

| 要求项 | 最低版本 | 说明 |
|--------|----------|------|
| Node.js | >= 25.3.0 | 运行时环境 |
| npm | >= 11.11.0 | 包管理器 |
| 操作系统 | 跨平台 | 支持 Linux、macOS、Windows |

资料来源：[package.json:engine-requirements](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/package.json)

## 安装方式

### NPM 全局安装（推荐）

```bash
npm install -g financial-modeling-prep-mcp-server
```

安装完成后，通过以下命令验证：

```bash
npx financial-modeling-prep-mcp-server --help
```

### NPX 方式运行

无需预安装，直接使用：

```bash
npx financial-modeling-prep-mcp-server
```

### MCP 注册表安装

该服务器已在多个 MCP 注册表上线，支持一键安装：

| 注册表 | 地址 |
|--------|------|
| Smithery.ai | https://smithery.ai/server/@imbenrabi/financial-modeling-prep-mcp-server |
| Glama.ai | https://glama.ai/mcp/servers/@imbenrabi/financial-modeling-prep-mcp-server |
| MCP Registry | https://registry.modelcontextprotocol.io/servers/io.github.imbenrabi/financial-modeling-prep-mcp-server |

资料来源：[README.md:registries](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/README.md)

## 配置 API 密钥

服务器需要有效的 FMP API 密钥才能正常运作。有两种配置方式：

### 环境变量方式

```bash
export FMP_ACCESS_TOKEN="your_api_key_here"
```

### 运行时参数方式

```bash
financial-modeling-prep-mcp-server --fmp-token "your_api_key_here"
```

> **注意**：根据用户反馈（issue #81），部分用户在使用 Smithery.ai 部署时遇到 API 密钥配置问题。确保环境变量名称为 `FMP_ACCESS_TOKEN`，而非 `FMP_API_TOKEN`。

资料来源：[server.json:arguments](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/server.json)

## 工具集配置

服务器支持按需加载功能模块，通过工具集（Tool Sets）进行管理：

| 工具集 | 功能 | 决策标准 |
|--------|------|----------|
| `search` | 股票搜索与符号列表 | 搜索股票、查找交易代码 |
| `quotes` | 实时报价数据 | 获取股票报价、实时价格 |
| `statements` | 财务报表 | 分析财务表现、审查财务报表 |
| `company` | 公司信息 | 获取公司详细信息 |
| `news` | 财经新闻 | 访问市场新闻、新闻稿 |
| `analyst` | 分析师覆盖 | 获取分析师评级、价格目标 |
| `technical-indicators` | 技术指标 | 计算 RSI、移动平均线等技术指标 |
| `esg` | ESG 与可持续性 | 访问 ESG 评级、可持续性数据 |
| `sec-filings` | SEC 文件 | 访问监管文件、8-K/10-K 表格 |
| `earnings` | 财报与电话会议 | 获取财报电话会议记录 |

资料来源：[src/constants/toolSets.ts:modules](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)

### 配置工具集参数

```bash
financial-modeling-prep-mcp-server --fmp-tool-sets "quotes,news,statements"
```

或通过环境变量：

```bash
export FMP_TOOL_SETS="quotes,news,statements"
```

## 服务器模式

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `DYNAMIC_TOOL_DISCOVERY` | 动态工具发现 | 按需加载工具 |
| `STATIC_TOOL_SETS` | 静态工具集 | 使用预定义工具集 |
| `ALL_TOOLS` | 全部工具 | 需要全部功能时 |

资料来源：[src/types/index.ts:ServerMode](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)

## 快速验证

创建测试文件 `test-tools.js`：

```javascript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { quotesTools } from "./dist/tools/quotes.js";
import { newsTools } from "./dist/tools/news.js";

const server = new McpServer({
  name: "fmp-test",
  version: "1.0.0"
});

quotesTools(server);
newsTools(server);

const transport = new StdioServerTransport();
server.connect(transport);
```

运行测试：

```bash
node test-tools.js
```

## 开发环境设置

如需参与开发，完整设置流程如下：

```bash
git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server
cd Financial-Modeling-Prep-MCP-Server
npm install
npm run build
```

开发期间使用监视模式：

```bash
npm run dev
```

资料来源：[CONTRIBUTING.md:setup](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CONTRIBUTING.md)

## 提交前检查清单

| 检查项 | 命令 |
|--------|------|
| 编译 | `npm run build` |
| 测试 | `npm run test:run` |
| 类型检查 | `npm run typecheck` |

## 常见问题

### Python 客户端兼容性问题

在 v2.6.9 中，参数名称已从 `from` 改为 `from_date`，以避免 Python 保留关键字冲突。如果使用 Python MCP 客户端框架，请确保更新到最新版本。

### batch-quote 端点权限问题

部分 Ultimate 计划用户报告了 batch-quote 端点的误报权限错误。这是由 MCP 层而非 FMP API 本身触发的假阳性。

### 版本验证

确保版本一致性：

```bash
npm run version:validate
```

资料来源：[CHANGELOG.md:v2.6.9](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CHANGELOG.md)

## 下一步

- 阅读完整文档：[docs/USAGE.md](docs/USAGE.md)
- 查看 API 参考：[docs/API_REFERENCE.md](docs/API_REFERENCE.md)
- 配置说明：[docs/CONFIGURATION.md](docs/CONFIGURATION.md)

---

<a id='system-architecture'></a>

## 系统架构

### 相关页面

相关主题：[API 客户端层](#api-clients), [服务器模式](#server-modes)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/toolception-adapters/ModeConfigMapper.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/ModeConfigMapper.ts)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [src/tools/news.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/news.ts)
- [src/api/insider-trades/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/insider-trades/types.ts)
- [server.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/server.json)
- [CONTRIBUTING.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CONTRIBUTING.md)
</details>

# 系统架构

Financial-Modeling-Prep-MCP-Server 是一个基于 Model Context Protocol (MCP) 的金融数据访问服务器，为 AI 助手和自动化工作流提供 Financial Modeling Prep API 的标准接口。本页面详细介绍该服务器的整体架构设计、核心组件及其交互关系。

## 架构概述

该服务器采用分层架构设计，核心目标是将复杂的金融数据 API 封装为 MCP 协议兼容的工具集，使 AI 代理能够通过标准化的工具调用访问财务数据。

```mermaid
graph TB
    subgraph "客户端层"
        A["AI 助手 / MCP 客户端"]
    end
    
    subgraph "MCP 协议层"
        B["MCP SDK 服务器"]
        C["JSON-RPC 处理器"]
    end
    
    subgraph "业务逻辑层"
        D["工具注册层"]
        E["API 客户端层"]
        F["服务器模式执行器"]
    end
    
    subgraph "外部服务层"
        G["FMP API"]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    E --> G
    
    F --> D
    F --> E
    
    style G fill:#ffcccc
```

## 核心目录结构

项目源代码位于 `src/` 目录下，按职责划分为多个子模块：

| 目录 | 功能描述 | 主要职责 |
|------|----------|----------|
| `src/api` | HTTP 客户端 | 与 FMP API 的通信，参数验证，响应处理 |
| `src/tools` | MCP 工具注册 | 定义 JSON-RPC 工具，参数 schema，错误处理 |
| `src/toolception-adapters` | 框架集成适配器 | 连接 MCP SDK 与业务逻辑 |
| `src/server-mode-enforcer` | 模式配置执行器 | 管理服务器运行模式，工具集加载策略 |
| `src/constants` | 常量定义 | 工具集配置，默认设置 |
| `src/endpoints` | HTTP 端点 | HTTP 服务器模式下的路由处理 |
| `src/prompts` | MCP 提示词 | 工具使用的描述性提示 |

资料来源：[CONTRIBUTING.md]()

## 服务器模式体系

服务器支持三种运行模式，通过 `ServerMode` 类型定义：

```typescript
type ServerMode = 'DYNAMIC_TOOL_DISCOVERY' | 'STATIC_TOOL_SETS' | 'ALL_TOOLS';
```

资料来源：[src/types/index.ts:31]()

### 模式详细说明

| 模式 | 描述 | 使用场景 |
|------|------|----------|
| `DYNAMIC_TOOL_DISCOVERY` | 动态工具发现，根据会话配置按需加载工具集 | 多租户环境，需要细粒度权限控制 |
| `STATIC_TOOL_SETS` | 静态工具集，加载预定义的工具集组合 | 固定功能集，简化部署 |
| `ALL_TOOLS` | 加载全部可用工具 | 管理员模式，完全访问 |

### 工具集（Tool Sets）

系统将相关工具组织为工具集，支持按需加载：

```typescript
type ToolSet =
  | "search"           // 股票搜索
  | "company"          // 公司信息
  | "quotes"           // 报价数据
  | "statements"       // 财务报表
  | "calendar"         // 财务日历
  | "charts"           // 价格图表
  | "news"             // 金融新闻
  | "analyst"          // 分析师覆盖
  | "market-performance"  // 市场表现
  | "insider-trades"   // 内部人交易
  | "institutional"    // 机构持仓
  | "indexes"          // 指数数据
  | "economics"        // 经济数据
  | "crypto"           // 加密货币
  | "forex"            // 外汇
  | "commodities"      // 大宗商品
  | "etf-funds"        // ETF基金
  | "esg"              // ESG评级
  | "technical-indicators"  // 技术指标
  | "senate"           // 政府交易
  | "sec-filings"      // SEC文件
  | "earnings"         // 财报与电话会议
  | "dcf"              // DCF估值
  | "bulk";            // 批量数据工具
```

资料来源：[src/types/index.ts:18-29]()

每个工具集包含以下元数据：

```typescript
interface ToolSetDefinition {
  name: string;           // 可读名称
  description: string;    // 功能描述
  decisionCriteria: string;  // 用户选择此工具集的条件
  modules: string[];      // 关联的内部模块列表
}
```

资料来源：[src/types/index.ts:34-39]()

## API 客户端架构

### FMPClient 核心客户端

`FMPClient` 是与 Financial Modeling Prep API 通信的核心客户端，负责处理 HTTP 请求、认证和响应解析：

```mermaid
graph LR
    A["工具调用"] --> B["Zod Schema 验证"]
    B --> C["API 客户端方法"]
    C --> D["HTTP 请求构建"]
    D --> E["FMP API 响应"]
    E --> F["类型安全的数据返回"]
```

### 领域特定客户端

API 客户端按功能域划分为多个子模块，目录结构为 `src/api/{domain}/`：

- `insider-trades/` - 内部人交易数据
- 新闻、股票报价、财务报表等...

每个领域客户端返回强类型的响应对象，确保数据处理的类型安全：

```typescript
// 示例：内部人交易响应类型
interface InsiderTradeResponse {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDisposablePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}
```

资料来源：[src/api/insider-trades/types.ts:1-18]()

## 工具注册系统

### 工具定义模式

每个 MCP 工具通过 `@modelcontextprotocol/sdk` 注册，遵循标准化模式：

```typescript
server.tool(
  "toolName",                    // 工具标识符
  "工具描述...",                  // 功能说明
  {
    // Zod Schema 定义的参数
    param1: z.string().describe("参数描述"),
    param2: z.number().optional().describe("可选参数")
  },
  async ({ param1, param2 }) => {
    // 工具实现逻辑
    const result = await apiClient.method({ param1, param2 });
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
    };
  }
);
```

资料来源：[src/tools/news.ts:1-30]()

### 参数命名规范

**已知问题**：某些工具曾使用 Python 保留字作为参数名（如 `from`），这会导致 Python MCP 客户端解析失败。在 v2.6.9 版本中已修复，将 `from` 重命名为 `from_date`：

> v2.6.9 更新说明：
> - 重命名 `from` 参数为 `from_date` 以避免 Python 保留字冲突
> - 更新 `@modelcontextprotocol/sdk` 依赖至 `^1.27.1`

资料来源：[CHANGELOG.md]()

## 配置系统

### 上下文类型

服务器通过 `FMPContext` 传递运行时配置：

```typescript
export type FMPContext = {
  config?: {
    FMP_ACCESS_TOKEN?: string;
  };
};
```

资料来源：[src/types/index.ts:5-9]()

### 会话配置

会话级别的配置支持动态调整：

```typescript
interface SessionConfig {
  FMP_ACCESS_TOKEN?: string;      // API 访问令牌
  FMP_TOOL_SETS?: string;         // 工具集列表
  DYNAMIC_TOOL_DISCOVERY?: string; // 动态发现开关
}
```

资料来源：[src/types/index.ts:44-49]()

### 配置来源优先级

```mermaid
graph TD
    A["命令行参数"] --> B["环境变量"]
    B --> C["会话配置"]
    C --> D["服务器默认值"]
    
    style A fill:#90EE90
    style D fill:#FFB6C1
```

### 命令行参数定义

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `--fmp-token` | string | 否 | FMP API 访问令牌 |
| `--port` | number | 否 | HTTP 服务器模式端口 |
| `--dynamic-tool-discovery` | boolean | 否 | 启用动态工具发现模式 |
| `--fmp-tool-sets` | string | 否 | 逗号分隔的工具集列表 |

资料来源：[server.json]()

### 环境变量

| 变量名 | 类型 | 秘密 | 说明 |
|--------|------|------|------|
| `FMP_ACCESS_TOKEN` | string | 是 | FMP API 访问令牌 |
| `PORT` | number | 否 | HTTP 服务器模式端口 |
| `DYNAMIC_TOOL_DISCOVERY` | boolean | 否 | 启用动态工具发现模式 |
| `FMP_TOOL_SETS` | string | 否 | 逗号分隔的工具集列表 |

资料来源：[server.json]()

## 模式配置映射器

`ModeConfigMapper` 是连接服务器模式与工具集的核心组件：

```mermaid
graph TB
    A["ModeConfigMapper"] --> B["resolveServerMode"]
    A --> C["resolveToolSets"]
    A --> D["buildToolCatalog"]
    
    B --> E["DYNAMIC_TOOL_DISCOVERY<br/>STATIC_TOOL_SETS<br/>ALL_TOOLS"]
    C --> F["工具集列表"]
    D --> G["工具目录"]
```

主要职责包括：

1. **解析服务器模式** - 根据执行器配置确定运行模式
2. **解析工具集** - 从执行器获取要加载的工具集列表
3. **构建工具目录** - 生成工具集的完整元数据目录

资料来源：[src/toolception-adapters/ModeConfigMapper.ts]()

## MCP 协议集成

### SDK 版本

项目依赖 `@modelcontextprotocol/sdk` 进行 MCP 协议实现，当前版本要求：

```json
{
  "@modelcontextprotocol/sdk": "^1.27.1"
}
```

### 传输层

服务器支持标准 MCP 传输机制，通过 `stdio` 进行本地通信，或通过 HTTP 服务器模式提供网络访问。

## 扩展指南

### 添加新工具

1. 在 `src/api/{domain}/` 中添加 API 客户端方法
2. 在 `src/tools/{module}.ts` 中注册 MCP 工具
3. 使用 Zod schema 定义参数

### 添加新工具集

1. 在 `TOOL_SETS` 中添加定义（`src/constants/toolSets.ts`）
2. 在 `ToolSet` 联合类型中添加新类型（`src/types/index.ts`）

### 添加新模块

1. 创建 `src/api/{domain}/{Domain}Client.ts`
2. 创建 `src/tools/{module}.ts` 注册函数
3. 在 `src/toolception-adapters/moduleAdapters.ts` 中添加适配器
4. 在 `src/constants/toolSets.ts` 中映射到工具集

## 已知问题与限制

### 计划门控误报

Issue #100 报告：batch-quote 端点对 Ultimate 计划用户错误返回 ACCESS DENIED。该问题发生在 MCP 层而非 API 层，属于计划检查的误报。

### Python 客户端兼容性

Issue #93 报告：工具参数名曾使用 Python 保留字（如 `from`、`to`），已通过 v2.6.9 版本将 `from` 重命名为 `from_date` 修复。

### API 密钥配置

Issue #81 报告：部分部署方式下 FMP_API_TOKEN 配置困难。建议通过环境变量 `FMP_ACCESS_TOKEN` 或命令行参数 `--fmp-token` 设置。

## 运行时要求

| 组件 | 最低版本 |
|------|----------|
| Node.js | >= 25.3.0 |
| npm | >= 11.11.0 |

资料来源：[CONTRIBUTING.md](), [package.json]()

## 技术栈

| 技术 | 用途 |
|------|------|
| TypeScript | 主语言，强类型支持 |
| Zod | 参数验证与 schema 定义 |
| `@modelcontextprotocol/sdk` | MCP 协议实现 |
| Vitest | 单元测试框架 |
| tsx | 开发模式热重载 |

---

<a id='api-clients'></a>

## API 客户端层

### 相关页面

相关主题：[系统架构](#system-architecture), [工具目录](#tools-catalog)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/api/FMPClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/FMPClient.ts)
- [src/api/quotes/QuotesClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/quotes/QuotesClient.ts)
- [src/api/company/CompanyClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/company/CompanyClient.ts)
- [src/api/statements/StatementsClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/statements/StatementsClient.ts)
- [src/api/news/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/news/types.ts)
- [src/api/insider-trades/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/insider-trades/types.ts)
</details>

# API 客户端层

## 概述

API 客户端层是 Financial Modeling Prep MCP Server 与外部 FMP API 之间的通信桥梁。该层封装了所有 HTTP 请求逻辑，负责认证、请求构建、响应解析以及错误处理，使上层工具注册代码无需直接处理底层网络细节。资料来源：[src/api/FMPClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/FMPClient.ts)()

## 架构设计

### 客户端组织结构

客户端按照功能域进行模块化划分，每个业务领域拥有独立的客户端模块：

| 客户端模块 | 功能域 | 核心职责 |
|-----------|--------|----------|
| `FMPClient` | 核心 | 主客户端，管理和分发访问令牌 |
| `QuotesClient` | 报价数据 | 股票、外汇、加密货币报价 |
| `CompanyClient` | 公司信息 | 公司概况、估值、搜索 |
| `StatementsClient` | 财务报表 | 资产负债表、利润表、现金流量表 |
| `NewsClient` | 新闻数据 | 股票新闻、财经新闻、新闻搜索 |

资料来源：[src/api/FMPClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/FMPClient.ts)()

### 分层架构图

```mermaid
graph TD
    A[MCP 工具层] --> B[API 客户端层]
    B --> C[FMPClient 核心客户端]
    C --> D[QuotesClient]
    C --> E[CompanyClient]
    C --> F[StatementsClient]
    C --> G[NewsClient]
    D --> H[FMP REST API]
    E --> H
    F --> H
    G --> H
    H --> I[FMP API 服务器]
```

## 核心组件详解

### FMPClient 主客户端

`FMPClient` 是所有 API 客户端的基类，负责管理访问令牌和提供统一的 API 调用接口：

```typescript
// 核心结构
export class FMPClient {
  constructor(accessToken: string, baseUrl?: string);
  
  // 域客户端实例
  readonly quotes: QuotesClient;
  readonly company: CompanyClient;
  readonly statements: StatementsClient;
  // ... 其他域客户端
}
```

客户端通过构造函数接收访问令牌，该令牌通过会话配置或环境变量获取。资料来源：[src/api/FMPClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/FMPClient.ts)()

### QuotesClient 报价客户端

报价客户端负责获取各类金融产品的实时和历史报价数据：

- **股票报价**：单支股票实时价格、批量报价
- **加密货币报价**：实时加密货币价格
- **外汇报价**：实时外汇汇率
- **指数报价**：市场指数数据

资料来源：[src/api/quotes/QuotesClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/quotes/QuotesClient.ts)()

### CompanyClient 公司客户端

公司客户端提供公司相关信息的数据访问：

- 公司概况和基本信息
- 公司估值指标
- 符号搜索功能
- 财务比率分析

资料来源：[src/api/company/CompanyClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/company/CompanyClient.ts)()

### StatementsClient 财务报表客户端

财务报表客户端封装了 FMP API 的财务报表相关端点：

- 资产负债表 (`balance-sheet-statement`)
- 利润表 (`income-statement`)
- 现金流量表 (`cash-flow-statement`)
- 财务报表完整列表

资料来源：[src/api/statements/StatementsClient.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/statements/StatementsClient.ts)()

## 类型定义系统

### 新闻数据类型

新闻 API 返回统一格式的数据结构：

```typescript
export interface NewsArticle {
  symbol: string | null;
  publishedDate: string;
  publisher: string;
  title: string;
  image: string;
  site: string;
  text: string;
  url: string;
}

export interface NewsParams {
  from?: string;
  to?: string;
  page?: number;
  limit?: number;
}
```

资料来源：[src/api/news/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/news/types.ts)()

### 内幕交易类型

```typescript
export interface InsiderTrade {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDispositivePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}
```

资料来源：[src/api/insider-trades/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/insider-trades/types.ts)()

### 类型组织结构

| 类型文件 | 用途 |
|---------|------|
| `src/api/news/types.ts` | 新闻相关接口定义 |
| `src/api/insider-trades/types.ts` | 内幕交易数据模型 |
| `src/types/index.ts` | 全局类型定义和工具集枚举 |

## 错误处理机制

### 客户端层错误处理

API 客户端采用统一的错误处理模式，通过 try-catch 捕获异常并返回结构化的错误响应：

```typescript
try {
  const results = await quotesClient.getQuote(symbol);
  return {
    content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
  };
} catch (error) {
  return {
    content: [
      {
        type: "text",
        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
      },
    ],
    isError: true,
  };
}
```

这种模式确保所有 API 调用错误都能以一致的格式返回，便于上层工具层统一处理。资料来源：[src/tools/news.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/news.ts)()

### 社区问题：批量报价端点误报

根据社区反馈 issue #100，批量报价端点 (batch-quote) 对 Ultimate 计划用户错误返回 ACCESS DENIED 错误。该问题发生在 MCP 层而非 API 层，表明需要检查客户端层的计划验证逻辑是否正确传递用户权限状态。资料来源：[Issue #100](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/100)()

## 请求参数规范

### 新闻 API 参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| `from_date` | string | 否 | 开始日期 (YYYY-MM-DD) |
| `to` | string | 否 | 结束日期 (YYYY-MM-DD) |
| `page` | number | 否 | 页码 (默认: 0) |
| `limit` | number | 否 | 结果数量限制 (默认: 20, 最大: 250) |

> 注意：在 v2.6.9 版本中，参数名 `from` 已重命名为 `from_date`，以避免与 Python 保留关键字冲突。资料来源：[CHANGELOG.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CHANGELOG.md)()

### 13F 表单参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| `cik` | string | 是 | CIK 号码 |
| `page` | number | 否 | 页码 (默认: 0) |

## 与工具层的集成

### 工具注册模式

API 客户端通过标准模式注册为 MCP 工具：

1. 创建客户端实例，注入访问令牌
2. 在工具定义中引用客户端方法
3. 使用 Zod 进行输入参数验证
4. 统一错误处理和响应格式化

```typescript
server.tool(
  "getStockNews",
  "获取最新股票市场新闻...",
  {
    from_date: z.string().optional().describe("开始日期 (YYYY-MM-DD)"),
    to: z.string().optional().describe("结束日期 (YYYY-MM-DD)"),
    page: z.number().optional().describe("页码"),
    limit: z.number().optional().describe("结果数量限制"),
  },
  async ({ from_date: from, to, page, limit }) => {
    const results = await newsClient.getStockNews({ from, to, page, limit });
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  }
);
```

资料来源：[src/tools/news.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/news.ts)()

## 配置与初始化

### 访问令牌配置

访问令牌可通过以下方式配置：

| 配置方式 | 优先级 | 说明 |
|---------|--------|------|
| 会话配置 `FMP_ACCESS_TOKEN` | 高 | 每个会话独立设置 |
| 环境变量 `FMP_ACCESS_TOKEN` | 低 | 全局默认值 |

> **重要**：根据 v2.6.7 版本的文档更新，客户端层仅允许通过会话配置设置 `FMP_ACCESS_TOKEN`，其他会话配置参数不受支持。资料来源：[CHANGELOG.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CHANGELOG.md)()

### 客户端实例化流程

```mermaid
sequenceDiagram
    participant Session as 会话配置
    participant Server as MCP 服务器
    participant FMPClient as FMPClient
    participant DomainClient as 域客户端
    
    Session->>Server: 提供 FMP_ACCESS_TOKEN
    Server->>FMPClient: 创建实例 (accessToken)
    FMPClient->>DomainClient: 创建域客户端实例
    DomainClient->>FMPClient: 返回引用
    FMPClient-->>Server: 返回完整客户端
```

## 扩展指南

### 添加新域客户端

1. 在 `src/api/{domain}/` 目录创建 `{Domain}Client.ts`
2. 继承 FMPClient 或使用其方法
3. 定义相关类型接口
4. 在 `FMPClient` 中注册新域客户端
5. 在工具文件中注册对应 MCP 工具

### 命名规范

- 客户端类名：`{Domain}Client` (如 `QuotesClient`)
- 文件名：`{Domain}Client.ts` (如 `QuotesClient.ts`)
- 类型文件：`src/api/{domain}/types.ts`

---

<a id='installation'></a>

## 安装部署

### 相关页面

相关主题：[快速开始](#quick-start), [配置指南](#configuration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/package.json)
- [Dockerfile](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/Dockerfile)
- [CONTRIBUTING.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/README.md)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [docs/CONFIGURATION.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/docs/CONFIGURATION.md)
</details>

# 安装部署

本文档详细介绍 Financial Modeling Prep MCP Server 的完整安装和部署流程，涵盖从环境准备到生产部署的全部步骤。

## 环境要求

### 运行时依赖

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | >= 25.3.0 | 服务器运行时环境 |
| npm | >= 11.11.0 | Node.js 包管理器 |

> **重要提示**：项目对 Node.js 版本有严格要求（>= 25.3.0），请在安装前确认当前版本。

### 版本验证

```bash
# 检查 Node.js 版本
node --version

# 检查 npm 版本
npm --version
```

如版本不符合要求，请通过 [Node.js 官网](https://nodejs.org/) 或使用 nvm 进行升级。

## 安装方式

本服务器支持多种安装方式，可根据使用场景选择合适的方法。

### NPM 全局安装

适用于需要全局访问服务器的场景：

```bash
npm install -g financial-modeling-prep-mcp-server
```

安装完成后可通过以下命令验证：

```bash
npx financial-modeling-prep-mcp-server --version
```

### NPX 临时运行

适用于一次性使用或测试场景：

```bash
npx financial-modeling-prep-mcp-server
```

### Docker 容器化部署

对于生产环境，推荐使用 Docker 进行隔离部署。

#### 构建镜像

```bash
docker build -t financial-modeling-prep-mcp-server .
```

#### 运行容器

```bash
docker run -d \
  -e FMP_API_KEY=your_api_key_here \
  -p 3000:3000 \
  --name fmp-mcp-server \
  financial-modeling-prep-mcp-server
```

#### Dockerfile 配置说明

```dockerfile
# 基础镜像
FROM node:25.3.0-slim

# 设置工作目录
WORKDIR /app

# 复制项目文件
COPY package*.json ./
COPY dist ./dist

# 安装依赖
RUN npm ci --only=production

# 暴露端口
EXPOSE 3000

# 启动命令
CMD ["node", "dist/index.js"]
```

### MCP 注册表安装

服务器已注册至多个 MCP 发现平台，支持一键安装：

| 注册平台 | 地址 |
|----------|------|
| MCP Registry | https://registry.modelcontextprotocol.io/servers/io.github.imbenrabi/financial-modeling-prep-mcp-server |
| Smithery.ai | https://smithery.ai/server/@imbenrabi/financial-modeling-prep-mcp-server |
| Glama.ai | https://glama.ai/mcp/servers/@imbenrabi/financial-modeling-prep-mcp-server |

## API 密钥配置

### 获取 FMP API 密钥

1. 访问 [Financial Modeling Prep 官网](https://site.financialmodelingprep.com/)
2. 注册账户并选择合适的订阅计划
3. 在个人设置中获取 API 密钥

### 环境变量配置

| 环境变量 | 必需 | 说明 |
|----------|------|------|
| `FMP_API_KEY` | 是 | Financial Modeling Prep API 密钥 |
| `FMP_ACCESS_TOKEN` | 是 | 会话级访问令牌 |
| `FMP_TOOL_SETS` | 否 | 指定启用的工具集 |
| `DYNAMIC_TOOL_DISCOVERY` | 否 | 动态工具发现开关 |

### 配置方式

#### 方式一：环境变量（推荐用于 Docker）

```bash
export FMP_API_KEY=your_api_key_here
export FMP_ACCESS_TOKEN=your_access_token_here
```

#### 方式二：会话配置（适用于 MCP 客户端）

某些 MCP 客户端支持在会话级别设置令牌：

```json
{
  "mcpServers": {
    "fmp": {
      "command": "npx",
      "args": ["-y", "financial-modeling-prep-mcp-server"],
      "env": {
        "FMP_ACCESS_TOKEN": "your_token"
      }
    }
  }
}
```

> **注意**：根据社区反馈（issue #81），部分用户在 Smithery.ai 部署时遇到 API KEY 配置困难。确保使用 `FMP_ACCESS_TOKEN` 而非 `FMP_API_KEY` 进行会话级配置。资料来源：[docs/CONFIGURATION.md]()

## 服务器模式

本服务器支持三种运行模式，通过 `SERVER_MODE` 环境变量控制：

| 模式 | 值 | 说明 |
|------|-----|------|
| 动态工具发现 | `DYNAMIC_TOOL_DISCOVERY` | 根据会话需求动态加载工具 |
| 静态工具集 | `STATIC_TOOL_SETS` | 使用预定义的工具集 |
| 全工具模式 | `ALL_TOOLS` | 加载全部可用工具 |

### 工具集配置

使用静态工具集模式时，可通过 `FMP_TOOL_SETS` 指定启用的工具集：

```bash
export FMP_TOOL_SETS=quotes,company,statements
```

### 可用工具集列表

| 工具集 | 说明 |
|--------|------|
| `search` | 搜索功能 |
| `company` | 公司信息 |
| `quotes` | 报价与价格数据 |
| `statements` | 财务报表 |
| `calendar` | 财务日历 |
| `charts` | 图表数据 |
| `news` | 新闻资讯 |
| `analyst` | 分析师评级 |
| `market-performance` | 市场表现 |
| `insider-trades` | 内部人交易 |
| `institutional` | 机构持仓 |
| `indexes` | 指数数据 |
| `economics` | 经济数据 |
| `crypto` | 加密货币 |
| `forex` | 外汇数据 |
| `commodities` | 大宗商品 |
| `etf-funds` | ETF 与基金 |
| `esg` | ESG 评级 |
| `technical-indicators` | 技术指标 |
| `senate` | 政府交易 |
| `sec-filings` | SEC 文件 |
| `earnings` | 盈利数据 |
| `dcf` | DCF 估值模型 |
| `bulk` | 批量数据工具 |

## 开发环境搭建

如需进行二次开发或贡献代码，请按以下步骤配置：

### 克隆项目

```bash
git clone https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server
cd Financial-Modeling-Prep-MCP-Server
```

### 安装依赖

```bash
npm install
```

### 构建项目

```bash
npm run build
```

### 开发模式

使用热重载进行开发：

```bash
npm run dev
```

### 运行测试

```bash
# 运行所有测试
npm run test:run

# 监视模式运行测试
npm run test

# TypeScript 类型检查
npm run typecheck
```

### 提交前检查清单

在提交代码前，请确保完成以下验证：

```bash
npm run build
npm run test:run
npm run typecheck
```

## 部署架构

```mermaid
graph TD
    A[客户端应用] --> B[MCP 客户端]
    B --> C[Financial Modeling Prep MCP Server]
    C --> D{FMP API}
    D --> E[免费用户]
    D --> F[专业用户]
    D --> G[企业用户]
    D --> H[旗舰用户]
    
    I[环境配置] --> C
    I --> FMP_ACCESS_TOKEN
    I --> FMP_TOOL_SETS
    I --> SERVER_MODE
```

## 常见问题

### API 密钥设置失败

**问题**：按照文档设置 `FMP_API_TOKEN` 后仍提示缺少密钥。

**解决方案**：
1. 确认使用的是 `FMP_ACCESS_TOKEN` 而非 `FMP_API_KEY`
2. 检查环境变量是否正确导出
3. 重启 MCP 客户端使配置生效

### 版本兼容性问题

**问题**：启动时报错 `Unsupported engine`。

**解决方案**：确保 Node.js 版本 >= 25.3.0，npm 版本 >= 11.11.0。

### Docker 容器端口冲突

**问题**：`Port 3000 is already in use`

**解决方案**：修改映射端口：

```bash
docker run -d -p 3001:3000 --name fmp-mcp-server financial-modeling-prep-mcp-server
```

## 验证安装

安装完成后，可通过以下方式验证服务器状态：

```bash
# 检查服务是否运行
curl http://localhost:3000/health

# 或使用 MCP 客户端测试连接
mcp-cli test --server financial-modeling-prep
```

## 版本信息

| 版本 | 发布日期 | 主要更新 |
|------|----------|----------|
| 2.6.10 | 2026-04-30 | 最新稳定版本 |
| 2.6.9 | 2026-04-24 | 修复 Python 关键字冲突 |
| 2.6.8 | 2026-02-03 | 代码库结构优化 |

完整版本历史请参阅 [CHANGELOG.md](CHANGELOG.md)。

---

<a id='configuration'></a>

## 配置指南

### 相关页面

相关主题：[服务器模式](#server-modes), [安装部署](#installation)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/CONFIGURATION.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/docs/CONFIGURATION.md)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [src/toolception-adapters/ModeConfigMapper.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/ModeConfigMapper.ts)
- [src/server-mode-enforcer/ServerModeEnforcer.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/server-mode-enforcer/ServerModeEnforcer.ts)
- [package.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/package.json)
- [CONTRIBUTING.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CONTRIBUTING.md)
</details>

# 配置指南

本页面详细说明 Financial Modeling Prep MCP Server 的配置系统，包括环境变量配置、会话配置、工具集管理以及服务器模式等核心概念。

## 概述

Financial Modeling Prep MCP Server 采用模块化架构设计，通过配置系统实现灵活的工具加载和访问控制。配置体系主要包含以下几个层面：

- **环境变量配置**：用于设置 API 凭证和全局服务器参数
- **会话配置**：支持按会话设置访问令牌和工具集范围
- **服务器模式**：控制工具发现和加载的行为模式
- **工具集（Tool Sets）**：将相关工具分组便于管理和授权

## 环境变量配置

### 必需配置

| 变量名 | 描述 | 必填 | 示例 |
|--------|------|------|------|
| `FMP_API_KEY` | Financial Modeling Prep API 密钥 | 是 | `your_api_key_here` |

### 可选配置

| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `FMP_ACCESS_TOKEN` | 访问令牌，用于会话级别认证 | - |
| `SERVER_MODE` | 服务器运行模式 | `STATIC_TOOL_SETS` |
| `LOG_LEVEL` | 日志级别 | `info` |

> **注意**：根据社区反馈（issue #81），部分用户在设置 `FMP_API_KEY` 时遇到困难。建议通过环境变量直接设置，而非依赖外部配置界面。

## 会话配置

会话配置允许在运行时动态调整访问权限和控制参数。配置类型定义如下：

```typescript
interface SessionConfig {
  FMP_ACCESS_TOKEN?: string;
  FMP_TOOL_SETS?: string;
  DYNAMIC_TOOL_DISCOVERY?: string;
}
```

### 会话配置限制

会话配置中**仅允许**设置以下参数：

| 参数 | 说明 |
|------|------|
| `FMP_ACCESS_TOKEN` | 会话级别的访问令牌，覆盖环境变量设置 |

> ⚠️ **重要**：会话配置仅支持 `FMP_ACCESS_TOKEN` 字段的设置。其他参数（如工具集选择）必须在服务器启动时的环境变量或配置文件中指定。

## 服务器模式

服务器支持三种运行模式，通过 `SERVER_MODE` 环境变量控制：

### 模式类型

| 模式 | 值 | 说明 |
|------|-----|------|
| 静态工具集 | `STATIC_TOOL_SETS` | 根据预定义工具集加载工具，性能可预测 |
| 动态工具发现 | `DYNAMIC_TOOL_DISCOVERY` | 根据请求动态发现和加载工具 |
| 全量工具 | `ALL_TOOLS` | 加载所有可用工具 |

```typescript
type ServerMode = 'DYNAMIC_TOOL_DISCOVERY' | 'STATIC_TOOL_SETS' | 'ALL_TOOLS';
```

### 模式配置映射

`ModeConfigMapper` 类负责解析和映射服务器模式配置：

```typescript
private static resolveToolSets(enforcer: ModeEnforcerView): ToolSet[] {
  if (enforcer.serverModeOverride === 'STATIC_TOOL_SETS') {
    return enforcer.toolSets;
  }
  return [];
}
```

### 模式选择建议

```mermaid
graph TD
    A[选择服务器模式] --> B{使用场景}
    B -->|固定工具集<br>性能优先| C[STATIC_TOOL_SETS]
    B -->|按需加载<br>灵活性优先| D[DYNAMIC_TOOL_DISCOVERY]
    B -->|开发测试<br>全量访问| E[ALL_TOOLS]
    C --> F[需配合 FMP_TOOL_SETS 配置]
    D --> G[动态发现开销较高]
    E --> H[生产环境不推荐]
```

## 工具集（Tool Sets）

工具集是将相关功能分组的管理单元，每个工具集包含多个模块。

### 预定义工具集

| 工具集标识 | 名称 | 描述 | 决策标准 |
|-----------|------|------|----------|
| `search` | 搜索 | 符号和公司搜索功能 | 搜索股票代码、公司信息 |
| `company` | 公司信息 | 公司详细信息和概况 | 获取公司基本信息、员工、高管 |
| `quotes` | 报价数据 | 实时和历史价格数据 | 获取股票报价、实时价格 |
| `statements` | 财务报表 | 财务报表和比率分析 | 分析财务表现、评估公司健康状况 |
| `calendar` | 财务日历 | 财报日历、分红、IPO等事件 | 追踪财报日期、公司事件、分红计划 |
| `charts` | 价格图表 | 历史价格和K线数据 | 查看价格历史、分析趋势、追踪市场动向 |
| `news` | 财经新闻 | 市场新闻和公告 | 访问市场新闻、新闻稿、财经文章 |
| `analyst` | 分析师覆盖 | 评级、价格目标和推荐 | 获取分析师评级、价格目标、研究建议 |
| `market-performance` | 市场表现 | 板块表现、市场涨跌榜 | 监控板块表现、查找涨跌股、追踪市场活动 |
| `insider-trades` | 内部交易 | 内部人士交易数据 | 追踪内部人士买卖、监测异常交易 |
| `institutional` | 机构持仓 | 机构投资者持仓信息 | 分析机构持仓变化、追踪大型投资者 |
| `indexes` | 指数数据 | 市场指数和表现数据 | 访问指数数据、追踪市场指数表现 |
| `economics` | 经济数据 | 宏观经济指标和数据 | 获取经济指标、GDP、CPI、利率数据 |
| `crypto` | 加密货币 | 加密货币价格和数据 | 获取加密货币报价、市场数据 |
| `forex` | 外汇市场 | 汇率和外汇数据 | 访问汇率、外汇市场数据 |
| `commodities` | 大宗商品 | 商品期货和价格数据 | 获取商品价格、期货数据 |
| `etf-funds` | ETF和基金 | ETF和共同基金数据 | 分析ETF持仓、基金表现 |
| `esg` | ESG与可持续 | 环境、社会和治理评分 | 访问ESG评分、可持续数据、环境评分 |
| `technical-indicators` | 技术指标 | RSI、SMA、EMA等技术分析指标 | 计算技术指标、RSI、移动平均线 |
| `senate` | 政府交易 | 国会和参议院交易披露 | 追踪政府交易、国会披露 |
| `sec-filings` | SEC文件 | SEC文件和监管文档 | 访问SEC文件、监管文档、8-K/10-K表格 |
| `earnings` | 财报与电话会 | 财报和电话会议记录 | 获取财报电话会记录、会议录音、财报分析 |
| `dcf` | DCF估值 | 折现现金流模型和公司估值 | 执行DCF估值、计算内在价值 |
| `bulk` | 批量数据 | 批量数据获取工具 | 批量获取数据、大规模数据导出 |

### 工具集配置示例

```bash
# 启用多个工具集
FMP_TOOL_SETS=quotes,statements,news

# 或使用单一声明式配置
FMP_TOOL_SETS=quotes+statements+news
```

### 工具集结构

每个工具集定义包含以下属性：

```typescript
interface ToolSetDefinition {
  name: string;              // 工具集显示名称
  description: string;       // 工具集功能描述
  decisionCriteria: string;  // 用户选择此工具集的标准
  modules: string[];         // 包含的模块列表
}
```

## 配置工作流

### 完整配置流程

```mermaid
graph TD
    A[开始配置] --> B{安装方式}
    B -->|NPM 全局安装| C[设置环境变量]
    B -->|Docker 部署| D[配置环境变量或文件]
    B -->|MCP 注册表| E[使用默认配置]
    C --> F[设置 FMP_API_KEY]
    D --> F
    E --> F
    F --> G{是否需要会话隔离}
    G -->|是| H[配置 FMP_ACCESS_TOKEN]
    G -->|否| I[选择服务器模式]
    H --> I
    I --> J{工具集需求}
    J -->|固定工具集| K[设置 STATIC_TOOL_SETS]
    J -->|按需加载| L[设置 DYNAMIC_TOOL_DISCOVERY]
    J -->|全部工具| M[设置 ALL_TOOLS]
    K --> N{配置 FMP_TOOL_SETS}
    N --> O[启动服务器]
    L --> O
    M --> O
```

## 工具参数配置

### 参数命名规范

> ⚠️ **已知问题**：部分工具参数名使用了 Python 保留字（如 `from`），可能导致 Python MCP 客户端兼容性问题（issue #93）。

在 v2.6.9 版本中，已将 `from` 参数重命名为 `from_date` 以避免冲突：

```typescript
// 工具参数定义示例
{
  from_date: z.string().optional().describe("Start date (YYYY-MM-DD)"),
  to: z.string().optional().describe("End date (YYYY-MM-DD)"),
  page: z.number().optional().describe("Page number"),
  limit: z.number().optional().describe("Result limit"),
}
```

### 常见参数类型

| 参数类型 | 格式 | 示例 |
|---------|------|------|
| 日期参数 | YYYY-MM-DD | `2024-01-15` |
| 分页参数 | 数字 | `0`, `1`, `2` |
| 限制参数 | 数字 | `20`, `50`, `100` |
| 符号参数 | 字符串 | `AAPL`, `MSFT` |

## 运行时配置验证

### 验证命令

```bash
# 版本一致性验证
npm run version:validate

# 类型检查
npm run typecheck
```

### 常见配置错误

| 错误类型 | 原因 | 解决方案 |
|---------|------|----------|
| `ACCESS DENIED` | API Key 无效或未设置 | 检查 `FMP_API_KEY` 环境变量 |
| 工具不可用 | 工具集未启用 | 检查 `FMP_TOOL_SETS` 配置 |
| 版本不匹配 | 配置文件版本不一致 | 运行 `npm run version:sync` |

## 安装与部署配置

### NPM 安装

```bash
npm install -g financial-modeling-prep-mcp-server
```

### Docker 部署

```bash
# 构建镜像
docker build -t fmp-mcp-server .

# 运行容器
docker run -e FMP_API_KEY=your_api_key fmp-mcp-server
```

> **Docker 说明**：从 v2.6.7 开始，Docker 安装说明已更新为从源代码构建 MCP 服务器镜像，而非使用预构建镜像。

### 运行时要求

| 组件 | 最低版本 |
|------|---------|
| Node.js | >= 25.3.0 |
| npm | >= 11.11.0 |

## 配置最佳实践

### 开发环境

```bash
# .env.development
FMP_API_KEY=your_dev_api_key
SERVER_MODE=ALL_TOOLS
LOG_LEVEL=debug
```

### 生产环境

```bash
# 生产环境配置
FMP_API_KEY=your_prod_api_key
SERVER_MODE=STATIC_TOOL_SETS
FMP_TOOL_SETS=quotes,statements,news,analyst
LOG_LEVEL=warn
```

### 安全建议

1. **凭证管理**：不要将 API Key 提交到版本控制系统
2. **会话隔离**：多用户场景下使用会话级别的 `FMP_ACCESS_TOKEN`
3. **最小权限**：仅启用所需的工具集，减少攻击面
4. **日志管理**：生产环境使用 `warn` 或 `error` 日志级别

## 故障排除

### 常见问题

**Q: API Key 无法设置？**
A: 确保通过环境变量 `FMP_API_KEY` 设置，而非通过配置文件。参考 issue #81 的解决方案。

**Q: 工具返回 ACCESS DENIED？**
A: 确认 API Key 有效且账户订阅级别支持该功能。部分高级功能需要 Ultimate 计划订阅。

**Q: Python 客户端参数错误？**
A: 确保使用 v2.6.9 或更高版本，该版本已修复保留字冲突问题。

## 相关文档

- [使用指南](docs/USAGE.md) - 客户端配置和请求示例
- [API 参考](docs/API_REFERENCE.md) - 完整工具目录
- [注册表配置](docs/REGISTRIES.md) - MCP 注册表集成说明

---

<a id='server-modes'></a>

## 服务器模式

### 相关页面

相关主题：[配置指南](#configuration), [系统架构](#system-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/toolception-adapters/ModeConfigMapper.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/ModeConfigMapper.ts)
- [src/toolception-adapters/moduleAdapters.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/moduleAdapters.ts)
- [src/toolception-adapters/coreModuleAdapters.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/coreModuleAdapters.ts)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [server.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/server.json)
</details>

# 服务器模式

服务器模式（Server Mode）是 Financial Modeling Prep MCP Server 的核心架构特性之一，用于控制工具的加载策略和运行时行为。该系统支持三种互斥的服务器运行模式，允许部署者根据实际需求灵活配置 MCP 服务器的工具暴露范围和发现机制。

## 模式概述

MCP 服务器支持三种服务器模式，每种模式对应不同的工具加载策略：

| 模式标识 | 模式名称 | 说明 |
|---------|---------|------|
| `DYNAMIC_TOOL_DISCOVERY` | 动态工具发现 | 运行时根据请求动态加载工具 |
| `STATIC_TOOL_SETS` | 静态工具集 | 预定义工具集，客户端可选择性加载 |
| `ALL_TOOLS` | 全量工具 | 启动时加载所有可用工具 |

资料来源：[src/types/index.ts:27-29]()

## 架构设计

服务器模式的实现采用了模块化适配器架构，核心组件包括模式配置映射器（ModeConfigMapper）、模块适配器（moduleAdapters）和核心适配器（coreModuleAdapters）。这种设计将工具发现逻辑与业务逻辑分离，便于扩展和维护。

```mermaid
graph TB
    subgraph "服务器模式层"
        A[Server Mode Enforcer] --> B[ModeConfigMapper]
        B --> C[Tool Catalog]
    end
    
    subgraph "工具加载层"
        C --> D[moduleAdapters]
        D --> E[coreModuleAdapters]
    end
    
    subgraph "工具注册层"
        E --> F[src/tools/*.ts]
        F --> G[MCP Server Tools]
    end
    
    subgraph "配置来源"
        H[--fmp-tool-sets] --> B
        I[--dynamic-tool-discovery] --> A
        J[环境变量 FMP_TOOL_SETS] --> B
    end
```

### ModeConfigMapper 职责

ModeConfigMapper 是服务器模式实现的核心类，负责将配置映射为标准化的工具目录结构：

```typescript
[key: ToolSet]: {
    name: string;
    description: string;
    decisionCriteria: string;
    modules: string[];
}
```

该映射器从两个来源解析工具集配置：当服务器模式为 `STATIC_TOOL_SETS` 时，从 Enforcer 级别配置读取工具集列表；其他模式下返回空数组，由动态发现机制处理。

资料来源：[src/toolception-adapters/ModeConfigMapper.ts:70-77]()

## 模式配置方式

### 命令行参数配置

服务器支持通过命令行参数配置运行模式：

| 参数 | 类型 | 说明 |
|-----|------|------|
| `--fmp-token` | string | FMP API 访问令牌 |
| `--port` | number | HTTP 服务器模式端口 |
| `--dynamic-tool-discovery` | boolean | 启用动态工具发现模式 |
| `--fmp-tool-sets` | string | 逗号分隔的工具集列表 |

资料来源：[server.json:23-50]()

### 环境变量配置

除命令行参数外，也可通过环境变量配置：

| 环境变量 | 说明 |
|---------|------|
| `FMP_ACCESS_TOKEN` | FMP API 访问令牌（敏感信息） |
| `PORT` | HTTP 服务器模式端口 |
| `DYNAMIC_TOOL_DISCOVERY` | 启用动态工具发现模式 |
| `FMP_TOOL_SETS` | 逗号分隔的工具集列表 |

资料来源：[server.json:51-78]()

### 会话级配置

客户端可在会话初始化时通过 session headers 设置个性化配置：

```typescript
interface SessionConfig {
  FMP_ACCESS_TOKEN?: string;
  FMP_TOOL_SETS?: string;
  DYNAMIC_TOOL_DISCOVERY?: string;
}
```

**重要限制**：根据 v2.6.7 版本的更新说明，会话配置目前仅支持 `FMP_ACCESS_TOKEN` 的动态设置，其他配置项必须在服务器级别预先配置。

资料来源：[src/types/index.ts:37-42]()

## 工具集体系

系统定义了 24 种预配置工具集，每种工具集对应特定的金融数据域：

```mermaid
graph LR
    A[Tool Sets] --> B[quotes 报价数据]
    A --> C[statements 财务报表]
    A --> D[company 公司信息]
    A --> E[news 新闻]
    A --> F[analyst 分析师]
    A --> G[esg ESG评级]
    A --> H[technical-indicators 技术指标]
    A --> I[更多...]
```

完整工具集列表包括：`search`、`company`、`quotes`、`statements`、`calendar`、`charts`、`news`、`analyst`、`market-performance`、`insider-trades`、`institutional`、`indexes`、`economics`、`crypto`、`forex`、`commodities`、`etf-funds`、`esg`、`technical-indicators`、`senate`、`sec-filings`、`earnings`、`dcf`、`bulk`。

资料来源：[src/types/index.ts:12-26]()

每种工具集包含四个属性：

- **name**：可读名称
- **description**：功能描述
- **decisionCriteria**：用户选择该工具集的决策依据
- **modules**：对应的底层模块数组

资料来源：[src/constants/toolSets.ts]()
资料来源：[src/types/index.ts:29-35]()

## 模式选择指南

| 使用场景 | 推荐模式 | 配置方式 |
|---------|---------|---------|
| 开发测试 | `STATIC_TOOL_SETS` | 限定工具集范围，便于调试 |
| 生产部署 | `ALL_TOOLS` | 完整功能暴露 |
| 按需加载 | `DYNAMIC_TOOL_DISCOVERY` | 运行时动态发现 |
| 资源受限环境 | `STATIC_TOOL_SETS` | 选择必要工具集 |

## 已知限制与问题

### Issue #100: batch-quote 端点误判

当前实现中存在一个计划级别验证的误判问题：batch-quote 端点会错误地拒绝 Ultimate 计划用户的请求。该错误发生在 MCP 层而非 FMP API 层，属于计划门控的误报。

### Issue #93: 参数命名兼容性问题

工具输入模式使用了 Python 保留关键字（如 `from`）作为参数名，可能破坏 Python MCP 客户端的兼容性。v2.6.9 版本已部分修复，将 `from` 参数重命名为 `from_date`。

### Issue #81: API Key 配置困难

用户反映在某些部署平台（如 Smithery）上设置 FMP API KEY 存在困难，配置后仍提示缺失令牌。

## 总结

服务器模式为 FMP MCP Server 提供了灵活的工具暴露策略。`DYNAMIC_TOOL_DISCOVERY` 模式适合需要运行时灵活性的场景，`STATIC_TOOL_SETS` 模式允许精细控制可用工具范围，而 `ALL_TOOLS` 模式则提供开箱即用的完整功能。选择合适的模式可优化资源使用并提升用户体验。

---

<a id='tools-catalog'></a>

## 工具目录

### 相关页面

相关主题：[工具使用指南](#tools-usage), [API 客户端层](#api-clients)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [src/toolception-adapters/ModeConfigMapper.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/ModeConfigMapper.ts)
- [src/tools/quotes.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/quotes.ts)
- [src/tools/company.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/company.ts)
- [src/tools/news.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/news.ts)
- [src/tools/form-13f.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/form-13f.ts)
- [src/api/insider-trades/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/insider-trades/types.ts)
</details>

# 工具目录

## 概述

Financial Modeling Prep MCP Server 提供了一套完整的金融数据访问工具集，通过 Model Context Protocol (MCP) 规范暴露给 AI 助手和自动化客户端。工具目录采用分层架构设计，将 FMP API 的全部功能组织为 24 个逻辑工具集（Tool Sets），每个工具集包含若干相关功能的 MCP 工具。

工具目录的核心价值在于：
- **模块化分组**：将相似功能的 API 调用归类到同一工具集
- **按需加载**：支持仅加载所需的工具集，减少资源消耗
- **权限隔离**：基于 FMP 订阅计划进行工具访问控制
- **统一接口**：通过 MCP 标准协议提供一致的调用体验

## 架构设计

### 工具集类型系统

工具集通过强类型系统定义，确保配置的一致性和编译时检查：

```typescript
export type ToolSet =
  | "search"
  | "company"
  | "quotes"
  | "statements"
  | "calendar"
  | "charts"
  | "news"
  | "analyst"
  | "market-performance"
  | "insider-trades"
  | "institutional"
  | "indexes"
  | "economics"
  | "crypto"
  | "forex"
  | "commodities"
  | "etf-funds"
  | "esg"
  | "technical-indicators"
  | "senate"
  | "sec-filings"
  | "earnings"
  | "dcf"
  | "bulk";
```

资料来源：[src/types/index.ts:22-47]()

### 工具集定义结构

每个工具集包含四个核心属性：

| 属性 | 类型 | 说明 |
|------|------|------|
| name | string | 人类可读的工具集名称 |
| description | string | 功能描述，用于 AI 决策 |
| decisionCriteria | string | 决策标准，指导何时使用此工具集 |
| modules | string[] | 关联的模块数组，对应 src/tools 下的文件 |

资料来源：[src/types/index.ts:49-60]()

## 工具集分类

### 数据获取类

#### 搜索工具集 (search)

提供股票符号和公司搜索功能，是用户查找金融数据的入口点。

| 功能 | 说明 |
|------|------|
| 符号搜索 | 根据关键词搜索股票代码和公司名称 |
| 批量符号解析 | 将符号列表转换为完整的公司信息 |

#### 公司信息工具集 (company)

访问公司基本信息和元数据。

| 功能 | 说明 |
|------|------|
| 公司概况 | 获取公司基本信息、行业分类、员工数量 |
| 管理层信息 | CEO、高管团队和组织结构 |
| ipo 数据 | 上市历史和估值信息 |

#### 行情数据工具集 (quotes)

提供实时和历史价格数据。**注意**：Issue #100 报告了 batch-quote 端点对 Ultimate 计划用户的错误拦截问题，错误发生在 MCP 层而非 FMP API 层。

| 功能 | 说明 |
|------|------|
| 实时报价 | 单个或批量股票当前价格 |
| 历史价格 | 日/周/月级别历史收盘数据 |
| 分时数据 | 分钟级别交易数据 |

资料来源：[src/tools/quotes.ts]()

### 财务报表类

#### 财务报表工具集 (statements)

提供四大财务报表及相关分析数据。

| 功能 | 说明 |
|------|------|
| 资产负债表 | 资产、负债和权益数据 |
| 损益表 | 收入、成本和利润数据 |
| 现金流量表 | 经营、投资和融资现金流 |
| 财务比率 | 常用财务指标计算 |

资料来源：[src/tools/statements.ts]()

#### 财务分析工具集 (analyst)

整合分析师观点和评级数据。

| 功能 | 说明 |
|------|------|
| 分析师推荐 | 买入/卖出/持有评级历史 |
| 目标价预测 | 分析师价格目标汇总 |
| 盈利预期 | EPS 预测和修正历史 |

### 市场数据类

#### 市场指数工具集 (indexes)

跟踪主要市场指数表现和成分股。

| 功能 | 说明 |
|------|------|
| 指数列表 | S&P 500、道琼斯等指数元数据 |
| 指数成分 | 成分股权重和调整历史 |
| 指数表现 | 日/周/月/季度/年度收益率 |

#### 大宗商品工具集 (commodities)

覆盖能源、金属和农产品期货数据。

#### 加密货币与外汇工具集 (crypto/forex)

提供数字资产和外汇市场数据。

### 另类数据类

#### ESG 与可持续发展工具集 (esg)

| 功能 | 说明 |
|------|------|
| ESG 评分 | 环境、社会和治理综合评分 |
| 环境数据 | 碳排放、能源消耗等 |
| 可持续性指标 | 绿色收入、供应链透明度 |

资料来源：[src/constants/toolSets.ts]()

#### 机构持仓工具集 (institutional/form-13f)

跟踪机构投资者的持仓变化。

| 功能 | 说明 |
|------|------|
| 13F 文件 | 机构持仓季度报告 |
| 持仓表现 | 机构投资者业绩分析 |
| 行业分布 | 持仓的行业配置分析 |

资料来源：[src/tools/form-13f.ts]()

#### 内部交易工具集 (insider-trades)

监控公司内部人员的股票交易活动。数据类型定义包括：

```typescript
interface InsiderTrade {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDispositivePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}
```

资料来源：[src/api/insider-trades/types.ts]()

#### 政府交易工具集 (senate)

追踪国会成员和参议员的股票交易披露。

#### SEC 文件工具集 (sec-filings)

提供监管文件和公司披露文档。

| 功能 | 说明 |
|------|------|
| 8-K 表格 | 重大事项即时报告 |
| 10-K/10-Q | 年度/季度报告 |
| 委托声明 | 股东大会相关文件 |

### 新闻与事件类

#### 新闻工具集 (news)

提供多来源金融新闻聚合。

| 功能 | 说明 |
|------|------|
| 通用新闻 | 市场wide新闻覆盖 |
| 股票新闻 | 特定股票的专题报道 |
| 加密新闻 | 数字资产行业新闻 |
| 外汇新闻 | 汇率相关新闻 |
| 新闻稿 | 公司官方新闻稿 |

新闻工具的参数模式已修复 Python 关键字冲突问题：

```typescript
{
  from_date: z.string().optional().describe("Start date (YYYY-MM-DD)"),
  to: z.string().optional().describe("End date (YYYY-MM-DD)"),
  page: z.number().optional().describe("Page number (default: 0)"),
  limit: z.number().optional().describe("Limit on number of results")
}
```

资料来源：[src/tools/news.ts]()

### 分析工具类

#### 技术指标工具集 (technical-indicators)

提供技术分析计算功能。

| 指标类型 | 说明 |
|----------|------|
| 趋势指标 | SMA, EMA, MACD |
| 动量指标 | RSI, Stochastic, CCI |
| 波动指标 | Bollinger Bands, ATR |
| 成交量指标 | OBV, Volume Profile |

#### DCF 估值工具集 (dcf)

提供内在价值评估的现金流折现模型。

### 批量数据类

#### 批量数据工具集 (bulk)

支持大规模数据导出和批量查询，适用于数据仓库填充和历史分析。

## 工具集配置映射

`ModeConfigMapper` 类负责将 FMP 的服务器模式转换为 toolception 框架的配置格式：

```mermaid
graph TD
    A[FMP ServerMode] --> B{ModeConfigMapper.toToolceptionConfig}
    B --> C[DYNAMIC_TOOL_DISCOVERY]
    B --> D[STATIC_TOOL_SETS]
    B --> E[ALL_TOOLS]
    C --> F[Catalog + Dynamic Loaders]
    D --> G[Filtered Catalog]
    E --> H[Full Catalog]
```

资料来源：[src/toolception-adapters/ModeConfigMapper.ts]()

## 参数命名规范

### Python 兼容性问题修复

Issue #93 报告工具参数使用 Python 保留字导致 Python MCP 客户端无法正常工作。v2.6.9 已修复此问题：

| 原参数名 | 新参数名 | 原因 |
|----------|----------|------|
| `from` | `from_date` | `from` 是 Python 保留字 |

此修复确保所有工具的 JSON Schema 与 Python 语法兼容。

资料来源：[CHANGELOG.md - v2.6.9]()

## 配置与使用

### 环境变量配置

| 变量名 | 说明 | 必需 |
|--------|------|------|
| FMP_ACCESS_TOKEN | FMP API 访问令牌 | 是 |
| FMP_TOOL_SETS | 逗号分隔的工具集列表 | 否 |
| DYNAMIC_TOOL_DISCOVERY | 启用动态工具发现 | 否 |

### 工具集白名单

在 toolception 配置中可通过 `allowlist` 指定允许的工具集：

```typescript
exposurePolicy: {
  namespaceToolsWithSetKey: true,
  maxActiveToolsets: 10,
  allowlist: ["quotes", "news", "company"]
}
```

## 项目结构

| 目录 | 职责 |
|------|------|
| src/tools/ | MCP 工具注册和实现 |
| src/api/ | HTTP 客户端和类型定义 |
| src/constants/toolSets.ts | 工具集配置定义 |
| src/toolception-adapters/ | 框架集成适配器 |

资料来源：[CONTRIBUTING.md]()

## 已知问题

| Issue | 状态 | 说明 |
|-------|------|------|
| #100 | 待修复 | batch-quote 对 Ultimate 用户错误拦截 |
| #93 | 已修复 | Python 保留字参数已重命名 |
| #81 | 已修复 | API KEY 配置流程已优化 |

## 扩展指南

### 添加新工具集

1. 在 `src/constants/toolSets.ts` 的 `TOOL_SETS` 对象中添加定义
2. 在 `src/tools/` 创建对应的工具注册文件
3. 在 `src/toolception-adapters/moduleAdapters.ts` 添加适配器
4. 更新 `src/types/index.ts` 中的 `ToolSet` 联合类型

### 添加新工具

1. 在 `src/api/{domain}/` 的客户端中添加方法
2. 在对应模块的 `src/tools/{module}.ts` 中注册工具
3. 使用 Zod schema 定义参数验证

详细步骤请参考 [docs/USAGE.md](docs/USAGE.md)。

---

<a id='tools-usage'></a>

## 工具使用指南

### 相关页面

相关主题：[工具目录](#tools-catalog), [常见问题与故障排除](#troubleshooting)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [GUIDE.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/GUIDE.md)
- [src/tools/AGENTS.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/AGENTS.md)
- [src/tools/news.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/news.ts)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [src/api/insider-trades/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/insider-trades/types.ts)
</details>

# 工具使用指南

本指南介绍 Financial-Modeling-Prep-MCP-Server 的工具系统架构、24个工具集的功能范围，以及如何正确使用和扩展工具。

## 工具系统概述

FMP MCP Server 通过 Model Context Protocol (MCP) 向 AI 助手暴露 Financial Modeling Prep API 的所有功能。工具系统采用模块化架构，将相关的 API 端点分组为不同的工具集。

**核心设计原则：**

- **永不抛异常**：工具处理函数必须捕获所有错误并返回 `{ content: [...], isError: true }` 格式的响应
- **全局唯一命名**：工具名称必须在所有28个模块中保持唯一
- **统一注解**：所有工具使用相同的注解：`readOnlyHint`、`idempotentHint`、`openWorldHint`
- **参数兼容性**：参数名不能使用 Python 保留关键字（如 `from` 已改为 `from_date`）

资料来源：[src/tools/AGENTS.md]()

## 24个工具集

系统支持24个功能模块，涵盖股票行情、财务数据、新闻、技术分析等金融数据领域：

| 工具集 | 名称 | 功能范围 |
|--------|------|----------|
| `search` | 搜索 | 股票代码搜索、公司目录查询 |
| `quotes` | 行情报价 | 实时价格、批量报价、历史行情 |
| `statements` | 财务报表 | 资产负债表、利润表、现金流量表 |
| `company` | 公司信息 | 基本面、高管、描述信息 |
| `analyst` | 分析师数据 | 评级、目标价、EPS修正 |
| `news` | 新闻 | 一般新闻、加密货币新闻、外汇新闻 |
| `insider-trades` | 内幕交易 | 高管/内部人交易披露 |
| `institutional` | 机构持仓 | 13F 机构持仓数据 |
| `etf-funds` | ETF基金 | ETF 持有量、基金数据 |
| `government-trading` | 政府交易 | 参议院/国会交易披露 |
| `crypto` | 加密货币 | 加密货币报价、新闻 |
| `forex` | 外汇 | 外汇货币对报价 |
| `commodities` | 大宗商品 | 商品期货价格 |
| `indexes` | 市场指数 | 指数数据、性能指标 |
| `market-performance` | 市场表现 | 市场概览、表现追踪 |
| `economics` | 经济数据 | 宏观经济指标 |
| `sec-filings` | SEC文件 | 8-K、10-K、监管文件 |
| `earnings` | 财报会议 | 财报电话会议记录 |
| `esg` | ESG评级 | 环境、社会、治理评分 |
| `technical-indicators` | 技术指标 | RSI、SMA、EMA 等 |
| `dcf` | DCF估值 | 现金流折现模型 |
| `bulk` | 批量数据 | 批量导出工具 |
| `charts` | 图表 | K线图数据 |
| `calendar` | 日历事件 | IPO、财报发布日历 |

资料来源：[src/constants/toolSets.ts]()
资料来源：[src/types/index.ts]()

## 工具使用流程

```mermaid
graph TD
    A[MCP客户端] --> B[工具调用请求]
    B --> C{MCP Server}
    C --> D{工具集权限检查}
    D -->|已授权| E[执行工具逻辑]
    D -->|未授权| F[返回权限错误]
    E --> G[调用FMP API]
    G --> H{API响应}
    H -->|成功| I[返回JSON数据]
    H -->|失败| J[捕获异常]
    J --> K[返回错误响应]
    I --> L[格式化输出]
    K --> L
    L --> M[MCP客户端]
```

## 参数规范

所有工具参数使用 Zod 进行模式验证。参数命名需要遵循以下规则：

**日期参数命名规则：**
- 使用 `from_date` 而非 `from`（避免 Python 保留关键字冲突）
- 使用 `to_date` 或 `to` 表示结束日期

**标准参数模式：**

```typescript
server.tool(
  "toolName",
  "工具描述，说明功能和使用场景",
  {
    // 必选参数
    symbol: z.string().describe("股票代码，如 AAPL"),
    
    // 可选参数
    from_date: z.string().optional().describe("开始日期 (YYYY-MM-DD)"),
    to_date: z.string().optional().describe("结束日期 (YYYY-MM-DD)"),
    limit: z.number().optional().describe("返回结果数量限制"),
    page: z.number().optional().describe("分页页码"),
  },
  async ({ symbol, from_date, to_date, limit, page }) => {
    // 工具实现
  }
);
```

资料来源：[src/tools/news.ts]()
资料来源：[src/tools/AGENTS.md]()

## 错误处理规范

**严格禁止在工具处理函数中抛出异常**。MCP 协议要求错误通过响应体返回，而非异常机制。

**正确的错误处理模式：**

```typescript
async ({ symbol, limit }) => {
  try {
    const results = await apiClient.getData({ symbol, limit });
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
        },
      ],
      isError: true,
    };
  }
}
```

**错误消息格式要求：**
- 必须以 `Error: ` 开头
- 保持一致的性格化输出

资料来源：[src/tools/AGENTS.md]()
资料来源：[src/tools/news.ts]()

## 常见使用问题

### Python 保留关键字问题

**问题描述**：部分工具参数名使用了 Python 保留关键字（如 `from`、`class`），导致 Python MCP 客户端无法正确解析。

**解决方案**：v2.6.9 版本已将 `from` 参数重命名为 `from_date`。如遇到其他保留关键字问题，请参考以下映射：

| 原参数名 | 新参数名 |
|----------|----------|
| `from` | `from_date` |

资料来源：[CHANGELOG.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CHANGELOG.md)

### API Key 配置问题

**问题描述**：用户报告在 Smithery.ai 集成时无法设置 `FMP_API_TOKEN`。

**解决方案**：
- 使用环境变量 `FMP_ACCESS_TOKEN`（不是 `FMP_API_TOKEN`）
- 在会话级别，只能设置 `FMP_ACCESS_TOKEN`，其他配置项仅支持服务器级别

```typescript
// 正确的配置方式
FMP_ACCESS_TOKEN=your_token_here
```

资料来源：[src/types/index.ts]()

### 批量报价权限问题

**问题描述**：`batch-quote` 端点对 Ultimate 计划用户返回 ACCESS DENIED 错误。

**说明**：这是已知的 MCP 层计划门控误报问题，错误发生在 MCP 层而非 FMP API 层。问题会在后续版本中修复。

## 添加新工具

如需扩展工具集，请按照以下步骤操作：

**流程概览：**

```mermaid
graph LR
    A[添加API客户端方法] --> B[注册工具]
    B --> C[添加适配器]
    C --> D[映射到工具集]
    D --> E[测试工具]
```

**详细步骤：**

| 步骤 | 操作 | 文件位置 |
|------|------|----------|
| 1 | 在现有客户端添加方法 | `src/api/{domain}/` |
| 2 | 在工具模块注册 | `src/tools/{module}.ts` |
| 3 | 添加适配器 | `src/toolception-adapters/moduleAdapters.ts` |
| 4 | 映射到工具集 | `src/constants/toolSets.ts` |

**工具注册示例：**

```typescript
server.tool(
  "toolName",
  "工具描述",
  {
    paramName: z.string().describe("参数说明"),
  },
  async ({ paramName }) => {
    try {
      const result = await client.getData({ paramName });
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    } catch (error) {
      return {
        content: [
          { type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` },
        ],
        isError: true,
      };
    }
  }
);
```

资料来源：[GUIDE.md]()

## 数据类型参考

### 内部人员交易数据

```typescript
interface InsiderTrade {
  symbol: string;
  filingDate: string;
  acceptedDate: string;
  cusip: string;
  nameOfReportingPerson: string;
  citizenshipOrPlaceOfOrganization: string;
  soleVotingPower: string;
  sharedVotingPower: string;
  soleDispositivePower: string;
  sharedDispositivePower: string;
  amountBeneficiallyOwned: string;
  percentOfClass: string;
  typeOfReportingPerson: string;
  url: string;
}
```

### DCF 估值数据

```typescript
interface DCFData {
  revenue?: number;
  netIncome?: number;
  operatingCashFlow?: number;
  freeCashFlow?: number;
  wacc?: number;
  terminalValue?: number;
  enterpriseValue?: number;
  equityValue?: number;
  equityValuePerShare?: number;
  price?: number;
  beta?: number;
}
```

资料来源：[src/api/insider-trades/types.ts]()
资料来源：[src/api/dcf/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/dcf/types.ts)

## 工具集决策指南

根据用户需求选择合适的工具集：

| 需求场景 | 推荐工具集 |
|----------|------------|
| 查询股票代码 | `search` |
| 获取实时价格 | `quotes` |
| 分析财务报表 | `statements` |
| 技术分析 | `technical-indicators` |
| 价值投资分析 | `dcf` |
| 跟踪内部交易 | `insider-trades` |
| SEC 文件研究 | `sec-filings` |
| 宏观经济分析 | `economics` |
| ESG 投资筛选 | `esg` |

---

<a id='troubleshooting'></a>

## 常见问题与故障排除

### 相关页面

相关主题：[配置指南](#configuration), [工具使用指南](#tools-usage)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/tools/news.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/news.ts)
- [src/api/news/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/news/types.ts)
- [src/types/index.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/types/index.ts)
- [src/toolception-adapters/ModeConfigMapper.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/ModeConfigMapper.ts)
- [src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
- [server.json](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/server.json)
- [GUIDE.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/GUIDE.md)
- [src/api/insider-trades/types.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/api/insider-trades/types.ts)
</details>

# 常见问题与故障排除

本文档汇总了 Financial Modeling Prep MCP Server 使用过程中可能遇到的常见问题、错误场景及解决方案。

## 安装与初始配置

### Node.js 版本要求不满足

**症状**: 服务器启动时报错 `node: command not found` 或版本不兼容错误。

**解决方案**: 本服务器要求 Node.js >= 25.3.0 和 npm >= 11.11.0。请升级 Node.js：

```bash
# 使用 nvm 升级 Node.js
nvm install 25.3.0
nvm use 25.3.0

# 验证版本
node --version  # 应显示 v25.3.0 或更高
npm --version   # 应显示 11.11.0 或更高
```

资料来源：[package.json:47-48]()

### API 密钥配置失败

**症状**: 连接服务器时收到 "ACCESS DENIED" 或 "missing FMP_ACCESS_TOKEN" 错误。

**原因分析**: 根据 Issue #81 的用户反馈，在 Smithery.ai 等平台配置时，可能出现 OAuth 字段留空后 API Token 无法传递的问题。

**解决方案**:

| 配置方式 | 环境变量 | 说明 |
|---------|---------|------|
| 全局环境变量 | `FMP_ACCESS_TOKEN` | 启动前设置 |
| 命令行参数 | `--fmp-token <token>` | 动态传入 |
| 会话配置 | `FMP_ACCESS_TOKEN` (仅限此字段) | 仅支持设置此单个字段 |

```bash
# 方式一：环境变量
export FMP_ACCESS_TOKEN=your_api_token_here
fmp-mcp

# 方式二：命令行参数
fmp-mcp --fmp-token your_api_token_here
```

资料来源：[server.json:19-22]()

**重要说明**: sessionConfig 参数仅允许设置 `FMP_ACCESS_TOKEN` 字段，不支持其他自定义字段的会话级配置。资料来源：[CHANGELOG.md](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/CHANGELOG.md)

### Docker 安装配置问题

**症状**: Docker 容器无法正常启动或认证失败。

**解决方案**: 从源码构建镜像而非使用预构建镜像：

```bash
# 构建本地镜像
docker build -t fmp-mcp-local .

# 运行容器
docker run -e FMP_ACCESS_TOKEN=your_token fmp-mcp-local
```

资料来源：[CHANGELOG.md:39-41]()

## 工具使用问题

### Python 保留关键字导致客户端解析失败

**症状**: Python MCP 客户端（如 LangChain、Claude SDK 等）无法正确调用工具，参数验证失败。

**原因分析**: Issue #93 报告了多个工具的参数名称使用了 Python 保留关键字，违反了 JSON Schema 到 Python 类型的转换规范。

**受影响的参数**:

| 原参数名 | 问题类型 | 建议替代名 |
|---------|---------|-----------|
| `from` | Python 保留关键字 | `from_date` |
| `class` | Python 保留关键字 | `class_name` |
| `import` | Python 保留关键字 | `import_data` |
| `global` | Python 保留关键字 | `global_flag` |

**版本修复**: v2.6.9 已将 `from` 参数重命名为 `from_date`：

```typescript
// 修复前 (v2.6.8)
{ from: z.string().optional() }

// 修复后 (v2.6.9+)
{ from_date: z.string().optional().describe("Start date (YYYY-MM-DD)") }
```

资料来源：[src/tools/news.ts:1-50](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/tools/news.ts)
资料来源：[CHANGELOG.md:24-27]()

### batch-quote 端点计划级别误判

**症状**: Ultimate 计划用户访问 batch-quote 相关工具时返回 "ACCESS DENIED - lower-tier plan" 错误。

**原因分析**: Issue #100 报告此问题由 MCP 层在请求到达 FMP API 前就进行了错误的计划验证，导致合法用户被错误拦截。

**排查步骤**:

1. 确认 FMP 账户当前订阅计划为 Ultimate
2. 检查 API Token 是否具有批量查询权限
3. 验证 token 未过期或被撤销
4. 联系 FMP 支持确认账户权限状态

**临时解决方案**: 使用单个股票报价工具替代批量查询，逐个获取数据。

资料来源：[Issue #100](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/100)

### 工具集未加载或不可用

**症状**: 尝试调用特定工具时报错 "Tool not found" 或功能完全不可用。

**原因分析**: 服务器可能运行在 `STATIC_TOOL_SETS` 模式，仅加载配置的工具集。

**解决方案**: 检查并配置 `FMP_TOOL_SETS` 参数：

```bash
# 启动时指定工具集
fmp-mcp --fmp-tool-sets quotes,company,statements

# 或使用环境变量
export FMP_TOOL_SETS="quotes,company,statements"
```

**可用工具集列表**:

| 工具集 ID | 名称 | 说明 |
|-----------|------|------|
| `search` | Search | 股票符号搜索 |
| `company` | Company Information | 公司基本信息 |
| `quotes` | Quotes & Price Data | 实时报价 |
| `statements` | Financial Statements | 财务报表 |
| `news` | News & Press Releases | 新闻资讯 |
| `technical-indicators` | Technical Indicators | 技术指标 |
| `sec-filings` | SEC Filings | SEC 文件 |
| `esg` | ESG & Sustainability | ESG 评级 |
| `dcf` | DCF Valuation | DCF 估值 |
| `bulk` | Bulk Data Tools | 批量数据 |

资料来源：[src/constants/toolSets.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/constants/toolSets.ts)
资料来源：[src/types/index.ts:24-47]()

## 数据类型与响应问题

### 返回数据类型定义

**NewsArticle 类型结构**:

| 字段 | 类型 | 说明 |
|-----|------|------|
| `symbol` | `string \| null` | 关联股票代码 |
| `publishedDate` | `string` | 发布日期 (ISO 8601) |
| `publisher` | `string` | 发布来源 |
| `title` | `string` | 文章标题 |
| `image` | `string` | 图片 URL |
| `site` | `string` | 来源网站 |
| `text` | `string` | 文章正文 |
| `url` | `string` | 原文链接 |

资料来源：[src/api/news/types.ts:14-21]()

**FMPArticle 类型结构**:

| 字段 | 类型 | 说明 |
|-----|------|------|
| `title` | `string` | 文章标题 |
| `date` | `string` | 发布日期 |
| `content` | `string` | 完整内容 |
| `tickers` | `string` | 关联股票代码列表 |
| `image` | `string` | 图片 URL |
| `link` | `string` | 原文链接 |
| `author` | `string` | 作者 |
| `site` | `string` | 来源网站 |

资料来源：[src/api/news/types.ts:3-12]()

### Insider 交易数据字段

| 字段 | 类型 | 说明 |
|-----|------|------|
| `symbol` | `string` | 股票代码 |
| `filingDate` | `string` | 提交日期 |
| `cusip` | `string` | CUSIP 编号 |
| `nameOfReportingPerson` | `string` | 报告人姓名 |
| `soleVotingPower` | `string` | 独有投票权 |
| `sharedVotingPower` | `string` | 共有投票权 |
| `percentOfClass` | `string` | 持股比例 |
| `typeOfReportingPerson` | `string` | 报告人类型 |

资料来源：[src/api/insider-trades/types.ts:1-18]()

## 服务器模式配置

### 三种服务器模式详解

```mermaid
graph TD
    A[服务器启动] --> B{启动参数配置}
    B --> C[ALL_TOOLS]
    B --> D[STATIC_TOOL_SETS]
    B --> E[DYNAMIC_TOOL_DISCOVERY]
    
    C --> F[加载全部 250+ 工具]
    D --> G[仅加载指定工具集]
    E --> H[运行时动态发现]
    
    F --> I[完整功能但资源占用高]
    G --> J[按需加载灵活性高]
    H --> K[智能按需加载]
```

| 模式 | 环境变量 | 命令行参数 | 说明 |
|------|---------|-----------|------|
| `ALL_TOOLS` | - | - | 加载所有工具 |
| `STATIC_TOOL_SETS` | `FMP_TOOL_SETS` | `--fmp-tool-sets` | 静态加载指定工具集 |
| `DYNAMIC_TOOL_DISCOVERY` | `DYNAMIC_TOOL_DISCOVERY=true` | `--dynamic-tool-discovery` | 动态发现 |

资料来源：[src/types/index.ts:49-51]()
资料来源：[src/toolception-adapters/ModeConfigMapper.ts](https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/blob/main/src/toolception-adapters/ModeConfigMapper.ts)

### ModeConfigMapper 配置映射

`ModeConfigMapper` 类负责将 FMP 服务器模式转换为 toolception 框架配置：

```typescript
interface ToolceptionConfig {
  catalog: ToolSetCatalog;       // 工具集目录
  moduleLoaders: Record<string, ModuleLoader>;  // 模块加载器
  startup: { mode: 'DYNAMIC' | 'STATIC' };
  context: { accessToken?: string };
  exposurePolicy: {
    namespaceToolsWithSetKey: boolean;
    maxActiveToolsets?: number;
    allowlist?: ToolSet[];
  };
}
```

资料来源：[src/toolception-adapters/ModeConfigMapper.ts:44-56]()

## 调试与诊断

### 启用调试模式

```bash
# 查看所有可用的工具集
fmp-mcp --help

# 验证配置
npm run version:validate

# 检查版本一致性
npm run version:info
```

### 常见错误码对照表

| 错误信息 | 可能原因 | 解决方案 |
|---------|---------|---------|
| `ACCESS DENIED` | Token 无效或权限不足 | 检查 FMP_ACCESS_TOKEN |
| `Tool not found` | 工具未加载 | 确认工具集配置 |
| `Invalid parameter` | 参数类型错误 | 检查参数 schema |
| `Network error` | 网络连接问题 | 检查防火墙/代理设置 |
| `Rate limit exceeded` | API 调用频率超限 | 降低请求频率 |

### 诊断流程图

```mermaid
graph TD
    A[遇到问题] --> B{错误类型?}
    B --> C[认证错误]
    B --> D[工具不可用]
    B --> E[数据错误]
    B --> F[性能问题]
    
    C --> C1{Token 配置正确?}
    C1 -->|否| C2[配置 API Token]
    C1 -->|是| C3[检查 Token 权限]
    
    D --> D1{工具集配置?}
    D1 -->|未配置| D2[配置 FMP_TOOL_SETS]
    D1 -->|已配置| D3[检查模块加载器]
    
    E --> E1{返回数据结构?}
    E1 -->|异常| E2[查看 API 文档]
    E1 -->|错误| E3[检查网络连接]
    
    F --> F1{延迟高?}
    F1 -->|是| F2[启用动态工具发现]
    F1 -->|否| F3[优化请求批次]
```

## 获取帮助

### 资源链接

| 资源 | 链接 |
|------|------|
| GitHub Issues | https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues |
| NPM 包 | `npm install financial-modeling-prep-mcp-server` |
| MCP Registry | https://registry.modelcontextprotocol.io/servers/io.github.imbenrabi/financial-modeling-prep-mcp-server |
| Smithery.ai | https://smithery.ai/server/@imbenrabi/financial-modeling-prep-mcp-server |
| Glama.ai | https://glama.ai/mcp/servers/@imbenrabi/financial-modeling-prep-mcp-server |

### 报告问题

报告新问题时请包含以下信息：

1. 服务器版本 (`npm list financial-modeling-prep-mcp-server`)
2. Node.js 版本 (`node --version`)
3. 完整的错误日志
4. 复现步骤
5. 环境配置（隐藏敏感信息如 API Token）

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：imbenrabi/financial-modeling-prep-mcp-server

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients。

## 1. 安装坑 · 来源证据：Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Tool input schemas use Python reserved keywords and invalid identifiers as parameter names, breaking Python MCP clients
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_75b7a65ba21a4165943ec8a7ebcd0091 | https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/93 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | last_activity_observed missing

## 4. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | no_demo; severity=medium

## 6. 安全/权限坑 · 来源证据：FMP API KEY impossible to set

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FMP API KEY impossible to set
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9ae13b6fa15041539df40160e45bb1b0 | https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/81 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 7. 安全/权限坑 · 来源证据：batch-quote endpoint incorrectly blocked for Ultimate plan users — MCP plan-gate false positive

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：batch-quote endpoint incorrectly blocked for Ultimate plan users — MCP plan-gate false positive
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e69c7ecfae6b40be92a4af0220588aaf | https://github.com/imbenrabi/Financial-Modeling-Prep-MCP-Server/issues/100 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.imbenrabi/financial-modeling-prep-mcp-server:2.6.10 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.imbenrabi%2Ffinancial-modeling-prep-mcp-server/versions/2.6.10 | release_recency=unknown

<!-- canonical_name: imbenrabi/financial-modeling-prep-mcp-server; human_manual_source: deepwiki_human_wiki -->