spiderswitch (Ailib Official)

人工智能生态系统蜘蛛开关

 

MCP（模型上下文协议）服务器，使代理能够从 ai-lib生态系统.

特性

• 协议驱动：从ai协议清单（ARCH-001）加载的所有模型配置
• 多提供商支持：在OpenAI、Anthropic、谷歌、DeepSeek等之间切换
• 运行时不可知：使用ai-lib-python SDK进行统一模型交互
• 符合MCP标准：通过stdio传输实现标准MCP工具
• 能力发现：查询可用模型及其功能
• 运行时配置文件信号：公开上层路由策略引擎的运行时能力配置文件
• 本地准备提示: list_models 包括每个提供程序的API密钥存在和代理就绪情况
• 显式退出路径: exit_switcher 重置切换器运行时/状态以进行干净回退
• 自动协议设置：自动检测本地 ai-protocol 路径和集合 AI_PROTOCOL_PATH 对于当前流程
• 官方Dist同步：官方尽力同步 dist/v1/*.json 快照到本地 ai-protocol/dist/v1

快速开始

安装

# Clone the repository
git clone https://github.com/ailib-official/spiderswitch.git
cd spiderswitch

# Install dependencies
pip install -e .

环境设置

设置API密钥：

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."

推荐的提供程序密钥映射：

安全说明：

• 更喜欢环境变量而不是传递 api_key 在工具论证中。
• 服务器会编辑日志中的敏感字段，但在参数中传递机密仍然会增加客户端跟踪中的暴露风险。

可选的运行时环境控件：

• SPIDERSWITCH_SYNC_ON_INIT=1 在运行时初始化期间启用dist-sync（默认：禁用）。
• SPIDERSWITCH_SYNC_DIST=0 在显式调用dist-sync时禁用它。
• AI_PROTOCOL_DIST_BASE_URL 覆盖原始dist源代码（默认的GitHub官方原始URL）。
• AI_PROTOCOL_DIST_API_BASE_URL 以覆盖GitHub API列出的模型/提供商的源dist-json。
• SPIDERSWITCH_LIST_CACHE_TTL_SEC 为了 list_models 缓存TTL（默认值： 5).
• SPIDERSWITCH_STATUS_CACHE_TTL_SEC 为了 get_status 缓存TTL（默认值： 2).

一键安装（插件市场风格）

bash scripts/install_one_click.sh

然后生成MCP客户端配置模板：

spiderswitch init --client cursor --output ~/.cursor/mcp.spiderswitch.json --force
spiderswitch doctor --json

离线安装（气隙/内联网）

从本地控制盘或本地源代码目录安装：

bash scripts/install_offline.sh /path/to/spiderswitch-0.4.0-py3-none-any.whl
# or
bash scripts/install_offline.sh /path/to/spiderswitch-source

配置

添加到MCP客户端配置中：

对于OpenCode

配置文件： ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spiderswitch": {
      "type": "local",
      "command": ["python3", "-m", "spiderswitch.server"],
      "enabled": true,
      "environment": {
        "AI_PROTOCOL_PATH": "/path/to/ai-protocol",
        "OPENAI_API_KEY": "sk-your-key",
        "ANTHROPIC_API_KEY": "sk-ant-your-key",
        "DEEPSEEK_API_KEY": "sk-your-key"
      }
    }
  }
}

适用于克劳德桌面/光标

配置文件： ~/.config/claude-desktop/config.json 或 ~/.cursor/mcp.json

{
  "mcpServers": {
    "spiderswitch": {
      "command": "python3",
      "args": ["-m", "spiderswitch.server"],
      "env": {
        "AI_PROTOCOL_PATH": "/path/to/ai-protocol"
      }
    }
  }
}

验证（OpenCode）

# List loaded MCP servers
opencode mcp list

# Expected output:
# ✓ spiderswitch connected
#   python3 -m spiderswitch.server

用法

在您的代理中，调用MCP工具：

# List available models
models = await mcp_client.call_tool("list_models", {})

# Switch to Claude 3.5 Sonnet
await mcp_client.call_tool(
    "switch_model",
    {"model": "anthropic/claude-3-5-sonnet"}
)

# Check current status
status = await mcp_client.call_tool("get_status", {})

可用的MCP工具

1.开关型号

切换到不同的AI模型/提供商。

参数：

• model （string，必填）：模型标识符（例如。， openai/gpt-4o, anthropic/claude-3-5-sonnet)
• api_key （字符串，可选）：显式API键（重写环境变量；不建议用于生产）
• base_url （字符串，可选）：用于测试/模拟的自定义基URL
• runtime_id （字符串，可选）：由上层策略选择的运行时目标

退货：

{
  "status": "success",
  "data": {
    "id": "anthropic/claude-3-5-sonnet",
    "provider": "anthropic",
    "capabilities": ["streaming", "tools", "vision"],
    "proxy_status": {
      "provider": "anthropic",
      "proxy_required_guess": false,
      "proxy_configured": false,
      "configured_proxy_env_vars": [],
      "hint": null
    },
    "warnings": []
  },
  "message": "Successfully switched to anthropic/claude-3-5-sonnet"
}

2.列表模型

列出注册提供商的所有可用型号。

参数：

• filter_provider （字符串，可选）：按提供者ID筛选
• filter_capability （字符串，可选）：按能力筛选(streaming, tools, vision, embeddings, audio)
• runtime_id （字符串，可选）：由上层策略选择的运行时目标

退货：

{
  "status": "success",
  "data": {
    "count": 2,
    "runtime_profile": {
      "runtime_id": "python-runtime",
      "language": "python",
      "supports": ["model_switching", "capability_filtering", "provider_manifest_loading"]
    },
    "models": [
      {
        "id": "openai/gpt-4o",
        "provider": "openai",
        "capabilities": ["streaming", "tools", "vision"],
        "api_key_status": {
          "provider": "openai",
          "has_api_key": true,
          "expected_env_vars": ["OPENAI_API_KEY"],
          "configured_env_vars": ["OPENAI_API_KEY"]
        },
        "proxy_status": {
          "provider": "openai",
          "proxy_required_guess": true,
          "proxy_configured": false,
          "configured_proxy_env_vars": [],
          "hint": "This provider may require proxy access in your network region. Set HTTPS_PROXY/HTTP_PROXY in the MCP server process environment if needed."
        }
      },
      {
        "id": "anthropic/claude-3-5-sonnet",
        "provider": "anthropic",
        "capabilities": ["streaming", "tools", "vision"]
      }
    ],
    "filtered": {
      "require_api_key": false,
      "provider": null,
      "capability": null
    }
  }
}

3.获取状态

获取当前模型状态和配置。

参数：

• runtime_id （字符串，可选）：查询特定运行时范围内的状态

退货：

{
  "status": "success",
  "data": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet",
    "capabilities": ["streaming", "tools", "vision"],
    "runtime_profile": {
      "runtime_id": "python-runtime",
      "language": "python",
      "supports": ["model_switching", "capability_filtering", "provider_manifest_loading"]
    },
    "is_configured": true,
    "connection_epoch": 3,
    "last_switched_at": "2026-03-02T09:00:00+00:00"
  }
}

4.出口切换器

显式重置spiderswitch状态和运行时客户端。

参数：

• runtime_id （字符串，可选）：作用域重置的运行时id
• scope （字符串，可选）： all （默认）或 runtime

退货：

{
  "status": "success",
  "data": {
    "exited": true,
    "status": {
      "provider": null,
      "model": null,
      "is_configured": false
    }
  }
}

API关键指南和故障排除

当 switch_model 由于缺少凭据而失败，响应包括：

• provider：哪个提供程序缺少凭据
• expected_env_vars：接受的环境变量名称
• hint：可操作的设置说明

典型设置流程：

1. 在MCP服务器进程环境中配置提供程序密钥。
2. 如果您的客户端不支持热环境重新加载，请重新启动MCP服务器进程。
3. 呼叫 switch_model.
4. 证实 get_status.

与代理运行时的连接协调

此MCP服务器在内部管理模型客户端生命周期。为了避免与代理自己的连接管理器发生冲突：

• 将MCP切换器视为模型选择的控制平面。
• 让代理方观察 get_status.connection_epoch.
• 仅在以下情况下重建代理端缓存会话 connection_epoch 增加。

此模式可防止模型切换后过时的会话重用，并支持确定性同步。

运行时路由边界

spiderswitch仅使用显式运行时信号执行路由操作：

• 运行时能力模型通过以下方式公开 runtime_profile （运行时中立模式）。
• 运行时选择策略仍保留在上层应用程序中。
• 内置注册表/解析器仅解析 runtime_id 并且没有实施成本/质量/业务战略。

建筑

spiderswitch/
├── src/
│   ├── server.py           # MCP server main entry point
│   ├── tools/              # MCP tool implementations
│   │   ├── switch.py       # switch_model tool
│   │   ├── list.py         # list_models tool
│   │   ├── status.py       # get_status tool
│   │   └── reset.py        # exit_switcher tool
│   ├── runtime/            # Runtime abstraction layer
│   │   ├── base.py         # Base runtime interface
│   │   ├── python_runtime.py  # ai-lib-python implementation
│   │   └── loader.py       # ProtocolLoader wrapper
│   └── state.py            # State management
├── tests/                  # Test suite
└── pyproject.toml          # Project configuration

发展

运行测试

# Install test dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/spiderswitch

使用模拟服务器进行测试

使用 人工智能协议模拟:

# Start mock server
docker-compose up -d ai-protocol-mock

# Run with mock
MOCK_HTTP_URL=http://localhost:4010 python -m spiderswitch.server

代码风格

# Format code
ruff format src tests

# Lint
ruff check src tests

# Type check
mypy src

协议驱动设计（ARCH-001）

此服务器遵循ai-lib设计原则：

一切逻辑皆算子，一切配置皆协议

所有提供程序配置都从ai协议清单加载。没有硬编码特定于提供者的逻辑。添加新的提供程序只需要ai协议中的清单文件。

路由边界：

• spiderswitch仅公开运行时/模型能力信号。
• 路由策略策略（成本/延迟/断路器/业务规则）属于上层应用程序。

确定性路由契约：

• 运行时解析顺序固定为 request runtime_id -> active state runtime_id -> default runtime.
• 重置支持作用域行为(scope=runtime)在不进行全局拆卸的情况下清除目标运行时。
• 合同测试 tests/test_runtime.py 验证解析器顺序和范围重置稳定性。

相关项目

• 人工智能协议 -协议规范
• ai库python -Python运行时SDK
• 艾利布生锈 -Rust运行时SDK
• ai libts -TypeScript运行时SDK

许可证

本项目根据以下任一方式获得许可：

• Apache许可证，版本2.0(特许通行证 或http://www.apache.org/licenses/LICENSE-2.0)
• MIT许可证(许可证-麻省理工学院 或http://opensource.org/licenses/MIT)

由您选择。

贡献

欢迎投稿！请确保：

1. 代码遵循PEP 8并通过 ruff check
2. 键入提示传递 mypy --strict
3. 包括对新功能的测试
4. 文档已更新

______________________________________________________________________

蜘蛛女巫 -MCP与ai lib相遇的地方。 🤖🔀