# Vise Logger

Vise Logger is a local MCP server that captures, rates, and archives Vise Coding sessions from various AI coding tools (tested with Cursor, GitHub Copilot, Cline, Roo, Junie, Codex, Kiro), storing them at viselo.gr for reference, comparisons, and searchability. Vise Logger uses a general approach for finding the log files, so that it ideally works out of the box for any AI coding tool / IDE.

As Sean Grove (OpenAI) and Dexter Horthy (HumanLayer) say: **The source spec (i.e. coding sessions) is the most valuable artifact**.

Just like you used to store the source code, not binaries, in GitHub,
you should now store your coding sessions as main source of truth, and not throw them away upon ending the coding session. Unlike Spec Driven Development (e.g. [Spec Kit](https://github.com/github/spec-kit), Vise Logger honors your specs without any restrictions like demanding a specific process).

On viselo.gr, you have
* an overview of your sessions
* a backup, as you can download each session as zip, containing the original format
* can share sessions with others
* get insights and advise from your sessions and of shared sessions.

Features planned for the future: 
1. pseudonymization
2. further advise, 
3. search
4. statistics (see https://fb-swt.gi.de/fileadmin/FB/SWT/Softwaretechnik-Trends/Verzeichnis/Band_45_Heft_3/5_TAV51_Farago.pdf).


## Installation and Setup
 
The sections below describe various ways to install the MCP server into your AI coding tool / IDE. But it is best if you follow the MCP server installation routine that your AI coding tool suggests. 

### Installation of MCP Server via PyPI

The easiest installation is using uv and fetching the latest version from PyPI (https://pypi.org/project/vise-logger/).

#### Installation via MCP JSON Configuration 

Installed (soon with pseudonymization since `PSEUDONYMIZATION_ENCRYPTION_KEY` is set) through PyPI by adding the following to the MCP config file (tested for Cline, Roo, Junie, Cursor, Kiro):
```json
"vise-logger": {
  "disabled": false,
  "timeout": 60,
  "type": "stdio",
  "command": "uv",
  "args": ["tool", "run", "vise-logger"],
  "env": {
    "PSEUDONYMIZATION_ENCRYPTION_KEY": "key via openssl rand -base64 32",
    "VISE_LOG_API_KEY": "your_API_key_from_viselo.gr",
    "OTEL_RESOURCE_ATTRIBUTES": "service.name=vise-logger,service.namespace=public-logs,deployment.environment=production",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp",
    "OTEL_EXPORTER_OTLP_HEADERS": "Basic MTM2MjQxMTpnbGNfZXlKdklqb2lNVFV5TWpJM05pSXNJbTRpT2lKMmFYTmxMV3h2WjJkbGNpSXNJbXNpT2lKMGNtd3ljRGM1U0ZCU1ZWQjNORGRrZEV3M05EUTNORTRpTENKdElqcDdJbklpT2lKd2NtOWtMV1YxTFhkbGMzUXRNaUo5ZlE9PQ=="
  }
}
```

#### Installation via VS Code 

VS Code has its own MCP host, which for instance GitHub Copilot is using. 
You can find the MCP JSON configuration file and follow the instruction from the previous section, or you can install Vise Logger via the link or command below.

##### Via Link

The link structure is the following (PSEUDONYMIZATION_ENCRYPTION_KEY and VISE_LOG_API_KEY `REDACTED`): 
```
vscode:mcp/install?%7B%22name%22%3A%22vise-logger%22%2C%22disabled%22%3Afalse%2C%22timeout%22%3A60%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22tool%22%2C%22run%22%2C%22vise-logger%22%5D%2C%22env%22%3A%7B%22PSEUDONYMIZATION_ENCRYPTION_KEY%22%3A%22REDACTED%22%2C%22VISE_LOG_API_KEY%22%3A%22REDACTED%22%2C%22OTEL_RESOURCE_ATTRIBUTES%22%3A%22service.name%3Dvise-logger%2Cservice.namespace%3Dpublic-logs%2Cdeployment.environment%3Dproduction%22%2C%22OTEL_EXPORTER_OTLP_ENDPOINT%22%3A%22https%3A%2F%2Fotlp-gateway-prod-eu-west-2.grafana.net%2Fotlp%22%2C%22OTEL_EXPORTER_OTLP_HEADERS%22%3A%22REDACTED%22%7D%7D)
```
You find the VS Code link without pseudonymization (i.e. without PSEUDONYMIZATION_ENCRYPTION_KEY), but with your own `VISE_LOG_API_KEY` pre-filled, on the page https://viselo.gr/settings.

##### Via Command Line

In VS Code, you can also do the installation (with pseudonymization) through the following command line:
```bash
code --add-mcp '{"name":"vise-logger","disabled":false,"timeout":60,"type":"stdio","command":"uv","args":["tool","run","vise-logger"],"env":{"PSEUDONYMIZATION_ENCRYPTION_KEY":"key via openssl rand -base64 32","VISE_LOG_API_KEY":"your_API_key_from_viselo.gr","OTEL_RESOURCE_ATTRIBUTES":"service.name=vise-logger,service.namespace=public-logs,deployment.environment=production","OTEL_EXPORTER_OTLP_ENDPOINT":"https://otlp-gateway-prod-eu-west-2.grafana.net/otlp","OTEL_EXPORTER_OTLP_HEADERS":"Basic MTM2MjQxMTpnbGNfZXlKdklqb2lNVFV5TWpJM05pSXNJbTRpT2lKMmFYTmxMV3h2WjJkbGNpSXNJbXNpT2lKMGNtd3ljRGM1U0ZCU1ZWQjNORGRrZEV3M05EUTNORTRpTENKdElqcDdJbklpT2lKd2NtOWtMV1YxTFhkbGMzUXRNaUo5ZlE9PQ=="}}'
```

### Local installation

This project uses `uv` for package and environment management.

1.  **Create a virtual environment:**
    ```bash
    uv venv
    ```

2.  **Activate the virtual environment:**
    *   On macOS/Linux:
        ```bash
        source .venv/bin/activate
        ```
    *   On Windows:
        ```bash
        .venv\Scripts\activate
        ```

3.  **Install the project in editable mode:**
    This command installs the project and its dependencies into the virtual environment. The `-e` flag (editable) ensures that any changes you make to the source code are immediately available without needing to reinstall.
    ```bash
    uv sync --extra dev
    ```
    This installs the runtime and dev dependencies, in editable mode. To only install the runtime dependencies, leave out argument `--extra dev`

4.  **Quality gates:**
    Formatting: `uv run ruff format . && uv run ruff check .`
    Type checking: `uv run mypy .`
    Testing: `VISE_LOG_API_KEY=you_API_key_from_viselo.gr uv run pytest`

If you have Vise Logger locally installed (e.g. for implementing new features), you can also use the following configuration:
```json
"vise-logger": {
  "disabled": false,
  "timeout": 60,
  "type": "stdio",
  "command": "uv",
  "args": [
    "--directory",
    "/local/dir/to/vise-logger",
    "run",
    "vise-logger"
  ],
  "env": {
    "VISE_LOG_API_KEY": "your_API_key_from_viselo.gr",
    "PSEUDONYMIZATION_ENCRYPTION_KEY": "key via openssl rand -base64 32",
    "OTEL_RESOURCE_ATTRIBUTES": "service.name=vise-logger,service.namespace=public-logs,deployment.environment=production",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp",
    "OTEL_EXPORTER_OTLP_HEADERS": "Basic MTM2MjQxMTpnbGNfZXlKdklqb2lNVFV5TWpJM05pSXNJbTRpT2lKMmFYTmxMV3h2WjJkbGNpSXNJbXNpT2lKMGNtd3ljRGM1U0ZCU1ZWQjNORGRrZEV3M05EUTNORTRpTENKdElqcDdJbklpT2lKd2NtOWtMV1YxTFhkbGMzUXRNaUo5ZlE9PQ=="
  }
}
```

## Environment Variables

`VISE_LOG_API_KEY`: Required. The API key for authenticating with the Vise Logger backend. This key is necessary for uploading sessions. Get it at https://viselo.gr/ by signing in, going to settings and then "Generate New Key".
The key is only shown once, so make sure you save it.

`OTEL_RESOURCE_ATTRIBUTES` (default "service.name=vise-logger,service.namespace=public-logs,deployment.environment=production"), `OTEL_EXPORTER_OTLP_ENDPOINT` (default "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp"), and `OTEL_EXPORTER_OTLP_HEADERS` (default "Basic MTM2MjQxMTpnbGNfZXlKdklqb2lNVFV5TWpJM05pSXNJbTRpT2lKMmFYTmxMV3h2WjJkbGNpSXNJbXNpT2lKMGNtd3ljRGM1U0ZCU1ZWQjNORGRrZEV3M05EUTNORTRpTENKdElqcDdJbklpT2lKd2NtOWtMV1YxTFhkbGMzUXRNaUo5ZlE9PQ=="): Optional. The logs are sent to the MCP host and to a file (see below), but you can also use open telemetry to send your logs to a server with an open telemetry endpoint. If you use the default values, they are sent to the developer of this project.


## Running the MCP Server

To run the MCP server directly from the command line:

```bash
vise-logger
```

## MCP Tools

This server provides two tools:

### `rate_and_upload(stars: float, comment: str = "")`

Rates and archives the current Vise Coding session. It finds the relevant log file, filters it for privacy, and simulates an upload to the backend.

### `configure_log_dir()`

Scans the system to find and verify the directory where your coding tool saves its logs. This helps speed up future searches.

**Warning:** This can be a very long-running operation, potentially taking minutes to hours, as it may scan your entire hard drive.

## Running Tests

With the virtual environment activated and the project installed in editable mode, you can run the integration tests:

```bash
python3 -m unittest discover tests
```

**Note on Best Practices:** Installing the package in editable mode (`-e`) is the recommended way to run tests for a distributable Python package. It correctly resolves imports without needing to modify `sys.path`, which is a less robust method. This approach simulates a real installation, making the testing environment more realistic.

## REST Endpoints The Sessions Are Sent to

The endpoint should have Content-Type: multipart/form-data and the following form fields:
* file (required): The zip file containing the AI coding session data
* metadata (required): JSON string with AI coding session metadata. The metadata JSON structure:
```
json{
  "marker": "string (required)",
  "tool": "string (required)",
  "stars": "number (required)",
  "comment": "string (optional)"
}
```

The official web application for Vise Logger is www.viselo.gr.
You can test it via
```
curl -X POST \
  -F "file=@session.zip" \
  -F 'metadata={"marker": "Rated session at 2025-07-30-20-56-11: 1.9 stars.", "tool": "curl", "stars": 1.9, "comment": "Just a curl test"}' \
  "https://studio--viselog.us-central1.hosted.app/api/v1/sessions"
```

## MCP server's logging and debugging

Vise Logger's own logs: if environment variables OTEL_RESOURCE_ATTRIBUTES, OTEL_EXPORTER_OTLP_ENDPOINT, and OTEL_EXPORTER_OTLP_HEADERS are set,
open telemetry (http/protobuf) is used for logging. You can log to the developer's cloud instance using
```
OTEL_RESOURCE_ATTRIBUTES="service.name=vise-logger,service.namespace=public-logs,deployment.environment=production"
OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-2.grafana.net/otlp"
OTEL_EXPORTER_OTLP_HEADERS="Basic MTM2MjQxMTpnbGNfZXlKdklqb2lNVFV5TWpJM05pSXNJbTRpT2lKMmFYTmxMV3h2WjJkbGNpSXNJbXNpT2lKMGNtd3ljRGM1U0ZCU1ZWQjNORGRrZEV3M05EUTNORTRpTENKdElqcDdJbklpT2lKd2NtOWtMV1YxTFhkbGMzUXRNaUo5ZlE9PQ=="
```
Logs are also written to a file, e.g. 
 `~/.local/state/vise-logger/log/mcp_server.log` 
 (path depends on your machine, see https://pypi.org/project/platformdirs/).
