> ## ⚠️ Disclaimer: Vibe Coding Project ⚠️
>
> This is a "vibe-based" coding project. While functional, it is developed with a focus on rapid implementation and experimentation. Use it at your own risk. The author is not responsible for any consequences, data loss, or unexpected behavior that may arise from its use.
>
> ---

# Quire MCP Server

This project provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Quire](https://quire.io/). It exposes tools that allow AI assistants to interact with your projects and tasks right from your AI chat interface.

This server uses OAuth2 for authentication and is designed to be run easily via `npx`.

## 1. Getting Your Quire Credentials

This server uses an OAuth2 refresh token for authentication. You only need to perform this setup process once.

### Step 1: Create a Quire Application

1.  Go to the [Quire Applications page](https://quire.io/apps/dev).
2.  Click **Create a new application**.
3.  Fill in the details:
    *   **Name**: Give your application a name (e.g., "My-MCP-Client").
    *   **Website**: You can use a placeholder, like `https://localhost`.
    *   **Redirect URI**: Set this to `https://localhost`. This is crucial for the next step.
4.  After creating the app, note down the **Client ID** and **Client Secret**.

### Step 2: Get an Authorization Code

1.  Construct the following URL in your browser, replacing `YOUR_CLIENT_ID` with the ID you got in the previous step.
    ```
    https://quire.io/oauth?client_id=YOUR_CLIENT_ID&redirect_uri=https://localhost
    ```
2.  Visit the URL. You will be asked to log in to Quire and authorize the application.
3.  After authorizing, your browser will be redirected to a blank page with a URL like:
    `https://localhost/?code=SOME_LONG_CODE`
4.  Copy the `code` value from the URL. This code is temporary and will be used in the next step.

### Step 3: Exchange the Code for a Refresh Token

1.  Open your terminal and use `curl` to make a POST request to Quire's token endpoint.
2.  Replace the placeholders with your actual credentials.

    ```bash
    curl -X POST https://quire.io/oauth/token \
      -d grant_type=authorization_code \
      -d code=PASTE_THE_CODE_FROM_STEP_2_HERE \
      -d client_id=YOUR_CLIENT_ID \
      -d client_secret=YOUR_CLIENT_SECRET
    ```

3.  The response will be a JSON object containing your `access_token` and `refresh_token`.
4.  **Save the `refresh_token` value.** This is the token you will use to run the server. It is long-lived and will be used to automatically fetch new access tokens.

## 2. Quick Start & Usage

### Set Environment Variables

Set the following three environment variables in your terminal.

```bash
# Replace with the credentials you obtained above
export QUIRE_CLIENT_ID="your_client_id"
export QUIRE_CLIENT_SECRET="your_client_secret"
export QUIRE_REFRESH_TOKEN="your_refresh_token"
```

### Run with npx

Once the environment variables are set, you can run the server with a single command:

```bash
npx quire-mcp
```

## 3. Cursor Setup Guide

1.  **Find your `mcp.json` file**: `~/.cursor-settings/mcp.json`
2.  **Add the server configuration**:

    ```json
    {
      "mcpServers": {
        "quire": {
          "command": "npx",
          "args": [
            "-y",
            "quire-mcp"
          ],
          "env": {
            "QUIRE_CLIENT_ID": "${env:QUIRE_CLIENT_ID}",
            "QUIRE_CLIENT_SECRET": "${env:QUIRE_CLIENT_SECRET}",
            "QUIRE_REFRESH_TOKEN": "${env:QUIRE_REFRESH_TOKEN}"
          }
        }
      }
    }
    ```
3.  **Ensure Environment Variables are Set**: Before launching Cursor, make sure the variables are set in your shell environment (`.zshrc`, `.bash_profile`, etc.).
4.  **Restart Cursor** to load the new MCP server.

## 4. For Developers

### Running from Source

1.  **Clone, install dependencies:**
    ```bash
    git clone <repository_url>
    cd quire-mcp && npm install
    ```
2.  **Create a `.env` file:**
    ```
    QUIRE_CLIENT_ID=your_client_id
    QUIRE_CLIENT_SECRET=your_client_secret
    QUIRE_REFRESH_TOKEN=your_refresh_token
    ```
3.  **Run the server:**
    ```bash
    npm run build
    npm start
    ```

### Running Tests
```bash
npm test
```

## Features

- List projects
- List tasks within a project
- (More features to be added)