🎯 个性教练MCP服务器-Puch AI黑客马拉松项目

基于模型上下文协议（MCP）构建的全面MBTI人格评估和辅导平台

该项目是一个复杂的人格辅导系统，结合了MBTI人格评估、智能匹配算法和个性化辅导工具。它是为Puch AI黑客马拉松而设计的，展示了MCP在创造人工智能驱动的个性见解和关系指导方面的力量。

🌟 项目概述

个性教练MCP服务器是一个功能齐全的个性评估和指导平台，提供：

MBTI人格评估：带有统计置信度评分的16题高级测验
智能匹配系统：算法驱动的个性兼容性匹配
个性化辅导：沟通和建立关系的情境感知技巧
实时通信工具：信息翻译和语调调整
持久用户配置文件：使用PostgreSQL/Supabase完成用户状态管理

🛠 技术栈

核心技术

Python 3.11+：现代异步/等待架构
FastMCP：高性能MCP服务器框架
HTTPX：带连接池的异步HTTP客户端
派丹蒂克：类型安全数据验证和序列化

身份验证和安全

承载令牌身份验证：基于RSA的JWT令牌验证
OAuth2支持：行业标准身份验证协议
安全密钥管理：基于环境的配置

数据库和持久性

PostgreSQL：通过Supabase建立主数据库
PostgREST：用于数据库操作的RESTful API层
JSONB 存储：灵活的个性数据模式
自动时间戳：带有触发器的审计跟踪

集装箱化和部署

码头工人：具有多阶段构建的容器化部署
Docker Compose：精心编排的开发环境
健康检查：内置监控和日志记录
环境变量：可配置的部署设置

数据处理与分析

美丽的汤：用于网页抓取的HTML解析
可读性：内容提取和简化
Markdownify：HTML到Markdown的转换
统计分析：置信度评分算法

🧠 核心功能

1.高级人格评估

MBTI测验引擎

16问题评估：涵盖所有四个人格轴的科学问题
多格式输入支持:

- 紧凑字符串格式(1a 2b 3c 4d) - 结构化JSON响应 - 自然语言回答（“强烈同意”、“中立”）

统计置信度评分：逐轴置信度指标（0-1标度）
响应消毒：强大的输入验证和规范化

# Example quiz generation
{
  "version": "1.0",
  "variant": "fixed", 
  "scale": {
    "labels": ["Strongly disagree", "Disagree", "Slightly disagree", "Neutral", 
               "Slightly agree", "Agree", "Strongly agree"],
    "values": [-3, -2, -1, 0, 1, 2, 3]
  },
  "questions": [
    {
      "id": "EI-1",
      "axis": "EI", 
      "prompt": "I feel energized by group conversations.",
      "positive_pole": "E"
    }
  ]
}

人格类型计算

轴评分：E/I、S/N、T/F、J/P维度的独立评分
类型派生：16类分类的算法计算
信心指标：每个轴的统计可靠性度量
数据验证：全面的输入净化和错误处理

2.智能匹配系统（即将推出）

兼容性算法

类型兼容性评分：多维人格契合度分析
共享兴趣检测：基于主题的关联度匹配
可用性重叠：时间窗交点计算
意图对齐：目的驱动的匹配（网络、指导等）

匹配功能

排名结果：带解释的评分候选人名单
简明语言基本原理：人类可读的匹配解释
可配置限制：结果集大小可调
实时更新：配置文件更改时的动态匹配

# Example match result
{
  "match_id": "user1|user2",
  "score": 3.2,
  "rationale": "Matched due to shared interests in AI, startups, type fit INTJ × ENFP, 
               similar intent, and time overlap Monday 19:00-20:00.",
  "shared_topics": ["ai", "startups"],
  "availability_overlap": "Monday 19:00-20:00"
}

3.综合辅导体系

沟通辅导

特定类型提示：针对每种MBTI类型的沟通提供量身定制的建议
情境感知指导：针对具体情况的辅导（反馈、协作、冲突）
微观辅导：快速、可操作的建议，可立即使用

消息翻译

音调自适应：为特定性格类型重写消息
风格脚手架：用于有效沟通的结构化模板
偏好匹配：根据收件人偏好调整沟通风格

职业与关系指导

综合的意见：针对所有16种性格类型的详细指导
优势和陷阱：对特定类型挑战的平衡观点
警告标志：潜在问题的早期指标
成功策略：每种类型的成熟方法

4.用户资料管理

配置文件组件

个性化数据：类型、置信度得分、测验历史
可用性窗口：灵活的基于时间的日程安排
兴趣话题：标签偏好系统
意图分类：目的驱动的分类
对应方管理：存储用于指导的参考类型

数据持久层

PostgreSQL后端：可靠、符合ACID标准的存储
自动时间戳：创建/更新跟踪
JSONB 灵活性：无模式首选项存储
迁移支持：向后兼容的架构更新

🏗 建筑

服务器架构

┌─────────────────────────────────────────────────────────────┐
│                    MCP Server (FastMCP)                    │
├─────────────────────────────────────────────────────────────┤
│  Authentication Layer (Bearer Token + RSA)                 │
├─────────────────────────────────────────────────────────────┤
│                    Business Logic                          │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐         │
│  │ Quiz Engine │ │  Matching   │ │  Coaching   │         │
│  │             │ │  Algorithm  │ │  System     │         │
│  └─────────────┘ └─────────────┘ └─────────────┘         │
├─────────────────────────────────────────────────────────────┤
│                 Database Layer (db.py)                     │
├─────────────────────────────────────────────────────────────┤
│               Supabase/PostgreSQL                          │
└─────────────────────────────────────────────────────────────┘

数据流

认证：通过RSA密钥对验证承载令牌
请求处理：Pydantic验证和类型检查
业务逻辑：特定领域的处理（测验、匹配、指导）
数据持久层：通过PostgREST异步数据库操作
响应生成：带错误处理的JSON序列化

数据库模式

-- Core personality data
users_quiz (user_id, type, confidence_by_axis, axis_sums, raw_answers, sanitized_answers)

-- User preferences and matching data  
users_profile (user_id, type, availability, topics, intent, is_looking)

-- Coaching relationships
user_counterpart_type (user_id, counterpart_type)

-- Communication rooms
rooms (room_id, participants, tokens, expires_at)

🚀 入门指南

先决条件

Python 3.11+：支持异步的现代Python
Docker&Docker编写：用于集装箱化部署
辅助数据库账户：用于持久数据存储
ngrok账户：用于公共HTTPS端点（开发）

快速设置

克隆并安装

git clone 
cd puchaihackathon/mcp-starter
uv venv && uv sync
source .venv/bin/activate

配置环境

cp .env.example .env
# Edit .env with your tokens and Supabase credentials

设置数据库

# In Supabase SQL editor, run the contents of supabase_schema.sql

运行服务器

# Local development
cd mcp-bearer-token && python mcp_starter.py

# Or with Docker
docker compose up -d

公开曝光

ngrok http 8086
# Note the HTTPS URL for Puch AI connection

环境配置

变量	描述	必填
`AUTH_TOKEN`	秘密身份验证令牌	✅
`MY_NUMBER`	WhatsApp号码（格式：919876543210）	✅
`SUPABASE_URL`	Supabase项目URL	✅
`SUPABASE_SERVICE_ROLE_KEY`	Supabase服务角色键	✅
`LOG_LEVEL`	记录详细信息（信息、调试）	❌
`HTTP_MAX_CONNECTIONS`	HTTP客户端连接池大小	❌
`HTTP_MAX_KEEPALIVE`	HTTP保持活动连接	❌

🔧 api参考

核心工具

`generate_quiz()`

生成标准化的16题MBTI评估。

参数：无（固定配置）退货：带问题和规模的JSON测验结构

`submit_quiz_compact(user_id, answers_compact)`

以紧凑的字符串格式处理测验答案。

参数:

user_id：唯一用户标识符
answers_compact：类似“1a 2b 3c 4d 5e 6f 7g 8a…”的字符串

退货: {type: "INTJ", confidence_by_axis: {EI: 0.8, SN: 0.9, TF: 0.7, JP: 0.85}}

`save_profile(user_id, type?, preferences?)`

存储用户配置文件和匹配的首选项。

参数:

user_id：用户标识符
type：MBTI类型（如果测验完成，则可选）
preferences：可用性、主题、意图、is_looking

退货: {ok: true, type: "INTJ"}

`find_matches(user_id, limit?)`

为用户查找兼容的个性匹配项。

参数:

user_id：用户查找匹配项
limit：最大结果（默认值：5）

退货：带有分数和理由的匹配对象数组

`coach_tip(user_id, context, target_type?)`

为特定场景提供沟通指导。

参数:

user_id：请求用户
context：情况描述
target_type：要与之通信的MBTI类型

退货: {target_type: "ESFJ", tips: ["tip1", "tip2", "tip3"]}

`translate(message, target_type)`

根据特定的性格类型重写消息。

参数:

message：原始消息
target_type：要适应的MBTI类型

退货: {target_type: "ISFJ", rewritten: "adapted message"}

实用工具

`validate()`

身份验证（Puch AI要求）。退货：电话号码字符串

`check_user_data_status(user_id)`

检查现有用户数据以引导对话流。退货：带有数据可用性标志的状态对象

`get_personality_guidance(user_id, guidance_type?)`

全面的职业和人际关系建议。退货：基于性格类型的详细指导

🎯 使用示例

完整的人格评估流程

# 1. Generate quiz
/mcp tool generate_quiz {}

# 2. Present questions to user and collect responses
# 3. Submit compact answers
/mcp tool submit_quiz_compact {
  "user_id": "user123",
  "answers_compact": "1a 2c 3e 4b 5f 6d 7g 8a 9c 10e 11b 12f 13d 14g 15a 16c"
}

# 4. Save user preferences
/mcp tool save_profile {
  "user_id": "user123",
  "preferences": {
    "availability": [{"day": "monday", "start": "18:00", "end": "20:00"}],
    "topics": ["technology", "entrepreneurship"],
    "intent": "networking"
  }
}

# 5. Find matches
/mcp tool find_matches {"user_id": "user123", "limit": 3}

沟通辅导示例

# Set a counterpart type for ongoing coaching
/mcp tool set_counterpart {
  "user_id": "user123", 
  "counterpart_type": "ESFJ"
}

# Get situational coaching tips
/mcp tool coach_tip {
  "user_id": "user123",
  "context": "need to give constructive feedback about missed deadline"
}

# Translate message for specific type
/mcp tool translate {
  "message": "We need to discuss the project timeline",
  "target_type": "ISFP"
}

🔍 技术深度潜水

人格评估算法

评估使用了一个复杂的评分系统：

题库：为每个MBTI轴精心设计的问题
响应映射：灵活的输入处理（字母、数字、文本）
置信度计算：每个轴的统计可靠性
类型派生：根据轴分数进行算法类型计算

匹配算法

兼容性评分考虑了多个因素：

def _type_fit_score(t1: str, t2: str, c1: dict, c2: dict) -> float:
    # Base compatibility by axis similarity/difference
    # Weighted by confidence levels
    # Returns 0-4 scale score

因素：

个性兼容性：MBTI类型的交互模式
共同利益：主题重叠分析
计划对齐：时间窗交点
意图匹配：目的兼容性

数据安全与隐私

承载令牌身份验证：安全的API访问
基于环境的秘密：没有硬编码凭据
输入消毒：全面验证
错误处理：优雅的故障模式
审计跟踪：自动时间戳跟踪

📊 性能和可扩展性

优化功能

连接池：具有持久连接的异步HTTP客户端
数据库索引：使用适当的索引优化查询
缓存策略：对频繁访问的数据进行内存缓存
异步架构：全程无阻塞I/O

监控和记录

结构化日志记录：带有相关ID的JSON格式日志
错误跟踪：全面的异常处理
性能指标：请求定时和吞吐量监控
健康检查：内置端点监控

🚀 部署选项

发展（地方）

python mcp-bearer-token/mcp_starter.py
ngrok http 8086

生产（Docker）

docker compose up -d
# Configure reverse proxy (nginx, traefik) for HTTPS

云平台

铁路: railway up 使用 Dockerfile
渲染：使用自动部署连接GitHub仓库
Heroku: git push heroku main
数字海洋应用平台：从GitHub导入

🤝 连接到Puch AI

启动MCP服务器 （本地或部署）
通过HTTPS公开 （韩国促进发展）
连接Puch AI:

   /mcp connect https://your-domain.ngrok.app/mcp your_auth_token

验证连接:

   /mcp validate

🛡 安全考虑

认证：带有RSA签名验证的承载令牌
输入验证：带类型检查的Pydantic模型
SQL注入：通过PostgREST进行参数化查询
速率限制：HTTP客户端超时和重试逻辑
错误清理：错误消息中没有敏感数据

🧪 测试

单元测试

pytest mcp-bearer-token/test_quiz_utils.py -v

集成测试

# Test full quiz flow
/mcp tool generate_quiz {}
/mcp tool submit_quiz_compact {"user_id": "test", "answers_compact": "1a 2b 3c 4d"}

负载测试

# Test concurrent connections
ab -n 100 -c 10 http://localhost:8086/health

📈 未来的增强功能

计划的功能

高级分析：人格趋势分析
集团动态：团队兼容性评估
学习算法：自适应匹配改进
移动应用程序：原生iOS/Android客户端
视频辅导：实时对话分析

📚 资源和文件

官方文件

Puch AI MCP文档: https://puch.ai/mcp
FastMCP框架: https://github.com/puchao/fastmcp
模型上下文协议: https://modelcontextprotocol.io

MBTI与人格科学

迈尔斯·布里格斯基金会: https://www.myersbriggs.org
人格研究：关于类型理论的学术论文
统计有效性：可靠性和有效性研究

技术参考

异步Python: https://docs.python.org/3/library/asyncio.html
PostgreSQL JSONB: https://www.postgresql.org/docs/current/datatype-json.html
Supabase：https://supabase.com/docs

🤝 贡献

我们欢迎捐款！请参阅我们的投稿指南：

分叉存储库
创建要素分支: git checkout -b feature/amazing-feature
提交更改: git commit -m 'Add amazing feature'
推送到分支: git push origin feature/amazing-feature
打开拉取请求

开发设置

git clone 
cd puchaihackathon/mcp-starter
uv venv && uv sync
pre-commit install  # Code formatting and linting

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🏆 黑客马拉松背景

这个项目是为 Puch AI黑客马拉松 展示模型上下文协议在创建复杂的AI驱动应用程序方面的能力。它展示了：

高级MCP集成：复杂的工具编排
实际应用：实用的个性辅导
技术卓越：生产就绪架构
创新：新颖的人格评估方法

Puchai Hackathon MCP Server

快速接入

详细介绍