# Installation Guide for Vikunja MCP Server

This guide provides instructions for setting up and running the Vikunja MCP server locally.

## Prerequisites

- Python 3.10 or newer
- `pip` (Python's package installer)

## Setup Instructions

Follow these steps to get the application running.

**1. Create a Virtual Environment**

It is highly recommended to run this application in a Python virtual environment to avoid conflicts with system-wide packages.

Create the environment using the following command:
```bash
python3 -m venv .venv
```

**2. Activate the Virtual Environment**

Before installing dependencies or running the application, you must activate the virtual environment.

*   **On macOS and Linux:**
    ```bash
    source .venv/bin/activate
    ```

*   **On Windows:**
    ```bash
    .\.venv\Scripts\activate
    ```

Your terminal prompt should change to indicate that you are now in the `.venv` environment.

**3. Install Dependencies**

With the virtual environment active, install the required Python packages from the `requirements.txt` file.
```bash
pip install -r requirements.txt
```

## Configuration

The application requires three environment variables to connect to your Vikunja instance. You must set these in your terminal before running the server.

Replace the placeholder values with your actual credentials.

```bash
export VIKUNJA_URL="https://your-vikunja-instance.com"
export VIKUNJA_USERNAME="your_username"
export VIKUNJA_PASSWORD="your_password"
```

**Note:** These variables are only set for the current terminal session. If you open a new terminal, you will need to set them again.

## Running the Application

Once the setup and configuration are complete, you can run the application with the following command:

```bash
python main.py
```

This will launch the interactive MCP shell.

## Usage

Here are the basic commands to get started:

1.  **Log in** to your Vikunja instance:
    ```
    > login
    ```

2.  **Search for tasks**:
    ```
    > search_tasks "My search query"
    ```

3.  **Add a new task** to a project:
    ```
    > add_task <project_id> "My new task title"
    ```

You can type `help` at any time to see a full list of commands, or `help <command_name>` for details on a specific one. To close the application, type `exit`.