Metadata-Version: 2.4
Name: mcp-kyvos-sample-client
Version: 1.0.0a1
Summary: A sample client implementation to interact with Kyvos MCP server.
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: aiohttp>=3.12.2
Requires-Dist: mcp>=1.9.1
Requires-Dist: openai-agents==0.0.16
Requires-Dist: python-dotenv
Requires-Dist: uv
Description-Content-Type: text/markdown

## MCP Kyvos Sample Client

The `mcp-kyvos-sample-client` is a sample client implementation that demonstrates how to interact with a Kyvos MCP server. It enables users to send natural language queries using either:

* **SSE (Server-Sent Events)** for web-based communication, or
* **STDIO** for command-line interaction.

The client supports both **Basic Authentication** and **OAuth 2.0**, with credentials and the Kyvos platform URL specified through a JSON configuration file.

## Installation

Install the MCP Kyvos sample client package from `pip`:

```bash
pip install mcp-kyvos-sample-client==1.0.0a1
```

---

## Configuration Overview

The client configuration is defined in a JSON file (e.g., `mcp.json`) or via environment files. There are two primary properties:

1. **clientConfiguration**
2. **mcpServers**
```json
{
  "clientConfiguration": {
    "openai-api-key": "sk-...",
    "auth_type": "basic"
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [
        "--env-file", "/path/to/.env"
      ]
    }
  }
}
```

## Client Credentials

These settings apply globally to the MCP client and control logging and authentication to OpenAI:

| Parameter           | Description                                                                               | Example                     | Required | Default value |
|---------------------|-------------------------------------------------------------------------------------------|-----------------------------|----------|---------------|
| `log_level`         | Log level Options: `DEBUG` (default), `INFO`                                              | `"INFO"`                    | No       | `"DEBUG"`     |
| `log_file`          | File path for client logs.                                                                | `"/var/log/mcp/client.log"` | No       | -             |
| `openai-api-key`    | API key for OpenAI integration.                                                           | `"sk-..."`                  | Yes      | -             |
| `auth_type`         | Type of authorization client need to use.                                                 | `basic/oauth`               | No       | `Oauth`       |
| `client_port`       | The port on which the client receives the callback from the server during the OAuth flow. | `3001`                      | No       | `3000`        |
| `openai_model_name` | OpenAI model name to use for generating responses.                                                                                     | `gpt-4o-mini`               | No       | `gpt-4o`      |

**Example**:

```json
"clientConfiguration":{
  "log_level": "INFO",
  "log_file": "/var/log/mcp/client.log",
  "openai-api-key": "sk-..."
}
```

---

## STDIO Mode

Runs synchronously over standard input/output, ideal for scripts and pipelines.

**Connect with stdio:**

| Field     | Description                                                                                | Examples                                                                | Required | 
|-----------|--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|----------|
| `type`    | Server connection type.                                                                    | `"stdio"` or `"sse"`                                                    | No       | -|
| `command` | The command used to start the server executable. It must be either an absolute path or available on the system PATH. | `"uv"`,`"python"`, or any command installed via `pip`.                  | Yes      |
| `args`    | Array of arguments passed to the command.                                                  | ["--kyvos-url", "https://your-kyvos-endpoint", "--verify-ssl", "false"] | Yes      | 
| `env`     | Environment variables for the server.                                                      | `"USERNAME"`:`"user123"`                                                | No       | 



**Example configuration in ************************`mcp.json`************************:**

```json
{
  "clientConfiguration": {
    "log_level": "INFO",
    "log_file": "/var/log/mcp/analytics-stdio.log",
    "openai-api-key": "sk-..."
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [
        "--kyvos-url", "https://your-kyvos-endpoint",
        "--kyvos-username", "user123",
        "--kyvos-password", "secret",
        "--openai-api-key", "sk-...",
        "--kyvos-prompt-file", "./prompt.txt",
        "--kyvos-default-folder", "/shared/folder",
        "--verify-ssl", "false"
      ]
    }
  }
}
```

**Or via environment file:**

```json
{
  "clientConfiguration": {
    "openai-api-key": "sk-..."
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [
        "--env-file", "/path/to/.env"
      ]
    }
  }
}
```

**Or set env vars:**

```json
{
  "clientConfiguration": {
   "openai-api-key": "sk-..."
  },
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "mcp-kyvos-server",
      "args": [],
      "env": {
        "KYVOS_URL": "https://your-kyvos-endpoint",
        "KYVOS_USERNAME": "user123",
        "KYVOS_PASSWORD": "secreat"
      }
    }
  }
}
```

---

## SSE Mode

Provides a persistent stream of responses from the MCP Kyvos server using HTTP SSE protocol.

**Connect with sse:**

| Field                    | Description                   | Examples                           | Required|
|--------------------------| ----------------------------- |------------------------------------|---------|
| `type`                   | Server connection type.       | `"sse"`                            | No|
| `url`                    | URL of the SSE server.        | `"http://<machine_ip>:<port>/sse"` |Yes|
| `username`     | Username for HTTP Basic Auth. | `"user123"`                        |No|
| `password`     | Password for HTTP Basic Auth. | `"secret"`                         |No|

> **Note:** Username and password will be base64 encoded and passed as a Basic Auth token in the `Authorization` header.
>
> **Note:** The `type` parameter is optional. If a **url** is provided, the client will automatically detect the type as `sse`; if a **command** is provided, it will detect `stdio` mode.
> 
> **Tip:** Ensure that the MCP server is running before starting the client in SSE mode.


```json
{
  "clientConfiguration": {
    "log_level": "DEBUG",
    "log_file": "/var/log/mcp/analytics-sse.log",
    "openai-api-key": "sk-..."
  },
  "mcpServers": {
    "analytics-sse": {
      "type": "sse",
      "url": "http://<machine_ip>:port/sse",
      "username": "user123",
      "password": "secret"
    }
  }
}
```
---
>
> For reference on the MCP Kyvos server and its supported command-line arguments, see [mcp-kyvos-server](https://pypi.org/project/mcp-kyvos-server/1.0.0a1/).
>
---
## Running the Client

To start the MCP Kyvos sample client using a configuration file, run:

```bash
mcp-kyvos-sample-client --config /path/to/mcp.json
```
---

>**Note**: On error like "Your input exceeds the context window of this model" use the command '/clear ' without quotes to reset the context. All previous context will be lost after using this command.
 

## License

This project is licensed under the MIT License.
