Metadata-Version: 2.4
Name: mcp-kyvos-server
Version: 2.0.0
Summary: mcp-kyvos-server is a server implementation that integrates the Kyvos platform with the Model Context Protocol (MCP). It enables users to query Kyvos semantic models using natural language, translating prompts into executable queries and returning results from Kyvos. The server supports both SSE and STDIO communication modes and allows secure authentication using user-provided Kyvos credentials (basic and OAuth2.0).
Author-email: Kyvos <support@kyvos.io>
License: MIT License
         
        Copyright (c) 2025 Kyvos Insights Inc
         
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights  
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell      
        copies of the Software, and to permit persons to whom the Software is          
        furnished to do so, subject to the following conditions:                        
         
        The above copyright notice and this permission notice shall be included in     
        all copies or substantial portions of the Software.                             
         
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR     
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,       
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE    
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER         
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN      
        THE SOFTWARE.
Requires-Python: >=3.10
Requires-Dist: click>=8.1.7
Requires-Dist: colorlog>=6.9.0
Requires-Dist: fastapi>=0.115.12
Requires-Dist: httpx>=0.28.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: mcp>=1.9.1
Requires-Dist: peewee>=3.18.1
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pyjwt>=2.10.1
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: python-jose>=3.4.0
Requires-Dist: requests-cache>=1.2.1
Requires-Dist: requests>=2.32.3
Requires-Dist: starlette>=0.37.1
Requires-Dist: trio>=0.29.0
Requires-Dist: truststore>=0.10.1
Requires-Dist: uvicorn>=0.27.1
Description-Content-Type: text/markdown

## MCP Kyvos Server

The **MCP Kyvos Server** enables agentic applications to interact with the Kyvos platform for querying business data. It supports two transport modes:

- **SSE (Server-Sent Events)**: This transport is suited for remote integrations. It uses HTTP requests for communication. It allows servers to handle multiple client connections efficiently. SSE mode supports both Basic and OAuth authorization. OAuth requires users to authenticate using their Kyvos credentials before establishing a connection, providing a secure and standardized login mechanism.
- **STDIO (Standard I/O)**: This transport is primarily used for inter-process communication within the same system. It’s particularly suitable for command-line tools and local integrations where the client and server operate within the same process. Only Basic authorization is supported in this mode.

---

## Tools

The MCP Kyvos server exposes the following tools:

1. **`kyvos_list_semantic_model`**
   - **Description:** Lists available semantic models with schema details.

2. **`kyvos_semantic_model_details`**
   - **Description:** Retrieves column metadata, query generation rules, querying instructions and summary instructions for a specified semantic model.
> **Note:**This tool replaces: `kyvos_list_semantic_model_columns` and `kyvos_sql_generation_prompt`, serving as a unified interface for retrieving column metadata as well as providing SQL generation guidance and rules.

3. **`kyvos_execute_query`**
   - **Description:** Executes a Spark SQL query on Kyvos.

## Installation

### Using uv (Recommended)

When using uv, no specific installation is needed. We will use `uvx` to directly run `mcp-kyvos-server`.

> **Note:** Make sure you have `uv` installed. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).

### Using pip

Install the `mcp-kyvos-server` package from pip:

```bash
pip install mcp-kyvos-server
```

## Configuration & Parameters

The server can be configured via environment variables or command-line flags. CLI flags override environment variables.

| Parameter                      | Environment Variable  | CLI Flag                                   | Required | Default Value                 | Description                                                                                                                                                            |
|--------------------------------|-----------------------|--------------------------------------------|:--------:|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Kyvos URL                      | `KYVOS_URL`           | `--kyvos-url <url>`                        |   Yes    | —                             | The base URL of the Kyvos server. Example: `https://<server-address>:<port>/kyvos`                                                                                     |
| Kyvos Username                 | `KYVOS_USERNAME`      | `--kyvos-username <username>`              |   Yes    | —                             | The Kyvos account username used to authenticate and log in to the Kyvos application. Will be overridden if using OAuth or basic-auth flow                              |
| Kyvos Password                 | `KYVOS_PASSWORD`      | `--kyvos-password <password>`              |   Yes    | —                             | The corresponding password for the provided `KYVOS_USERNAME`, used for authentication with the Kyvos application. Will be overridden if using OAuth or basic-auth flow |
| Default Folder                 | `KYVOS_DEFAULT_FOLDER` | `--kyvos-default-folder <folder>`          |    No    | —                             | Folder containing multiple semantic models used for querying and metadata management in the Kyvos platform                                                             |
| Transport                      | —                     | `--transport <stdio or sse>`               |    No    | `stdio`                       | The type of communication transport to use: `stdio` for standard input/output or `sse` for Server-Sent Events                                                          |
| SSL Verification               | `VERIFY_SSL`          | `--verify-ssl <true or false>`             |    No    | `false`                       | Flag to enable or disable SSL certificate verification when making HTTP requests to Kyvos                                                                              |
| Max Rows                       | `MAX_ROWS`            | `--max-rows <max_rows>`                    |    No    | 1000                          | Limit the number of rows in the query response                                                                                                                         |
| Environment File               | —                     | `--env-file <file_path>`                   |    No    | —                             | Path to an `.env` file from which to load environment variables                                                                                                        |
| SSL Key                        | `SSL_KEY_FILE`        | `--ssl-key-file <file_path>`               |    No    | —                             | Path to the SSL private key file used to enable HTTPS on the server                                                                                                    |
| SSL Certificate                | `SSL_CERTIFICATE_FILE` | `--ssl-certificate-file <file_path>`       |    No    | —                             | Path to the SSL certificate file used to enable HTTPS on the server                                                                                                    |
| Auth Type                      | `SERVER_AUTH_TYPE`    | `--server-auth-type <basic/oauth/no_auth>` |    No    | `basic`                       | Type of authorization to start the server with                                                                                                                         |
| Port                           | —                     | `--port <port>`                            |    No    | 8000                          | Port on which to run the server                                                                                                                                        |
| MCP Server URL                 | `MCP_SERVER_URL`      | `--mcp-server-url <url>`                   |   Yes    | -                             | The full URL where the MCP server will run (e.g., http://mcp.server:9090)                                                                                              |
| MCP Kyvos Server Database Path | `MCP_KYVOS_DB_PATH`   | —                                          |    No    | `HOME_PATH/.mcp_kyvos_server` | The path where the MCP server database will be created                                                                                                                 |
| Log Level                      | —                     | `--log-level`                              |    No    | `DEBUG`                       | Specifies the log level to use (e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL).                                                                                          |


---
> OAuth Callback URL: When configuring oauth as the auth type, you must register the following URL as the Redirect / Callback URI in your OAuth provider's application settings:
https://<mcp-server-host>:<port>/auth/callback

> **Note:** The is_folder_name_required parameter has been removed, and providing a folder name is now mandatory for all queries on the MCP server.

## Sample `.env` File

Create a `.env` file with the required parameters for your MCP-Kyvos server:

```env
KYVOS_URL=https://kyvos.cloud/kyvos
KYVOS_USERNAME=your-username
KYVOS_PASSWORD=your-password
KYVOS_DEFAULT_FOLDER=Business Catalog
MCP_SERVER_URL=https://mcp-server:9090
```

---

## AI Space & Semantic Model URL Parameters

The MCP Kyvos Server supports scoped querying through URL query parameters appended to the `/sse` endpoint. The `type` parameter determines the querying mode.

### Query Parameters

| Parameter          | Description                                                                                                                                                    |
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `requestType`      | Querying mode: `AI_Space` or `Semantic_Model`. Defaults to `semanticmodel` if not provided.                                                                    |
| `AISpaceName`      | Name of the Kyvos AI Space to query within. Used when `requestType=AI_Space`.                                                                                  |
| `folderName`       | When `requestType=Semantic_Model`: Name of the folder containing the semantic models. When `requestType=AI_Space`: Name of the folder containing the AI Space. |
| `semanticModelName` | Name of the specific semantic model to query. Used when `requestType=Semantic_Model`.                                                                          |

### Mode: AI Space (`requestType=AI_Space`)

Targets semantic models residing within a specific Kyvos AI Space. Both `AISpaceName` and `folderName` are required.

```
http://<machine_ip>:<port>/sse?requestType=AI_Space&folderName=SalesFolder&AISpaceName=SalesSpace
```

### Mode: Semantic Model (`requestType=Semantic_Model`)

Targets semantic models of a particular folder, or a specific semantic model directly. `semanticModelName` is optional — if not provided, all semantic models within the given folder will be available for querying. If the user intends to query only a particular semantic model, `semanticModelName` can be passed as a parameter; otherwise, only `folderName` is sufficient.

```
http://<machine_ip>:<port>/sse?requestType=Semantic_Model&folderName=SalesFolder&semanticModelName=RevenueSM
```

Without `semanticModelName`:
```
http://<machine_ip>:<port>/sse?requestType=Semantic_Model&folderName=SalesFolder
```

### Client Configuration Example

```json
{
  "mcpServers": {
    "kyvos-sse": {
      "url": "http://<machine_ip>:<port>/sse?type=aispace&spaceName=SalesSpace&folderName=SalesFolder"
    }
  }
}
```
### Scoped Querying in STDIO Mode

Similar to SSE mode's URL query parameters (`requestType`, `folderName`, etc.), STDIO mode supports scoped querying via environment variables or CLI `--env-file`.

| Environment Variable   | Description                                                                 |
|------------------------|-----------------------------------------------------------------------------|
| `REQUEST_TYPE`                 | Querying mode: `AI_Space` or `Semantic_Model`                                 |
| `FOLDER_NAME`          | Folder containing the semantic model(s) or AI Space                        |
| `AI_SPACE_NAME`           | Name of the Kyvos AI Space. Required when `TYPE=AI_Space`                   |
| `SEMANTIC_MODEL_NAME`  | Name of a specific semantic model. Used when `TYPE=Semantic_Model`          |

---


## No-Auth Mode

The MCP Kyvos Server supports a `no_auth` authentication mode for scenarios where the client application does **not support OAuth**, but OAuth-style flow is still required by the integration.

In this mode:

* The **client does not perform real OAuth authentication**
* The **MCP server authenticates internally using configured Kyvos username and password**
* The server generates and returns simulated OAuth tokens to the client
* This allows OAuth-based workflows to function even when the client lacks native OAuth support

---

### How It Works

When `no_auth` is enabled:

1. The client connects as if using OAuth.
2. The MCP server authenticates to Kyvos using:

   * `KYVOS_USERNAME`
   * `KYVOS_PASSWORD`
3. The server loads token values from a provided JSON file.
4. The server returns those tokens to the client as a simulated OAuth response.

This allows clients that only support Basic-style authentication to operate in environments where OAuth mode is expected.

---

### Starting the Server in No Auth Mode

```bash
mcp-kyvos-server --transport sse --server-auth-type no_auth --env-file /path/to/.env 
```

---

### When to Use No-OAuth

Use `no_auth` when:

* The client application does not support OAuth
* You need to simulate OAuth behavior

---

## Usage

### SSE Mode

1. **Start the MCP server** with SSE transport.

   Using env file:
   ```bash
   mcp-kyvos-server --transport sse --env-file /path/to/.env
   ```

   Or provide arguments directly:
   ```bash
   mcp-kyvos-server --kyvos-url https://your-kyvos-endpoint --kyvos-username user123 --kyvos-password pass123 
   ```

2. **Configure your client application** to include the SSE server in its MCP server configuration:

   ```json
   {
     "mcpServers": {
       "kyvos-sse": {
         "url": "http://<machine_ip>:<port>/sse"
       }
     }
   }
   ```

### STDIO Mode

Configure your client application as follows:

#### Using uvx:

```json
{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "uvx",
      "args": [
        "mcp-kyvos-server",
        "--env-file", 
        "/path/to/.env"
      ]
    }
  }
}
```

#### Using pip:

```json
{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "python3",
      "args": [
        "-m", 
        "mcp_kyvos_server", 
        "--env-file", 
        "/path/to/.env"
      ]
    }
  }
}
```

> **Note:** If using a virtual environment, provide the full path to the environment's `python` executable (`/path/to/venv/python3`). On Windows, replace `python3` with `python`.


## Claude Desktop Usage

### STDIO Mode Configuration

#### Using `uvx` 

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "uvx",
      "args": [
        "mcp-kyvos-server", 
        "--env-file", 
        "/full/path/to/.env"
      ]
    }
  }
}
```

#### Using `pip`

If you've installed `mcp-kyvos-server` via `pip`:
```
pip install mcp-kyvos-server
```
**Use Python module directly**

```json
{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "python3",
      "args": [
        "-m", 
        "mcp_kyvos_server", 
        "--env-file", 
        "/full/path/to/.env"
      ]
    }
  }
}
```

> **Note:** If using a virtual environment, provide the full path to the environment's `python` executable (`/path/to/venv/python3`). On Windows, replace `python3` with `python`.


### SSE Mode Support (Remote)

> **Important:** Claude Desktop does *not* natively support SSE (Server-Sent Events). It only supports `stdio` transport.

To connect Claude Desktop to a **remote SSE MCP server**, use [`mcp-remote`](https://github.com/geelen/mcp-remote), a CLI tool that bridges remote SSE servers to local stdio clients.

#### Setup with `mcp-remote`

1. **Install Node.js (v18 or higher)** - [Download here](https://nodejs.org)

2. **Configure Claude Desktop to use `mcp-remote` via `npx`:**

   ```json
   {
     "mcpServers": {
       "mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/sse",
           "--allow-http"
         ]
       }
     }
   }
   ```
   
   > **Note:** Replace `<your-machine-ip>` and `<port>` with the actual address of your SSE server. Use the `--allow-http` flag if using HTTP-based MCP server URL.
   
   >  If your `claude_desktop_config.json` already contains other settings (e.g., `preferences`), merge only the `mcpServers` block into the existing file. For example:

   ```json
   {
     "mcpServers": {
       "kyvos-sse-oauth": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/sse",
           "--allow-http"
         ]
       }
     },
     "preferences": {
       ...your existing preferences...
     }
   }
   ```
   #### Passing Scoped Query Parameters via Headers (Recommended for Claude Desktop)
   
   Claude Desktop uses `mcp-remote` as a stdio-to-SSE bridge. Because Claude Desktop cannot append query parameters to the SSE URL directly, you can pass scoped query parameters as **custom request headers** instead. The server reads these headers as a fallback when URL query parameters are absent.
   
   > **Note:** This requires Node.js v18 or higher and uses `npx mcp-remote`.
   
   ##### Supported Headers
   
   | Header                    | Equivalent URL Query Parameter | Description                                                       |
   |---------------------------|-------------------------------|-------------------------------------------------------------------|
   | `Kyvos-Request-Type`      | `requestType`                 | Querying mode: `AI_Space` or `Semantic_Model`                     |
   | `Kyvos-Folder-Name`       | `folderName`                  | Folder containing the semantic model(s) or AI Space               |
   | `Kyvos-AI-Space-Name`     | `AISpaceName`                 | Name of the Kyvos AI Space. Required when `AI_Space` mode is used |
   | `Kyvos-Semantic-Model-Name` | `semanticModelName`           | Name of a specific semantic model                                 |
   
   ##### Configuration Example
   
   Add this to your `claude_desktop_config.json`:
   
   ```json
   {
     "mcpServers": {
       "kyvos-sse": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/sse",
           "--allow-http",
           "--header", "Kyvos-Request-Type:${KYVOS_REQUEST_TYPE}",
           "--header", "Kyvos-Folder-Name:${KYVOS_FOLDER_NAME}",
           "--header", "Kyvos-AI-Space-Name:${KYVOS_AI_SPACE_NAME}",
           "--header", "Kyvos-Semantic-Model-Name:${KYVOS_SEMANTIC_MODEL_NAME}"
         ],
         "env": {
           "KYVOS_REQUEST_TYPE":            "AI_Space",
           "KYVOS_FOLDER_NAME":             "SalesFolder",
           "KYVOS_AI_SPACE_NAME":           "SalesSpace",
           "KYVOS_SEMANTIC_MODEL_NAME":     "revenue_model"
         }
       }
     }
   }
   ```
   
   > **Note:** Only include the headers relevant to your querying mode. For `Semantic_Model` mode, `Kyvos-AI-Space-Name` can be omitted. For `AI_Space` mode, `Kyvos-Semantic-Model-Name` can be omitted.
   
   ##### Mode-specific Examples
   
   **AI Space mode:**
   ```json
   "env": {
     "KYVOS_REQUEST_TYPE":  "AI_Space",
     "KYVOS_FOLDER_NAME":   "SalesFolder",
     "KYVOS_AI_SPACE_NAME": "SalesSpace"
   }
   ```
   
   **Semantic Model mode (specific semantic model):**
   ```json
   "env": {
     "KYVOS_REQUEST_TYPE":        "Semantic_Model",
     "KYVOS_FOLDER_NAME":         "SalesFolder",
     "KYVOS_SEMANTIC_MODEL_NAME": "revenue_model"
   }
   ```
   
   **Semantic Model mode (Semantic models of provided folder):**
   ```json
   "env": {
     "KYVOS_REQUEST_TYPE":  "Semantic_Model",
     "KYVOS_FOLDER_NAME":   "SalesFolder"
   }
   ```

> After saving the configuration file, completely quit Claude Desktop and restart it. The application needs to restart to load the new configuration and start the MCP server.

**Note**: If you encounter an **OAuth authorization error**, try the following steps:
1. **Delete the `.mcp-auth` folder**  
    - On **Linux/macOS**:  
      ```bash
      ~/.mcp-auth
      ```  
    - On **Windows** (Command Prompt):  
      ```
      C:\Users\<your-username>\.mcp-auth
      ```

2. **Restart the `mcp-kyvos-server`**

## Gemini CLI Usage

### STDIO Mode Configuration

To integrate `mcp-kyvos-server` with **Gemini CLI**, use the STDIO transport mode. This allows Gemini to spawn and communicate with the MCP Kyvos server locally.

#### Using `uvx`

In your Gemini CLI configuration file (e.g., `~/.gemini/config.json`), add the following MCP server entry:

```json
{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "uvx",
      "args": [
        "mcp-kyvos-server", 
        "--env-file", 
        "/full/path/to/.env"
      ]
    }
  }, 
  "theme": "Default",
  "selectedAuthType": "oauth-personal"
}
```

#### Using `pip`

If you've installed `mcp-kyvos-server` via `pip`:
```
pip install mcp-kyvos-server
```
** Use Python module directly**

```json
{
  "mcpServers": {
    "kyvos-stdio": {
      "command": "python3",
      "args": [
        "-m", 
        "mcp_kyvos_server", 
        "--env-file", 
        "/full/path/to/.env"
      ]
    }
  },
  "theme": "Default",
  "selectedAuthType": "oauth-personal"
}
```


### SSE Mode Support (Remote)

> **Important:** Gemini Cli does *not* natively support SSE (Server-Sent Events). It only supports `stdio` transport.

To connect Gemini Cli to a **remote SSE MCP server**, use [`mcp-remote`](https://github.com/geelen/mcp-remote), a CLI tool that bridges remote SSE servers to local stdio clients.

#### Setup with `mcp-remote`

1. **Install Node.js (v18 or higher)** - [Download here](https://nodejs.org)

2. **Configure Claude Desktop to use `mcp-remote` via `npx`:**

   ```json
   {
     "mcpServers": {
       "mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://<your-machine-ip>:<port>/sse",
           "--allow-http"
         ]
       }
     },
     "theme": "Default",
     "selectedAuthType": "oauth-personal"
   }
   ```

   > **Note:** Replace `<your-machine-ip>` and `<port>` with the actual address of your SSE server. Use the `--allow-http` flag if using HTTP-based MCP server URL.

**Note**: If you encounter an **OAuth authorization error**, try the following steps:
1. **Delete the `.mcp-auth` folder**  
    - On **Linux/macOS**:  
      ```bash
      ~/.mcp-auth
      ```  
    - On **Windows** (Command Prompt):  
      ```
      C:\Users\<your-username>\.mcp-auth
      ```

2. **Restart the `mcp-kyvos-server`**

---


## License

This project is licensed under the MIT License.