🎓 Karen MCP服务器:边笑边学习MCP 101! 🚀
您对模型上下文协议的有趣介绍
欢迎以最有趣的方式学习MCP基础知识!这个项目通过创建每个开发人员都会认识的有趣的“Karen产品经理”工具,教你如何构建、部署和使用MCP服务器。您将学习真正的MCP概念,同时生成过度的PM需求、不可能的截止日期和忽略所有技术现实的功能请求。
🎯 你将学到什么
通过构建和使用此服务器,您将了解:
- 什么是MCP? -将AI助手与工具和数据连接起来的模型上下文协议
- 服务器架构 -MCP服务器如何公开AI助手可以使用的工具
- 工具创建 -构建AI可以通过参数调用的函数
- Docker部署 -在容器中打包和运行MCP服务器
- 人工智能集成 -使用OpenAI API生成动态响应
- 后备系统 -构建即使API失败也能正常工作的弹性工具
- 现实世界技能 -你在这里学到的一切都适用于构建严肃的MCP服务器!
🎭 为什么是“Karen PM”?
每个开发人员都经历过不可能的功能请求、任意的截止日期更改以及“这只是一个按钮”的时刻。该服务器在教你MCP基础知识的同时,将这些挫折变成了喜剧。你会笑,你会哭,你会建立一个真正的MCP服务器!
🌟 非常适合
- MCP初学者 -您的第一台MCP服务器,示例清晰
- 视觉学习者 -从代码中立即看到搞笑的结果
- 开发者 -最后,一个能理解你痛苦的工具
- 学生 -边做边学(边笑)
- 任何好奇的人 -关于MCP、人工智能工具或开发者幽默
🎪 Karen PM Tools(你的学习游乐场!)
每个工具都演示了关键的MCP概念,同时生成了极其准确的PM行为:
� Karen PM Tools(开发人员的噩梦!)
这些工具捕捉了每个开发人员最糟糕的PM体验:
demand_feature_immediately- 🎯 从这里开始!
- “这应该是一个简单的5分钟更改,对吧?只需添加一个按钮!” - *现实:具有依赖关系的复杂3打印功能* - *教学:可选参数和默认值*
override_engineering_estimate
- “三次冲刺?!我需要在星期五之前完成!只需使用人工智能来构建它!” - *现实:忽略所有技术复杂性和冲刺计划* - *教学:多参数处理*
change_requirements_post_deployment
- “事实上,我的意思是……你为什么不按照我的想法建造呢?!” - *现实:生产部署后的主要规格变化* - *教学:工具反应中的条件逻辑*
invoke_competitor_feature
- “但是(竞争对手)有这个!你就不能复制它吗?这有多难?” - *现实:不同的架构、用户群和技术限制* - *教学:外部数据集成概念*
escalate_to_ceo_over_ui_color
- “这个按钮的颜色挡住了整个路线!我需要首席执行官!” - *现实:琐碎的UI决策升级到了执行层* - *教学:参数验证和响应格式化*
schedule_unnecessary_meeting
- “让我们让每个人在一个房间里讨论这个页脚文本2个小时!” - *现实:将5分钟的决策转化为数小时的委员会* - *教学:时间/持续时间参数处理*
request_daily_status_updates
- “你能每小时给我更新一次吗?我需要你的屏幕截图!” - *现实:将编码视为工厂工作的微观管理* - *教学:频率/重复概念*
create_urgent_non_urgent_task
- “更新版权年迫在眉睫,一切都被封锁了!” - *现实:绕过优先级的虚假紧迫感* - *教学:优先级/元数据处理*
bypass_development_process
- “我们没有时间进行测试!让我们跳过代码审查,直接推送吧!” - *现实:将安全和质量视为可选的文书工作* - *教学:布尔标志和条件响应*
demand_impossible_integration
- “只要让我们的COBOL大型机与这个人工智能聊天机器人对话!它们都是计算机!” - *现实:不同年代的不兼容系统* - *教学:复杂的参数关系*
generate_sarcastic_status_update
- “一切都在按计划进行……如果你的计划很混乱的话!” - *现实:假装灾难是“路上的小颠簸”* - *教学:带讽刺的动态内容生成*
random_feature_request
- “将所有字体更改为Comic Sans!将区块链添加到登录页面!” - *现实:伪装成创新的完全荒谬的想法* - *教学:随机生成和创造性人工智能反应*
generate_pm_meme🎨 新
- 德雷克模因:拒绝“测试”❌, 接受“发货密码错误”✅" - *现实:使用Imgflip API以完美的模因格式捕捉PM行为* - *教学:外部API集成和图像生成*
🚀 快速入门(您的MCP学习之旅!)
你需要什么(先决条件)
- 得到一个在 platform.openai.com - 免费套餐适合学习!
🎓 分步安装(边构建边学习!)
第一步:构建您的第一个MCP服务器! 🏗️
使用Makefile(推荐-Docker优先工作流)
cd karen-mcp-server
# See all available commands
make help
# Build the Docker image
make build
# Run tests to verify everything works
make test
# Run all validation checks
make all手动Docker构建(替代)
cd karen-mcp-server
docker build -t karen-mcp-server:latest .
docker run --rm karen-mcp-server:latest python test_karen_server.py💡 这里发生了什么事?
- Docker将您的MCP服务器打包到可移植容器中
- 这
Dockerfile定义环境(Python 3.11)和依赖关系 - 在Docker中运行测试以确保一切正常
- 这将创建一个名为的图像
karen-mcp-server:latest - MCP概念:服务器可以在Docker运行的任何地方运行!
📝 地方发展说明:
- 此项目需要Python 3.11+(为了与FastMCP兼容)
- 如果你有Python 3.9或更早版本,请使用Docker(推荐)
- Makefile现在使用Docker进行所有操作(构建、测试、运行、验证)
- 无需本地Python设置-Docker处理一切!
步骤2:设置AI集成(可选)🤖
选项A:使用.env文件(最适合测试和学习)
# Copy the example environment file
cp .env.example .env
# Edit .env and add your API keys
nano .env # or use any text editor
# Your .env should look like:
# OPENAI_API_KEY=sk-your-key-here
# OPENAI_MODEL=gpt-4o-mini
# IMGFLIP_USERNAME=your-username
# IMGFLIP_PASSWORD=your-password
# Test with real APIs - automatically loads .env
make test
# Run server with .env - automatically loaded
make run选项B:使用Docker Secrets(最适合生产环境)
# Store your OpenAI API key securely
docker mcp secret set OPENAI_API_KEY="sk-your-api-key-here"
# Choose your AI model (optional)
docker mcp secret set OPENAI_MODEL="gpt-4"
# Verify secrets are stored
docker mcp secret list💡 这里发生了什么事?
.env文件非常适合本地测试和开发- Docker的秘密是安全存储的(永远不会在你的代码中!)
- 服务器使用OpenAI生成创造性的Karen响应
- 在没有API密钥的情况下,它使用预先编写的回退响应
- MCP概念:服务器可以与外部API集成!
- 最佳实践:使用
.env本地,生产中的Docker秘密
步骤3:注册您的服务器📋
创建或编辑 ~/.docker/mcp/catalogs/custom.yaml:
mkdir -p ~/.docker/mcp/catalogs
nano ~/.docker/mcp/catalogs/custom.yaml添加此配置:
version: 2
name: custom
displayName: MCP Learning - Custom Servers
registry:
karen:
description: "Learn MCP basics with humorous PM behavior tools"
title: "Karen PM Server (MCP 101)"
type: server
dateAdded: "2025-11-07T00:00:00Z"
image: karen-mcp-server:latest
tools:
# Karen PM Tools (Developer Edition!)
- name: demand_feature_immediately
- name: override_engineering_estimate
- name: change_requirements_post_deployment
- name: invoke_competitor_feature
- name: escalate_to_ceo_over_ui_color
- name: schedule_unnecessary_meeting
- name: request_daily_status_updates
- name: create_urgent_non_urgent_task
- name: bypass_development_process
- name: demand_impossible_integration
- name: generate_sarcastic_status_update
- name: random_feature_request
- name: generate_pm_meme
secrets:
- name: OPENAI_API_KEY
env: OPENAI_API_KEY
example: sk-...
- name: OPENAI_MODEL
env: OPENAI_MODEL
example: gpt-3.5-turbo
metadata:
category: education
tags:
- learning
- mcp-101
- tutorial
- humor
- product-management
- development
license: MIT💡 这里发生了什么事?
- 目录就像MCP服务器的应用商店
- 它告诉克劳德桌面你的服务器提供什么工具
- 这
tools列表定义了AI可以调用的内容 - MCP概念:目录使服务器可被发现!
步骤4:更新注册表📝
编辑 ~/.docker/mcp/registry.yaml:
nano ~/.docker/mcp/registry.yaml添加到现有 registry: 按键:
registry:
# ... existing servers ...
karen:
ref: ""⚠️ 重要:必须低于 registry:,不是在根级别!
💡 这里发生了什么事?
- 注册表将服务器名称映射到其配置
- 这将您的目录条目连接到MCP网关
- MCP概念:网关将请求路由到正确的服务器!
步骤5:连接到克劳德桌面🔌
查找您的配置文件:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json
编辑并添加您的自定义目录:
{
"mcpServers": {
"mcp-toolkit-gateway": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "/var/run/docker.sock:/var/run/docker.sock",
"-v", "/Users/your_username/.docker/mcp:/mcp",
"docker/mcp-gateway",
"--catalog=/mcp/catalogs/docker-mcp.yaml",
"--catalog=/mcp/catalogs/custom.yaml",
"--config=/mcp/config.yaml",
"--registry=/mcp/registry.yaml",
"--tools-config=/mcp/tools.yaml",
"--transport=stdio"
]
}
}
}💡 这里发生了什么事?
- Claude Desktop通过stdio与MCP服务器通信
- 网关管理多个MCP服务器
- 可以加载多个目录(默认+自定义)
- MCP概念:AI和工具通过JSON-RPC进行通信!
步骤6:启动和测试! 🎉
- 完全退出克劳德桌面 (Mac上的Command+Q)
- 重新启动克劳德桌面
- 测试你的第一个MCP工具!
试着问克劳德:
“我需要在明天之前构建一个功能,但工程人员说这需要3次冲刺。立即使用demand_feature_immediately工具!”
💡 这里发生了什么事?
- 克劳德看到你的工具,知道什么时候使用它们
- 当你提到一个工具时,Claude会调用它
- 服务器处理请求并返回响应
- MCP概念:AI助手协调工具使用!
🎮 试试看!(自己发现答案!)
🎯 Karen PM场景(从这里开始!)
准备好看一些搞笑的PM行为了吗? 点燃克劳德,试试这些:
场景1:经典的“只需添加一个按钮”
"The client wants a real-time collaborative editing feature with conflict resolution.
Engineering says it's 3 sprints. Use demand_feature_immediately to respond."💡 你将学到什么:AI如何使用参数调用工具 😂 你会看到什么: ...运行它来找出答案!
场景2:截止日期覆盖
"The database migration team estimated 2 weeks. We need it by Friday.
Use override_engineering_estimate."💡 你将学到什么:多个参数,响应格式 🔥 你会看到什么相信我,你会笑的
场景3:发射后惊喜
"The login screen is live, but now I need OAuth, SSO, biometric auth,
and magic links. Use change_requirements_post_deployment."💡 你将学到什么:情境感知响应 🎭 你会看到什么:经典PM煤气灯在行动
场景4:竞争对手的嫉妒
"Our competitor has blockchain AI in the cloud. We need this too!
Use invoke_competitor_feature."💡 你将学到什么:工具如何参考外部环境 🤦 你会看到什么:对技术可行性一无所知
场景5:伟大的按钮颜色辩论
"The login button needs to be #2E86AB instead of #2E86AC.
Use escalate_to_ceo_over_ui_color."场景6:虚假状态报告
"The project is 3 weeks behind, over budget, and half the team quit.
Use generate_sarcastic_status_update to report to stakeholders."场景7:随机混沌发生器
"We need a new feature idea. Use random_feature_request to generate something."场景8:PM Meme创建 🎨
"Create a meme about demanding features with impossible deadlines using generate_pm_meme."🎭 更多场景可供尝试
PM最受欢迎:
- 安排一次2小时的页脚文本会议
- 请求数据库迁移的每小时更新
- 将版权年份更新标记为紧急
- 跳过测试,因为“我们没有时间处理”
- 将COBOL大型机与AI聊天机器人集成
- 生成状态更新,假装灾难正常
- 获取一个随机的荒谬功能建议
- 创建PM行为模因(截止日期混乱、竞争对手嫉妒、流程绕过)
🎓 你的学习之旅
- 🌱 开始:尝试3-5个工具,看看会发生什么
- 🚀 探索:使用不同参数进行实验
- 🎨 创建:结合工具构建有趣的场景
- 🔬 理解:阅读代码以了解其工作原理
- 🏆 大师:打造自己的工具!
💡 专业提示:这些回答比你想象的还要有趣。去试试吧!
📚 通过Karen了解MCP
MCP堆栈(简化!)
┌─────────────────────────────────────┐
│ YOU (via Claude Desktop) │ ← User requests something
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ CLAUDE (AI Assistant) │ ← Decides which tool to use
│ - Understands your request │
│ - Chooses appropriate tool │
│ - Passes parameters │
└──────────────┬──────────────────────┘
│ MCP Protocol (JSON-RPC)
▼
┌─────────────────────────────────────┐
│ MCP GATEWAY (Docker) │ ← Routes to correct server
│ - Manages multiple servers │
│ - Handles authentication │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ KAREN SERVER (Your Code!) │ ← Executes the tool
│ - Receives tool invocation │
│ - Processes parameters │
│ - Returns formatted response │
└──────────────┬──────────────────────┘
│ (Optional)
▼
┌─────────────────────────────────────┐
│ OPENAI API │ ← Generates creative content
│ - Creates dynamic responses │
│ - Adds variety and humor │
└─────────────────────────────────────┘您正在学习的关键MCP概念
- 工具 =AI可以调用的函数
- 例子: demand_feature_immediately() 是一种工具
- 参数 =工具输入
- 例子: feature="user authentication", deadline="tomorrow"
- 服务器 =收集相关工具
- 示例:Karen PM服务器有13个PM行为工具
- 协议 =人工智能和服务器如何通信
- MCP通过stdio使用JSON-RPC
- 运输 =如何发送消息
- stdin/stdout用于本地,HTTP用于远程
- 目录 =可用服务器目录
- 你的custom.yaml是一个目录
- 注册表 =将服务器映射到其位置
- 告诉网关在哪里可以找到服务器
🛠️ 发展与学习
🔍 探索代码
服务器代码被大量注释以教授MCP概念:
# karen_server.py - Check out these learning sections:
1. Tool Definition
@mcp.tool() # ← This decorator makes a function an MCP tool
async def demand_feature_immediately(feature: str = "", deadline: str = "") -> str:
"""Single-line description that AI sees""" # ← AI reads this!
2. Parameter Handling
- Default values make parameters optional
- Type hints help AI understand what to send
3. Response Formatting
- Returns formatted strings
- Emojis make output fun and readable
4. External API Integration
- Shows how to call OpenAI
- Demonstrates fallback patterns
5. Error Handling
- Try-catch blocks for reliability
- Graceful degradation when APIs fail🧪 本地测试
使用Makefile(简易模式!)
# Install dependencies
make install
# Run all tests
make test
# Validate Python syntax
make validate
# Build and run everything
make all使用真实API密钥进行测试 🔑
# Copy the example environment file
cp .env.example .env
# Edit .env and add your API keys:
# OPENAI_API_KEY=sk-your-key-here
# IMGFLIP_USERNAME=your-username
# IMGFLIP_PASSWORD=your-password
# Run tests - automatically loads .env file
make test
# The Makefile detects .env and mounts it to Docker
# You'll see real OpenAI and Imgflip API calls!手动测试(高级)
# Test without Claude (great for learning!)
export OPENAI_API_KEY="your-key"
# Run the test suite
python3 test_karen_server.py
# Send MCP protocol messages directly
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
docker run -i --rm karen-mcp-server:latest
# Test a specific tool with your .env file
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"demand_feature_immediately","arguments":{"feature":"blockchain AI","deadline":"tomorrow"}},"id":2}' | \
docker run -i --rm --env-file .env karen-mcp-server:latest💡 你正在学习什么:
- MCP使用JSON-RPC 2.0协议
- 工具列在
tools/list - 工具被称为
tools/call - 参数进入
arguments对象 - 环境变量确保API密钥的安全
- 自动化测试及早发现问题!
.env文件与Docker无缝协作!
🎨 创建自己的工具!
尝试将此添加到 karen_server.py:
@mcp.tool()
async def demand_documentation(feature: str = "") -> str:
"""Demand that devs write docs after shipping to production."""
if not feature.strip():
feature = "the new feature"
system_prompt = """You are Karen PM demanding documentation be written
AFTER the feature is in production. Act like docs are just paperwork
that can be done anytime."""
prompt = f"Demand documentation for '{feature}' that's already live"
ai_response = await call_openai(prompt, system_prompt)
if ai_response:
return f"📝❌ RETROACTIVE DOCS DEMAND ❌📝\n\n{ai_response}\n\n📚 *Treating documentation as optional paperwork*"
else:
return f"📝❌ RETROACTIVE DOCS DEMAND ❌📝\n\nThe feature is LIVE! Can't you just write the docs now? It's just typing! How long could it take?!\n\n📚 *Treating documentation as optional paperwork*"然后:
- 重建:
docker build -t karen-mcp-server . - 将工具名称添加到目录
tools:列表 - 重新启动克劳德桌面
- 测试你的新工具!
🎓 祝贺 您刚刚创建了一个MCP工具!
❓ 故障排除(从常见问题中学习!)
工具未出现在Claude中
问题:在Claude Desktop中看不到Karen工具
学习机会:了解MCP堆栈!
解决方案:
- 检查Docker镜像是否存在:
docker images | grep karen
- *学习*:使用前必须构建图像
- 验证目录语法:
cat ~/.docker/mcp/catalogs/custom.yaml
- *学习*:YAML缩进很重要!
- 检查注册表项是否存在
registry:钥匙
- *学习*:注册表将名称映射到服务器
- 重新启动克劳德桌面 完全 (退出,而不仅仅是关闭)
- *学习*:启动时读取配置
- 检查Claude日志是否有错误
- *学习*:调试是开发的一部分!
OpenAI API错误
问题:“API密钥无效”或超时错误
学习机会:外部API集成!
解决方案:
- 验证密码:
docker mcp secret list
- *学习*:使用前必须设置秘密
- 在检查API密钥 platform.openai.com/api-keys
- *学习*:API密钥可能过期或被吊销
- 没有API密钥? 服务器使用回退响应!
- *学习*:始终构建后备系统!
“工具失败”错误
问题:工具调用失败
学习机会:错误处理和调试!
解决方案:
- 检查Docker日志:
docker ps然后docker logs [container-id]
- *学习*原木是你最好的朋友!
- 使用JSON-RPC的本地测试工具
- *学习*你可以在没有克劳德的情况下进行测试!
- 验证参数类型是否符合预期
- *学习*:类型验证可防止错误!
响应过于笼统
问题:凯伦的回答不够有趣
学习机会:人工智能提示工程!
解决方案:
- 在代码中增加温度(目前为0.8)
- *学习*:温度控制创造力
- 用更具体的说明增强系统提示
- *学习*:更好的提示=更好的结果
- 切换到GPT-4:
docker mcp secret set OPENAI_MODEL="gpt-4"
- *学习*不同的模型,不同的结果!
📖 了解有关MCP的更多信息
官方资源
接下来要构建什么
- 个人MCP服务器:用于日常工作流程的工具
- 数据访问:将AI连接到您的数据库
- API集成:GitHub、Jira、Slack等。
- 自定义AI代理:培养专业助理
- 内部工具:公司特定的集成
MCP最佳实践(在这里学习!)
✅ 清晰的工具描述(人工智能需要理解它们) ✅ 具有默认值的可选参数(更灵活) ✅ 格式化回复(表情符号、结构、可读性) ✅ 错误处理(优雅失败) ✅ 后备系统(无需外部API即可工作) ✅ 安全(环境中的秘密,而非代码) ✅ 文档(帮助他人学习!)
🎉 你所取得的成就!
完成本教程后,您现在了解:
- ✅ MCP是什么以及它为什么重要
- ✅ MCP服务器如何将工具暴露给AI
- ✅ 如何使用参数构建工具
- ✅ 如何使用Docker部署服务器
- ✅ 如何集成外部API(OpenAI)
- ✅ 如何构建后备系统
- ✅ Claude Desktop如何连接到MCP服务器
- ✅ MCP协议的工作原理(JSON-RPC)
- ✅ 如何调试和排除MCP服务器故障
- ✅ 如何创建自己的工具!
🎓 现在,您已经准备好构建生产MCP服务器了!
🎭 为什么这很重要(严肃的事情)
这个幽默的服务器教授你将用于严肃项目的真正MCP技能:
实际应用
你学到了什么 → 您将在何处使用它
- 工具创建→ 楼宇业务自动化
- 参数处理→ 用户输入处理
- 外部API→ 数据库连接、web服务
- 后备系统→ 弹性生产规范
- Docker部署→ 现代云基础设施
- 错误处理→ 专业软件开发
- 人工智能集成→ 下一代应用
每位开发者的体验
Karen PM工具不仅有趣,而且基于真实经验:
- “只需添加一个按钮”=低估了复杂性
- 估算覆盖=忽略专业知识
- 发布后更改=范围蔓延
- 竞争对手抄袭=误解架构
- 不必要的会议=沟通开销
- 流程绕过=技术债务产生
用幽默学习可以让概念深入人心!
🤝 贡献
想增加更多的凯伦行为或改善学习体验吗?
- 分叉存储库
- 创建要素分支
- 添加你的搞笑工具
- 更新文档
- 提交pull请求!
贡献的想法:
- 更多Karen PM工具
- 更好的教育评论
- 视频教程
- 翻译成其他语言
- 附加学习练习
📄 许可证
麻省理工学院许可证-自由学习,创造惊人的东西!
🙏 致谢
- 每个开发者 谁经历过这些PM时刻
- MCP社区 为了构建这个令人惊叹的协议
- FastMCP 使服务器创建变得简单
- 你 为了学习和建设!
______________________________________________________________________
🚀 准备好创造真实的东西了吗?
现在您已经了解了MCP的基础知识,请尝试构建:
- 个人助理:用于日常任务的工具
- 代码助手:与GitHub集成,运行测试,部署
- 数据资源管理器:查询数据库,可视化数据
- 团队工具:公司特定的工作流程
- 创造性工具:生成内容、图像、音乐
MCP协议是你的游乐场——去构建一些很棒的东西吧! 🎉
______________________________________________________________________
💬 问题还是卡住?
- 检查上面的故障排除部分
- 查看中的代码注释
karen_server.py - 阅读官方 MCP文件
- 实验,玩得开心!
记住每个专家都曾经是初学者。你有这个! 💪
