python-services/Retrieve/MCP_USAGE.md

# MCP 包装服务使用说明

## 概述

这个服务使用 `FastApiMCP` 将生物医学RAG服务包装成MCP（Model Context Protocol）工具，可以通过MCP客户端调用。

## 服务配置

在 `main.py` 中，服务被包装为：

```python
mcp = FastApiMCP(app, name="bio qa mcp", include_operations=["bio_qa_stream_chat"])
mcp.mount_sse()
```

## 可用的MCP操作

### 1. bio_qa_stream_chat

这是主要的生物医学问答操作，提供流式RAG问答服务。

## 调用方式

### 方式1: 通过MCP客户端调用

#### 1.1 配置MCP客户端

在你的MCP客户端配置中添加：

```json
{
  "bio_qa_mcp": {
    "url": "http://localhost:9487/sse",
    "transport": "sse"
  }
}
```

#### 1.2 调用示例

```python
# 使用MCP客户端调用
from langchain_mcp_adapters.client import MultiServerMCPClient

# 配置MCP服务器
mcp_config = {
    "bio_qa_mcp": {
        "url": "http://localhost:9487/sse",
        "transport": "sse"
    }
}

# 创建客户端
client = MultiServerMCPClient(mcp_config)

# 获取工具
tools = await client.get_tools()

# 使用工具
# 工具名称: bio_qa_stream_chat
# 参数: query (问题), lang (语言，可选，默认"en")
```

### 方式2: 直接HTTP调用

#### 2.1 直接调用API端点

```bash
# 调用生物医学问答接口
curl -X POST "http://localhost:9487/mcp/bio_qa" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=什么是糖尿病？&lang=zh"
```

#### 2.2 Python requests调用

```python
import requests

# 调用接口
response = requests.post(
    "http://localhost:9487/mcp/bio_qa",
    data={
        "query": "什么是糖尿病？",
        "lang": "zh"
    }
)

# 处理流式响应
for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))
```

## 参数说明

### bio_qa_stream_chat 操作

- **query** (必需): 问题内容
- **lang** (可选): 语言设置
  - `"zh"`: 中文
  - `"en"`: 英文（默认）

## 响应格式

服务返回流式响应（Server-Sent Events），格式为：

```
data: {"type": "result", "content": "回答内容..."}
data: {"type": "result", "content": "更多内容..."}
data: {"type": "done", "content": "完成"}
```

## 使用场景

### 1. 在LangChain中使用

```python
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_openai import ChatOpenAI

# 创建代理
llm = ChatOpenAI(model="gpt-4")
agent = create_openai_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools)

# 执行问答
result = await agent_executor.ainvoke({
    "input": "请帮我查询关于糖尿病的相关信息"
})
```

### 2. 在Streamlit应用中使用

```python
import streamlit as st
from langchain_mcp_adapters.client import MultiServerMCPClient

# 初始化MCP客户端
@st.cache_resource
def get_mcp_client():
    config = {
        "bio_qa_mcp": {
            "url": "http://localhost:9487/sse",
            "transport": "sse"
        }
    }
    return MultiServerMCPClient(config)

# 使用
client = get_mcp_client()
tools = await client.get_tools()
```

## 部署说明

### 1. 启动服务

```bash
cd python-services/Retrieve
python main.py
```

服务将在 `http://localhost:9487` 启动。

### 2. 环境变量配置

确保设置了必要的环境变量：

```bash
export ENVIRONMENT=prod
export QA_LLM_MAIN_API_KEY=your-api-key
export QA_LLM_MAIN_BASE_URL=your-api-url
# ... 其他配置
```

### 3. 网络访问

- 本地访问: `http://localhost:9487`
- 远程访问: `http://your-server-ip:9487`

## 故障排除

### 常见问题

1. **连接失败**: 检查服务是否启动，端口是否正确
2. **认证错误**: 检查API密钥配置
3. **流式响应中断**: 检查网络连接稳定性

### 日志查看

服务会记录详细的日志信息，包括：
- 请求处理时间
- 错误信息
- 操作状态

## 扩展功能

### 添加新的MCP操作

1. 在 `routers/mcp_sensor.py` 中添加新的路由
2. 在 `main.py` 的 `include_operations` 中添加操作名称
3. 重新启动服务

### 自定义响应格式

可以修改 `ChatService` 来定制响应格式，满足不同的MCP客户端需求。