xplainable-mcp-server

Xplainable MCP 服务

面向 Xplainable 平台的 Model Context Protocol 服务。它使大模型 Agent（Claude 或任何 MCP 客户端）能够训练、部署、优化并解释透明的机器学习模型。Agent 负责协调整个流程：检查数据、确定特征和预处理方式、训练、读取指标并反复迭代。

训练始终在 Xplainable 平台的服务端运行，MCP 主机不会在本地拟合模型。

两种使用方式

1. 托管 — 将 MCP 客户端连接到 https://mcp.xplainable.io（OAuth 登录，无需安装）。
2. 本地 — 使用 Xplainable API 密钥，通过 stdio 自行运行服务。本文档的其余部分介绍这种方式。

快速开始（本地）

1. 获取 API 密钥

在 platform.xplainable.io 创建一个。

2a. Claude Code

claude mcp add xplainable \
  -e XPLAINABLE_API_KEY=your-api-key-here \
  -- uvx --from git+https://github.com/xplainable/xplainable-mcp-server.git xplainable-mcp

2b. Claude Desktop

将以下内容添加到 MCP 设置文件中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "xplainable": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xplainable/xplainable-mcp-server.git", "xplainable-mcp"],
      "env": {
        "XPLAINABLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

没有 uv？请改为克隆并安装：

git clone https://github.com/xplainable/xplainable-mcp-server.git
cd xplainable-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e .

然后在上面的配置中使用 "command": "/path/to/xplainable-mcp-server/.venv/bin/xplainable-mcp"（不带参数）。

3. 试用

向 Agent 提问：“我有哪些模型和数据集？” — 它应该会调用 models_list_team_models 和 datasets_list_team_datasets。

迭代循环

工具集让 Agent 掌控每一项训练决策：

1. datasets_list_team_datasets / models_list_team_models / deployments_list_deployments — 查看团队的资源
2. datasets_preview_dataset_json(dataset_id) — 检查列、类型和样本行；确定目标、要删除的列，以及是否需要预处理
3. （可选）preprocessing_list_available_transformers → preprocessing_create_preprocessor_from_spec → preprocessing_preview_from_data，以验证转换后的输出 3b. 为每个数据集声明一次特征关系： datasets_infer_relationships 会根据证据提出衍生列、蕴含关系 和单调性提示；使用 datasets_set_relationships 提交（使用 models_apply_relationships 将其重新应用于旧版本）
4. models_train_model(dataset_id, target_column, model_name, ...) — 在服务端同步训练；返回模型/版本 ID、训练/测试指标和特征重要性
5. 检查：models_get_feature_info / gpt_explain_model；比较 训练与测试指标
6. 迭代：使用 models_refit_features 按特征调优，或通过不同特征/预处理方式重新训练
7. deployments_deploy(version_id) — 满意后部署（然后调用 deployments_activate_deployment）
8. 使用模型：inference_predict / optimisers_run_optimiser / reports_create_report（并轮询 reports_get_job_status）

工具集

工具由服务器在启动时从 xplainable-client 包中由 @mcp_tool 装饰的方法生成，不包含任何已检入的生成文件。工具集采用扁平结构： 所有注册表工具都会公开，并根据其类别派生 MCP 注解（read → 只读提示，write → 破坏性操作提示）。

配置

变量	必需	描述
XPLAINABLE_API_KEY	是（本地）	来自 platform.xplainable.io 的 API 密钥
XPLAINABLE_HOST / XPLAINABLE_HOSTNAME	否	平台主机覆盖值（默认为 https://platform.xplainable.io）。请将两者设为相同的值。
XPLAINABLE_INFERENCE_HOST	否	直接调用推理工具（inference_score_dataset、optimisers_run_portfolio）的推理服务器覆盖值；默认为 https://inference.xplainable.io。平台主机不是生产环境时，请设置此值。
XPLAINABLE_ORG_ID / XPLAINABLE_TEAM_ID	否	如果 API 密钥未绑定到团队，则用于绑定组织/团队
MCP_TRANSPORT	否	stdio（默认）或 streamable-http
LOG_LEVEL	否	DEBUG、INFO（默认）、WARNING、ERROR

请参阅 .env.example。API 密钥仅从环境变量中读取， 绝不会通过工具暴露。

CLI

xplainable-mcp-cli list-tools            # list all available tools
xplainable-mcp-cli validate-config       # check env configuration
xplainable-mcp-cli test-connection       # test API connectivity
xplainable-mcp-cli generate-docs         # generate tool documentation

Docker（HTTP 模式）

cp .env.example .env   # fill in your API key
docker compose up --build

容器会在 8000 端口通过 streamable-HTTP 提供服务，并提供 /health 端点。除 localhost 以外的场景，请在反向代理处终止 TLS。

开发

git clone https://github.com/xplainable/xplainable-mcp-server.git
cd xplainable-mcp-server
pip install -e ".[dev]"

pytest            # run tests
ruff check .      # lint

运行时工具生成

客户端支持的工具在导入时由 xplainable_mcp/runtime_tools.py 根据 xplainable-client 中的 @mcp_tool 注册表生成；无需同步步骤。只需升级固定的 xplainable-client 版本，即可获取新增或变更的工具；测试套件（tests/test_surface.py）会固定工具数量， 确保所有表面变更都是经过明确决定的。

兼容性

MCP 服务	xplainable-client	fastmcp
当前（main）	>=1.13.0	>=2.0.0,<3.0.0

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT 许可证 — 请参阅 LICENSE。