Aiera MCP

\[！重要\] ：test_tube：这个项目是实验性的，可能会发生重大变化。

Aiera MCP工具

A. 模型上下文协议（MCP） 提供访问权限的包 艾埃拉 财务数据。此存储库包含一个独立的MCP服务器和一个可重用的Python包。

概述

该软件包将Aiera API端点作为MCP工具公开，提供对全面财务数据的访问，包括：

• 事件：日历事件、成绩单和元数据
• 公司信息：符号、摘要、部门和观察名单
• 公司文件：新闻稿、幻灯片演示、披露等。
• 行情走势：归档数据和元数据
• 财务数据：损益表、资产负债表和现金流量表
• 第三桥：专家洞察活动
• 搜索：在成绩单、SEC备案内容、公司文件等中进行语义搜索。

安装

选项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  # Install with dev dependencies

1. 设置预提交挂钩 （建议开发）：

uv run pre-commit install

1. 设置环境变量:

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

或者，创建一个 .env 项目根目录中的文件（请参见 配置 下节）。

1. 运行独立服务器:

uv run entrypoint.py

配置

该软件包使用Pydantic BaseSettings进行配置管理。所有设置都可以通过环境变量或 .env 文件。

可用设置

使用.env文件

创建一个 .env 项目根目录中的文件（使用 .env.example 作为模板）：

# Copy the example file
cp .env.example .env

# Edit with your values
AIERA_API_KEY=your-api-key-here
AIERA_BASE_URL=https://graphql.aiera.com/api  # Optional: override default
DEFAULT_PAGE_SIZE=100  # Optional: override default

程序化配置

以编程方式访问和修改设置：

from aiera_mcp import get_settings, reload_settings

# Get current settings
settings = get_settings()
logger.debug(f"Base URL: {settings.aiera_base_url}")
logger.debug(f"Page Size: {settings.default_page_size}")

# Reload settings from environment (useful for testing)
reload_settings()

自定义设置实例

对于高级用例，您可以创建自定义设置实例：

from aiera_mcp.config import AieraSettings

# Create settings with custom values
custom_settings = AieraSettings(
    aiera_base_url="https://custom.aiera.com/api",
    default_page_size=100,
    http_timeout=60.0
)

用法

作为一个包裹

from aiera_mcp import register_aiera_tools, set_api_key_provider

# Basic usage with AIERA_API_KEY environment variable
# Returns the tool registry dictionary
tools = register_aiera_tools()

# For OAuth systems (e.g., aiera-public-mcp)
from your_auth_system import get_current_api_key
tools = register_aiera_tools(api_key_provider=get_current_api_key)

# Or configure API key provider globally
set_api_key_provider(get_current_api_key)

# Import individual tool functions directly
from aiera_mcp import find_events, make_aiera_request, correct_bloomberg_ticker

包装内容

工具

• 事件: find_events, find_conferences, get_event, get_upcoming_events
• 备案: find_filings, get_filing
• 公司文件: find_company_docs, get_company_doc, get_company_doc_categories, get_company_doc_keywords
• 第三桥: find_third_bridge_events, get_third_bridge_event
• 搜索: search_transcripts, search_filings
• 股票: find_equities, get_equity_summaries, get_sectors_and_subsectors, get_financials
• 索引和观察名单: get_available_indexes, get_index_constituents, get_available_watchlists, get_watchlist_constituents

公用事业

• API函数: make_aiera_request
• 注册: register_aiera_tools -配置API密钥提供程序并获取工具注册表
• 认证: set_api_key_provider, get_api_key, clear_api_key_provider -OAuth兼容性功能

配置

• get_settings, reload_settings, AieraSettings -配置管理功能（参见 配置)
• DEFAULT_PAGE_SIZE, DEFAULT_MAX_PAGE_SIZE, AIERA_BASE_URL -常量（从设置中加载，可以通过环境变量覆盖）
• AVAILABLE_TOOLS -所有24个可用工具名称的列表

先决条件

• Python 3.11或更高版本
• 安爱拉API钥匙
• 星光紫外线 （用于发展）

Claude桌面配置

选项1：使用独立服务器

1. 跟随 Claude Desktop MCP安装说明 并找到您的配置文件。
2. 使用以下配置：

- 替换 ` 使用您的实际Aiera API密钥 - 替换 ` 使用您的主目录路径

claude_desktop_config.json (Standalone Server)

{
    "mcpServers": {
        "Aiera MCP": {
           "command": "uv",
           "args": [
               "run",
               "--with",
               "git+https://github.com/aiera-inc/aiera-mcp.git",
               "aiera-mcp"
            ],
            "env": {
               "AIERA_API_KEY": ""
            }
        }
    }
}

选项2：使用本地安装

claude_desktop_config.json (Local Installation)

{
    "mcpServers": {
        "Aiera MCP": {
           "command": "/.local/bin/uv",
           "args": [
               "run",
               "--directory",
               "/aiera-mcp",
               "python",
               "entrypoint.py"
            ],
            "env": {
               "AIERA_API_KEY": ""
            }
        }
    }
}

用法示例

集成后，您可以提示Claude访问Aiera数据：

Get the latest earnings call transcript for Apple Inc. and summarize key points

主要特点

• API全面覆盖：将大多数Aiera API端点实现为MCP工具
• 柔性集成：用作独立服务器或作为Python包集成
• 兼容OAuth：与OAuth身份验证系统无缝集成（例如aiera公共mcp）
• 多重身份验证：支持环境变量和OAuth提供程序
• 数据验证：用于更正股票代码、关键字和其他参数的内置实用程序
• 类型安全：基于Pydantic的参数验证，具有自动模式生成功能
• 注册模式：集中的工具元数据和配置管理
• 开发就绪：具有测试和linting工具的完整开发环境

某些端点可能需要特殊权限。有关更多详细信息，请联系您的Aiera代表。

认证

此软件包支持两种身份验证方法：

环境变量（默认）

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

OAuth集成

对于像aiera公共mcp这样的OAuth系统：

from aiera_mcp import register_aiera_tools
from your_oauth_system import get_current_api_key

register_aiera_tools(api_key_provider=get_current_api_key)

包自动处理API密钥解析，并从OAuth提供程序回退到环境变量。

测试

手动集成测试

由于集成测试已被删除，请使用手动测试脚本根据真实的Aiera API验证MCP工具。

设置：

# Set up API key
export AIERA_API_KEY="your_api_key_here"

手动测试脚本：

# Test all available tools
AIERA_API_KEY=your_api_key_here uv run python scripts/manual_test.py

# Test specific tool categories
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

手动测试脚本：

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

发展

版本管理

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

创建发布：

# 1. Ensure all changes are committed and pushed
git add . && git commit -m "Prepare release"

# 2. Create and push a version tag
git tag v1.2.3  # Use semantic versioning
git push origin v1.2.3

# 3. Create GitHub release (optional but recommended)
gh release create v1.2.3 --generate-notes

版本格式：

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

使用以下命令从Git历史记录中自动确定包版本 hatch-vcs.

预提交钩子

此项目使用预提交来保证代码质量：

# Install hooks (one time setup)
uv run pre-commit install

# Run manually
uv run pre-commit run --all-files

链接

• Aiera REST文档
• 模型上下文协议
• MCP Python SDK

隐私政策

该MCP服务器与Aiera的API交互以获取相关的财务数据。 所有数据请求均受Aiera隐私政策和服务条款的约束，并需要一个活动帐户。

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