内容
# MCP-Reflect
[](https://pypi.org/project/mcp-reflect/)
[](https://pypi.org/project/mcp-reflect/)
[](https://github.com/JonesH/mcp-reflect/actions/workflows/test.yml)
[](https://opensource.org/licenses/MIT)
**MCP-Reflect** 是一款用于增强模型自我反省能力的模型控制协议（MCP）工具。它通过结构化的评估和反馈帮助改善人工智能的响应。
## 特性
- ✅ **定性响应改进** - 将模型输出转化为更准确、清晰和完整的版本
- ✅ **结构化自我评估** - 在多个质量维度上评估响应
- ✅ **具体的改进建议** - 为每个维度提供可行的反馈
- ✅ **多种处理模式** - 独立、迭代或比较地处理响应
- ✅ **MCP兼容** - 与Claude和其他MCP兼容的助手无缝集成
## 评估维度
MCP-Reflect 在以下关键维度评估模型响应：
- **准确性**：事实正确性和无错误
- **清晰度**：响应结构良好且易于理解
- **完整性**：是否涵盖了主题的所有相关方面
- **相关性**：响应直接回答查询的程度
- **连贯性**：推理的逻辑流程和一致性
- **简洁性**：适当的长度，无不必要的重复
- **有用性**：响应的实用价值和可行动性
- **推理能力**：逻辑、证据和论证的质量
- **安全性**：对敏感话题的负责任处理
## 安装
### 使用pip
```bash
# 从PyPI安装（稳定版本）
pip install mcp-reflect
# 安装所有依赖项（包括可选依赖）
pip install "mcp-reflect[core]"
# 从TestPyPI安装最新开发版本
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "mcp-reflect[core]"
```
### 使用Poetry
```bash
# 从PyPI安装（稳定版本）
poetry add mcp-reflect
# 从TestPyPI安装（开发版本）
poetry source add --priority=supplemental test-pypi https://test.pypi.org/simple/
poetry add --source test-pypi mcp-reflect
```
### 使用UV
UV是一个用Rust编写的快速Python包安装程序。要使用UV安装：
```bash
# 安装UV（如果尚未安装）
curl -sSf https://install.ultraviolet.rs | sh
# 全局安装包作为工具
uv tool install mcp-reflect
# 或使用pip安装包
uv pip install mcp-reflect
# 运行包而无需安装
uvx mcp-reflect
```
## 使用
### 启动服务器
直接从命令行运行MCP服务器：
```bash
mcp-reflect
```
或以编程方式：
```python
from mcp_reflect.server import run_server
# 在自定义主机和端口上启动
run_server(host="127.0.0.1", port=9000)
```
### 使用HTTP服务器运行
MCP-Reflect可以提供一个HTTP服务器用于API访问：
```bash
# 安装支持HTTP服务器
pip install "mcp-reflect[all]"
# 使用UV安装（支持HTTP服务器）
uv tool install "mcp-reflect[all]"
# 运行HTTP服务器
mcp-reflect-uvx
```
您可以使用环境变量自定义主机和端口：
```bash
# 设置自定义主机和端口
export HOST=127.0.0.1
export PORT=8080
mcp-reflect-uvx
```
或以编程方式：
```python
from mcp_reflect.server import run_uvx_server
# 这将在指定的主机和端口上启动一个HTTP服务器
run_uvx_server()
```
一旦运行，服务器通过HTTP端点提供MCP工具，可以被API客户端访问。
### 基本反射
使用该工具的最简单方法是传递一个模型响应进行反射：
```python
import asyncio
from mcp_reflect.server import reflect
async def improve_response():
result = await reflect(
response="地球大约有6000年历史，根据某些估计。",
query="地球有多老？"
)
print(f"改进的响应：{result.improved_response}")
print(f"整体评估：{result.overall_assessment}")
# 打印每个维度的分数
for score in result.scores:
print(f"{score.dimension.value}：{score.score}/10 - {score.improvement_suggestion}")
asyncio.run(improve_response())
```
### 顺序处理
使用不同的策略处理多个响应：
```python
import asyncio
from mcp_reflect.server import sequential_reflect
async def process_multiple_responses():
responses = [
"地球大约有6000年历史，根据某些估计。",
"地球形成于大约45亿年前，但有不同的方法来确定这一点。"
]
# 迭代处理（每个反射都建立在之前的改进基础上）
results = await sequential_reflect(responses=responses, mode="iterative")
# 显示最终的改进响应
print(f"最终的改进响应：{results[-1].improved_response}")
asyncio.run(process_multiple_responses())
```
### 与Claude集成
MCP-Reflect旨在与Claude和其他MCP兼容的助手无缝集成。以下是如何与Claude一起使用它：
1. 启动MCP服务器：`mcp-reflect`
2. 将Claude连接到服务器（通常由您的客户端应用程序处理）
3. 直接从Claude调用反射工具：
```
我想分析和改进我之前的响应。你能为此使用反射工具吗？
<response>
地球大约有6000年历史，根据某些估计。
</response>
```
## 高级用法
### 自定义评估关注点
关注特定维度以实现有针对性的改进：
```python
import asyncio
from mcp_reflect.models import EvaluationDimension
from mcp_reflect.server import reflect
async def focused_evaluation():
result = await reflect(
response="地球大约有6000年历史，根据某些估计。",
query="地球有多老？",
focus_dimensions=[
EvaluationDimension.ACCURACY,
EvaluationDimension.REASONING
]
)
# 打印聚焦评估结果
for score in result.scores:
print(f"{score.dimension.value}：{score.score}/10")
asyncio.run(focused_evaluation())
```
### 自定义改进指令
提供特定的改进指导：
```python
import asyncio
from mcp_reflect.server import reflect
async def guided_improvement():
result = await reflect(
response="地球大约有6000年历史，根据某些估计。",
improvement_prompt="添加科学共识和使用的方法论进行测年。"
)
print(result.improved_response)
asyncio.run(guided_improvement())
```
## 工作原理
MCP-Reflect使用多阶段过程来评估和改进模型响应：
1. **分析阶段**：分析原始响应，涵盖多个质量维度
2. **评分阶段**：每个维度都获得一个具体的分数和理由
3. **改进阶段**：生成具体的改进建议
4. **综合阶段**：创建响应的改进版本
5. **封装阶段**：将所有见解结构化为一个全面的结果
## 开发
### 设置
```bash
# 克隆仓库
git clone https://github.com/JonesH/mcp-reflect.git
cd mcp-reflect
# 使用Poetry安装
poetry install
# 运行测试
poetry run pytest
```
### 项目结构
- `mcp_reflect/models.py` - 评估的数据模型
- `mcp_reflect/evaluator.py` - 核心评估逻辑
- `mcp_reflect/server.py` - MCP服务器和工具定义
- `tests/` - 测试套件
## 许可证
该项目在MIT许可证下许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 贡献
欢迎贡献！请随时提交拉取请求。
1. 分叉仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开拉取请求
