Skip to main content
Glama
juyitingmcp

聚义厅MCP

by juyitingmcp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

聚义厅MCP客户端 🎭

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

🙏 致谢声明

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

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

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

npm version npm downloads GitHub Workflow Status Codecov TypeScript

GitHub license GitHub stars GitHub forks GitHub issues PRs Welcome

Node.js Maintenance Last Commit Bundle Size

Related MCP server: mcp-agent-forge

📖 简介

聚义厅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

📚 文档

🤝 贡献

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

贡献流程

  1. Fork 项目

  2. 创建特性分支 (git checkout -b feature/amazing-feature)

  3. 提交更改 (git commit -m 'Add some amazing feature')

  4. 推送到分支 (git push origin feature/amazing-feature)

  5. 创建 Pull Request

开发规范

  • 使用 TypeScript 进行开发

  • 遵循 ESLint 代码规范

  • 编写单元测试覆盖新功能

  • 更新相关文档

📄 许可证

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

🔗 相关资源

🌟 核心人格介绍

💕 粉丝妹 (fan_girl)

  • 定位: 积极支持者，亮点发现专家

  • 特长: 发现优势，放大价值点

  • 适用场景: 产品推广、优势分析、信心构建

🎯 小布丁 (product_strategist)

  • 定位: 商业分析师，产品策略专家

  • 特长: 市场分析，商业模式设计

  • 适用场景: 商业规划、产品策略、市场评估

📊 项目统计

  • 开发时间: 2025年1月

  • 代码行数: 3000+ 行

  • 测试覆盖: 85%+

  • 文档完整度: 90%+

  • 支持平台: macOS, Windows, Linux

🙏 致谢

🌟 特别感谢

🛠️ 技术致谢

📞 支持

🔄 更新日志

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

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

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

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

Available Tools

3 tools
list_heroes列出所有英雄C

显示聚义厅中所有可用的英雄角色

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNo可选：按分类筛选英雄
sourceNo可选：按数据源筛选英雄

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it 'displays' heroes, which suggests a read-only operation, but doesn't clarify if it's safe, if it requires authentication, what the output format is (e.g., list, pagination), or any rate limits. For a tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence in Chinese that directly states the tool's purpose without unnecessary words. It is front-loaded and appropriately sized for a simple listing tool, with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no annotations, no output schema, and two parameters, the description is incomplete. It doesn't explain the return values (e.g., what data about heroes is shown), behavioral aspects like safety or performance, or how to interpret the parameters beyond the schema. For a tool with this complexity, more context is needed to guide the agent effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters ('category' and 'source') well-documented in the schema, including an enum for 'source'. The description does not add any meaning beyond the schema, such as explaining what 'category' values might be or how filtering works. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('显示' meaning 'display') and the resource ('所有可用的英雄角色' meaning 'all available hero characters'), with the specific context of '聚义厅' (likely a game or system name). It distinguishes from 'summon_hero' (which likely creates or invokes a hero) but not explicitly from 'search_heroes' (which might offer more advanced filtering). The purpose is clear but sibling differentiation is incomplete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like 'search_heroes' is provided. The description implies it lists all heroes, but it doesn't specify if 'search_heroes' is for more complex queries or if this tool is the default for basic listing. Usage context is implied but not stated, leaving gaps for the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_heroes搜索英雄C

根据关键词搜索匹配的英雄角色

ParametersJSON Schema
NameRequiredDescriptionDefault
keywordYes搜索关键词，可以是英雄名称或描述中的词语

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action ('搜索' - search) without detailing what '匹配' (matching) entails (e.g., partial/full matches, case sensitivity), the scope of search (e.g., across names, descriptions, or other attributes), or any limitations (e.g., rate limits, authentication needs). For a search tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence: '根据关键词搜索匹配的英雄角色' (search for matching hero characters based on keywords). It is front-loaded with the core action and resource, with no wasted words, making it highly concise and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a search function with one parameter) and the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., a list of heroes, details, or just IDs), how results are formatted, or any error conditions. For a tool with no structured output information, the description should provide more context about behavioral outcomes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the parameter 'keyword' fully documented in the schema as '搜索关键词，可以是英雄名称或描述中的词语' (search keyword, which can be hero name or words in description). The description adds no additional meaning beyond this, so it meets the baseline score of 3 where the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '根据关键词搜索匹配的英雄角色' (search for matching hero characters based on keywords). It specifies the verb '搜索' (search) and resource '英雄角色' (hero characters), making the function unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_heroes' or 'summon_hero', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_heroes' (which might list all heroes without filtering) or 'summon_hero' (which might involve a different action), nor does it specify any prerequisites or exclusions for usage. This leaves the agent without context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

summon_hero召唤英雄C

从聚义厅召唤指定的英雄角色

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes英雄名称，如：粉丝妹、小布丁、暖心姐姐、拆解大师等

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('summon') but doesn't explain what 'summon' entails—whether it's a read, write, or side-effect operation, what permissions are needed, or what the outcome looks like. This leaves critical behavioral traits unspecified for a tool that likely performs an action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence in Chinese that directly states the tool's purpose. It's front-loaded with the core action and resource, with no wasted words. However, it could be slightly more structured by explicitly mentioning the parameter or outcome.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a 'summon' action with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after summoning (e.g., success/failure, side effects, or return values), leaving gaps in understanding the tool's full behavior and context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the parameter 'name' documented as '英雄名称' (hero name) with examples. The description adds no additional meaning beyond the schema, such as format constraints or usage context. Baseline 3 is appropriate since the schema adequately covers the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('召唤' meaning 'summon') and the resource ('英雄角色' meaning 'hero character'), specifying it's from '聚义厅' (a gathering hall). It distinguishes from siblings like 'list_heroes' and 'search_heroes' by being an invocation rather than a query. However, it doesn't explicitly differentiate the scope or verb specificity beyond the basic action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'list_heroes' or 'search_heroes'. The description implies it's for summoning a specific hero, but it doesn't state prerequisites, exclusions, or contextual cues for choosing this over sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedlist_heroes
    • First observedsearch_heroes
    • First observedsummon_hero
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: list_heroes displays all heroes, search_heroes finds heroes based on keywords, and summon_hero calls a specific hero. There is no overlap or ambiguity between these operations.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (list_heroes, search_heroes, summon_hero) with snake_case. The naming is predictable and uniform throughout the set.

Tool Count4/5

With 3 tools, the server is well-scoped for managing a hero roster, but it feels slightly thin as it lacks operations like updating or removing heroes. However, the core functions are covered appropriately.

Completeness4/5

The tools cover listing, searching, and summoning heroes, which are essential operations for the domain. Minor gaps exist, such as no update or delete tools, but agents can work around this for basic functionality.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers