MCP Annual Report

Annual Report MCP Server

English | 中文

FastMCP服务器，设计用于通过承载令牌身份验证分析年度报告。此服务器提供访问和处理以markdown格式存储的年度报告数据的工具。

🚀 特性

• 年度报告分析：访问和分析以markdown文件存储的年度报告
• 承载令牌身份验证：通过可配置的身份验证实现API安全访问
• 分页内容访问：通过分页高效检索大型报告文档
• 健康检查端点：内置健康监测，确保服务可用性
• 现代Python堆栈：使用FastMCP、Starlette和其他现代Python库构建

📁 项目结构

mcp-annual-report/
├── main.py                    # Application entry point
├── pyproject.toml            # Project configuration and dependencies
├── middleware/               # Authentication middleware
│   └── auth.py              # Bearer token authentication
├── tools/                   # MCP tools and functionality
│   ├── __init__.py
│   ├── registry.py          # Tool registration manager
│   └── report.py            # Annual report analysis tools
├── data/                    # Annual report data storage
│   └── popmart-2023e/       # Sample: Pop Mart 2023 annual report
├── Makefile                 # Development commands
└── .pre-commit-config.yaml  # Code quality configuration

🛠️ 安装

先决条件

• Python 3.12或更高版本
• uv包管理器（推荐）或pip

设置

1. 克隆存储库:

   git clone https://github.com/jorben/mcp-annual-report.git
   cd mcp-annual-report

1. 安装依赖项 （使用紫外线）：

   make install

或者使用pip：

   pip install -e .

1. 配置环境:

创建一个 .env 使用您的身份验证令牌的文件：

   MCP_AUTH_TOKEN=your_bearer_token_here

🚀 用法

启动服务器

# using uv
uv run main.py

# or using python
python main.py

服务器将于启动 http://localhost:4200 默认情况下。

可用端点

• 健康检查: GET /health -无需身份验证
• MCP接口: /mcp -需要承载令牌身份验证

认证

所有API请求（健康检查除外）都需要承载令牌身份验证：

curl -H "Authorization: Bearer your_token_here" http://localhost:4200/mcp

可用工具

1.列出报告

获取所有可用年度报告的列表：

# Tool: list_reports
# Returns: List of report names

2.获取报告内容

从具有分页的特定年度报告中检索内容：

# Tool: get_report_content
# Parameters:
#   - report_name: Name of the report (from list_reports)
#   - offset: Starting page number (default: 0)
#   - limit: Number of pages to retrieve (default: 10, max: 500)
# Returns:
#   - content: Concatenated markdown content
#   - total_pages: Total number of pages in the report
#   - current_page_range: Range of pages returned

🧪 数据格式

年度报告作为单独的降价文件存储在 data/ 目录：

data/
└── company-year/
    ├── page_0001.md
    ├── page_0002.md
    └── ...

每个标记文件都包含从年度报告相应页面中提取的OCR文本内容。

🔧 发展

代码质量工具

# Format code
make format

# Lint code
make lint

# Fix linting issues
make fix

# Run pre-commit checks
make check

添加新报告

1. 在下创建新目录 data/ 与格式 company-year
2. 添加具有命名模式的markdown文件 page_XXXX.md
3. 确保文件按顺序编号，以便正确分页

📦 依赖项

核心依赖关系

• fastmcp：用于构建MCP服务器的FastMCP框架
• python dotenv：环境变量管理
• 小星星：用于web应用程序的ASGI框架
• 优维康：ASGI服务器实现

发展依赖性

• 预承诺：用于代码质量的Git挂钩框架
• 颈毛：快速Python linter和格式化程序

🔐 安全

• API访问的承载令牌认证
• 可配置令牌验证
• 公共端点的基于路径的排除
• 已验证请求的请求状态管理

📝 许可证

此项目根据LICENSE文件中指定的条款获得许可。

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行代码质量检查： make check
5. 提交拉取请求

📞 支持

有关问题和疑问，请使用GitHub问题跟踪器。