mirror of https://github.com/linshenkx/prompt-optimizer.git synced 2026-05-08 06:28:50 +08:00

Files

linshen 1a55a5e719 feat(server): 集成 MCP 服务器

本次提交主要集成了 MCP 服务器，为系统增加了用户提示词优化工具，并通过优化部署流程，提升了整体易用性。

具体变更内容包括：

* **功能增强:**
    * 集成 MCP 服务器，提供用户和系统提示词优化工具，支持 stdio 和 HTTP 两种传输方式，并集成了 Claude Desktop。
    * 实现基于会话的 HTTP 传输，允许多客户端连接，并为每个会话创建独立的 MCP 服务器实例，确保会话间的隔离性。

* **部署优化:**
    * 将 MCP 服务器端口变更为与 Web 界面共享 80 端口，通过路径区分，简化了 Docker 部署配置，降低了部署复杂度。
    * 优化 Docker 部署流程，使用 Supervisor 进行进程管理，并改进模板参数（使用枚举类型 + 默认值），同时提供了包含 MCP 服务器使用说明的 Docker 部署文档。

* **代码优化与重构:**
    * 优化模型选择逻辑，提高模型选择的准确性。
    * 优化日志记录功能，支持更灵活的日志级别设置，并添加了详细的错误提示和调试信息，方便问题排查。
    * 重构代码，分离构建和启动入口，优化环境变量加载和模型初始化逻辑，提高了代码的可维护性和可扩展性，并解决了构建副作用问题。

* **文档更新:**
    * 更新工具描述和使用说明，提供了用户和系统提示词工具的具体示例，并补充了迭代提示词工具的改进需求描述和使用场景。
    * 更新 Docker 部署方案，包含了 `docker-compose.yml`、`Dockerfile` 和 `env.local.example` 配置示例，并更新了 README 文档以明确连接方式。
    * 更新 `nginx.conf`，使用环境变量 `NGINX_PORT`，修改 `start-services.sh`，增加 nginx 配置处理，更新 `supervisord.conf`，调整 MCP 服务器启动方式，优化 `Dockerfile`，安装额外依赖并调整工作目录，调整环境变量加载机制，使用 `preload-env.cjs`。

* **其他:**
    * 提供快速开始指南、环境变量配置和问题排除等文档，更新了相关文档链接和获取帮助指引，并完成了基础测试用例和开发/设计文档。

本次更新旨在提升用户在提示词优化方面的能力，并简化部署流程，提高系统的整体可用性和可维护性。

2025-07-27 00:31:23 +08:00

8.6 KiB

Raw Permalink Blame History

MCP Server 模块技术实现详解

🔧 架构设计

整体架构

MCP Server 模块采用了分层架构设计，确保了与 Core 模块的解耦：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   MCP Client    │    │   MCP Client    │
│ (Claude Desktop)│    │ (MCP Inspector) │    │   (Custom App)  │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │ MCP Protocol
          ┌────────────────────────────────────────────────┐
          │              MCP Server                        │
          │  ┌─────────────────────────────────────────┐   │
          │  │           Transport Layer               │   │
          │  │  ┌─────────────┐  ┌─────────────────┐   │   │
          │  │  │    stdio    │  │ Streamable HTTP │   │   │
          │  │  └─────────────┘  └─────────────────┘   │   │
          │  └─────────────────────────────────────────┘   │
          │  ┌─────────────────────────────────────────┐   │
          │  │           MCP Protocol Layer            │   │
          │  │            ┌─────────┐                  │   │
          │  │            │  Tools  │                  │   │
          │  │            └─────────┘                  │   │
          │  └─────────────────────────────────────────┘   │
          │  ┌─────────────────────────────────────────┐   │
          │  │         Service Adapter Layer           │   │
          │  └─────────────────────────────────────────┘   │
          └────────────────────┬───────────────────────────┘
                               │
          ┌────────────────────────────────────────────────┐
          │              Core Module                       │
          │  ┌─────────────┐ ┌─────────────┐ ┌──────────┐  │
          │  │PromptService│ │ LLMService  │ │ Template │  │
          │  └─────────────┘ └─────────────┘ │ Manager  │  │
          │  ┌─────────────┐ ┌─────────────┐ └──────────┘  │
          │  │HistoryMgr   │ │ ModelMgr    │ ┌──────────┐  │
          │  └─────────────┘ └─────────────┘ │ Memory   │  │
          │                                  │ Storage  │  │
          │                                  └──────────┘  │
          └────────────────────────────────────────────────┘

模块结构

packages/mcp-server/
├── package.json                 # 项目配置和依赖
├── tsconfig.json               # TypeScript 配置
├── src/
│   ├── index.ts                # 主入口点（仅导出）
│   ├── start.ts                # 启动入口点
│   ├── config/                 # 配置管理
│   │   ├── environment.ts      # 环境变量管理
│   │   ├── models.ts           # 默认模型配置
│   │   └── templates.ts        # 默认模板配置
│   ├── tools/                  # MCP Tools 实现
│   │   ├── index.ts            # Tools 导出
│   │   ├── optimize-user-prompt.ts      # 用户提示词优化
│   │   ├── optimize-system-prompt.ts    # 系统提示词优化
│   │   └── iterate-prompt.ts            # 提示词迭代优化
│   ├── adapters/               # 服务适配层
│   │   ├── core-services.ts    # Core 服务初始化和管理
│   │   ├── parameter-adapter.ts # 参数格式转换
│   │   └── error-handler.ts    # 错误处理适配
│   └── utils/                  # 工具函数
│       └── logging.ts          # 日志工具
├── examples/                   # 使用示例
│   ├── stdio-client.js         # stdio 客户端示例
│   └── http-client.js          # HTTP 客户端示例
├── docs/                       # 文档
│   └── README.md               # 使用说明
└── tests/                      # 测试文件
    ├── tools.test.ts           # Tools 测试
    └── integration.test.ts     # 集成测试

🐛 问题诊断与解决

环境变量加载时机问题

问题描述: Core 包的 defaultModels 在模块导入时就初始化，无法读取到后来通过 dotenv 加载的环境变量。

解决方案: 创建预加载脚本 (preload-env.js)，在 Node.js 启动时预加载环境变量：

// preload-env.js
import { config } from 'dotenv';
import { resolve, dirname } from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// 按优先级加载环境变量
const paths = [
  resolve(process.cwd(), '.env.local'),
  resolve(process.cwd(), '../.env.local'),
  resolve(__dirname, '../../.env.local'),
  // ... 更多路径
];

paths.forEach(path => {
  try {
    config({ path });
  } catch (error) {
    // 忽略文件不存在的错误
  }
});

使用 -r 参数预加载:

{
  "scripts": {
    "dev": "node -r ./preload-env.js dist/start.js --transport=http"
  }
}

构建时产生后台进程问题

问题描述: 在 src/index.ts 文件末尾有立即执行的代码，当 tsup 构建时会意外启动服务器并占用端口。

解决方案: 文件分离策略

src/index.ts - 只导出函数，不执行：

// 导出 main 函数供外部调用
export { main };

src/start.ts - 专门用于启动：

#!/usr/bin/env node
import { main } from './index.js';

// 启动服务器
main().catch(console.error);

更新构建配置：

{
  "scripts": {
    "build": "tsup src/index.ts src/start.ts --format cjs,esm --dts --clean",
    "dev": "node -r ./preload-env.js dist/start.js --transport=http"
  }
}

📝 实施步骤

项目结构设计与初始化
Core 服务管理器实现
参数适配层实现
默认配置管理
MCP Tools 实现
错误处理与转换
MCP Server 实例创建
多传输方式支持
测试与文档

🔍 调试过程

在开发过程中，我们使用了以下调试方法：

MCP Inspector 调试: 使用官方调试工具进行协议级别测试
日志驱动调试: 详细记录每个环节状态，快速定位问题
分层测试策略: 先测试 Core 服务再测试 MCP 包装，快速定位问题

🧪 测试验证

构建测试

✅ CJS/ESM 双格式输出
✅ TypeScript 类型定义生成
✅ 构建时无副作用（不启动服务器）

功能测试

✅ 环境变量正确加载
✅ 模型自动选择和配置
✅ 模板加载和管理
✅ MCP 工具注册和调用
✅ HTTP/stdio 双传输支持

兼容性测试

✅ Windows 10/11
✅ Node.js 18+
✅ MCP Inspector 集成
✅ Claude Desktop 兼容

8.6 KiB Raw Permalink Blame History