Spacebridge MCP

1***IMPORTANT: This project is deprecated. Spacebridge MCP server is now available over HTTPS. See instructions at https://spacebridge.io***
2 
3 
4# SpaceBridge-MCP
5 
6A Model Context Protocol (MCP) server that integrates with the SpaceBridge REST API (https://spacebridge.io/docs) to automate issue management across connected issue trackers.
7 
8![SpaceBridge-MCP Overview](assets/diagram.png)
9 
10## Overview
11 
12SpaceBridge-MCP is a Model Context Protocol (MCP) server designed to integrate AI development tools (like Claude code, Windsurf, Cursor) with the SpaceBridge issue aggregation platform. It allows developers to interact with their issue trackers directly from their coding environment via their AI assistant.
13 
14**Core Benefits:**
15 
16*   **Reduced Context Switching:** Manage issues (search, create, view) without leaving the development environment.
17*   **Automated Issue Tracking:** Facilitates workflows where AI assistants can automatically find or create relevant issues associated with code changes (e.g., for commit messages).
18*   **Enhanced AI Context:** Provides AI assistants with access to issue details (via `get_issue_by_id`), enabling more context-aware code generation and analysis.
19*   **Centralized Interaction:** Leverages SpaceBridge to interact with multiple underlying issue trackers (Jira, GitHub Issues, etc.) through a single interface.
20 
21**Functionality:**
22 
23The server exposes MCP tools and resources that translate natural language requests from an AI assistant into SpaceBridge API calls. Key features include intelligent duplicate checking (using similarity search and LLM comparison) before issue creation and flexible handling of organization/project context.
24 
25## Features
26 
27*   **Resource:** `get_issue_by_id`: Retrieves details for a specific issue using its SpaceBridge ID.
28*   **Tool:** `search_issues`: Searches for issues based on a query string using either full-text or similarity search.
29*   **Tool:** `create_issue`: Creates a new issue. Before creation, it performs a similarity search for potentially duplicate issues and uses an LLM to compare the top results against the new issue's content. If a likely duplicate is found, it returns the existing issue's ID; otherwise, it creates the new issue.
30*   **Tool:** `update_issue`: Updates an existing issue.
31 
32## Getting Started
33 
34### Prerequisites
35 
36*   Python 3.9+
37*   pip (Python package installer)
38*   Access to a SpaceBridge instance and API key.
39*   OpenAI API Key (for the `create_issue` tool's duplicate check).
40 
41### Installation using pip
42 
431.  Install the package:
44    ```bash
45    pip install spacebridge-mcp
46    ```
47 
48### Installation from source
49 
501.  Clone the repository:
51    ```bash
52    git clone <repository-url>
53    cd spacebridge-mcp
54    ```
552.  Create and activate a virtual environment (recommended):
56    ```bash
57    # Use .venv as requested by user
58    python -m venv .venv
59    source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
60    ```
613.  Install the package in editable mode, including development dependencies (for testing):
62    ```bash
63    # Use the specific python from your virtual env if 'pip' isn't found directly
64    .venv/bin/python -m pip install -e ".[dev]"
65    # Or if 'pip' is correctly on PATH for the venv:
66    # pip install -e ".[dev]"
67    ```
68    *Note: This installs the package such that changes to the source code are immediately reflected without reinstalling. Including `[dev]` installs packages needed for running tests, like `pytest` and `respx`.*
69 
70### Configuration
71 
72The server requires the following configuration values:
73 
74*   **Required:**
75    *   `SPACEBRIDGE_API_KEY`: Your API key for authenticating with SpaceBridge.
76*   **Optional (Configuration & Context):**
77    *   `SPACEBRIDGE_ORG_NAME`: Explicitly sets the organization context. (Optional).
78    *   `SPACEBRIDGE_PROJECT_NAME`: Explicitly sets the project context. (Optional).
79*   **Optional (Duplicate Detection Behavior):**
80    *   `OPENAI_API_KEY`: Your OpenAI API key. *Required* if you want to use OpenAI for duplicate checking. If not provided, the server falls back to threshold-based checking.
81    *   `DUPLICATE_SIMILARITY_THRESHOLD`: Sets the similarity score threshold (0.0 to 1.0) used for duplicate detection when `OPENAI_API_KEY` is *not* provided. (Default: `0.75`).
82    *   `OPENAI_API_BASE`: Specifies a custom base URL for the OpenAI API (e.g., for local models or other providers). (Used only if `OPENAI_API_KEY` is set).
83    *   `OPENAI_MODEL`: Specifies the OpenAI model name to use for duplicate checks. (Default: `gpt-4o`). (Used only if `OPENAI_API_KEY` is set).
84 
85These values, along with organization/project context, can be provided in multiple ways. The server determines the final values based on the following order of precedence (highest first):
86 
871.  **Command-line Arguments:** Pass arguments when running the server. These override all other methods.
88    ```bash
89    spacebridge-mcp-server \
90      --spacebridge-api-key "YOUR_SB_KEY" \
91      --openai-api-key "YOUR_OPENAI_KEY" \
92      --org-name "YOUR_ORG" \        # Explicit Org Name
93      --project-name "YOUR_PROJECT"  # Explicit Project Name
94      # --project-dir "/path/to/your/project" # Optional: Specify dir for Git detection
95    ```
96    *(Use `spacebridge-mcp-server --help` to see all available arguments.)*
97 
982.  **Environment Variables:** Set standard environment variables. These override `.env` files and Git detection.
99    ```bash
100    # Example setting required and some optional vars
101    export SPACEBRIDGE_API_KEY="YOUR_SB_KEY"
102    export OPENAI_API_KEY="YOUR_OPENAI_KEY" # If using OpenAI duplicate check
103    export SPACEBRIDGE_ORG_NAME="YOUR_ORG"
104    export SPACEBRIDGE_PROJECT_NAME="YOUR_PROJECT"
105    # Then run:
106    spacebridge-mcp-server
107    ```
108 
1093.  **.env File:** Create a file named `.env` in the directory where you run the server. Environment variables and command-line arguments override values in this file.
110    ```dotenv
111    # .env file content
112    SPACEBRIDGE_API_KEY="YOUR_SB_KEY"
113    OPENAI_API_KEY="YOUR_OPENAI_KEY"
114    SPACEBRIDGE_ORG_NAME="YOUR_ORG"
115    SPACEBRIDGE_PROJECT_NAME="YOUR_PROJECT"
116    ```
117    The server automatically loads values from this file if it exists.
118 
1194.  **Git Configuration Detection:** If organization and project are not set via arguments or environment variables, the server attempts to detect them from the `.git/config` file.
120    *   It first checks in the directory specified by the `--project-dir` argument (if provided).
121    *   If `--project-dir` is not used, it checks the current working directory where the server was started.
122 
123**Context Handling Priority:**
124 
125The organization and project context used for API calls is determined as follows:
126 
1271.  **Startup Context:** The context determined during server startup (using the precedence above: Args > Env Vars > Git Detection) is used by default.
1282.  **Tool Parameter Fallback:** If (and only if) the server could *not* determine the context during startup (e.g., no explicit config provided and not running in a Git repository), the optional `org_name` and `project_name` parameters provided in a tool call (`search_issues`, `create_issue`, `update_issue`) will be used as a fallback.
129 
130**Note on Client Configuration:** When configuring MCP clients like Claude code (see "Connecting MCP Clients" section), passing credentials or context via the client's `--env` flags effectively sets them as environment variables for the server process (Priority 2). This is the recommended way to provide explicit context in environments where Git detection might fail (like Windsurf or Cursor).
131 
132### Running the Server
133 
134Once installed and configured, you can run the server using the command defined in `pyproject.toml`:
135 
136```bash
137spacebridge-mcp-server
138```
139 
140The server will start listening for MCP connections via standard input/output (stdio) by default.
141 
142## Connecting MCP Clients
143 
144This server uses standard input/output (stdio) for communication. You need to configure your MCP client (e.g., Claude code, Windsurf, Cursor) to launch the `spacebridge-mcp-server` command and pass the required environment variables.
145 
146**Configuration Steps:**
147 
1481.  **Install:** Ensure `spacebridge-mcp` is installed (see Installation section). The `spacebridge-mcp-server` command should be available in your environment's path (e.g., inside your virtual environment's `bin` directory if installed from source, or globally if installed via `pip install spacebridge-mcp`).
1492.  **Find Server Path:** Determine the full path to the `spacebridge-mcp-server` executable. If you installed in a virtual environment `.venv`, it might be `/path/to/your/project/.venv/bin/spacebridge-mcp-server`. If installed globally, you can often find it with `which spacebridge-mcp-server` (Linux/macOS) or `where spacebridge-mcp-server` (Windows).
1503.  **Add Server to Client:** Use your MCP client's command for adding a new server.
151 
152**Example using `claude mcp add` (Claude code):**
153 
154```bash
155claude mcp add spacebridge \
156  /full/path/to/your/spacebridge-mcp-server \
157  --scope user \
158  --env SPACEBRIDGE_API_KEY="your-spacebridge-api-key" \
159  --env OPENAI_API_KEY="your-openai-api-key" \
160```
161 
162*   Replace `/full/path/to/your/spacebridge-mcp-server` with the actual path found in step 2.
163*   Replace the placeholder API URL and keys with your actual credentials.
164*   `--scope user` makes the server available across all your projects in Claude code. Use `--scope project` to limit it to the current project.
165 
166**Other Clients (Windsurf, Cursor, etc.):**
167 
168Refer to the specific documentation for your client. The general principle is the same: provide a name for the server and the command to execute it, ensuring the necessary environment variables (`SPACEBRIDGE_API_KEY`, `OPENAI_API_KEY`, and optionally `SPACEBRIDGE_ORG_NAME`, `SPACEBRIDGE_PROJECT_NAME`) are passed to the command's environment. Some clients might have dedicated fields for environment variables, while others might require a wrapper script. Passing `SPACEBRIDGE_ORG_NAME` and `SPACEBRIDGE_PROJECT_NAME` is recommended for clients where the server's working directory might not match the actual project directory (e.g., Windsurf, Cursor).
169 
170## Usage Tips & Agentic Workflows
171 
172*   **Automated Commit Messages:** Configure your AI tool (e.g., via custom instructions or rules in Claude code, Windsurf, Cursor) to automatically reference relevant issue IDs when generating commit messages.
173    *   *Example Rule/Instruction:* "When generating a commit message, always ask the SpaceBridge-MCP tool to find or create an issue related to the changes and include the resulting issue ID (e.g., `SB-123`) in the commit message footer."
174    *   The AI can then use the `search_issues` or `create_issue` tool via this MCP server. If an issue exists, it gets the ID; if not, `create_issue` makes one and returns the new ID.
175*   **Context Augmentation:** When asking your AI assistant to work on a feature or bug, provide the SpaceBridge issue ID. The assistant can then use the `get_issue_by_id` resource via this MCP server to fetch the full context (description, comments, status) directly from your tracker, leading to more informed code generation or analysis.
176*   **Quick Issue Creation:** Simply ask your assistant "Create an issue about [brief description]" while coding. The `create_issue` tool will handle the similarity search and creation process.
177 
178## Where to Find Us
179 
180*   [MCP Review](https://mcpreview.com/mcp-servers/spacecode-ai/SpaceBridge-MCP)
181 
182## Development
183 
184### Running Tests
185 
1861.  Ensure you have installed the development dependencies:
187    ```bash
188    .venv/bin/python -m pip install -e ".[dev]"
189    ```
1902.  Run pytest from the project root directory:
191    ```bash
192    .venv/bin/python -m pytest -vvv
193    ```
194 
195## Contributing
196 
197Contributions are welcome! Please follow these steps:
198 
1991.  **Find an Issue or Suggest an Idea:**
200    *   Check the [GitHub Issues](https://github.com/spacecode-ai/SpaceBridge-MCP/issues) to see if your issue or idea is already being tracked.
201    *   If not, open a new issue to discuss your proposed change or report a bug.
202 
2032.  **Fork the Repository:** Create your own fork of the project on GitHub.
204 
2053.  **Create a Branch:** Create a new branch in your fork for your changes:
206    ```bash
207    git checkout -b feature/your-feature-name
208    ```
209 
2104.  **Set Up Development Environment:**
211    *   Ensure you have Python 3.8+ installed.
212    *   Create and activate a virtual environment (e.g., using `venv`):
213        ```bash
214        python -m venv .venv
215        source .venv/bin/activate  # Linux/macOS
216        # .\.venv\Scripts\activate # Windows
217        ```
218    *   Install the project with development dependencies:
219        ```bash
220        python -m pip install -e ".[dev]"
221        ```
222 
2235.  **Make Your Changes:** Implement your feature or bug fix.
224 
2256.  **Run Tests:** Ensure all tests pass:
226    ```bash
227    python -m pytest -vvv
228    ```
229 
2307.  **Lint and Format:** Ensure code style consistency (assuming Ruff is used, adjust if needed):
231    ```bash
232    ruff check . --fix
233    ruff format .
234    ```
235 
2368.  **Commit Your Changes:** Commit your changes with a clear and descriptive message.
237    ```bash
238    git commit -m "feat: Add feature X" # Or fix:, chore:, etc.
239    ```
240 
2419.  **Push to Your Fork:**
242    ```bash
243    git push origin feature/your-feature-name
244    ```
245 
24610. **Open a Pull Request:** Go to the original repository on GitHub and open a Pull Request from your fork's branch to the `main` branch of the original repository. Provide a clear description of your changes in the PR.
247 
24811. **Code Review:** Wait for maintainers to review your PR. Address any feedback provided.
249 
250## License
251 
252This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
253