STARWARCLOUD STARWAR.AI
返回市场
爱瑞亚-mcp

爱瑞亚-mcp

作者：aiera-inc2 星标更新：2025-11-19
安装使用来源：spider==github.com

项目介绍

<a href="https://www.aiera.com"> <div align="center"> <picture> <source media="(prefers-color-scheme: light)" srcset="assets/aiera_logo_lightmode.png"> <source media="(prefers-color-scheme: dark)" srcset="assets/aiera_logo_darkmode.jpeg"> <img alt="Aiera logo" src="assets/aiera_logo_darkmode.jpeg" height="100"> </picture> </div> </a> <br>

[!IMPORTANT] :test_tube: 本项目是实验性的，可能会有重大变更。

Aiera MCP 工具

这是一个提供访问 Aiera 财务数据的 Model Context Protocol (MCP) 包。此仓库包含一个独立的 MCP 服务器和一个可重用的 Python 包。

概览

此包公开了 Aiera API 端点作为 MCP 工具，提供了全面的财务数据访问，包括：

  • 事件：日历事件、会议记录及其元数据
  • 公司信息：符号、摘要、行业分类及观察名单
  • 公司文档：新闻稿、幻灯片演示文稿、披露文件
  • SEC 文件：文件数据及其元数据
  • 搜索：在会议记录和 SEC 文件内容中进行语义搜索
  • Transcrippets：创建、管理和检索会议记录摘录
  • Third Bridge：专家见解事件

安装

方案 1：作为 Python 包（推荐）

从 GitHub 直接安装：

pip install git+https://github.com/aiera-inc/aiera-mcp.git

或者添加到你的 pyproject.toml：

dependencies = [
    "aiera-mcp-tools @ git+https://github.com/aiera-inc/aiera-mcp.git@main",
]

方案 2：本地开发

  1. 克隆并安装：
git clone https://github.com/aiera-inc/aiera-mcp.git
cd aiera-mcp
uv sync --group dev  # 使用开发依赖项安装
  1. 设置 pre-commit 钩子（开发推荐）：
uv run pre-commit install
  1. 设置环境变量：
export AIERA_API_KEY="your-aiera-api-key"
  1. 运行独立服务器：
uv run entrypoint.py

使用

作为包

import asyncio
from mcp.server.fastmcp import FastMCP
from aiera_mcp import register_aiera_tools

# 基础使用，使用 AIERA_API_KEY 环境变量
mcp = FastMCP("MyServer")
register_aiera_tools(mcp)

# 对于 OAuth 系统（例如 aiera-public-mcp）
from your_auth_system import get_current_api_key
register_aiera_tools(mcp, get_current_api_key)

# 使用 Pydantic 验证集成包
from aiera_mcp.tools import register_tools
register_tools(mcp)

# 选择性工具注册 - 只包含特定工具
register_tools(mcp, include_tools=['find_events', 'get_event'])

# 选择性工具注册 - 排除特定工具
register_tools(mcp, exclude_tools=['delete_transcrippet', 'create_transcrippet'])

# 或者全局配置
from aiera_mcp import set_api_key_provider
set_api_key_provider(get_current_api_key)

# 或者导入单独函数
from aiera_mcp import find_events, make_aiera_request, correct_bloomberg_ticker

包内容

工具

  • 事件：find_events, get_event, get_upcoming_events
  • 文件：find_filings, get_filing
  • 股票：find_equities, get_equity_summaries, get_sectors_and_subsectors
  • 指数与观察名单：get_available_indexes, get_index_constituents, get_available_watchlists, get_watchlist_constituents
  • 公司文档：find_company_docs, get_company_doc, get_company_doc_categories, get_company_doc_keywords
  • 搜索：search_transcripts, search_filings, search_filing_chunks
  • Transcrippets：find_transcrippets, create_transcrippet, delete_transcrippet
  • Third Bridge：find_third_bridge_events, get_third_bridge_event

实用工具

  • API 函数：make_aiera_request
  • 数据校正：correct_bloomberg_ticker, correct_keywords, correct_categories, correct_provided_ids, correct_event_type, correct_transcript_section
  • 注册：
    • register_aiera_tools - 注册所有工具到任何 FastMCP 服务器实例（用于独立服务器）
    • register_tools - 基于注册表的注册，带有 Pydantic 验证和选择性过滤（用于包集成）
  • 工具发现：
    • get_all_tool_names - 获取所有可用工具名称列表
    • get_categories - 获取所有工具类别
    • get_tools_by_category - 按类别筛选工具
    • get_tools_by_read_only - 按只读状态筛选工具
    • get_destructive_tools - 获取所有潜在破坏性工具
  • 认证：set_api_key_provider, get_api_key, clear_api_key_provider - OAuth 兼容函数

常量

  • DEFAULT_PAGE_SIZE, DEFAULT_MAX_PAGE_SIZE, AIERA_BASE_URL, CITATION_PROMPT
  • AVAILABLE_TOOLS - 所有 24 个可用工具名称列表

选择性工具注册

register_aiera_tools 函数支持可选的 include 和 exclude 参数来注册工具子集：

from mcp.server.fastmcp import FastMCP
from aiera_mcp import register_aiera_tools, EVENT_TOOLS, THIRD_BRIDGE_TOOLS

mcp = FastMCP("MyServer")

# 注册仅与事件相关的工具
register_aiera_tools(mcp, include=["find_events", "get_event", "get_upcoming_events"])

# 使用预定义的工具组以方便使用
register_aiera_tools(mcp, include=EVENT_TOOLS)

# 注册所有工具，除了 Third Bridge
register_aiera_tools(mcp, exclude=THIRD_BRIDGE_TOOLS)

# 结合 OAuth 认证
from your_auth_system import get_current_api_key
register_aiera_tools(mcp, get_current_api_key, include=EVENT_TOOLS)

可用工具组

该包提供了预定义的工具组以应对常见使用场景：

  • EVENT_TOOLS：["find_events", "get_event", "get_upcoming_events"]
  • FILING_TOOLS：["find_filings", "get_filing"]
  • EQUITY_TOOLS：["find_equities", "get_equity_summaries", "get_sectors_and_subsectors"]
  • INDEX_WATCHLIST_TOOLS：["get_available_indexes", "get_index_constituents", "get_available_watchlists", "get_watchlist_constituents"]
  • COMPANY_DOC_TOOLS：["find_company_docs", "get_company_doc", "get_company_doc_categories", "get_company_doc_keywords"]
  • SEARCH_TOOLS：["search_transcripts", "search_filings", "search_filing_chunks"]
  • TRANSCRIPPET_TOOLS：["find_transcrippets", "create_transcrippet", "delete_transcrippet"]
  • THIRD_BRIDGE_TOOLS：["find_third_bridge_events", "get_third_bridge_event"]
  • AVAILABLE_TOOLS：所有 24 个可用工具的完整列表

使用示例

# 注册核心金融工具（事件 + 文件 + 股票）
core_tools = EVENT_TOOLS + FILING_TOOLS + EQUITY_TOOLS
register_aiera_tools(mcp, include=core_tools)

# 注册除 Third Bridge 以外的所有工具（适用于基本订阅）
register_aiera_tools(mcp, exclude=THIRD_BRIDGE_TOOLS)

# 注册仅搜索/发现工具
discovery_tools = ["find_events", "find_filings", "find_equities", "find_company_docs"]
register_aiera_tools(mcp, include=discovery_tools)

错误处理

该函数验证工具名称，并提供有用的错误消息：

# 这将引发 ValueError: 在 'include' 中指定未知工具：['nonexistent_tool']
register_aiera_tools(mcp, include=["nonexistent_tool"])

# 这将引发 ValueError: 不能同时指定 'include' 和 'exclude' 参数
register_aiera_tools(mcp, include=EVENT_TOOLS, exclude=FILING_TOOLS)

前提条件

  • Python 3.11 或更高版本
  • 一个 Aiera API 密钥
  • Astral UV（用于开发）

Claude Desktop 配置

方案 1：使用独立服务器

  1. 遵循 Claude Desktop MCP 安装指南，找到你的配置文件。
  2. 使用以下配置：
    • 将 <your_api_key_here> 替换为你的实际 Aiera API 密钥
    • 将 <your_directory> 替换为你家目录路径
<details> <summary>claude_desktop_config.json (独立服务器)</summary> 
{
    "mcpServers": {
        "Aiera MCP": {
           "command": "uv",
           "args": [
               "run",
               "--with",
               "git+https://github.com/aiera-inc/aiera-mcp.git",
               "--with",
               "mcp[cli]",
               "mcp",
               "run",
               "aiera_mcp/server.py"
            ],
            "env": {
               "AIERA_API_KEY": "<your_api_key_here>"
            }
        }
    }
}
</details>

方案 2：使用本地安装

<details> <summary>claude_desktop_config.json (本地安装)</summary> 
{
    "mcpServers": {
        "Aiera MCP": {
           "command": "<your_directory>/.local/bin/uv",
           "args": [
               "run",
               "--with",
               "mcp[cli]",
               "mcp",
               "run",
               "<your_directory>/aiera-mcp/aiera_mcp/server.py"
            ],
            "env": {
               "AIERA_API_KEY": "<your_api_key_here>"
            }
        }
    }
}
</details>

选择性工具注册

该包支持选择性注册以包含或排除特定工具：

from aiera_mcp.tools import register_tools, get_all_tool_names, get_destructive_tools

# 获取可用工具
all_tools = get_all_tool_names()
print(f"可用工具: {all_tools}")

# 注册仅只读工具（排除破坏性操作）
destructive_tools = list(get_destructive_tools().keys())
register_tools(mcp, exclude_tools=destructive_tools)

# 注册仅与事件相关的工具
event_tools = ['find_events', 'get_event', 'get_upcoming_events']
register_tools(mcp, include_tools=event_tools)

# 错误处理并提供建议
try:
    register_tools(mcp, include_tools=['find_event'])  # 拼写错误
except ValueError as e:
    print(e)  # 将建议： "您是指： find_event -> ['find_events', 'get_event']"

使用示例

一旦集成，你可以提示 Claude 访问 Aiera 数据：

获取苹果公司的最新收益电话会议记录并总结关键点

主要特性

  • 全面 API 支持：实现大多数 Aiera API 端点作为 MCP 工具
  • 灵活集成：可以作为独立服务器使用，也可以集成到 Python 包中
  • OAuth 兼容：无缝集成到 OAuth 认证系统（如 aiera-public-mcp）
  • 多认证：支持环境变量和 OAuth 提供商
  • 数据验证：内置工具用于纠正股票代码、关键词和其他参数
  • 选择性注册：包含或排除特定工具，具有智能错误处理和建议
  • 工具发现：辅助函数按类别、权限和功能探索可用工具
  • 类型安全：基于 Pydantic 的参数验证，自动生成模式
  • 注册表模式：集中管理工具元数据和配置
  • 开发就绪：完整的开发环境，包括测试和代码检查工具

某些端点可能需要特殊权限。请联系您的 Aiera 代表了解更多信息。

认证

此包支持两种认证方法：

环境变量（默认）

export AIERA_API_KEY="your-aiera-api-key"

OAuth 集成

对于像 aiera-public-mcp 这样的 OAuth 系统：

from your_oauth_system import get_current_api_key
register_aiera_tools(mcp, get_current_api_key)

该包会自动处理 API 密钥解析，从 OAuth 提供商回退到环境变量。

测试

手动集成测试

由于已移除集成测试，使用手动测试脚本来验证 MCP 工具与实际 Aiera API 的一致性。

设置：

# 设置 API 密钥
export AIERA_API_KEY="your_api_key_here"

手动测试脚本：

# 测试所有可用工具
AIERA_API_KEY=your_api_key_here uv run python scripts/manual_test.py

# 测试特定工具类别
AIERA_API_KEY=your_api_key_here uv run python scripts/manual_test.py find_events
AIERA_API_KEY=your_api_key_here uv run python scripts/manual_test.py find_filings
AIERA_API_KEY=your_api_key_here uv run python scripts/manual_test.py create_transcrippet

手动测试脚本：

  • 直接调用 API 并将其与工具输出进行比较
  • 单独测试每个工具函数
  • 记录差异和问题以帮助调试
  • 提供对工具行为的全面验证

开发

版本管理

此包使用基于 Git 标签的自动语义版本控制：

创建发布：

# 1. 确保所有更改已提交并推送
git add . && git commit -m "准备发布"

# 2. 创建并推送版本标签
git tag v1.2.3  # 使用语义版本控制
git push origin v1.2.3

# 3. 创建 GitHub 发布（可选但推荐）
gh release create v1.2.3 --generate-notes

版本格式：

  • 发布版本：1.2.3（来自 Git 标签如 v1.2.3）
  • 开发版本：1.2.4.dev5+g1a2b3c4（根据提交自动生成）

包版本由 hatch-vcs 自动从 Git 历史中确定。

Pre-commit 钩子

此项目使用 pre-commit 进行代码质量控制：

# 安装钩子（一次性设置）
uv run pre-commit install

# 手动运行
uv run pre-commit run --all-files

链接

隐私政策

此 MCP 服务器通过与 Aiera 的 API 交互来获取相关财务数据。 所有数据请求均受 Aiera 的隐私政策和服务条款约束，并需要有效的账户。

  • Aiera 隐私政策：https://aiera.com/privacy-policy/
  • 数据处理：此服务器不存储或缓存任何用户数据。
  • API 密钥：您的 Aiera API 密钥仅用于向其 API 认证请求。