Using Pia MCP Server

PIA MCP示例

此目录包含演示如何将PIA MCP服务器与LangChain和各种LLM提供程序集成的示例脚本。

您可以了解更多关于PIA的MCP服务器的信息 这里

LangChain MCP集成示例

此示例显示了如何连接到PIA MCP服务器，发现可用工具，并将其与由OpenAI、Azure OpenAI、Claude或Hugging Face模型支持的AI代理一起使用。

特性

• 远程MCP连接：使用官方的HTTP/SSE连接到PIA MCP服务器 langchain-mcp-adapters
• 动态工具发现：自动发现并加载所有可用的MCP工具
• 多种LLM支持：适用于OpenAI、Azure OpenAI、Claude（Anthropic）和Hugging Face模型
• LangChain集成：使用现代LangChain 1.0 API将MCP工具与LangChain代理无缝集成
• 查询示例：包括常见用例的工作示例

此目录中的文件

• langchain_mcp_example.py -完整的工作示例脚本
• requirements.txt -示例中的Python依赖关系
• env.example -环境变量模板（复制到 .env)
• README.md -此文件

实施说明：此示例使用官方 langchain-mcp-adapters 用于连接到远程HTTP/SSE MCP服务器的包。该实现使用：

• MultiServerMCPClient 随着 streamable_http 远程MCP服务器的传输
• create_agent 从LangChain 1.0开始创建现代代理
• 自动工具发现和转换为LangChain工具
• 适用于任何调用LLM的工具（OpenAI、Azure、Claude）

快速开始

1.设置虚拟环境（推荐）

使用虚拟环境可以隔离依赖关系：

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

# Your prompt should now show (venv) indicating the venv is active

2.安装依赖项

# Make sure your virtual environment is activated
pip install -r requirements.txt

3.配置环境变量

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

# Edit .env with your actual API keys
# Use your preferred text editor:
nano .env
# or
vim .env
# or
code .env  # VS Code

所需变量：

• PIA_API_KEY -从 https://mcp.programintegrity.org/get-api-key。如果您没有PIA社区帐户，请按照链接创建一个
• LLM_PROVIDER -选择： openai, azure, claude，或 huggingface
• 提供程序特定的API密钥（有关详细信息，请参见env.example）

您只需要配置一个LLM提供程序，但可以随意设置多个提供程序进行比较。

4.运行示例

# Make sure your virtual environment is activated
# Run with default example queries:
python langchain_mcp_example.py

# Or run with your own query:
python langchain_mcp_example.py "What is ambulance fraud?"

# Another example:
python langchain_mcp_example.py "Find recent cybersecurity reports from OIGs"

## LLM Provider Setup

Choose one of the following providers and configure the corresponding environment variables in your `.env` file:

### OpenAI (Default)

LLM_PROVIDER=openai OPENAI_API_KEY=sk-...your-openai-api-key... OPENAI_MODEL=gpt-4 # optional, default: gpt-4

**获取API密钥：** https://platform.openai.com/api-keys

### Azure OpenAI

LLM_PROVIDER=azure AZURE_OPENAI_API_KEY=your-azure-api-key AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/ AZURE_OPENAI_DEPLOYMENT=your-deployment-name AZURE_OPENAI_API_VERSION=2024-02-15-preview # optional

**设置要求：**

1. Azure订阅
1. 在Azure门户中创建的Azure OpenAI资源
1. 模型部署（GPT-5、GPT-5-mini等）
1. 从以下位置获取凭据：https://portal.azure.com

### 克劳德（人类学）

LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-...your-anthropic-api-key... CLAUDE_MODEL=claude-3-5-sonnet-20241022 # optional

**获取API密钥：** https://console.anthropic.com/

### 拥抱脸

LLM_PROVIDER=huggingface

Use either HF_TOKEN (preferred) or HUGGINGFACE_API_KEY

HF_TOKEN=hf_...your-huggingface-token...

Default model: Qwen/Qwen2.5-72B-Instruct

HUGGINGFACE_MODEL=Qwen/Qwen2.5-72B-Instruct

**获取API密钥：** https://huggingface.co/settings/tokens

**重要提示：** 您选择的HuggingFace模型 **必须支持函数调用/工具使用** 让代理人正常工作。支持函数调用的推荐型号：

- `Qwen/Qwen2.5-72B-Instruct` （默认，性能优异）
- `Qwen/Qwen2.5-7B-Instruct` （更小、更快）
- `mistralai/Mixtral-8x7B-Instruct-v0.1`

注意：许多Llama模型不支持通过HuggingFace路由器API进行函数调用。

## 示例的作用

1. **连接到PIA MCP服务器** -建立HTTP连接到https://mcp.programintegrity.org
1. **初始化MCP会话** -执行MCP协议握手
1. **发现工具** -检索所有可用的搜索工具（GAO、OIG、CRS、DOJ、Congress.gov、行政命令）
1. **转换为LangChain工具** -将每个MCP工具包装为LangChain `StructuredTool`
1. **创建AI代理** -使用您选择的LLM设置LangChain代理
1. **执行查询** -Agent会自动选择并调用适当的工具来回答问题

## 可用的MCP工具

脚本会自动从PIA MCP服务器发现这些工具：

**通用搜索工具：**

- `pia_search_content` -搜索文档内容和建议
- `pia_search_content_facets` -获取可用的筛选值
- `pia_search_titles` -仅搜索文档标题

**数据源特定工具：**

- `pia_search_content_gao` -GAO报告和建议
- `pia_search_content_oig` -Oversight.gov（监察长报告）
- `pia_search_content_crs` -国会研究服务报告
- `pia_search_content_doj` -司法部文件
- `pia_search_content_congress` -Congress.gov立法
- `pia_search_content_executive_orders` -《联邦公报》行政命令

**实用工具：**

- `referenced_agencies` -获取数据库中的机构列表

## 查询示例

Search for fraud-related recommendations

python langchain_mcp_example.py "Find open recommendations about fraud from GAO"

Search executive orders

python langchain_mcp_example.py "What executive orders address artificial intelligence?"

Search recent reports

python langchain_mcp_example.py "Show me the latest cybersecurity reports from OIG"

Search across multiple sources

python langchain_mcp_example.py "Find recommendations about improper payments"

Get specific information

python langchain_mcp_example.py "What agencies are most mentioned in DOJ documents?"

## 故障排除

### 虚拟环境问题

**问题：** `python3: command not found`

Try using 'python' instead of 'python3':

python -m venv venv

**问题：** 虚拟环境未激活

Make sure you're in the examples directory

pwd # Should show: .../pia-mcp/examples

Try activating again:

source venv/bin/activate

Check if it worked (you should see (venv) in your prompt):

which python # Should show: .../examples/venv/bin/python

### 依赖安装问题

**问题：** `pip: command not found`

Make sure your virtual environment is activated

Then try:

python -m pip install -r requirements.txt

**问题：** 权限被拒绝错误

This shouldn't happen with venv, but if it does:

Make sure your virtual environment is activated (you should see (venv) in prompt)

If still having issues, recreate the venv:

rm -rf venv python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

### API密钥错误

**问题：** `PIA_API_KEY environment variable is required`

Make sure you created and edited the .env file:

ls -la .env # File should exist cat .env # Should show your configuration

Make sure you're running from the examples directory:

pwd # Should show: .../pia-mcp/examples

**问题：** `OPENAI_API_KEY environment variable is required`

- 验证您为所选的设置了正确的API密钥 `LLM_PROVIDER` 在 `.env`
- 对于Azure，您需要 `AZURE_OPENAI_API_KEY`，不 `OPENAI_API_KEY`
- 对于克劳德，你需要 `ANTHROPIC_API_KEY`

### 连接问题

**问题：** `Connection timeout` 或 `Connection refused`

Check your internet connection

curl https://mcp.programintegrity.org/health

Verify the PIA_MCP_URL in your .env file:

cat .env | grep PIA_MCP_URL

Should show: PIA_MCP_URL=https://mcp.programintegrity.org

### 导入错误

**问题：** `ModuleNotFoundError: No module named 'langchain'`

Make sure your virtual environment is activated

source venv/bin/activate

Reinstall dependencies

pip install -r requirements.txt

Verify installation

pip list | grep langchain

## 高级用法

### 使用不同的模型

编辑您的 `.env` 文件以使用不同的模型：

OpenAI - use GPT-4 Turbo

OPENAI_MODEL=gpt-4-turbo

Claude - use Claude Opus

CLAUDE_MODEL=claude-3-opus-20240229

Hugging Face - use Mistral

HUGGINGFACE_MODEL=mistralai/Mistral-7B-Instruct-v0.2

### 在提供商之间切换

您可以通过在中更改一行来快速切换提供商 `.env`:

To use OpenAI:

LLM_PROVIDER=openai

To use Azure:

LLM_PROVIDER=azure

To use Claude:

LLM_PROVIDER=claude

然后再次运行脚本-不需要更改代码！

### 自定义代理

编辑 `langchain_mcp_example.py` 自定义：

- 代理系统提示（第342行）
- 温度和其他LLM参数（第253-306行）
- 工具选择和过滤（第233-238行）

## 获取API密钥

### PIA MCP服务器（必需）

注册地址：https://mcp.programintegrity.org/register

### LLM提供者（选择一个）

- **开放人工智能**: https://platform.openai.com/api-keys
- **Azure OpenAI**: https://portal.azure.com（需要Azure订阅）
- **克劳德/人类学**: https://console.anthropic.com/
- **拥抱脸**: https://huggingface.co/settings/tokens

## 完整设置示例（逐步）

以下是从头开始的完整演练：

1. Navigate to examples directory

cd /path/to/pia-mcp/examples

2. Create and activate virtual environment

python3 -m venv venv source venv/bin/activate # You should see (venv) in your prompt

3. Install dependencies

pip install -r requirements.txt

4. Copy environment template

cp env.example .env

5. Edit .env file (use your preferred editor)

nano .env

Add your PIA_API_KEY

Choose your LLM_PROVIDER

Add the corresponding API key

6. Save and close the editor (Ctrl+X, then Y, then Enter for nano)

7. Test the setup

python langchain_mcp_example.py "Test query: find fraud reports"

8. When done, deactivate virtual environment

deactivate

## 支持

- **主要文件**：参见 [../README.md](../README.md) 用于PIA MCP服务器文档
- **问题**：在GitHub存储库上打开一个问题
- **问题**：检查上面的故障排除部分