watsonx.government MCP服务器

用于IBM watsonx.government的现代模型上下文协议（MCP）服务器，使用FastMCP构建。使AI助手能够与watsonx.government API进行交互，以实现AI模型生命周期管理和治理。

🌟 特性

核心能力

模型条目管理：创建和管理AI用例
外部模型跟踪：从外部平台注册模型
工作空间协会：将项目和空间链接到用例
模型跟踪：跨生命周期阶段跟踪模型版本
配置资源：查询服务器状态和环境设置

现代建筑

FastMCP框架：基于最新的MCP SDK和FastMCP构建
寿命管理：自动客户端初始化和清理
上下文注入：工具的类型安全依赖注入
结构化输出：用于验证响应的Pydantic模型
多环境支持：在开发、暂存和生产之间无缝切换
自动身份验证：透明的IAM令牌管理和缓存
进度报告：实时日志记录和进度更新
类型安全：全程提供完整的类型提示和Pydantic验证

📋 先决条件

Python 3.11或更高版本
具有watsonx.governance访问权限的IBM Cloud API密钥
访问watsonx.治理目录

🚀 快速开始

安装

克隆存储库:

git clone 
cd wxgov_mcp_server

使用紫外线进行安装（推荐）:

uv sync

或者使用pip：

pip install -e .

发展：

pip install -e ".[dev]"

配置环境:

cp .env.example .env

编辑 .env 并设置您的API密钥：

WXGOV_ENVIRONMENT=production
WXGOV_PROD_API_KEY=your_api_key_here

运行服务器

发展模式 （与MCP检查员一起）：

uv run mcp dev main.py

生产模式:

python main.py
# or
uv run main.py

在Claude桌面中安装:

uv run mcp install main.py --name "watsonx.governance"

⚙️ 配置

环境变量

WXGOV_ENVIRONMENT：目标环境（开发、暂存、生产）
WXGOV_DEV_API_KEY：开发环境的API密钥
WXGOV_STAGING_API_KEY：用于暂存环境的API密钥
WXGOV_PROD_API_KEY：生产环境的API密钥

环境配置

服务器支持在中配置的多个环境 config/environments.yaml:

environments:
  dev:
    api_url: "https://api.dev.dataplatform.cloud.ibm.com"
    iam_url: "https://iam.test.cloud.ibm.com"
    api_key_env_var: "WXGOV_DEV_API_KEY"
  
  production:
    api_url: "https://api.dataplatform.cloud.ibm.com"
    iam_url: "https://iam.cloud.ibm.com"
    api_key_env_var: "WXGOV_PROD_API_KEY"

🛠️ 可用工具

1.创建_使用_案例

在watsonx.government中创建新的模型条目（AI用例）。

所需参数:

name：模型条目名称
description：详细说明
catalog_id：目标目录GUID

可选参数:

risk_level：风险等级（低、中、高）-默认值：“低”
status：状态（开发、验证、生产、退役）-默认值：“开发”
owner：所有者标识符
tags：标签列表
environment：目标环境

示例:

{
  "name": "Customer Churn Prediction",
  "description": "ML model to predict customer churn risk",
  "catalog_id": "abc-123-def",
  "risk_level": "medium",
  "tags": ["churn", "classification"]
}

2.创建外部模型

在watsonx.government中创建一个外部模型（model Stub）。

所需参数:

name：型号名称
description：型号说明
catalog_id：目标目录GUID
model_type：模型类型（例如，“分类”、“回归”）
external_model_provider：提供商名称（例如“AWS SageMaker”）

可选参数:

input_type：输入数据类型
algorithm：使用的算法
deployment_details：部署信息
tags：标签列表
environment：目标环境

示例:

{
  "name": "Fraud Detection Model v1.2",
  "description": "XGBoost model for fraud detection",
  "catalog_id": "abc-123-def",
  "model_type": "classification",
  "external_model_provider": "AWS SageMaker",
  "algorithm": "xgboost",
  "deployment_details": {
    "endpoint": "https://api.example.com/predict",
    "version": "1.2.0"
  }
}

3.关联_工作空间_结束_案例

将工作空间（项目/空间）与AI用例相关联。

所需参数:

ai_usecase_id：模型条目资产GUID
inventory_id：目录GUID
workspaces：工作区对象列表 id, type，以及 name

可选参数:

phase_name：生命周期阶段（开发、验证、操作）-默认值：“开发”
environment：目标环境

示例:

{
  "ai_usecase_id": "usecase-789",
  "inventory_id": "catalog-abc",
  "workspaces": [
    {
      "id": "proj-123",
      "type": "project",
      "name": "Development Project"
    },
    {
      "id": "space-456",
      "type": "space",
      "name": "Production Space"
    }
  ],
  "phase_name": "Develop"
}

4.轨道模型

将外部模型跟踪到AI用例。

所需参数:

inventory_id：模型所在的库存ID
asset_id：模型资产ID
usecase_inventory_id：用例库存ID
usecase_id：AI用例ID
version_number：版本号
approach_id：方法ID

可选参数:

phase：生命周期阶段（开发、验证、操作）-默认值：“开发”
owner：所有者标识符
environment：目标环境

示例:

{
  "inventory_id": "catalog-abc",
  "asset_id": "model-123",
  "usecase_inventory_id": "catalog-abc",
  "usecase_id": "usecase-789",
  "version_number": "1.0.0",
  "approach_id": "approach-001",
  "phase": "Develop"
}

🔐 认证

服务器使用IBM IAM进行身份验证：

API密钥：通过环境变量提供
代币交换：API密钥交换为承载令牌
令牌缓存：令牌通过自动刷新缓存在内存中
自动刷新：令牌在到期前5分钟刷新

🏃 运行服务器

Claude桌面集成

该服务器旨在与Claude Desktop无缝协作。使用MCP CLI安装：

uv run mcp install main.py --name "watsonx.governance" \
  -v WXGOV_ENVIRONMENT=production \
  -v WXGOV_PROD_API_KEY=your_api_key_here

或者手动添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "wxgov": {
      "command": "uv",
      "args": ["run", "/path/to/wxgov_mcp_server/main.py"],
      "env": {
        "WXGOV_ENVIRONMENT": "production",
        "WXGOV_PROD_API_KEY": "your_api_key_here"
      }
    }
  }
}

开发与测试

与MCP检查员一起 （建议开发）：

uv run mcp dev main.py

直接执行:

python main.py
# or with uv
uv run main.py

特定运输:

# stdio (default)
python main.py

# HTTP server
python -c "from src.server import mcp; mcp.run(transport='sse')"

📁 项目结构

wxgov_mcp_server/
├── src/
│   ├── server.py              # FastMCP server with lifespan
│   ├── context.py             # AppContext dataclass
│   ├── config.py              # Configuration management
│   ├── models/                # Pydantic response models (NEW)
│   │   ├── __init__.py
│   │   ├── use_case.py     # UseCaseResult
│   │   ├── external_model.py  # ExternalModelResult
│   │   ├── workspace.py       # WorkspaceAssociationResult
│   │   └── tracking.py        # TrackingResult
│   ├── resources/             # Resource endpoints (NEW)
│   │   ├── __init__.py
│   │   └── config.py          # Configuration resources
│   ├── auth/
│   │   ├── iam_client.py      # IAM authentication
│   │   └── token_cache.py     # Token caching
│   ├── client/
│   │   └── wxgov_client.py    # HTTP client
│   ├── tools/
│   │   ├── use_case.py     # Use case implementation
│   │   ├── external_model.py  # External model implementation
│   │   ├── workspace.py       # Workspace association implementation
│   │   └── tracking.py        # Model tracking implementation
│   └── utils/
│       ├── exceptions.py      # Custom exceptions
│       └── logger.py          # Logging utilities
├── config/
│   └── environments.yaml      # Environment configurations
├── tests/                     # Test suite
├── examples/                  # Example scripts
├── main.py                    # Entry point (simplified)
├── pyproject.toml            # Project configuration
└── README.md                 # This file

🆕 v0.2.0的新增功能

快速MCP迁移

现代化建筑：从低级服务器迁移到FastMCP
寿命管理：自动客户端初始化和清理
上下文注入：接收键入的工具 Context 参数自动
结构化输出：所有工具都返回经过验证的Pydantic模型
资源端点新 config:// 服务器自检资源
简化入口点: main.py 现在只有8行了！

关键改进

代码减少约40%：更清洁、更可维护的实施
类型安全：完整的类型提示 AppContext 数据类
更好的错误处理：自动错误格式化和记录
进度报告：通过实时更新 ctx.info() 和 ctx.error()
现代模式：遵循最新的MCP SDK最佳实践

🧪 测试

运行测试：

pytest

覆盖范围：

pytest --cov=src --cov-report=html

🔍 故障排除

身份验证错误

问题: AuthenticationError: IAM authentication failed

解决方案:

验证API密钥是否正确并具有正确的权限
检查是否设置了API密钥环境变量
确保您使用的是正确的环境（开发/测试/生产）

API错误

问题: APIError: API Error 404: Not Found

解决方案:

验证catalog_id、asset_id或其他id是否正确
检查目标环境中是否存在资源
确保您有权访问指定的资源

配置错误

问题: ConfigurationError: Environment 'xyz' not configured

解决方案:

检查 config/environments.yaml 对于可用环境
验证 WXGOV_ENVIRONMENT 设置为有效环境
确保环境配置完成

📚 其他资源

🤝 贡献

欢迎投稿！请按照以下步骤操作：

分叉存储库
创建要素分支
进行更改
添加测试
提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🆘 支持

对于问题和疑问：

在GitHub上打开一个问题
联系维护人员

🔄 版本历史记录

v0.2.0（当前）-快速MCP迁移

突发：迁移到FastMCP框架
为所有工具添加结构化Pydantic输出
实现了客户端初始化的生命周期管理
为工具添加了上下文注入模式
新资源端点： config://environments, config://status
简化入口点和服务器初始化
通过进度报告增强日志记录
全面提高型号安全性

v0.1.0

低级服务器的初始版本
四个核心工具：create_use_case、create_external_model、associate_workspaces_to_use_cse、track_model
多环境支持
使用令牌缓存进行自动身份验证
全面的错误处理和记录

📚 迁移指南（v0.1.0→ v0.2.0）

如果您从v0.1.0升级，以下是主要更改：

对于用户

无需更改 -工具界面保持不变
可用的新功能：查询 config:// 服务器信息资源
更好的反应：工具现在返回带验证的结构化数据

对于开发者

服务器初始化：现在使用 FastMCP 与寿命管理器
工具签名：添加 ctx: Context[ServerSession, AppContext] 参数
返回类型：工具返回Pydantic模型而不是字符串
客户端访问：从以下位置获取客户 ctx.request_context.lifespan_context
日志记录：使用 await ctx.info(), await ctx.error() 而不是直接记录器

请参阅服务器.py 查看完整示例。

wxgov MCP server

快速接入

详细介绍

watsonx.government MCP服务器

🌟 特性

核心能力

现代建筑

📋 先决条件

🚀 快速开始

安装

运行服务器

⚙️ 配置

环境变量

环境配置

🛠️ 可用工具

1.创建_使用_案例

2.创建外部模型

3.关联_工作空间_结束_案例

4.轨道模型

🔐 认证

🏃 运行服务器

Claude桌面集成

开发与测试

📁 项目结构

🆕 v0.2.0的新增功能

快速MCP迁移

关键改进

🧪 测试

🔍 故障排除

身份验证错误

API错误

配置错误

📚 其他资源

🤝 贡献

📄 许可证

🆘 支持

🔄 版本历史记录

v0.2.0（当前）-快速MCP迁移

v0.1.0

📚 迁移指南（v0.1.0→ v0.2.0）

对于用户

对于开发者

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP