Metadata-Version: 2.4
Name: guru-pk-mcp
Version: 1.1.2
Summary: MCP server enabling AI expert debates - 13 thought leaders engage in 4-round philosophical discussions on your questions
Project-URL: Homepage, https://github.com/MitsudoAI/guru-pk-mcp
Project-URL: Repository, https://github.com/MitsudoAI/guru-pk-mcp.git
Project-URL: Issues, https://github.com/MitsudoAI/guru-pk-mcp/issues
Project-URL: Documentation, https://github.com/MitsudoAI/guru-pk-mcp/blob/main/README.md
Project-URL: Changelog, https://github.com/MitsudoAI/guru-pk-mcp/releases
Project-URL: Source Code, https://github.com/MitsudoAI/guru-pk-mcp
Project-URL: Bug Tracker, https://github.com/MitsudoAI/guru-pk-mcp/issues
Author-email: Ryu <ryu@mitsudo.tech>
License: MIT License
        
        Copyright (c) 2025 MitsudoAI Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,charlie-munger,claude-desktop,cursor,elon-musk,expert-debate,mcp,model-context-protocol,philosophy,socrates,thought-leaders,uvx
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0.0
Requires-Dist: mcp>=1.10.1
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Guru-PK MCP 专家辩论系统

基于MCP（Model Context Protocol）的AI专家辩论系统，让不同领域的思想家围绕您的问题进行多轮智慧碰撞。

## ✨ 核心特色

- 🎭 **13位内置专家** - 涵盖哲学、商业、科学、战略等领域
- 🔄 **4轮PK流程** - 独立思考 → 交叉辩论 → 最终立场 → 智慧综合  
- 🌟 **自然语言创建专家** - 只需描述需求，AI自动生成专属思想家
- 📊 **智能推荐** - 自动推荐最适合的专家组合
- 📚 **会话管理** - 本地保存，支持导出和恢复

## 🚀 快速安装

### 1. 安装依赖
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. 配置MCP客户端

**推荐方式：从PyPI安装**
```json
{
  "mcpServers": {
    "guru-pk": {
      "command": "uvx",
      "args": ["--from", "guru-pk-mcp", "guru-pk-mcp-server"],
      "env": {
        "DATA_DIR": "~/.guru-pk-data"
      }
    }
  }
}
```

> **注意**: macOS用户可能需要使用完整路径：`/Users/{用户名}/.local/bin/uvx`

**开发方式：从源码安装**
```json
{
  "mcpServers": {
    "guru-pk": {
      "command": "uvx", 
      "args": ["--from", "/path/to/guru-pk-mcp", "guru-pk-mcp-server"],
      "env": {
        "DATA_DIR": "~/.guru-pk-data"
      }
    }
  }
}
```

### 3. 开始使用
重启MCP客户端，输入 `guru_pk_help` 获取帮助，或直接提问开始专家辩论！

## 🎭 专家阵容

### 哲学思辨
🧠 **苏格拉底** - 批判思维，质疑表面答案  
☯️ **王阳明** - 心学大师，知行合一  
🧘 **克里希那穆提** - 觉察智慧，当下哲学  

### 商业创新  
🚀 **埃隆·马斯克** - 第一性原理，颠覆创新  
📚 **查理·芒格** - 多元思维，投资智慧  
🍎 **史蒂夫·乔布斯** - 产品完美主义，用户体验  
🌸 **稻盛和夫** - 敬天爱人，经营哲学  

### 经济战略
💰 **冯·米塞斯** - 奥地利学派，人类行动学  
⚔️ **孙子** - 兵学圣祖，战略思维  
📖 **曾国藩** - 修身治国，渐进改良  

### 科学方法
🔬 **卡尔·波普尔** - 可证伪性，批判理性主义  
🔄 **杰伊·福雷斯特** - 系统动力学，反馈环理论  
🧠 **大卫·伯恩斯** - CBT心理学，认知重构  

## 💡 使用方法

### 基础工具
- `start_pk_session` - 启动专家辩论
- `guru_pk_help` - 获取系统帮助
- `list_available_personas` - 查看所有专家
- `recommend_personas` - 智能推荐专家组合

### 🌟 智能自定义专家创建（重点功能）

**全新架构：MCP Host端LLM智能生成 + MCP Server端保存**

#### 第一步：获取创建指导
```
create_custom_persona_from_description({
  "description": "我想要一个世界历史方面的顶尖专家"
})
```

#### 第二步：LLM生成专家数据
系统返回详细指导后，让MCP Host端的LLM生成完整专家数据：
```json
{
  "name": "汤因比",
  "emoji": "📚",
  "description": "英国著名历史学家，文明史研究的集大成者",
  "core_traits": ["文明史观", "挑战-应战理论", "宏观历史视野"],
  "speaking_style": "宏观深邃，善于从文明兴衰中提炼规律",
  "base_prompt": "详细的角色提示词..."
}
```

#### 第三步：保存专家
```
save_custom_persona({
  "persona_data": { /* 上面生成的完整数据 */ }
})
```

**🎯 核心优势：**
- 🧠 **真正智能** - 利用MCP Host端LLM的强大生成能力
- 🎭 **专业定制** - 创建真正有价值的领域专家，而非通用模板
- 🔧 **完整验证** - 自动处理名称冲突、数据验证等技术细节
- 📚 **详细指导** - 提供专家数据模板和创建要点

#### 🌟 推荐专家领域
- **历史学**: 汤因比、黄仁宇、钱穆
- **物理学**: 爱因斯坦、费曼、霍金  
- **文学**: 莎士比亚、鲁迅、村上春树
- **艺术**: 达芬奇、毕加索、宫崎骏
- **经济学**: 亚当·斯密、凯恩斯、张五常

### 传统使用示例
```
问题："如何在AI时代保持竞争力？"
专家：["苏格拉底", "埃隆马斯克", "大卫伯恩斯"]
```

### 🌟 推荐组合

**投资决策** - 冯·米塞斯 + 查理·芒格 + 埃隆·马斯克  
**心理成长** - 苏格拉底 + 大卫·伯恩斯 + 克里希那穆提  
**战略决策** - 孙子 + 曾国藩 + 查理·芒格  
**科学理性** - 卡尔·波普尔 + 苏格拉底 + 杰伊·福雷斯特

## 🔄 辩论流程

1. **独立思考** - 每位专家独立分析
2. **交叉辩论** - 互相批评和借鉴  
3. **最终立场** - 形成完善方案
4. **智慧综合** - 融合终极答案

## 🛠️ 技术架构

**语言**: Python 3.10+ | **框架**: MCP | **包管理**: UVX  
**存储**: 本地JSON | **特点**: 零部署、隐私保护

### 项目结构
```
src/guru_pk_mcp/
├── server.py           # MCP服务器
├── personas.py         # 13位专家配置  
├── session_manager.py  # 会话管理
├── custom_personas.py  # 自定义专家
└── models.py          # 数据模型
```

## 🎨 高级功能

### 🌟 自然语言创建专家（核心优势）

**革命性的专家创建体验** - 这是Guru-PK MCP最强大的功能，也是与其他AI辩论系统的核心差异化优势。

#### 🎯 为什么这个功能如此重要？
专家辩论系统的价值**完全取决于专家角色的质量**。传统方式需要：
- 📝 手动填写复杂的JSON配置
- 🔍 研究专家背景和思维特点  
- ✍️ 编写详细的角色提示词
- 🐛 调试和优化专家表现

**现在只需一句话** → 系统自动完成所有工作！

#### ⚡ 超简单的创建流程
```bash
# 1. 用自然语言描述需求
create_custom_persona_from_description({
  "description": "我想要一个现代教育领域最顶尖的大师"
})

# 2. 系统智能生成完整模板
# 3. 您确认或微调
# 4. 立即可用于专家辩论！
```

#### 🎭 智能推荐专家库
系统内置了各领域顶级专家的模板：

**教育领域**: 肯·罗宾逊（创造力教育）  
**AI科技**: 杰弗里·辛顿（深度学习教父）  
**心理治疗**: 维克多·弗兰克尔（意义疗法）  
**商业创新**: 克莱顿·克里斯坦森（颠覆式创新）  
**设计思维**: 蒂姆·布朗（设计思维）  
...更多领域持续扩展

#### 💡 使用技巧
```bash
# 具体领域
"我需要一个区块链技术专家"
"我想要一个儿童心理学家"  
"我需要一个可持续发展专家"

# 特定需求
"我想要一个擅长解决团队冲突的专家"
"我需要一个专门研究创业失败的专家"
"我想要一个关注女性领导力的专家"

# 历史人物
"我想要一个像爱因斯坦一样的物理学家"
"我需要一个类似甘地的精神领袖"
```

### 传统方式：手动创建专家
如果您仍希望手动创建，可以使用 `create_custom_persona` 工具

### 数据管理  
- 自动保存会话到本地JSON
- 支持Markdown导出
- 历史会话查看和恢复
- 完全本地化，保护隐私

### 统计分析
- 会话完成率和活跃度
- 热门专家排行榜  
- 问题领域分析
- 讨论质量统计

## 📱 兼容性

支持所有MCP兼容应用：Claude Desktop、Cursor、TRAE、DeepChat、Cherry Studio等

## 💡 使用提示

- 输入 `guru_pk_help` 获取系统介绍
- 直接提问开始专家辩论  
- 使用 `list_available_personas` 查看专家
- 推荐使用UVX方式安装，零配置依赖管理

## 💭 设计理念

### 灵感来源
本项目受到 [人生教练团Agent](https://mp.weixin.qq.com/s/QGNzRRo7U3Y2fmvOXNJvyw) 的启发。原文提出了多角色PK的创新思路，通常这类系统会使用LangGraph等Agent框架开发，而原作者选择了"飞书MCP"实现更简单的方案，思路巧妙。

### 技术方案对比

**🔧 Agent框架开发**
- ✅ 功能强大，可集成多个LLM API
- ✅ 前端交互灵活，控制性强
- ❌ 开发复杂度高
- ❌ API调用成本高昂

**☁️ 飞书MCP方案**  
- ✅ 几乎零开发，部署简单
- ✅ 利用现有飞书生态
- ❌ 依赖第三方服务
- ❌ 定制化程度有限

**🏠 本地MCP方案（本项目）**
- ✅ 与订阅制Chat APP结合，无API费用
- ✅ 数据本地化，隐私保护
- ✅ 开源可定制，技术独立
- ❌ 依赖MCP客户端实现，兼容性差异
- ❌ 需要一定开发工作

### 核心优势
本项目选择本地MCP方案，在保持"专家PK"、"大神PK"、"人生教练团"这类AI专家辩论系统的核心理念的同时，**最大化成本效益** —— 既避免了高额API费用，又提供了足够的灵活性和隐私保护。
