spice-labs-mcp 0.1.1
The MCP server from Spice Labs to expand on the usability of our tools
Requires Python: >=3.10

# Spice Labs MCP Server
Python server implementing Model Context Protocol (MCP) for various operations from Spice Labs. This allows LLMs to leverage the information and tooling provided with Spice Labs products.

rename to Spice Labs MCP, in line with spicelabs cli 

## Features
- Get public Artifact Dependency Graph (ADG) or alias
- Get entries 'upward'
- Get PURLS 'upward'
- Get high-level terminal nodes 'upward'
- Get ADG entries in bulk
- Get 'downstream' ADG nodes 

## Tools
- **get_entry**
    - Fetches the public ADG entry or alias from a given identifier
    - Input:
      - identifier (83 character gitoid URL)
      
- **get_north**
  - Returns the ADG entries 'up' from an identifier 
  - Input:
    - identifier (83 character gitoid URL)
    
- **get_north_purls**
  - Return all PURLs of nodes 'up' from identifier
  - Input: 
    - identifier (83 character gitoid URL)

- **get_north_terminals**
  - Return high-level terminal nodes above identifier
  - Input:
    - identifier (83 character gitoid URL)

- **bulk_lookup**
  - Fetch ADG entries from identifiers
  - Input:
    - identifiers (list of 83 character gitoid URLs)

- **flatten**
  - Return all downstream nodes from identifier
  - Input:
    - identifier (83 character gitoid URL)

- **flatten_source**
  - Return all downstream nodes via 'built:from' from identifier
  - Input:
    - identifier (83 character gitoid URL)

- **get package based on purl** (zataar)
  
## Getting Started

This section contains instructions on how to install, build, and run the server locally.


#### **Option 1: Using `venv` and `pip`**

1.  **Prerequisites:** Ensure you have Python (3.8 or higher) installed.
2.  **Create a Virtual Environment:** It is recommended to install the package within a virtual environment.
    ```bash.
    # Create the virtual environment
    python -m venv venv
    
    # Activate the environment
    # On macOS/Linux:
    source venv/bin/activate
    # On Windows:
    # venv\Scripts\activate
    ```
3.  **Installation with Pip:** Install the package from the Python Package Index (PyPI).
    ```bash
    pip install spice-labs-mcp
    ```

#### **Option 2: Using `uv`**

1.  **Install `uv`:** If you do not have `uv` installed, you can install it with the following command:
    ```bash
    # On macOS and Linux
    curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
    
    # On Windows (PowerShell)
    powershell -ExecutionPolicy ByPass -c "irm [https://astral.sh/uv/install.ps1](https://astral.sh/uv/install.ps1) | iex"
    ```
2.  **Create a Virtual Environment:** `uv` can create a virtual environment for the project.
    ```bash
    uv venv
    ```
3.  **Install Dependencies:** Activate the environment and use `uv` to install the required packages.
    ```bash
    # Activate the environment
    # On macOS/Linux:
    source .venv/bin/activate
    # On Windows:
    # .venv\Scripts\activate

    # Install the package
    uv pip install spice-labs-mcp
    
    ```

## Connecting to Local LLM Clients

This MCP server can be connected to various AI assistants and development environments that support local `stdio` connections. Below are instructions for several leading platforms.

### **Anthropic Claude Desktop**

For the desktop application, you configure a local server by editing a JSON configuration file.

1.  **Open Claude Desktop Settings:**
    * In the Claude Desktop app, navigate to the main application menu (e.g., `Claude` in the macOS menu bar) and select `Settings...`.
    * Go to the **Developer** tab.

2.  **Edit the Configuration File:**
    * Click the **Edit Config** button. This will open the `claude_desktop_config.json` file in your default text editor.
    * The file is located at:
        * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

3.  **Add the Server Configuration:**
    * Add the following JSON object to the `mcpServers` dictionary. Replace `"my-custom-server"` with Spice-Labs-MCP and update the `command` and `args` to point to main.py.

    ```json
    {
      "mcpServers": {
        "my-custom-server": {
          "command": "node",
          "args": ["/path/to/main.py"]
        }
      }
    }
    ```

4.  **Restart Claude Desktop:**
    * Completely quit and restart the application. The spice-labs-mcp and its tools will then be available in the tool selection menu within the chat interface.

### **Google Gemini**

In environments like VS Code with the Gemini Code Assist extension, local MCP servers can be configured by editing a settings file.

1.  **Locate Gemini Settings:** Open your Gemini settings JSON file. In many environments, this is located in your user home directory at `~/.gemini/settings.json`.

2.  **Add the Server Configuration:** Add the server's details to the `mcp.servers` list in the JSON file.

    ```json
    {
      "mcp.servers": [
        {
          "name": "spice-labs-mcp",
          "transport": "stdio",
          "command": ["node", "/path/to/spice-labs-mcp.js"]
        }
      ]
    }
    ```

3.  **Reload the Environment:** Reload your IDE or application (e.g., in VS Code, open the Command Palette and run `Developer: Reload Window`). The Gemini agent will now have access to the tools provided by your server. You can typically verify this by using a command like `/mcp` in the chat to list connected servers.

### **Codename Goose**

1.  **Get to Add custon extension page:** Under the Extensions tab of the Goose GUI, then click Add custom extension button at the top of the page

2. **Input information for spice-labs-mcp** Extension name: spice-labs-mcp Command: uv run absolute/path/main.py

3.  **Restart Goose:** Relaunch your Goose session. The tools from your local MCP server will now be available to the agent.

---

## Copyright and license

The contents of this repository are copyrighted by Spice Labs, Inc. and licensed under the Apache 2.0 license

```txt
Copyright 2025 Spice Labs, Inc. & Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```