An open API service indexing awesome lists of open source software.

https://github.com/mitsudoai/guru-pk-mcp

Multi-round AI expert debate system via MCP - Three thought leaders engage in deep discussions on any topic
https://github.com/mitsudoai/guru-pk-mcp

ai-agents ai-reasoning critical-thinking expert-debate guru-pk infographics mcp-server tufte-design

Last synced: 12 days ago
JSON representation

Multi-round AI expert debate system via MCP - Three thought leaders engage in deep discussions on any topic

Awesome Lists containing this project

README

          

# πŸ“š Language Versions | ε€šθ―­θ¨€η‰ˆζœ¬ | 言θͺžγƒγƒΌγ‚Έγƒ§γƒ³

🌐 **[English](README.md)** | πŸ‡¨πŸ‡³ **[δΈ­ζ–‡](README_zh.md)** | πŸ‡―πŸ‡΅ **[ζ—₯本θͺž](README_ja.md)**

---

## Guru-PK MCP Intelligent Expert Debate System

An AI expert debate system based on local MCP (Model Context Protocol), featuring **dynamic expert generation architecture** that intelligently creates the most suitable expert combinations based on questions for multi-round intellectual confrontation.

## ✨ Core Features

- 🏭 **Dynamic Expert Generation** - Completely question-driven, generating dedicated expert combinations each time
- 🌟 **Unlimited Expert Pool** - Breaking fixed expert limitations, supporting expert generation in any domain
- πŸ”„ **Multi-Round PK Process** - Independent Thinking β†’ Cross-Debate β†’ Final Positions β†’ Wisdom Synthesis
- 🎨 **Tufte-Style Infographics** - Transform expert debates into single-page dynamic infographics strictly following data visualization master Edward Tufte's design principles
- πŸ€– **Intelligent Division Architecture** - MCP Host-side LLM handles intelligent analysis, MCP Server-side provides process guidance

## 🌐 Online Demo

**πŸ‘‰ [View Infographic Demo](https://mitsudoai.github.io/guru-pk-mcp/)**

This webpage displays Tufte-style dynamic infographics created using this MCP tool, intuitively showcasing the powerful capabilities of the expert debate system.

## πŸš€ Quick Installation

### 1. Install Dependencies

**Method 1: Using Installation Script (Recommended)**

**macOS/Linux:**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows:**

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Method 2: Install with pip (All Platforms)**

```bash
pip install uv
```

**Method 3: Download Installation Package**

Download the installation package for your platform from [UV Releases](https://github.com/astral-sh/uv/releases)

### 2. Configure MCP Client

**Recommended Method: Install from PyPI**

```json
{
"mcpServers": {
"guru-pk": {
"command": "uvx",
"args": ["--from", "guru-pk-mcp", "guru-pk-mcp-server"],
"env": {
"DATA_DIR": "~/.guru-pk-data" // macOS/Linux: ~ directory, Windows: %USERPROFILE% directory
}
}
}
}
```

> **Update Instructions**:
>
> - When you need to update `guru-pk-mcp` to the latest version, run:
>
> ```bash
> uvx pip install --upgrade guru-pk-mcp
> ```
>
> - This command fetches and installs the latest released version from PyPI
> - If you encounter cache issues, you can force refresh:
>
> ```bash
> uvx --refresh-package guru-pk-mcp --from guru-pk-mcp python -c "print('βœ… UVX cache refreshed')"
> ```
>
> **Notes**:
>
> - macOS users might need to use the full path: `/Users/{username}/.local/bin/uvx`
> - Windows users: `~` automatically resolves to user home directory (e.g., `C:\\Users\\{username}`), no manual modification needed

**Development Method: Install from Source**

```json
{
"mcpServers": {
"guru-pk": {
"command": "uvx",
"args": ["--from", "/path/to/guru-pk-mcp", "guru-pk-mcp-server"],
"env": {
"DATA_DIR": "~/.guru-pk-data" // macOS/Linux: ~ directory, Windows: %USERPROFILE% directory
}
}
}
}
```

> **Local Development Instructions**:
>
> - For local development scenarios, if you need to refresh uvx cache, use `make refresh-uvx`
> - This command forces UVX to reinstall the local package, ensuring the use of latest code changes

## Getting Started

Restart your MCP client, enter `guru_pk_help` to get help, or directly ask questions to start expert debates!

```javascript
// 1. Natural language questions (most recommended usage)
Are there any directions in the field of generative AI that are particularly suitable for individual entrepreneurship? Please have three experts PK

// 2. Intelligent candidate expert generation (system automatic execution)
start_pk_session: Are there any directions in the field of generative AI that are particularly suitable for individual entrepreneurship?

// 3. Intelligent candidate expert generation (user limits expected expert scope)
start_pk_session: Are there any directions in the field of generative AI that are particularly suitable for individual entrepreneurship? Find two AI field experts and one famous individual entrepreneur to debate
```

### πŸ’‘ Usage Tips

**Starting Debates**:

- πŸ€– **`start_pk_session: direct question`** - Default high-efficiency batch processing mode (recommended)
- πŸ”„ **`start_stepwise_pk_session: direct question`** - Traditional step-by-step dialogue mode

**Tool Functions**:

- πŸ“‹ `guru_pk_help` - Get system introduction and detailed help
- πŸ“„ `export_session` - Export session as Markdown file
- 🎨 `export_session_as_infographic` - Export session as Tufte-style single-page dynamic infographic
- πŸ“„ `export_enhanced_session` - Export enhanced analysis report
- 🌍 `set_language` - Set expert reply language

### πŸ“± Compatibility

Supports all MCP-compatible applications: Claude Desktop, Cursor, TRAE, DeepChat, Cherry Studio, etc.

### 🎯 Recommended Configuration

**Most Recommended MCP Hosts**:

- πŸ’° **Subscription-based MCP Hosts calculated by user requests** - Such as Cursor and overseas TRAE
- 🌟 **Advantages**:
- Significant cost advantages: subscription billing calculated by user requests, not API call counts or token billing
- Claude models have the best MCP support with excellent instruction-following capabilities

### ⚠️ Not Recommended Configuration

- 🚫 **TRAE Domestic Version** - Built-in domestic models have sensitive word censorship issues that may interrupt expert debate processes, affecting user experience

## πŸ› οΈ Technical Architecture

**Intelligent Division Principles**:

- 🧠 **MCP Host-side LLM**: Responsible for complex semantic analysis and intelligent generation
- πŸ”§ **MCP Server-side**: Provides concise process control and data management

### Dynamic Expert Generation Flow

```mermaid
flowchart TD
A[πŸ€” Raise Question] --> B[🧠 Intelligent Analysis]
B --> C[πŸ‘₯ Generate Candidates]
C --> D[πŸš€ Start Debate]

A1[Ask system directly about any topic]
B1[MCP Host-side LLM deeply analyzes question characteristics]
C1[Dynamically create 3 most relevant experts]
D1[Launch multi-round PK process]

A -.-> A1
B -.-> B1
C -.-> C1
D -.-> D1

style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
```

### πŸ”„ Debate Flow

**Two Debate Modes**:

πŸš€ **Batch Processing Mode** (`start_pk_session`) - **Default Recommended**

- ⚑ High Efficiency: Generate all expert answers in one round, saving about 60% time
- 🎯 Use Cases: Rapidly obtain multi-perspective analysis, efficient decision support

πŸ”„ **Stepwise Mode** (`start_stepwise_pk_session`) - Traditional Experience

- 🎭 Interactive: Experts speak sequentially, allowing real-time adjustment and deep exploration
- 🎯 Use Cases: Deep contemplation, enjoying the complete debate process

**4-Round Debate Flow**:

```mermaid
flowchart TD
A[πŸ€” Independent Thinking] --> B[βš”οΈ Cross-Debate]
B --> C[🎯 Final Positions]
C --> D[🧠 Wisdom Synthesis]

A1[Each expert independently analyzes the problem]
B1[Experts mutually question and learn from each other]
C1[Form their respective refined solutions]
D1[Ultimate answer integrating all perspectives]

A -.-> A1
B -.-> B1
C -.-> C1
D -.-> D1

B --> B2[Multi-round Interaction]
B2 --> B

style A fill:#e3f2fd
style B fill:#fce4ec
style C fill:#e8f5e8
style D fill:#fff8e1
style B2 fill:#f3e5f5
```