# Claude AI + MCP 工具调用模板项目

## 项目概述

这是一个基于 Claude AI 的 MCP (Model Context Protocol) 工具调用模板项目。项目实现了完整的 AI 对话界面，支持 Claude AI 通过后端服务器调用 MCP 工具，并将结果实时返回给前端。

### 关键配置要求

**服务端口必须是 `8080` 才能被外网访问！**

- **内网访问**: `http://localhost:8080`
- **外网访问**: `https://d8d-ai-vscode-8080-{workspace_id}-{item_id}-template-6-group.dev.d8d.fun/`

> ⚠️ **重要**: 如果服务运行在其他端口（如 5000），外网将无法访问！

---

## 项目结构

```
/mnt/code/223-240-template-6/
├── backend/          # Flask 后端服务
│   ├── app.py       # 主应用入口
│   └── requirements.txt
├── frontend/         # 前端静态文件
│   └── index.html   # 单页面应用
└── CLAUDE.md        # 本文档
```

---

## 开发指南

### 环境准备

```bash
# 安装 Python 依赖
cd backend
pip install -r requirements.txt
```

### 启动服务

**必须使用端口 8080 启动服务：**

```bash
cd backend
python app.py
```

服务默认将在 `http://localhost:8080` 启动。

### 验证服务

1. 检查服务是否启动：访问 `http://localhost:8080`
2. 检查外网访问：使用外网地址格式 `https://d8d-ai-vscode-8080-{workspace_id}-{item_id}-template-6-group.dev.d8d.fun/`

---

## 端口配置

### 当前配置

- **Flask 应用端口**: 8080
- **前端代理配置**: 8080

### 修改端口（不推荐）

如果必须修改端口，需要同时修改以下位置：

1. `backend/app.py` 中的 `port` 参数
2. `frontend/index.html` 中的 API 请求地址

**注意**: 修改为非 8080 端口后，外网将无法访问服务！

---

## 故障排除

### 问题 1: 外网无法访问

**症状**: 使用外网地址访问时显示连接失败

**原因**: 服务未运行在 8080 端口

**解决方案**:
```bash
# 检查服务端口
netstat -tuln | grep 8080

# 确保后端以端口 8080 启动
cd backend
python app.py
```

### 问题 2: CORS 错误

**症状**: 前端请求被 CORS 策略阻止

**解决方案**: 确认 `backend/app.py` 中已正确配置 CORS：

```python
from flask_cors import CORS
CORS(app, resources={r"/*": {"origins": "*"}})
```

### 问题 3: MCP 工具调用失败

**症状**: AI 响应显示工具调用错误

**检查项目**:
- 后端日志是否有错误信息
- MCP 配置是否正确
- Claude API 密钥是否有效

### 问题 4: 流式输出中断

**症状**: 响应中途停止或不完整

**解决方案**:
- 检查网络连接稳定性
- 确认后端没有超时限制
- 检查前端 EventSource 连接状态

---

## 技术栈

- **后端**: Flask + Python 3.x
- **前端**: 原生 HTML/CSS/JavaScript
- **AI**: Claude API (Anthropic)
- **协议**: MCP (Model Context Protocol)

---

## 开发者注意事项

1. **端口固定**: 服务端口固定为 8080，不可随意更改
2. **外网地址格式**: `https://d8d-ai-vscode-8080-{workspace_id}-{item_id}-template-6-group.dev.d8d.fun/`
3. **流式响应**: 使用 Server-Sent Events (SSE) 实现流式输出
4. **CORS 配置**: 后端需要正确配置 CORS 以支持前端跨域请求

---

## 更新日志

- 2026-03-16: 添加端口配置文档和故障排除指南
- 2026-03-16: 实现流式输出解决 504 超时问题
- 2026-03-16: 前端 UI 优化 - 工具调用过程可视化
- 2026-03-16: 实现完整的 MCP 工具调用管道