SpaceBridge MCP Server 使用说明

项目简介

SpaceBridge MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在连接 AI 开发工具（如 Claude code, Windsurf, Cursor）与 SpaceBridge issue 聚合平台。它允许开发者在不离开编码环境的情况下，通过 AI 助手直接与 Issue 跟踪器进行交互，从而减少上下文切换，自动化 Issue 跟踪，并增强 AI 上下文感知能力。

主要功能点

Issue 检索: 通过 'get_issue_by_id' 资源，根据 SpaceBridge ID 获取指定 Issue 的详细信息。
Issue 搜索: 通过 'search_issues' 工具，根据关键词进行 Issue 搜索，支持全文搜索和相似度搜索。
Issue 创建: 通过 'create_issue' 工具，创建新的 Issue。创建前会进行相似 Issue 检查，避免重复 Issue。
Issue 更新: 通过 'update_issue' 工具，更新现有 Issue 的信息。
上下文管理: 支持组织和项目上下文管理，允许在特定组织和项目下进行 Issue 操作。
配置灵活: 支持通过命令行参数、环境变量、.env 文件和 Git 配置多种方式进行服务器配置。

安装步骤

环境准备: 确保已安装 Python 3.9+ 和 pip。

安装 SpaceBridge MCP Server:

通过 pip 安装:

pip install spacebridge-mcp

从源代码安装:

git clone <repository-url>
cd SpaceBridge-MCP
python -m venv .venv
source .venv/bin/activate  # 或 .venv\Scripts\activate (Windows)
.venv/bin/python -m pip install -e ".[dev]" # 或 pip install -e ".[dev]"

配置 SpaceBridge 和 OpenAI API Key:

SpaceBridge API URL: SpaceBridge 实例的 API 地址 (例如 'https://your-spacebridge.com/api/v1')。
SpaceBridge API Key: 用于 SpaceBridge API 鉴权的 API Key。
OpenAI API Key: 用于 'create_issue' 工具进行重复 Issue 检查的 OpenAI API Key。

可以通过以下方式配置，优先级从高到低: 命令行参数 > 环境变量 > .env 文件 > Git 配置。

方式一：命令行参数 (启动服务器时指定)

spacebridge-mcp-server \
  --spacebridge-api-url "YOUR_URL" \
  --spacebridge-api-key "YOUR_SB_KEY" \
  --openai-api-key "YOUR_OPENAI_KEY" \
  --org-name "YOUR_ORG" \
  --project-name "YOUR_PROJECT"

方式二：环境变量 (设置环境变量)

export SPACEBRIDGE_API_URL="YOUR_URL"
export SPACEBRIDGE_API_KEY="YOUR_SB_KEY"
export OPENAI_API_KEY="YOUR_OPENAI_KEY"
export SPACEBRIDGE_ORG_NAME="YOUR_ORG"
export SPACEBRIDGE_PROJECT_NAME="YOUR_PROJECT"
spacebridge-mcp-server

方式三：.env 文件 (在服务器启动目录下创建 '.env' 文件)

SPACEBRIDGE_API_URL="YOUR_URL"
SPACEBRIDGE_API_KEY="YOUR_SB_KEY"
OPENAI_API_KEY="YOUR_OPENAI_KEY"
SPACEBRIDGE_ORG_NAME="YOUR_ORG"
SPACEBRIDGE_PROJECT_NAME="YOUR_PROJECT"

方式四：Git 配置 (如果未通过以上方式配置组织和项目，服务器会自动尝试从 '.git/config' 文件中检测)。

启动 SpaceBridge MCP Server: 在命令行中运行：
```
spacebridge-mcp-server
```
服务器默认通过标准输入/输出 (stdio) 监听 MCP 连接。

服务器配置 (MCP 客户端配置)

以下为 MCP 客户端 (如 Claude code) 连接 SpaceBridge MCP Server 的配置信息 (JSON 格式)，请根据实际情况替换占位符。

{
  "serverName": "spacebridge",  // 自定义服务器名称，在客户端中用于标识
  "command": "/path/to/spacebridge-mcp-server", // SpaceBridge MCP Server 启动命令的完整路径，如果是全局安装，可以只写 'spacebridge-mcp-server'，否则需要写虚拟环境或安装目录下的完整路径。
  "args": [], // 启动参数，本例中不需要额外参数
  "env": { // 环境变量配置，用于传递 SpaceBridge 和 OpenAI API Key 等敏感信息，以及组织和项目上下文
    "SPACEBRIDGE_API_URL": "YOUR_SPACEBRIDGE_API_URL", // 替换为你的 SpaceBridge API URL
    "SPACEBRIDGE_API_KEY": "YOUR_SPACEBRIDGE_API_KEY", // 替换为你的 SpaceBridge API Key
    "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",      // 替换为你的 OpenAI API Key (如果需要创建 Issue 功能)
    "SPACEBRIDGE_ORG_NAME": "YOUR_ORG_NAME",        // (可选) 替换为你的 SpaceBridge 组织名称，如果需要在特定组织下操作
    "SPACEBRIDGE_PROJECT_NAME": "YOUR_PROJECT_NAME"  // (可选) 替换为你的 SpaceBridge 项目名称，如果需要在特定项目下操作
  },
  "scope": "user" // (可选) 服务器作用域，"user" 表示全局可用，"project" 表示仅在当前项目可用，根据客户端具体配置调整
}

注意:

请将 '/path/to/spacebridge-mcp-server' 替换为 'spacebridge-mcp-server' 启动命令的实际路径。可以通过 'which spacebridge-mcp-server' (Linux/macOS) 或 'where spacebridge-mcp-server' (Windows) 命令查找。
请务必替换 'YOUR_SPACEBRIDGE_API_URL', 'YOUR_SPACEBRIDGE_API_KEY', 'YOUR_OPENAI_API_KEY', 'YOUR_ORG_NAME', 'YOUR_PROJECT_NAME' 为你实际的配置信息。
'env' 中的环境变量配置会传递给 'spacebridge-mcp-server' 进程，作为服务器运行时的配置。
'scope' 参数根据 MCP 客户端的具体配置进行调整，例如 Claude code 支持 'user' 和 'project' 两种 scope。

基本使用方法

连接 MCP 客户端: 在你的 MCP 客户端 (如 Claude code, Windsurf, Cursor) 中，按照客户端的指引添加 MCP 服务器，并填入上述服务器配置信息。
使用 AI 助手: 在你的开发环境中，通过 AI 助手的自然语言交互，调用 SpaceBridge MCP Server 提供的工具和资源，例如：
- 询问 AI 助手 "查找关于登录 bug 的 issue" ，AI 助手将调用 'search_issues' 工具进行 issue 搜索。
- 要求 AI 助手 "创建一个 issue 标题为 '添加深色模式'，描述为 '为应用添加深色模式主题'"，AI 助手将调用 'create_issue' 工具创建 issue。
- 告知 AI 助手 "请获取 issue ID 为 SB-123 的 issue 信息"，AI 助手将调用 'get_issue_by_id' 资源获取 issue 详情。
- 指示 AI 助手 "更新 issue ID 为 SB-123 的 issue 状态为 '已完成'"，AI 助手将调用 'update_issue' 工具更新 issue 信息。

更多使用技巧和 Agentic Workflow，请参考仓库 README.md 文档。

关键词