> ## Documentation Index
> Fetch the complete documentation index at: https://www.swaitch.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

> Complete reference for all swAItch MCP tools

swAItch exposes four MCP tools that follow a natural workflow: discover → browse → fetch (conversation or message).

## `list_sources`

Discover which IDEs have conversation data available on the user's system.

**Call this first** to see what's available before trying to fetch conversations.

### Parameters

None.

### Response

```json theme={null}
{
  "sources": [
    {
      "ide": "cursor",
      "name": "Cursor",
      "data_path": "/Users/you/Library/Application Support/Cursor/User/globalStorage",
      "status": "available",
      "conversation_count": 4
    }
  ],
  "total": 1,
  "available": 1
}
```

### Status Values

| Status        | Meaning                                     |
| ------------- | ------------------------------------------- |
| `available`   | IDE data found and parseable                |
| `not_found`   | IDE not installed or no data directory      |
| `unsupported` | IDE detected but parser not yet implemented |
| `error`       | Detection failed (see `error_message`)      |

***

## `list_conversations`

List conversations from a specific IDE source with lightweight summaries.

### Parameters

| Parameter | Type    | Required | Default | Description                       |
| --------- | ------- | -------- | ------- | --------------------------------- |
| `source`  | string  | Yes      | —       | IDE identifier (e.g., `"cursor"`) |
| `limit`   | integer | No       | 50      | Maximum conversations to return   |
| `offset`  | integer | No       | 0       | Pagination offset                 |

### Response

```json theme={null}
{
  "source": "cursor",
  "conversations": [
    {
      "conversation_id": "c5da982d-b628-4fc8-98de-01f6c4454fc7",
      "title": "Building an app called swaitch",
      "summary": "Status: completed",
      "source": "cursor",
      "updated_at": "2026-02-20T23:41:36.708Z",
      "message_count": 15
    }
  ],
  "total": 4
}
```

***

## `get_conversation`

Get the full conversation content including all messages and artifacts.

### Parameters

| Parameter         | Type   | Required | Description                              |
| ----------------- | ------ | -------- | ---------------------------------------- |
| `conversation_id` | string | Yes      | ID from `list_conversations` results     |
| `source`          | string | Yes      | IDE identifier matching the conversation |

### Response

```json theme={null}
{
  "conversation_id": "c5da982d-b628-4fc8-98de-01f6c4454fc7",
  "title": "Building an app called swaitch",
  "summary": "",
  "source": "cursor",
  "messages": [
    {
      "role": "user",
      "content": "hello",
      "timestamp": "2026-02-20T23:40:59.901Z",
      "metadata": {}
    },
    {
      "role": "assistant",
      "content": "Hello. How can I help you today?",
      "timestamp": "2026-02-20T23:41:02.082Z",
      "metadata": {
        "model": "default",
        "thinking": "The user has simply said hello..."
      }
    }
  ],
  "artifacts": {},
  "metadata": {
    "status": "completed",
    "message_count": 15,
    "db_path": "/Users/you/Library/Application Support/Cursor/User/globalStorage/state.vscdb"
  }
}
```

***

## `get_conversation_message`

Get the full, untruncated content of a specific message. This is useful when `get_conversation` returns a message with `"is_truncated": true` due to length limits.

### Parameters

| Parameter    | Type   | Required | Description                           |
| ------------ | ------ | -------- | ------------------------------------- |
| `message_id` | string | Yes      | The unique ID of the message to fetch |

### Response

```json theme={null}
{
  "message_id": "msg-123456",
  "content": "Full, untruncated message text goes here...",
  "source": "cursor"
}
```

## Error Handling

All tools return error information inline rather than throwing exceptions:

```json theme={null}
{
  "error": "Unknown source 'vim'. Available: ['cursor']",
  "conversations": []
}
```

```json theme={null}
{
  "error": "Conversation 'invalid-id' not found in cursor"
}
```