# MCP Server 配置完整指南

## 📌 重要说明

根据安装方式不同，Claude Code CLI 的配置也不同。请根据你的实际情况选择对应的配置。

---

## 方式 1: 开发环境（推荐用于开发和调试）

### 适用场景
- 你在项目目录下开发
- 需要实时修改代码并测试
- 使用虚拟环境

### 配置文件
使用 `mcp_server_config.json`

### Claude Code CLI 配置

```json
{
  "mcpServers": {
    "questions-mcp-server": {
      "command": "H:\\project\\questions_mcp_server\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "src.main"
      ],
      "cwd": "H:\\project\\questions_mcp_server",
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      },
      "timeout": 120000
    }
  }
}
```

**注意**：
- ✅ 需要先创建虚拟环境并安装依赖
- ✅ `command` 路径必须是你实际的项目路径
- ✅ 环境变量可以放在 `.env` 文件中

---

## 方式 2: 通过 pip/uv 安装（推荐用于生产环境）

### 安装步骤

#### 选项 A: 使用 uv（推荐）

```bash
# 安装包
uv pip install dist/questions_mcp_server-1.0.8-py3-none-any.whl

# 或从 PyPI 安装（如果已发布）
uv pip install questions-mcp-server
```

#### 选项 B: 使用 pip

```bash
pip install dist/questions_mcp_server-1.0.8-py3-none-any.whl
```

### Claude Code CLI 配置（方式 2A - 推荐）

使用 `mcp_server_config_installed.json`

```json
{
  "mcpServers": {
    "questions-mcp-server": {
      "command": "questions-mcp-server",
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "EMBEDDING_API_KEY": "sk-s66up3d6Pei7CzIZH27zlPF6YJYhaMhU2p5NICmHUKR00aE0"
      },
      "timeout": 120000
    }
  }
}
```

**优点**：
- ✅ 简洁，直接使用命令名
- ✅ 跨平台兼容
- ✅ 自动使用正确的 Python 环境

### Claude Code CLI 配置（方式 2B - 替代方案）

使用 `mcp_server_config_pip.json`

```json
{
  "mcpServers": {
    "questions-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "questions_mcp_server"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "EMBEDDING_API_KEY": "sk-s66up3d6Pei7CzIZH27zlPF6YJYhaMhU2p5NICmHUKR00aE0"
      },
      "timeout": 120000
    }
  }
}
```

**注意**：
- ⚠️ 需要确保 `python` 命令指向正确的 Python 环境
- ⚠️ 包名是 `questions_mcp_server`（下划线），不是 `questions-mcp-server`（连字符）

---

## 方式 3: 使用 uvx（最简单，推荐）

### Claude Code CLI 配置

```json
{
  "mcpServers": {
    "questions-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "H:\\project\\questions_mcp_server\\dist\\questions_mcp_server-1.0.8-py3-none-any.whl",
        "questions-mcp-server"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "EMBEDDING_API_KEY": "sk-s66up3d6Pei7CzIZH27zlPF6YJYhaMhU2p5NICmHUKR00aE0"
      },
      "timeout": 120000
    }
  }
}
```

**优点**：
- ✅ 无需手动安装
- ✅ uvx 会自动创建隔离环境
- ✅ 每次都使用最新的包

**或者从 PyPI 安装（如果已发布）**：

```json
{
  "mcpServers": {
    "questions-mcp-server": {
      "command": "uvx",
      "args": [
        "questions-mcp-server"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "EMBEDDING_API_KEY": "sk-s66up3d6Pei7CzIZH27zlPF6YJYhaMhU2p5NICmHUKR00aE0"
      },
      "timeout": 120000
    }
  }
}
```

---

## 配置参数说明

### timeout（超时时间）

```json
"timeout": 120000
```

- **单位**: 毫秒（ms）
- **推荐值**: 120000（2分钟）
- **原因**: 
  - 首次启动需要下载 ChromaDB 等依赖（约 30-60 秒）
  - 数据库初始化需要时间
  - 默认 30 秒超时不够

### 环境变量

```json
"env": {
  "PYTHONIOENCODING": "utf-8",
  "PYTHONUNBUFFERED": "1",
  "EMBEDDING_API_KEY": "your-api-key"
}
```

- **PYTHONIOENCODING**: 确保 UTF-8 编码（Windows 必需）
- **PYTHONUNBUFFERED**: 禁用缓冲，确保日志实时输出
- **EMBEDDING_API_KEY**: Embedding API 密钥（必需）

---

## 配置文件位置

### Windows

```
C:\Users\你的用户名\AppData\Roaming\Claude\config\claude_desktop_config.json
```

或使用环境变量：

```
%APPDATA%\Claude\config\claude_desktop_config.json
```

### macOS

```
~/Library/Application Support/Claude/config/claude_desktop_config.json
```

### Linux

```
~/.config/Claude/config/claude_desktop_config.json
```

---

## 验证配置

### 1. 测试命令行入口点

安装后测试：

```bash
# 方式 1: 直接运行
questions-mcp-server

# 方式 2: 使用 python -m
python -m questions_mcp_server

# 方式 3: 使用 uvx
uvx questions-mcp-server
```

应该看到服务器启动（可能因为缺少 API 密钥而失败，但入口点工作正常）

### 2. 检查安装位置

```bash
# Windows
where.exe questions-mcp-server

# Linux/macOS
which questions-mcp-server
```

### 3. 查看日志

服务器启动后，检查日志文件：

```
./logs/app.log
./logs/error.log
```

---

## 常见问题

### Q1: 配置后仍然连接超时？

**检查清单**：
- ✅ 是否设置了 `timeout: 120000`
- ✅ Python 路径是否正确
- ✅ 环境变量是否设置（特别是 EMBEDDING_API_KEY）
- ✅ 是否重启了 Claude Code CLI

### Q2: 找不到 questions-mcp-server 命令？

**解决方案**：
1. 确认包已正确安装：`pip list | grep questions`
2. 检查 Python Scripts 目录是否在 PATH 中
3. 尝试使用完整路径或 `python -m` 方式

### Q3: 打包后配置不生效？

**原因**：
- 开发环境的配置使用了绝对路径
- 需要使用安装后的配置

**解决**：
- 使用 `mcp_server_config_installed.json` 或 `mcp_server_config_pip.json`
- 不要使用开发环境的 `mcp_server_config.json`

### Q4: 如何在不同环境间切换？

**建议**：
- 开发时使用方式 1（开发环境）
- 测试时使用方式 2（pip 安装）
- 生产时使用方式 3（uvx）

---

## 推荐配置总结

| 场景 | 推荐方式 | 配置文件 |
|------|---------|----------|
| 开发调试 | 方式 1 | `mcp_server_config.json` |
| 本地测试 | 方式 2A | `mcp_server_config_installed.json` |
| 生产部署 | 方式 3 | uvx 配置 |
| 快速验证 | 方式 3 | uvx 配置 |

---

## 版本历史

- **v1.0.8**: 添加 timeout 配置，修复 STDIO 通信问题
- **v1.0.7**: 初始 MCP 支持

---

**参考文档**：
- `CLAUDE_CODE_MCP_CONFIG.md` - 详细配置指南
- `CHANGELOG_v1.0.8.md` - 版本更新日志
- `配置更新说明.txt` - 超时配置说明
