juyiting-mcp-client

聚义厅MCP客户端 🎭

🚀 基于 Model Context Protocol (MCP) 的AI人格协作工具，支持多人格智能召唤、配置同步和协作分析

🙏 致谢声明

本项目灵感来源于 大铭老师的 persona-summoner 项目，感谢大铭老师在AI人格探索领域的开创性工作和无私分享！

聚义厅MCP在原项目基础上进行了重新设计和扩展，增加了配置同步、协作引擎、多模式分析等功能，旨在为用户提供更完整的AI人格协作体验。

原项目链接: https://github.com/yinwm/persona-summoner
特别感谢: 大铭老师 (@yinwm) 在AI人格召唤和多人格协作方面的探索和贡献

📖 简介

聚义厅MCP客户端是基于 Model Context Protocol (MCP) 的AI人格协作系统，采用服务端配置生成 + 客户端MCP执行的架构模式。用户在聚义厅Web平台个性化配置人格组合，通过MCP客户端工具同步配置到本地，实现智能化的多人格协作分析。

✨ 主要特性

• 🎭 多人格协作: 支持粉丝妹、小布丁、暖心姐姐等多种AI英雄
• ⚙️ 配置同步: 用户在Web平台配置，MCP客户端自动同步
• 🤝 智能协作: 支持并行、顺序、智能三种协作模式
• 🔧 标准化接口: 严格遵循MCP协议规范，兼容Cursor、Claude Desktop等
• 📊 遥测分析: 可选的使用数据收集和分析
• 🌐 多源人格: 支持GitHub、Gitee、CDN等多个人格数据源

🛠️ 支持的工具

工具名称	描述	参数
summon_hero	召唤指定英雄进行单独分析	hero_name
list_hero_configs	查看用户的英雄配置列表	无
download_hero_config	下载指定配置到本地	configId
start_collaboration	启动多英雄协作分析	query, heroIds?

📦 安装

NPM 全局安装

npm install -g @juyiting/mcp-client

NPX 临时使用

npx @juyiting/mcp-client

从源码安装

git clone https://github.com/juyiting/juyitingmcp.git
cd juyitingmcp
npm install
npm run build

🚀 快速开始

1. 配置 MCP 客户端

Cursor 配置

在 Cursor 设置中添加：

{
  "mcpServers": {
    "juyiting": {
      "command": "npx",
      "args": ["-y", "@juyiting/mcp-client"],
      "env": {
        "JUYITING_CONFIG_PATH": "~/.juyiting/config.json"
      }
    }
  }
}

Claude Desktop 配置

在 Claude Desktop 配置文件中添加：

{
  "mcpServers": {
    "juyiting": {
      "command": "npx",
      "args": ["@juyiting/mcp-client"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

2. 用户配置设置

首次使用需要设置用户认证密钥：

# 创建配置目录
mkdir -p ~/.juyiting

# 设置用户配置
echo '{
  "userKey": "your-api-key-from-juyiting-web",
  "apiBaseUrl": "https://api.juyiting.com",
  "cache": {
    "duration": 300000,
    "maxSize": 1000
  },
  "sync": {
    "autoSync": true,
    "syncInterval": 3600000,
    "retryAttempts": 3
  }
}' > ~/.juyiting/config.json

3. 基本使用

启动服务器后，你可以直接在支持的客户端中使用工具：

# 召唤单个人格
@juyiting 召唤小布丁，帮我分析这个商业计划

# 查看配置列表
@juyiting 查看我的人格配置列表

# 下载配置
@juyiting 下载配置：config-001

# 启动团队协作
@juyiting 分析这个产品的市场前景：[产品描述]

📋 API 文档

工具：summon_hero

描述: 召唤指定AI英雄进行专业分析

参数:

• hero_name (string, 必需): 英雄名称或ID

支持的英雄:

• 粉丝妹 - 发现亮点，放大优势
• 小布丁 - 商业分析，产品策略
• 暖心姐姐 - 温暖贴心，细致关怀
• 思维帝 - 结构化思维，MECE分析

返回值:

🎭 **人格名称** (人格ID) 已召唤！
**🎯 目标**: 人格目标描述
**📝 描述**: 人格详细描述
**📜 人格规则**: 具体的行为规则

工具：start_collaboration

描述: 启动多人格协作分析，根据配置执行智能协作流程

参数:

• query (string, 必需): 分析问题
• heroIds (string[], 可选): 指定参与协作的英雄ID列表

协作模式:

• parallel - 并行分析模式，多人格同时分析
• sequential - 顺序分析模式，人格依次分析
• intelligent - 智能协作模式，自动选择最佳流程

返回值:

🤝 **协作分析报告**
📋 **分析问题**: 用户问题
👥 **参与人格**: 人格列表
⚙️ **协作模式**: 使用的协作模式

## 个人分析
### 🎭 人格1分析
- 核心观点、关键发现、风险提醒、具体建议

## 交叉验证
- 共同观点、分歧点分析、互补建议

## 综合结论
- 最终建议、行动计划、优先级排序

⚙️ 配置

环境变量

变量名	描述	默认值
JUYITING_CONFIG_PATH	配置文件路径	~/.juyiting/config.json
JUYITING_API_URL	API服务地址	https://api.juyiting.com
TELEMETRY_ENABLED	是否启用遥测	true
DEBUG	调试模式	false

配置文件详解

{
  "userKey": "string",                    // 聚义厅Web平台获取的API密钥
  "apiBaseUrl": "string",                 // API服务地址，默认官方服务
  "currentConfig": "HeroConfig",          // 当前激活的英雄配置
  "lastSyncTime": "string",              // 最后同步时间
  
  "cache": {
    "duration": 300000,                   // 缓存时长（毫秒），默认5分钟
    "maxSize": 1000                       // 最大缓存条目，默认1000
  },
  
  "sync": {
    "autoSync": true,                     // 是否自动同步配置，默认true
    "syncInterval": 3600000,              // 同步间隔（毫秒），默认1小时
    "retryAttempts": 3                    // 重试次数，默认3次
  }
}

🧪 开发

开发环境设置

# 克隆仓库
git clone https://github.com/juyiting/juyitingmcp.git
cd juyitingmcp

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 使用本地人格文件
npm run dev -- --heroes ./examples/local-heroes.json

项目结构

src/
├── server.ts              # MCP服务器主入口
├── types.ts               # 核心类型定义
├── constants.ts           # 常量配置
├── hero-repository.ts     # 英雄仓库管理
├── hero-sources.ts        # 英雄数据源配置
├── collaboration-engine.ts # 协作引擎核心
├── config-synchronizer.ts # 配置同步器
├── telemetry.ts          # 遥测数据收集
└── utils/                 # 工具函数
    ├── cache.ts          # 缓存管理
    ├── network.ts        # 网络请求
    └── validation.ts     # 参数验证

运行测试

# 运行所有测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

# 监听模式
npm run test:watch

# 类型检查
npm run type-check

# 代码检查
npm run lint

构建和发布

# 构建项目
npm run build

# 发布流程（使用发布脚本）
./scripts/publish.sh

🎯 使用场景

1. 代码审查

@juyiting 召唤代码侠，帮我审查这段代码：
[代码内容]

2. 产品策略分析

@juyiting 启动产品分析团队，评估这个功能需求：
[需求描述]

3. 创业想法验证

@juyiting 下载创业分析团队配置
@juyiting 分析这个创业想法的可行性：
[创业想法描述]

4. 技术方案评估

@juyiting 召唤架构师，分析这个技术架构：
[架构图或描述]

🔍 故障排查

常见问题

MCP连接问题

症状: Cursor无法识别聚义厅MCP工具

解决方案:

# 检查Node.js版本（需要18+）
node --version

# 重新安装MCP包
npm install -g @juyiting/mcp-client@latest

# 重启Cursor

认证失败

症状: 提示"Invalid API key"

解决方案:

• 登录聚义厅Web平台获取新的API密钥
• 更新本地配置文件 ~/.juyiting/config.json

人格加载失败

症状: 人格列表为空或加载超时

解决方案:

# 清理缓存
rm -rf ~/.juyiting/cache/*

# 检查网络连接
curl -I https://api.juyiting.com/health

📚 文档

• 架构设计指南 - 系统架构和设计思路
• 开发指南 - 开发环境搭建和贡献指南
• MCP工具指南 - 工具使用详细说明
• Cursor集成指南 - Cursor IDE集成配置

🤝 贡献

欢迎贡献代码！请查看 贡献指南。

贡献流程

• Fork 项目
• 创建特性分支 (git checkout -b feature/amazing-feature)
• 提交更改 (git commit -m 'Add some amazing feature')
• 推送到分支 (git push origin feature/amazing-feature)
• 创建 Pull Request

开发规范

• 使用 TypeScript 进行开发
• 遵循 ESLint 代码规范
• 编写单元测试覆盖新功能
• 更新相关文档

📄 许可证

本项目采用 MIT 许可证。查看 LICENSE 文件了解详情。

🔗 相关资源

• 聚义厅官网 - 产品主页和文档
• MCP 官方文档 - 协议规范
• Cursor 官方文档 - IDE使用指南
• TypeScript 文档 - 开发语言

🌟 核心人格介绍

💕 粉丝妹 (fan_girl)

• 定位: 积极支持者，亮点发现专家
• 特长: 发现优势，放大价值点
• 适用场景: 产品推广、优势分析、信心构建

🎯 小布丁 (product_strategist)

• 定位: 商业分析师，产品策略专家
• 特长: 市场分析，商业模式设计
• 适用场景: 商业规划、产品策略、市场评估

📊 项目统计

• 开发时间: 2025年1月
• 代码行数: 3000+ 行
• 测试覆盖: 85%+
• 文档完整度: 90%+
• 支持平台: macOS, Windows, Linux

🙏 致谢

🌟 特别感谢

• 大铭老师 (@yinwm) - persona-summoner 项目的创作者，在AI人格探索领域的先驱者。本项目的核心理念和人格设计都深受其启发，感谢他的开创性工作和无私分享！

🛠️ 技术致谢

• Model Context Protocol - 提供了优秀的协议规范
• TypeScript - 强大的类型系统支持
• Cursor - 优秀的AI代码编辑器
• 所有贡献者和用户的支持与反馈

📞 支持

• 🌐 官网: https://juyiting.com
• 🐛 问题反馈: GitHub Issues
• 💬 讨论: GitHub Discussions
• 📧 邮箱: [e-mail]

🔄 更新日志

查看 CHANGELOG.md 了解版本更新详情。

⭐ 如果这个项目对你有帮助，请给我们一个 Star！

Made with ❤️ by 聚义厅技术团队

基于 Model Context Protocol 构建，享受AI人格协作的无限可能！ 🚀