Kaedim MCP 代理
A. 模型上下文协议（MCP） 实现智能3D资产请求处理。采用事件驱动、工具化的架构，自动化完成从验证→规划→艺术家分配→交付的完整生命周期。
这个系统的作用
自动化3D资产创建工作室操作：
- 验证 技术要求
- 计划 最佳工作流程
- 分配（或指定） 最优秀的可用艺术家
- 执行 生产过程
- 交付 最终资产
📦 设置
先决条件Python 3.11+，Git，终端
# Quick start
git clone https://github.com/BryanTJJ99/Kaedim_MCP_Agent.git
cd Kaedim_MCP_Agent
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python3 -c "import mcp; print('✅ MCP SDK installed')"可选的大语言模型（LLM）集成 (创建 .env):
OPENAI_API_KEY=your_key_here
OPENAI_MODEL=gpt-4o-mini
MCP_HTTP_BASE_URL=http://127.0.0.1:8765数据包含在其中的示例数据 data/ （请求、艺术家、预设、规则）
🚀 使用方法
两种部署模式：
1. Stdio 模式 （开发）
cd Kaedim_MCP_Agent && source .venv/bin/activate
# Basic processing
python3 run_agent.py --requests data/requests.json --artists data/artists.json --presets data/presets.json --rules data/rules.json
# With LLM enhancement for ReAct (requires OPENAI_API_KEY)
python3 run_agent.py --requests data/requests.json --artists data/artists.json --presets data/presets.json --rules data/rules.json --agent-type llm2. HTTP 模式 (生产)
# Terminal 1: Start server
uvicorn mcp_server_http:app --host 127.0.0.1 --port 8765
# Terminal 2: Run client (With LLM enhancement for ReAct (requires OPENAI_API_KEY)
python3 run_agent_http.py --requests data/requests.json --artists data/artists.json --presets data/presets.json --rules data/rules.json --server-url http://127.0.0.1:8765 --agent-type llm选项
| 选项 | 描述 | 示例 |
|---|---|---|
--agent-type | mcp 或者 llm | --agent-type llm |
--output | 输出文件 | --output my_decisions.json |
--server-url | HTTP服务器URL | --server-url http://127.0.0.1:8765 |
输出： decisions.json （主要结果）， mcp.log (调试信息)
🧪 测试与项目结构
# Run tests
python3 run_tests.py # All tests
python3 run_tests.py --skip-performance # Faster
python3 test_basic.py # Basic only覆盖范围✅ 验证 ✅ 容量溢出 ✅ 恒等性 ✅ 业务规则 ✅ 错误处理
Kaedim_MCP_Agent/
├── run_agent.py / run_agent_http.py # Clients
├── mcp_server.py / mcp_server_http.py # Servers
├── data/ # Sample data
├── tests/ # Test suites
└── decisions.json / mcp.log # Output建筑学
该系统展示出 两种MCP部署模式 展示不同的应用场景：
模式1：基于标准输入输出的MCP（开发与单客户端）
┌─────────────────────┐ MCP Protocol ┌─────────────────────┐
│ │ (stdio) │ │
│ MCP Client │◄──────────────────► │ MCP Server │
│ (run_agent.py) │ │ (mcp_server.py) │
│ │ │ │
│ - Process requests │ │ - validate_preset │
│ - Launch server │ │ - plan_steps │
│ - Generate decisions│ │ - assign_artist │
│ - Customer messages │ │ - record_decision │
└─────────────────────┘ └─────────────────────┘
│ ▲
└─── Spawns as child process ──────────────┘模式2：基于HTTP的MCP（生产环境与多客户端）
┌─────────────────────┐ HTTP/JSON-RPC ┌─────────────────────┐
│ MCP Client A │◄──────────────────► │ │
│ (run_agent_http.py) │ │ Long-Lived │
└─────────────────────┘ │ MCP Server │
│ (mcp_server_http.py)│
┌─────────────────────┐ HTTP/JSON-RPC │ │
│ MCP Client B │◄──────────────────► │ - validate_preset │
│ (run_agent_http.py) │ │ - plan_steps │
└─────────────────────┘ │ - assign_artist │
│ - record_decision │
┌─────────────────────┐ HTTP/JSON-RPC │ - Shared state │
│ MCP Client C │◄──────────────────► │ - Concurrent access │
│ ... │ │ │
└─────────────────────┘ └─────────────────────┘🛠 MCP 工具：系统的核心
每个工具都代表了3D资产生产流程中的一个关键决策点。以下是每个工具背后直观的逻辑：
🔍（放大镜图标，常用于表示搜索、查看细节等动作） validate_preset(request_id, account_id)
“从技术上讲，我们能提供客户想要的东西吗？”
问题每位客户都有独特的技术需求——不同的命名规范、纹理打包格式和质量标准。处理配置无效的请求会浪费艺术家们数天的时间，并导致生成无法使用的资源。
逻辑：
- 命名验证检查客户的文件命名模式是否配置正确（例如，“AXR\*{资产}\*{lod}”）
- 纹理打包验证确保所有4个RGBA通道都被正确映射（红色=遮挡，绿色=金属度，蓝色=粗糙度，透明度=自发光）
- 版本兼容性验证已指定预设版本且该版本受支持
现实世界中的例子:
- ✅ ArcadiaXR 配置完整 → “验证通过（v3）”
- ❌ TitanMfg 缺少 alpha 通道 → “缺少纹理通道：a”
- ❌ BlueNova 没有配置 → “未找到纹理打包配置”
回报： {ok: boolean, errors: string[], preset_version: number}
______________________________________________________________________
📋（清单/待办事项列表） plan_steps(request_id)
“创建这个资源的最佳工作流程是什么？”
问题不同的资产类型需要不同的制作步骤。一个风格化的角色需要不同于真实车辆的工作流程。业务规则决定了特定的要求（优先级队列、特定的导出格式、质量检查）。
逻辑：
- 基础工作流程从标准步骤开始：
qa_check → delivery - 规则匹配扫描业务规则以添加专门步骤：
- 账户“ArcadiaXR”+ 风格“stylized_hard_surface”→ 添加 style_tweak_review - 引擎“Unreal”→ 添加 export_unreal_glb - 拓扑“仅四边形”→ 添加 validate_topology_quad_only - 优先级“priority” → 启用加急队列（24小时服务级别协议）
- 时间估算根据复杂性和特殊要求计算工时
现实世界中的例子：
req-001 (ArcadiaXR, Unreal, stylized) →
["style_tweak_review", "export_unreal_glb", "qa_check", "delivery"]
Estimated: 14 hours退货： **Returns**: {步骤: 字符串数组, 匹配规则: 规则匹配数组, 估计小时数: 数字, 优先队列: 布尔值}\`
______________________________________________________________________
👩🎨（女画家） assign_artist(request_id)
“目前谁是能满足这个特定需求的最佳艺术家？”
问题不同的艺术家有不同的专长、可用性和工作量。风格化角色专家不应被分配绘制写实车辆的任务，而工作量已超负荷的艺术家也不应再被分配更多工作。系统需要智能匹配，综合考虑技能、能力和业务优先级。
逻辑:
1. 技能评分计算每位艺术家与请求要求的匹配程度 2. 优先评估检查此请求是否需要加急处理\ 3. 能力过滤只考虑有可用时段的艺术家 4. 词典序排名按技能匹配度排序 → 优先级 → 能力 → 负载 5. 选择选择最佳候选人，并考虑备选方案
艺术家匹配机制的工作原理
技能评分系统:
字典序排名 （不仅仅是简单的积分总数）：
- 技能得分 （最多20个）- 首先考虑技术最佳适配
- 优先级标志 - 如果艺术家有空，加急请求将优先处理
- 可用容量 - 可用时间段越多 = 排名越高
- 当前负载 - 更倾向于选择工作不那么繁忙的艺术家
- 艺术家姓名 - 确定性决胜规则
现实世界中的例子：
Request: Unreal, stylized_hard_surface, priority
├─ Ada: skill_score=15 (style+engine), available=0 → Excluded (at capacity)
├─ Ben: skill_score=10 (engine only), available=1, priority_boost=true → Selected
├─ Cleo: skill_score=5 (topology only), available=1 → Alternative
└─ Result: "Ben assigned - matches engine unreal, priority boost, has 1 slots available"______________________________________________________________________
📝（一个表示“笔记”或“待办事项”的符号） record_decision(request_id, decision)
“我们如何为质量和合规性维护完整的审计轨迹？”
问题生产环境需要实现全程可追溯性。当客户询问“为什么我的请求被延迟了？”或“谁负责处理这个资产？”时，你需要有完整的每项决策记录。
逻辑:
- 唯一决策ID为每个决策生成UUID
- 完整上下文存储包含所有工具结果的完整决策对象
- 审计轨迹/审计路径保持所有工具调用的时间顺序记录
- 指标收集追踪处理时间和成功率
- 事件发射（或事件触发）为监控系统广播决策事件
被记录下来的内容：
{
"decision_id": "uuid-1234",
"request_id": "req-001",
"status": "success",
"rationale": "Human-readable explanation",
"validation_result": {...},
"plan": {...},
"assignment": {...},
"trace": [
{"step": "validate_preset", "timestamp": "...", "result": {...}},
{"step": "plan_steps", "timestamp": "...", "result": {...}},
{"step": "assign_artist", "timestamp": "...", "result": {...}}
],
"metrics": {"processing_time_ms": 15, "agent_type": "mcp_client"}
}退货： {decision_id: string, status: string} + 事件发射
📊 资源与处理流程
MCP Resources（公司名，可译为“MCP资源公司”或根据具体语境简化为“MCP资源”） （系统知识库）：
resource://requests- 收到的3D资产请求resource://artists- 艺术家简介及技能/能力resource://presets- 客户技术要求resource://rules- 业务工作流程规则
处理示例:
Request: ArcadiaXR, Unreal, stylized_hard_surface
├─ validate_preset ✅ Complete config (v3)
├─ plan_steps → [style_tweak_review, export_unreal_glb, qa_check, delivery]
├─ assign_artist → Ben (score: 7/20, 1 slot available)
└─ record_decision → "mcp-req-001-1758521644"
Output: {status: "success", artist: "Ben", rationale: "..."}🚨 错误处理与限制
优雅的错误处理 配备客户安全消息传递功能：
// Validation failure example
{
"status": "validation_failed",
"customer_message": "Configuration issue for TitanMfg: Your texture packing is incomplete. Please configure all RGBA channels.",
"clarifying_question": "Should we use default channel mappings or wait for your configuration?"
}当前的局限性：
- ❌（表示错误或否） 容量溢出没有真正的排队（虚假的“已排队”承诺）
- ❌（这个符号本身没有具体的中文翻译，它通常表示“错误”或“取消”的意思，但直接作为符号时，我们不进行翻译，而是保留其原样或根据上下文解释其含义。） 静态容量没有实时的艺术家可用性更新
- ❌ 基本技能匹配仅进行字符串匹配，不使用机器学习/模糊逻辑
- ❌（这个符号在中文中通常表示“错误”或“取消”，但直接翻译时，由于它是一个符号而非具体词汇，所以一般保留原样或根据上下文解释其含义。） 无状态的服务器重启后无持久性保存
🤖 功能与活动
智能代理早期验证停止，人类可读的理由，对客户安全的错误消息，完整的审计轨迹。
活动： tool.called， tool.completed， validation.failed， decision.recorded （用于监控系统）。
未来工作
智能排队系统实现真实队列管理，具备位置追踪功能，基于SLA（服务级别协议）的优先级设定，以及备选方案（外部承包商、简化工作流程）。
增强匹配基于机器学习的技能评分、艺术家表现学习、动态能力管理。
企业功能持久层、外部系统集成、高级业务规则引擎。