使用说明

项目简介

本项目是一个基于Model Context Protocol (MCP) 构建的服务器，旨在为 Claude For Desktop 等 LLM 应用提供访问和分析瑞典公司年度报告及组织数据的能力。它通过 Bolagsverket 的 API 获取官方数据，并利用 LlamaIndex 和 Tavily API 提供文档索引和公司信息查询功能。此服务器主要用于演示 MCP 服务器在实际应用中的潜力，非生产环境。

主要功能点

年度报告问答：允许用户向 Claude 提问关于特定公司年度报告的问题，服务器将检索并分析报告内容，返回答案。
组织数据查询：提供工具从 Bolagsverket 获取公司的基本组织信息，如名称、地址等。
公司名称查组织号：通过公司名称，利用 Tavily API 查询对应的组织号码。
数据本地存储与索引：下载的年度报告会被解析并存储在本地，并建立索引以加速后续查询。
API 密钥管理：使用 '.env' 文件管理 Bolagsverket, Tavily 和 OpenAI (LlamaIndex) 的 API 密钥，方便配置。

安装步骤

克隆仓库:

git clone https://github.com/GunnarPomiloAI/annual_report_mcp_server.git
cd annual_report_mcp_server

安装依赖: 确保已安装 Python 和 pip，然后运行：

pip install -r requirements.txt

配置 API 密钥:

根据以下模板，填入您申请的 API 密钥：

OPENAI_API_KEY=您的OpenAI API密钥 (用于LlamaIndex向量化，即使您不直接使用OpenAI，LlamaIndex默认依赖)
BV_CLIENT_ID=您的Bolagsverket Client ID
BV_CLIENT_SECRET=您的Bolagsverket Client Secret
TAVILY_API_KEY=您的Tavily API密钥

注意: Bolagsverket API 访问需要向 Bolagsverket 申请。Tavily API 密钥可以在 Tavily 官网免费获取（用于研究和测试目的）。

安装到 Claude For Desktop (MCP客户端):
- 启动 Claude For Desktop 应用程序。
- 在 Claude 的 MCP 服务器管理界面，选择 "安装服务器"。
- 在弹出的对话框中，输入以下命令并安装：
```
annual-report-mcp-server.py
```
  如果安装过程中遇到依赖或路径问题，请参考下一步的 服务器配置 手动调整 'claude_desktop_config.json' 文件。

服务器配置 (Claude For Desktop)

如果自动安装遇到问题，您可能需要手动编辑 Claude 的配置文件 'claude_desktop_config.json'。该文件通常在 Claude 应用的配置目录下，首次安装 MCP 服务器时会自动创建。

找到 'claude_desktop_config.json' 文件，并在 'mcpServers' 字段下添加或修改 'annual_report_mcp_server' 的配置。配置信息应如下所示（请根据您的实际绝对路径进行修改）：

{
  "mcpServers": {
    "annual_report_mcp_server": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "source /ABSOLUTE/PATH/TO/annual_report_mcp_server/.venv/bin/activate && /ABSOLUTE/PATH/TO/annual_report_mcp_server/.local/bin/uv run --with mcp[cli] mcp run /ABSOLUTE/PATH/TO/annual_report_mcp_server/annual_report_mcp_server.py"
      ]
    }
  }
}

配置参数说明:

'"command": "/bin/bash"': 指定运行命令的 shell，通常为 bash。
'"args"': 命令参数列表，这里使用 '-c' 执行一段复合命令：
- '"source /ABSOLUTE/PATH/TO/annual_report_mcp_server/.venv/bin/activate"': 激活项目虚拟环境 (如果使用虚拟环境)。请将 '/ABSOLUTE/PATH/TO/annual_report_mcp_server' 替换为您的 'annual_report_mcp_server' 仓库的绝对路径。 如果未使用虚拟环境，可以移除此部分。
- '" && "'：连接命令，确保先激活虚拟环境再运行后续命令。
- '"/ABSOLUTE/PATH/TO/annual_report_mcp_server/.local/bin/uv run --with mcp[cli] mcp run /ABSOLUTE/PATH/TO/annual_report_mcp_server/annual_report_mcp_server.py"': 使用 'uv run' 运行 MCP 服务器脚本。'uv' 是一个更快的 pip 和 virtualenv 替代品，如果系统中没有 'uv'，可能需要替换为 'python' 或 'python3'，并调整相应的命令。 '--with mcp[cli]' 确保包含 'mcp' 命令行工具，'mcp run' 是 'mcp' 库提供的运行服务器的命令，最后指定服务器脚本 'annual_report_mcp_server.py' 的绝对路径。同样，请务必将路径替换为您的实际路径。

重要提示: '/ABSOLUTE/PATH/TO/annual_report_mcp_server' 需要替换成您 'annual_report_mcp_server' 仓库在您电脑上的绝对路径。您可以通过 'pwd' 命令在终端中查看当前目录的绝对路径。

基本使用方法

确保 Claude For Desktop 客户端已安装并运行，且已成功安装并配置 'annual_report_mcp_server'。
在 Claude 中，您可以像正常对话一样提问。
要使用年度报告分析功能，您可以向 Claude 提出类似以下的问题：
- "请分析公司 'XX公司' (组织号码: 'XXXXXX-XXXX') 2022年的年度报告，并总结其主要财务表现。"
- "根据 'YY公司' (组织号码: 'YYYYYY-YYYY') 的年度报告，他们的研发投入是多少？"
要查询组织数据，您可以提问：
- "请获取 'ZZ公司' (组织号码: 'ZZZZZZ-ZZZZ') 的组织信息。"
要通过公司名称查找组织号码，您可以提问：
- "请查找 'AA公司' 的组织号码。"

注意: 首次查询某个公司的年度报告时，服务器可能需要一些时间下载和处理数据。后续查询同一年度报告将会更快，因为数据和索引已经本地缓存。

关键词