insightiq

InsightIQ：经济洞察助手

InsightIQ 是一个本地 MCP 服务，可让 AI Agent（Claude Code、Claude Desktop 或任何其他 MCP 客户端）查询真实的 FRED（美联储经济数据）序列及其历史观测值，从而回答经济问题。

流程如下：

1. Agent 搜索 FRED 的实时序列目录（使用 search_economic_series 或 get_economic_data 工具），查找与用户问题相关的序列。
2. Agent 获取所需序列的年度观测值和单位。
3. Agent 自行分析数据并回答用户的问题——InsightIQ 只返回检索到的数据，不会生成解释。

安装

已在 npm 上发布，名称为 insightiq-mcp。 你需要先获取免费的 FRED API 密钥：点击此处获取。

{
  "mcpServers": {
    "insightiq": {
      "command": "npx",
      "args": ["-y", "insightiq-mcp"],
      "env": {
        "FRED_API_KEY": "your_fred_api_key_here"
      }
    }
  }
}

将其添加到 MCP 客户端的配置中（Claude Code 使用 .mcp.json 文件，Claude Desktop 使用“设置 → 开发者 → 编辑配置”）。完整的工具参考和各客户端的详细说明，请参阅 mcp/README.md。

架构

flowchart TD
  agent[Agent / MCP Client] -->|Tool calls, stdio| mcp[InsightIQ MCP Server]

  mcp -->|Search phrases| fredSearch[FRED series/search]
  fredSearch -->|Real FRED series IDs| mcp

  mcp -->|Series IDs| fredApi[FRED API]
  fredApi -->|Annual observations and metadata| mcp

  mcp -->|Raw retrieved data| agent

所有内容都由 Agent 宿主启动的单个本地进程运行。InsightIQ 本身没有数据库、本地目录、独立后端服务，也不会在任何地方调用大模型——唯一对数据进行推理的模型，是驱动调用方 Agent 的大模型。

工具

search_economic_series

搜索 FRED 的实时序列目录。接收 queries：1-3 个简洁的 FRED 风格关键词短语（例如 ["inflation", "consumer price index"]），而不是完整问题——FRED 的全文搜索实际上要求短语中的每个词都匹配，因此简短且具体的短语远比句子有效。仅返回真实的 FRED 序列 ID 和标题；绝不会编造序列 ID。正因如此，每个短语在提交给 FRED 前都会经过填充词过滤器处理。可选的 limit（默认值为 4）和 tags/excludeTags（FRED 的标签词汇，例如地理区域或季节调整）可进一步缩小结果范围。

get_series_observations

获取指定 FRED 序列 ID 的历史年度观测值和单位。仅返回原始数据——不会生成摘要或解释。

get_economic_data

便捷工具，将以上两个工具串联起来：如果提供了 searchQueries，则使用它搜索相关序列（否则使用原始的 question），然后获取这些序列的观测值。仍然只返回原始数据。接受与 search_economic_series 相同的 limit/tags/excludeTags。

list_series_tags

给定一个主题短语，返回匹配序列中实际存在的 FRED 标签及其序列数量——这是使用上述 tags/excludeTags 的探索步骤，因为通常很难可靠地猜出 FRED 的标签词汇。

---

开发

以下内容仅适用于想要修改或贡献此服务的情况——使用时不需要（使用说明请参阅上方的 安装）。

• mcp/：MCP 服务。src/tools/ 是对外提供的工具；src/services/ 和 src/clients/ 包含 FRED 搜索和数据获取逻辑；evals/ 包含 MCP 层的评估套件（工具契约 + 检索召回率）。

前置条件：Node.js 20 或更高版本、FRED API 密钥。

git clone https://github.com/ravi-p-k-1/InsightIQ.git
cd InsightIQ/mcp
npm install

从 mcp/.env.template 创建 mcp/.env：

FRED_API_KEY=your_fred_api_key_here

直接运行以确认其可以启动：

npm start

仓库根目录中有一个项目专用的 .mcp.json，可将 Claude Code 指向你的本地检出版本（在仓库根目录打开项目时会自动加载，首次使用时需要你批准）——这便于在发布新版本前测试更改。

验证

GitHub Actions 会在推送到 main 和提交拉取请求时运行 CI：安装 依赖项并检查语法，不会调用 FRED。

cd mcp
find src evals -name "*.js" -print0 | xargs -0 -n1 node --check

没有单独的单元测试套件——正确性和质量通过 MCP 级别的评估来验证：评估会在进程内将真实客户端连接到真实服务，并以 Agent 的实际使用方式驱动服务。这些评估会调用实时 FRED API，因此需要手动运行，而非在 CI 中运行：

cd mcp
npm run eval:contract          # tool inventory, schema/error-path, happy-path checks
npm run eval:retrieval         # retrieval recall floor (single raw question)
npm run eval:retrieval:smart   # retrieval recall ceiling (curated query plans)

eval:retrieval 衡量无查询智能能力时的基线（当前问题集上为 45.3%）；eval:retrieval:smart 会重放一组已签入代码库、按问题整理的搜索短语和标签，这些内容是按胜任 Agent 的方式选定的（得分为 62.4%），评估时无需实时调用 LLM。各项评估的检查内容请参阅 mcp/README.md。