NRC ADAMS AI

ADAMS MCP服务器

一种模型上下文协议（MCP）服务器，为LLM和AI代理提供工具，用于从NRC ADAMS（全机构文档访问和管理系统）存储库中的文档中搜索、下载和提取文本。

特性

• 混合搜索：使用可选的Google自定义搜索补充搜索NRC ADAMS数据库
• 文件下载：按登录号下载文件
• PDF文本提取：从PDF文件中提取文本内容以进行LLM处理
• 稳健的错误处理：全面的输入验证和错误消息
• 重试逻辑：API请求的内置重试机制

安装

先决条件

• Python 3.8或更高版本
• pip包管理器

设置

1. 克隆或下载此存储库

1. 安装依赖项：

pip install -r requirements.txt

1. （可选）为补充搜索配置Google自定义搜索API：

- 复制 .env.example 到 .env:

     cp .env.example .env

- 将您的Google API凭据添加到 .env:

     GOOGLE_API_KEY=your_api_key_here
     GOOGLE_CX=your_custom_search_engine_id_here

- 从以下位置获取凭据：https://developers.google.com/custom-search/v1/overview

部署选项

ADAMS MCP服务器可以以多种方式运行，以实现最大的便携性：

快速入门（直接Python）

python adams_mcp.py

使用启动脚本（建议用于开发）

./start_server.sh

Docker容器

docker build -t adams-mcp:latest .
docker run -d --name adams-mcp --env-file .env adams-mcp:latest

Docker Compose（推荐用于生产环境）

docker-compose up -d

📖 有关详细的部署说明，请参阅 部署.md

这包括：

• Claude桌面配置
• 生产部署检查表
• 故障排除指南
• 解释了所有部署方法

用法

启动MCP服务器

python adams_mcp.py

服务器将登录到 mcp_server.log 在当前目录中。

可用工具

1. search_adams

在NRC ADAMS数据库中搜索核监管文件。

参数：

• query （必填）：搜索关键字（最多500个字符）
• max_pages （可选）：要获取的ADAMS结果页数（1-10，默认值：1）
• top_n （可选）：返回的顶部结果数（1-50，默认值：5）
• use_google （可选）：是否补充谷歌搜索（默认：true）

退货：

• 词典与 results 包含文档元数据（标题、登录号、日期、类型等）的列表

例子：

{
  "query": "reactor safety analysis",
  "max_pages": 2,
  "top_n": 10,
  "use_google": true
}

2. download_adams

按登录号从NRC ADAMS下载文件。

参数：

• accession_number （必填）：NRC登录号（例如“ML12345A678”）
• directory （可选）：下载目录（默认：“./downloads”）

退货：

• 词典与 path 到下载的文件

例子：

{
  "accession_number": "ML12345A678",
  "directory": "./my_downloads"
}

3. summarize_pdf

从下载的PDF文件中提取文本内容。

参数：

• path （必填）：PDF的文件路径
• max_chars （可选）：要提取的最大字符数（100-10000，默认值：2000）

退货：

• 词典包含：

- text：提取的文本内容 - total_pages：PDF中的页数 - total_chars：PDF中的总字符数 - extracted_chars：提取的字符数

例子：

{
  "path": "./downloads/ML12345A678.pdf",
  "max_chars": 5000
}

直接使用Python API

这 adams_client_v3.py 模块也可以用作独立的Python库：

from adams_client_v3 import AdamsClient

# Initialize client
client = AdamsClient()

# Search for documents
results = client.search(
    query="emergency preparedness",
    max_pages=2
)

# Download a document
for doc in results[:3]:
    file_path = doc.download(directory="./my_pdfs")
    print(f"Downloaded: {file_path}")

# Save search results to JSON
client.save_results_to_json(results, "search_results.json")

高级搜索选项

# Search with filters
results = client.search(
    query="inspection report",
    filters={
        "DocumentType": "Inspection Report",
        "DocketNumber": "05000456"
    },
    max_pages=3
)

# Search recent documents
results = client.search(
    added_this_month=True,
    max_pages=1
)

# Search by accession number
results = client.search(
    filters={"AccessionNumber": "ML12345A678"}
)

配置

环境变量

• GOOGLE_API_KEY：Google自定义搜索API密钥（可选）
• GOOGLE_CX：谷歌自定义搜索引擎ID（可选）

日志记录

MCP服务器登录到 mcp_server.log。您可以在中调整日志记录级别 adams_mcp.py:

logging.basicConfig(
    filename="mcp_server.log",
    level=logging.INFO,  # Change to DEBUG for more verbose logging
    format="%(asctime)s [%(levelname)s] %(message)s"
)

错误处理

所有工具都以一致的格式返回错误信息：

{
  "error": "Description of what went wrong"
}

常见错误：

• 查询字符串为空或无效
• 参数值超出界限
• 网络/API故障
• 找不到文件错误
• 无效的登录号

项目结构

adams_mcp/
├── adams_mcp.py           # MCP server implementation
├── adams_client_v3.py     # ADAMS API client library
├── server.json            # MCP server configuration
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variable template
├── .gitignore            # Git ignore rules
└── README.md             # This file

发展

运行测试

（待实施的测试）

pytest tests/

贡献

1. 遵循PEP 8风格指南
2. 将文档字符串添加到所有函数和类中
3. 包括所有公共方法的输入验证
4. 更新新功能的测试

许可证

（在此处添加您的许可证）

关于NRC ADAMS

美国核管理委员会的全机构文件访问和管理系统（ADAMS）为公众提供了对核电站、燃料循环设施和放射性材料相关文件的访问。这包括检查报告、许可证申请、信函等。

• ADAMS公共网站：https://www.nrc.gov/reading-rm/adams.html
• ADAMS Web界面：https://adams.nrc.gov/wba/

支持

对于问题或疑问：

• 检查登录 mcp_server.log
• 查看工具返回的错误消息
• 确保所有依赖项都已正确安装
• 如果使用谷歌搜索，请验证是否设置了环境变量

版本历史记录

• 0.1.0 （当前）

- 初始版本 - 搜索、下载和PDF文本提取工具 - ADAMS+谷歌搜索 - 输入验证和错误处理