mcp_llm-debate 1.0.0

package/src/debate-engine.js

@@ -0,0 +1,218 @@
+/**
+ * 辩论引擎 - 核心编排逻辑
+ * 负责根据辩论图定义，按轮次依次调用 LLM 生成各角色发言
+ */
+
+import { LLMClient } from './llm-client.js';
+import { SessionManager } from './session-manager.js';
+
+export class DebateEngine {
+  constructor(llmClient, sessionManager) {
+    this.llm = llmClient;
+    this.sessions = sessionManager;
+  }
+
+  /**
+   * 执行一次完整的辩论
+   * @param {Object} graphDef - 辩论图定义
+   * @param {Object} input - 输入参数 {subject, context, previous_session_id}
+   * @param {Object} options - 选项 {parallel, timeout_ms, stream}
+   * @returns {Promise<Object>} 辩论结果 session
+   */
+  async runDebate(graphDef, input, options = {}) {
+    const { subject, context = {}, previous_session_id } = input;
+
+    // 创建或加载 session
+    let session;
+    if (previous_session_id) {
+      session = this.sessions.getSession(previous_session_id);
+      if (!session) {
+        throw new Error(`上一轮 Session 未找到: ${previous_session_id}`);
+      }
+    } else {
+      session = this.sessions.createSession(graphDef, subject, context);
+    }
+
+    const rounds = graphDef.rounds || [];
+    const roles = graphDef.roles || [];
+    const rules = graphDef.rules || {};
+    const sessionId = session.session_id;
+
+    // 构建辩论历史（用于上下文传递）
+    const history = session.rounds.map(r => ({
+      role: 'assistant',
+      content: `[${r.role}] ${r.content}`
+    }));
+
+    // 记录哪些阶段已完成，避免重复执行
+    const completedPhases = new Set(session.rounds.map(r => r.phase));
+
+    // 按顺序执行每个轮次
+    for (const round of rounds) {
+      // 跳过已完成的阶段
+      if (completedPhases.has(round.phase) && !options.force) {
+        continue;
+      }
+
+      const speakers = round.speakers || [];
+      const roundResults = [];
+
+      if (options.parallel) {
+        // 并行模式：同一轮所有角色同时发言
+        const roleMessages = speakers.map(speakerName => {
+          const role = roles.find(r => r.name === speakerName);
+          const systemPrompt = this._buildSystemPrompt(role, round, subject, context, rules, history);
+          const msg = {
+            messages: [
+              { role: 'system', content: systemPrompt },
+              { role: 'user', content: `辩论主题：${subject}\n当前环节：${round.description}\n请根据你的角色定位进行发言。` }
+            ]
+          };
+          // 如果角色指定了 model，传入该模型
+          if (role && role.model) {
+            msg.options = { model: role.model };
+          }
+          return msg;
+        });
+
+        const responses = await this.llm.chatBatch(roleMessages);
+
+        for (let i = 0; i < speakers.length; i++) {
+          const speakerResult = {
+            role: speakers[i],
+            phase: round.phase,
+            phase_description: round.description,
+            content: responses[i],
+            type: 'speech'
+          };
+          roundResults.push(speakerResult);
+          history.push({
+            role: 'assistant',
+            content: `[${speakers[i]}] ${responses[i]}`
+          });
+        }
+      } else {
+        // 串行模式：按顺序依次发言（后发言者看到先发言者的内容）
+        for (const speakerName of speakers) {
+          const role = roles.find(r => r.name === speakerName);
+          const systemPrompt = this._buildSystemPrompt(role, round, subject, context, rules, history);
+
+          // 构建当前发言的上下文，包含之前所有发言历史
+          const messages = [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: `辩论主题：${subject}\n当前环节：${round.description}\n请根据你的角色定位进行发言。` }
+          ];
+
+          // 如果角色指定了 model，传入该模型
+          const chatOptions = role && role.model ? { model: role.model } : {};
+          const response = await this.llm.chat(messages, chatOptions);
+          const speakerResult = {
+            role: speakerName,
+            phase: round.phase,
+            phase_description: round.description,
+            content: response,
+            type: 'speech'
+          };
+
+          roundResults.push(speakerResult);
+
+          // 立即将本轮发言加入历史，后续发言者可以看到
+          history.push({
+            role: 'assistant',
+            content: `[${speakerName}] ${response}`
+          });
+        }
+      }
+
+      // 将本轮所有发言保存到 session
+      for (const result of roundResults) {
+        session = this.sessions.appendRound(sessionId, result);
+      }
+    }
+
+    // 生成总结并完成 session
+    const summary = this._generateSummary(session, graphDef);
+    session = this.sessions.finalizeSession(sessionId, {
+      summary,
+      round_count: session.rounds.length
+    });
+
+    return session;
+  }
+
+  /**
+   * 续辩：基于已有 session 继续辩论
+   */
+  async continueDebate(sessionId, graphDef, subject, context = {}) {
+    const existingSession = this.sessions.getSession(sessionId);
+    if (!existingSession) {
+      throw new Error(`Session 未找到: ${sessionId}`);
+    }
+
+    return await this.runDebate(graphDef, {
+      subject: subject || existingSession.subject,
+      context: { ...existingSession.context, ...context },
+      previous_session_id: sessionId
+    }, { force: true });
+  }
+
+  /**
+   * 构建角色的 system prompt
+   */
+  _buildSystemPrompt(role, round, subject, context, rules, history) {
+    let prompt = `## 角色设定\n`;
+    prompt += `你是辩论中的「${role ? role.name : '参与者'}」。\n`;
+    prompt += `角色描述：${role ? role.persona : '请基于理性和逻辑参与讨论'}\n\n`;
+    prompt += `## 辩论信息\n`;
+    prompt += `辩论主题：${subject}\n`;
+    prompt += `当前环节：${round ? round.description : '自由讨论'}\n`;
+
+    if (context && Object.keys(context).length > 0) {
+      prompt += `\n## 背景信息\n${JSON.stringify(context, null, 2)}\n`;
+    }
+
+    if (rules && Object.keys(rules).length > 0) {
+      prompt += `\n## 规则要求\n`;
+      if (rules.min_response_length) {
+        prompt += `- 每条发言不少于 ${rules.min_response_length} 字。\n`;
+      }
+      if (rules.requires_fact_checking) {
+        prompt += `- 请基于事实进行论证，避免主观臆断。\n`;
+      }
+      if (rules.turn_limit) {
+        prompt += `- 同一角色在每个环节最多发言 ${rules.turn_limit} 次。\n`;
+      }
+    }
+
+    if (history.length > 0) {
+      prompt += `\n## 辩论历史\n`;
+      // 只取最近 15 条历史，避免超出上下文窗口
+      const recentHistory = history.slice(-15);
+      for (const msg of recentHistory) {
+        prompt += `${msg.content}\n`;
+      }
+    }
+
+    return prompt;
+  }
+
+  /**
+   * 生成辩论摘要
+   */
+  _generateSummary(session, graphDef) {
+    const totalRounds = session.rounds.length;
+    const uniqueRoles = [...new Set(session.rounds.map(r => r.role))];
+    const completedPhases = [...new Set(session.rounds.map(r => r.phase))];
+    const startTime = new Date(session.created_at);
+    const endTime = new Date(session.updated_at);
+    const durationMs = endTime - startTime;
+
+    return {
+      total_speeches: totalRounds,
+      roles_involved: uniqueRoles,
+      phases_completed: completedPhases,
+      duration_seconds: (durationMs / 1000).toFixed(1),
+      total_phases: graphDef.rounds ? graphDef.rounds.length : 0
+    };
+  }
+}

package/src/graph-loader.js

@@ -0,0 +1,95 @@
+/**
+ * 辩论图加载器 - 负责加载内置辩论图模板和支持内联自定义定义
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const GRAPHS_DIR = path.join(__dirname, '..', 'graphs');
+
+export class GraphLoader {
+  constructor(graphsDir = GRAPHS_DIR) {
+    this.graphsDir = graphsDir;
+  }
+
+  /**
+   * 按名称加载内置辩论图
+   * @param {string} name - 辩论图名称（不含 .json 后缀）
+   * @returns {Object|null}
+   */
+  loadGraph(name) {
+    const filePath = path.join(this.graphsDir, `${name}.json`);
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    try {
+      return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 列出所有内置辩论图模板
+   * @returns {Array<{name, description, roleCount, roundCount}>}
+   */
+  listGraphs() {
+    if (!fs.existsSync(this.graphsDir)) {
+      return [];
+    }
+
+    const files = fs.readdirSync(this.graphsDir)
+      .filter(f => f.endsWith('.json'))
+      .sort();
+
+    return files.map(f => {
+      try {
+        const graph = JSON.parse(fs.readFileSync(path.join(this.graphsDir, f), 'utf-8'));
+        return {
+          name: graph.name,
+          description: graph.description,
+          roleCount: graph.roles ? graph.roles.length : 0,
+          roundCount: graph.rounds ? graph.rounds.length : 0,
+          roles: graph.roles ? graph.roles.map(r => r.name) : []
+        };
+      } catch {
+        return { name: f.replace('.json', ''), description: '(加载失败)' };
+      }
+    });
+  }
+
+  /**
+   * 解析 graph 参数，支持字符串名称和 JSON 对象
+   * @param {string|Object} graphParam - 图名称或完整定义
+   * @returns {Object} 辩论图定义
+   */
+  parseGraphDefinition(graphParam) {
+    if (!graphParam) {
+      throw new Error('辩论图参数不能为空');
+    }
+
+    // 字符串：先尝试加载内置模板，再尝试解析为 JSON
+    if (typeof graphParam === 'string') {
+      const builtIn = this.loadGraph(graphParam);
+      if (builtIn) return builtIn;
+
+      try {
+        return JSON.parse(graphParam);
+      } catch {
+        throw new Error(`辩论图未找到: "${graphParam}"。使用 list_debate_graphs 查看可用模板。`);
+      }
+    }
+
+    // 对象：直接使用
+    if (typeof graphParam === 'object' && graphParam !== null) {
+      if (!graphParam.roles || !graphParam.rounds) {
+        throw new Error('自定义辩论图必须包含 roles 和 rounds 字段');
+      }
+      return graphParam;
+    }
+
+    throw new Error('无效的辩论图定义');
+  }
+}

package/src/index.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+/**
+ * mcp_llm-debate - MCP 服务器入口
+ *
+ * 注册 5 个辩论相关工具，支持 stdio / http / rest 三种传输方式。
+ *
+ * 环境变量配置：
+ *   LLM_API_KEY     - LLM API 密钥（必填）
+ *   LLM_BASE_URL    - API 基础 URL（默认: https://api.openai.com/v1）
+ *   LLM_MODEL       - 模型名称（默认: gpt-4o）
+ *   SERVER_TRANSPORT - 传输方式: stdio | http | rest（默认: stdio）
+ *   SERVER_PORT     - HTTP/REST 端口（默认: 3000）
+ *   SERVER_HOST     - 绑定地址（默认: 127.0.0.1）
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { fileURLToPath } from 'url';
+
+import { LLMClient } from './llm-client.js';
+import { SessionManager } from './session-manager.js';
+import { GraphLoader } from './graph-loader.js';
+import { DebateEngine } from './debate-engine.js';
+import { loadConfig, getLLMConfig } from './config.js';
+
+// ============================================================
+// 工具定义
+// ============================================================
+const TOOLS = [
+  {
+    name: "run_debate",
+    description: "执行一次辩论。根据辩论图定义，由多个 AI 角色围绕主题进行结构化辩论。支持内置模板（如 classic-debate）或自定义辩论图。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        graph: {
+          type: "string",
+          description: "辩论图名称（如 classic-debate, panel-discussion, socratic-dialogue, brainstorming）或内联 JSON 定义"
+        },
+        input: {
+          type: "object",
+          properties: {
+            subject: { type: "string", description: "辩论主题" },
+            context: { type: "object", description: "额外的上下文信息（可选）" },
+            previous_session_id: { type: "string", description: "续辩时传入的上一轮 session_id（可选）" }
+          },
+          required: ["subject"]
+        },
+        options: {
+          type: "object",
+          properties: {
+            timeout_ms: { type: "number", description: "超时时间（毫秒）" },
+            parallel: { type: "boolean", description: "是否并行执行同一轮的所有角色发言，默认为串行" },
+            stream: { type: "boolean", description: "是否流式返回结果" }
+          }
+        }
+      },
+      required: ["graph", "input"]
+    }
+  },
+  {
+    name: "continue_debate",
+    description: "基于上轮结果续辩。传入已有 session_id 继续辩论，可以换主题或增加新上下文。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string", description: "历史 session ID" },
+        graph: { type: "string", description: "辩论图名称或内联定义" },
+        subject: { type: "string", description: "辩论主题（可选，默认使用原主题）" },
+        context: { type: "object", description: "额外上下文信息（可选）" }
+      },
+      required: ["session_id", "graph"]
+    }
+  },
+  {
+    name: "get_debate_graph",
+    description: "获取指定辩论图的完整定义，包括角色设定、轮次流程和规则。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "辩论图名称" }
+      },
+      required: ["name"]
+    }
+  },
+  {
+    name: "get_debate_result",
+    description: "拉取历史辩论 session 的完整结果，包括所有轮次的发言记录和最终总结。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string", description: "session ID" }
+      },
+      required: ["session_id"]
+    }
+  },
+  {
+    name: "list_debate_graphs",
+    description: "列出所有可用的内置辩论图模板，包括名称、描述和角色数量。",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  }
+];
+
+// ============================================================
+// 格式化帮助函数
+// ============================================================
+
+function _formatDebateResult(session) {
+  const lines = [];
+  lines.push(`=== 辩论结果 ===`);
+  lines.push(`Session ID: ${session.session_id}`);
+  lines.push(`主题: ${session.subject}`);
+  lines.push(`辩论图: ${session.graph_name || '自定义'}`);
+  lines.push(`状态: ${session.status}`);
+  lines.push(`创建时间: ${session.created_at}`);
+  lines.push('');
+
+  // 按阶段组织发言
+  const phases = [...new Set(session.rounds.map(r => r.phase))];
+  for (const phase of phases) {
+    const phaseRounds = session.rounds.filter(r => r.phase === phase);
+    const phaseDesc = phaseRounds[0]?.phase_description || phase;
+    lines.push(`\n--- ${phaseDesc} ---`);
+    for (const round of phaseRounds) {
+      lines.push(`\n[${round.role}]`);
+      lines.push(round.content);
+    }
+  }
+
+  // 总结
+  if (session.result && session.result.summary) {
+    lines.push(`\n--- 总结 ---`);
+    lines.push(`发言总数: ${session.result.summary.total_speeches}`);
+    lines.push(`参与角色: ${session.result.summary.roles_involved.join(', ')}`);
+    lines.push(`完成环节: ${session.result.summary.phases_completed.join(' -> ')}`);
+    lines.push(`耗时: ${session.result.summary.duration_seconds}秒`);
+  }
+
+  return lines.join('\n');
+}
+
+// ============================================================
+// 工具执行器（可复用，供 MCP 和 REST 传输层共用）
+// ============================================================
+
+/**
+ * 创建工具执行上下文
+ * @param {Object} options - 可选覆盖配置
+ * @returns {{ llmClient, sessionManager, graphLoader, debateEngine, config }}
+ */
+export function createToolContext(options = {}) {
+  const config = loadConfig(options);
+  const llmClient = new LLMClient(getLLMConfig(config));
+  const sessionManager = new SessionManager(config.dataDir);
+  const graphLoader = new GraphLoader(config.graphsDir);
+  const debateEngine = new DebateEngine(llmClient, sessionManager);
+
+  return { llmClient, sessionManager, graphLoader, debateEngine, config };
+}
+
+/**
+ * 执行单个工具调用（可被 MCP 和 REST 传输层共用）
+ * @param {string} name - 工具名称
+ * @param {Object} args - 工具参数
+ * @param {Object} ctx - 工具执行上下文（由 createToolContext 创建）
+ * @returns {Promise<{content: Array}>} MCP 格式的响应
+ */
+export async function executeTool(name, args, ctx) {
+  const { graphLoader, debateEngine, sessionManager } = ctx;
+
+  switch (name) {
+    // ---- run_debate ----
+    case "run_debate": {
+      const graphDef = graphLoader.parseGraphDefinition(args.graph);
+      const result = await debateEngine.runDebate(graphDef, args.input, args.options || {});
+      const output = _formatDebateResult(result);
+      return { content: [{ type: "text", text: output }] };
+    }
+
+    // ---- continue_debate ----
+    case "continue_debate": {
+      const graphDef = graphLoader.parseGraphDefinition(args.graph);
+      const result = await debateEngine.continueDebate(
+        args.session_id, graphDef, args.subject, args.context || {}
+      );
+      return { content: [{ type: "text", text: _formatDebateResult(result) }] };
+    }
+
+    // ---- get_debate_graph ----
+    case "get_debate_graph": {
+      const graph = graphLoader.loadGraph(args.name);
+      if (!graph) throw new Error(`辩论图未找到: "${args.name}"`);
+      return { content: [{ type: "text", text: JSON.stringify(graph, null, 2) }] };
+    }
+
+    // ---- get_debate_result ----
+    case "get_debate_result": {
+      const session = sessionManager.getSession(args.session_id);
+      if (!session) throw new Error(`Session 未找到: "${args.session_id}"`);
+      return { content: [{ type: "text", text: JSON.stringify(session, null, 2) }] };
+    }
+
+    // ---- list_debate_graphs ----
+    case "list_debate_graphs": {
+      const graphs = graphLoader.listGraphs();
+      const output = graphs.map((g, i) =>
+        `${i + 1}. ${g.name} - ${g.description}\n   角色: ${g.roleCount}个 | 环节: ${g.roundCount}个`
+      ).join('\n\n');
+      return { content: [{ type: "text", text: output || '暂无可用辩论图模板。' }] };
+    }
+
+    default:
+      throw new Error(`未知工具: "${name}"`);
+  }
+}
+
+// ============================================================
+// MCP 服务器工厂
+// ============================================================
+
+/**
+ * 创建已配置好工具处理器的 MCP Server 实例
+ * @param {Object} ctx - 工具执行上下文（由 createToolContext 创建）
+ * @returns {Server}
+ */
+export function createServer(ctx) {
+  const server = new Server(
+    {
+      name: "mcp_llm-debate",
+      version: "1.0.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // 列出工具
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+  }));
+
+  // 调用工具
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      return await executeTool(name, args, ctx);
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `错误: ${error.message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  return server;
+}
+
+// ============================================================
+// 启动 stdio 模式（默认，向后兼容）
+// ============================================================
+
+async function main() {
+  const config = loadConfig();
+
+  // 检查配置
+  if (!config.apiKey) {
+    console.error('警告: 未配置 LLM API 密钥。请设置环境变量 LLM_API_KEY 或 OPENAI_API_KEY。');
+  }
+
+  if (process.env.LLM_BASE_URL) {
+    console.error(`LLM API 端点: ${config.baseUrl}`);
+  }
+
+  console.error(`LLM 模型: ${config.model}`);
+  console.error('mcp_llm-debate 服务器启动中 (stdio 模式)...');
+
+  const ctx = createToolContext(config);
+  const server = createServer(ctx);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('mcp_llm-debate 服务器已就绪');
+}
+
+// 仅在直接执行 index.js 时启动 stdio 模式（不是被 import 时）
+const isMainModule = process.argv[1] && (
+  process.argv[1] === fileURLToPath(import.meta.url) ||
+  process.argv[1].replace(/\\/g, '/').endsWith('/src/index.js')
+);
+
+if (isMainModule) {
+  main().catch((error) => {
+    console.error('服务器启动失败:', error);
+    process.exit(1);
+  });
+}

package/src/lib.js

@@ -0,0 +1,45 @@
+/**
+ * mcp_llm-debate 库导出入口
+ *
+ * 让其他 Node.js 项目可以直接 import 核心类使用：
+ *
+ *   import { DebateEngine, LLMClient, SessionManager, GraphLoader } from 'mcp_llm-debate';
+ *
+ * 或者使用便捷工厂函数：
+ *
+ *   import { createDebateEngine, createLLMClient } from 'mcp_llm-debate';
+ */
+
+import { DebateEngine } from './debate-engine.js';
+import { LLMClient } from './llm-client.js';
+import { SessionManager } from './session-manager.js';
+import { GraphLoader } from './graph-loader.js';
+import { loadConfig, getLLMConfig } from './config.js';
+import { createServer } from './index.js';
+
+// 核心类
+export { DebateEngine, LLMClient, SessionManager, GraphLoader };
+// 配置
+export { loadConfig, getLLMConfig };
+// MCP 服务器工厂（用于自定义传输层）
+export { createServer };
+
+/**
+ * 便捷工厂：创建 LLMClient
+ * @param {Object} options - { apiKey, baseUrl, model }
+ */
+export function createLLMClient(options = {}) {
+  const config = loadConfig(options);
+  return new LLMClient(getLLMConfig(config));
+}
+
+/**
+ * 便捷工厂：创建完整的辩论引擎
+ * @param {Object} options - { apiKey, baseUrl, model, dataDir, graphsDir }
+ */
+export function createDebateEngine(options = {}) {
+  const config = loadConfig(options);
+  const llmClient = new LLMClient(getLLMConfig(config));
+  const sessionManager = new SessionManager(config.dataDir);
+  return new DebateEngine(llmClient, sessionManager);
+}