StepZen MCP演示
背景
这是一个演示，旨在展示 @tool StepZen中的指令。GraphQL模式构建在电信公司的演示API之上。
使用演示，用户会问诸如“用户有什么设备”或“用户是否应该使用不同的计划”或“客户是否有任何礼品余额”等问题。
实施
我们在这个回购中实现了一个基于OpenAPI规范的伪REST API。然后，我们使用API实现了StepZen GraphQL模式和API。最后，我们包括 @tool StepZen GraphQL模式中的指令，以定义由StepZen MCP服务器为API端点托管的特定MCP工具。
入门指南
先决条件
- Python 3.13+（用3.13测试）
- 紫外线 用于Python包管理
- StepZen CLI用于部署GraphQL模式（对于本地REST API开发是可选的）
运行REST API
- 安装依赖项：
uv sync- 启动API服务器：
uv run python main.pyAPI将于 http://localhost:8080
- 查看交互式API文档，网址：
- Swagger用户界面：http://localhost:8080/docs - 重新记录：http://localhost:8080/redoc
测试API
示例查询：
# Search for customers
curl "http://localhost:8080/customers?query=an"
# Get a specific customer
curl "http://localhost:8080/customers/c_25f0e1a4"
# Get contracts for a customer
curl "http://localhost:8080/contracts?customerId=c_25f0e1a4"
# Get contract usage
curl "http://localhost:8080/contracts/con_b72c3e1b/usage?range=currentCycle"
# Get device for a contract
curl "http://localhost:8080/contracts/con_b72c3e1b/device"
# Browse available plans
curl "http://localhost:8080/plans"
# Get usage history
curl "http://localhost:8080/contracts/con_b72c3e1b/usage/history?lookbackDays=7&bucket=day"
# Check coverage by ZIP code
curl "http://localhost:8080/coverage?zip=10001"模拟数据
API在启动时生成一组一致的模拟数据：
- 15位客户拥有真实的个人资料
- 每位客户1-3份合同
- 相关设备、使用数据、计费历史和忠诚度积分
- 7移动和平板电脑计划
数据是使用具有固定种子的Faker库生成的，以确保重启之间的一致性。
API结构
REST API实现中定义的所有端点 telecom_demo_api_open_api_v_0_1.yaml:
- 客户 -搜索和检索客户资料
- 合同 -服务合同、积分/忠诚度和计费
- 用法 -数据/语音/文本使用跟踪和历史记录
- 数据礼品 -数据赠送资格和限制
- 设备 -设备信息和规格
- 计划 -服务计划目录和详细信息
- 参考 -枚举、查找和覆盖率数据
部署
部署到IBM云代码引擎
获取此API联机的最简单方法：
./deploy.sh这将在一个命令中构建API并将其部署到IBM云代码引擎。看 部署.md 有关详细的部署说明和设置。
主要特点：
- 无需Docker文件（使用构建包）
- 不使用时可扩展到零（成本最低）
- 部署更新的一个命令
- 自动HTTPS端点
GraphQL架构
这 stepzen/ 目录包含一个完整的StepZen GraphQL模式，该模式将REST API包装为：
- 可导航图 使用
@materializer链接类型的指令 - 查询入口点 客户、合同、计划、设备和使用情况
- 类型安全架构 遵循GraphQL最佳实践
关键关系
Customer → contracts[] → Contract
Contract → customer → Customer
Contract → plan → PlanDetail
Contract → device → Device
Contract → currentUsage → UsageSummary
Contract → points → ContractPoints部署GraphQL API
cd stepzen
stepzen deploy看 stepzen/README.md 有关详细的模式文档和示例查询。
实时端点：
- REST API：https://telecom-api.1ttbs4ed5d8o.us-south.codeengine.appdomain.cloud
- GraphQL API：（通过StepZen CLI部署）
- MCP端点：（在以下位置自动可用
/mcp路径）
MCP工具
GraphQL模式包括 5个MCP工具 AI助手可以使用：
GraphQL工具
- 电信目录 -浏览计划、设备和网络覆盖范围
- 暴露： plans, plan, device, coverage, lookups 查询 - 用法：“哪些计划的数据量超过30GB？”
规定工具
- 客户设备查找 -查找客户拥有的设备
- 用法：“客户John Smith有什么设备？” - 隐私：过滤掉电子邮件、电话、地址
- 客户使用情况检查 -检查当前周期数据/语音/文本使用情况
- 用法：“客户Jane Doe使用了多少数据？” - 隐私：过滤个人身份信息
- 计划建议 -分析客户是否应该改变计划
- 用法：“客户John Smith是否应该采用不同的计划？” - 包括：使用历史、计费成本、替代计划 - 隐私：过滤个人身份信息
- 数据礼品余额 -检查数据赠送资格和余额
- 用法：“顾客Jane Doe有礼品余额吗？” - 隐私：过滤个人身份信息
工具实施细节
- 地点：
stepzen/tools.graphql定义所有@tool指令 - 操作：
stepzen/operations/包含指定的GraphQL查询工具 - 安全： 所有面向客户的工具都会过滤PII（电子邮件、电话、地址）
- 文档： 完整的工具使用指南
stepzen/README.md