---
name: typex-use
description: 'TypeX Messaging: Operate TypeX via a local MCP server to send messages and manage group chats. Supports sending and replying to messages, searching chat history, managing group members, uploading and downloading images and files (including app-managed large file transfers), managing emoji reactions, and setting message reminders. Use when the user needs to send a message, view or search chat history, download files from chats, view group members, search groups, create group chats, manage bookmarks, or set message reminders.'
compatibility: 'Requires TypeX desktop app with MCP enabled in Settings. Default endpoint: http://127.0.0.1:52222/mcp/'
metadata:
  version: 1.1.1
---

# TypeX Usage Guide

Operate the TypeX desktop app via the MCP protocol—send messages, manage group chats, set reminders, search content, and more.

## Core Concepts

- **Message**: text, rich text, image, file, audio, video, sticker, forwarded messages, multiple images/files, cards, etc.
- **Chat**: group or direct conversation, identified by name or participants.
- **Contact**: person identified by display name or TypeX ID.
- **Thread**: reply chain under a group message for a sub-topic discussion.
- **Reaction**: emoji on a message.
- **Reminder**: due-date on a message.
- **Mention**: aggregated @mention inbox.

```
Chat (Group / Direct / Thread)
├── Member
└── Message
    ├── Reaction
    └── Resource (Image / File / Audio / Video)
```

## Agent Rules

Read this section first on every TypeX task.

### Planning Rules

Before executing:

1. **Classify** — read-only, normal write, or high-risk write (remove member, bulk/sensitive).
2. **Identify target** — contact, group, message, or file.
3. **Resolve ambiguity** — search first; stop if 0 or many matches (see Recovery Rules).
4. **Read then write** — gather `opaque_ref` / `message_ref` via read tools before mutations.
5. **Verify** — report only what tools returned (`ok:true`); never assume success.

### Tool Priority Rules

| Task                                                                             | First tool                                                                            | Never use instead                                     |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Send / reply / search history / remind / react / star / link / upload / download | `typex.search_contact` (or one-step `contact_name` / `target.name`)                   | `typex.search_user_to_add`                            |
| Group target                                                                     | `typex.search_contact` with `search_group=true`                                       | contact-only search                                   |
| Add new friend                                                                   | `typex.search_user_to_add` → confirm not-yet-added candidate → `typex.add_contact`    | `typex.search_contact` for global directory           |
| @mention inbox                                                                   | `typex.list_mentions`                                                                 | manual search across all groups                       |
| Remove member                                                                    | `typex.remove_group_members` (preview → confirm)                                      | `typex.search_contact`, `typex.resolve_group_members` |
| Add member to group                                                              | `typex.search_contact` → `typex.resolve_group_members` → `typex.manage_group_members` | `typex.search_user_to_add`                            |
| Create group                                                                     | `typex.resolve_group_members` → `typex.create_group_chat`                             | —                                                     |
| Who am I                                                                         | `typex.get_me`                                                                        | —                                                     |
| Folder feeds                                                                     | `typex.list_folder_feeds`                                                             | —                                                     |

**Default chain for message-targeting tasks:** `search_contact` → `search_chat_records` → write tool.

### Never

- Fabricate contacts, groups, messages, members, search results, links, or file paths.
- Claim an action succeeded without a successful tool response.
- Pick a target when multiple candidates exist—always ask the user.
- Expose internal refs (`opaque_ref`, `message_ref`, `chat_ref`, etc.) to the user.
- Use `typex.search_user_to_add` for messaging, chat search, reminders, or reactions.
- Reply to an @mention by DMing the sender—use `chat_ref` + `reply_to_message_ref`.
- Use `typex.send_message` for Thread sub-topics—use `typex.create_thread_reply`.
- Use `typex.search_contact` to find in-group members for removal.

### Recovery Rules

| Situation                              | Action                                                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `search_contact` returns 0             | Tell user the name may be wrong; ask for TypeX ID, email, recent message snippet, or whether to add a friend (`search_user_to_add`). |
| Multiple candidates                    | Show numbered options (name, TypeX ID, last activity); retry with `ref` / `opaque_ref` after user picks.                             |
| `search_chat_records` returns 0        | Confirm chat target; retry without `query`, widen time range, or increase `limit`.                                                   |
| `file_download_hint=text_mention_only` | Filename appears in text only—not a downloadable attachment.                                                                         |
| Download list empty                    | Retry `list_chat_downloadable_files` without `query`.                                                                                |
| Remove preview: name not found         | Call `typex.list_group_members`; show in-group names; ask user to correct spelling.                                                  |
| Remove fails (permission)              | Explain only group owner/admin can remove members.                                                                                   |
| MCP connection fails                   | Ask user to open TypeX → Settings → MCP and enable it.                                                                               |
| Ref invalid / not found                | Do not reuse stale refs — re-run the search tool that produced them.                                                                 |
| Send/write fails                       | See Retry Policy; then recheck target with `search_contact`.                                                                         |

### Retry Policy

| Tool type                                                                         | Policy                                                                                                                     |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Read tools (`search_contact`, `search_chat_records`, `list_mentions`, etc.)       | Retry up to **2** times with adjusted params (drop `query`, widen time range, increase `limit`, or pick confirmed `ref`).  |
| Normal write tools (`send_message`, `upload_chat_file`, `message_reaction`, etc.) | Retry **at most once** after rechecking target/refs.                                                                       |
| High-risk write (`remove_group_members` execute)                                  | **Never** auto-retry after `user_confirmed:true`. If it fails, report the error; start over with preview if the user asks. |
| MCP connection errors                                                             | Do not spam retries — ask user to verify TypeX is running and MCP is enabled.                                              |

### Tool Cost Policy

- Prefer **one-step** calls (`contact_name`, `target.name`) before multi-tool chains.
- Run `search_contact` **once** per target per task; reuse its `opaque_ref` in the same flow.
- Avoid repeating `search_chat_records` with identical parameters — change `query`, time range, or `limit` instead.
- Use the **smallest `limit`** that answers the question (agent browsing policy: request `limit=20` unless the user asks for more; tool defaults may be higher).
- Do not call `list_mentions` with a high `message_limit` unless the user needs a deep @mention scan.

### Context Compression

- When `search_chat_records` or `list_mentions` returns **more than 20** hits: summarize top items (sender, time, one-line preview) first; ask whether to narrow (keyword, time range, chat) or expand.
- Default `limit=20` for browsing unless the user requests more.
- Never dump large message batches into the reply.

### Confirmation Rules

**Require confirmation:** add-contact after `search_user_to_add` returns a not-yet-added candidate, removing group members (use `remove_group_members` preview first), batch/irreversible ops, sensitive data scope.

**Execute directly:** clear send/reply/create-group instructions; all read-only ops.

### Ambiguity Handling

Clarify when: similar contact names, multiple matching groups, unclear message target, vague "send it to them", missing attachment, no active conversation for reply. Present short, numbered options.

### Response Style

Be concise and action-oriented. Report tool results directly. Summarize search hits before expanding.

## Connection & Identity

- MCP endpoint: `http://127.0.0.1:52222/mcp/` — enable in TypeX desktop → Settings → MCP.
- All operations run as the signed-in user. Access depends on membership and role (owner/admin for member removal).

## Operations Quick Reference

| Category  | Operation               | MCP Tool(s)                                                               |
| --------- | ----------------------- | ------------------------------------------------------------------------- |
| Identity  | Get current user        | `typex.get_me`                                                            |
| Folders   | List folder feeds       | `typex.list_folder_feeds`                                                 |
| Contacts  | Search contacts/groups  | `typex.search_contact`                                                    |
| Contacts  | Search user to add      | `typex.search_user_to_add`                                                |
| Contacts  | Add contact             | `typex.add_contact`                                                       |
| Messages  | Send message            | `typex.send_message`                                                      |
| Messages  | Reply in chat           | `typex.send_message` (+ `reply_to_message_ref`)                           |
| Messages  | Reply in thread         | `typex.create_thread_reply`                                               |
| Messages  | Search / read history   | `typex.search_chat_records`                                               |
| Messages  | Get message link        | `typex.create_message_link`                                               |
| Messages  | Message reminder        | `typex.message_reminder`                                                  |
| Messages  | View @mentions          | `typex.list_mentions`                                                     |
| Groups    | Create group chat       | `typex.resolve_group_members` → `typex.create_group_chat`                 |
| Groups    | Add group members       | `typex.resolve_group_members` → `typex.manage_group_members` (action=add) |
| Groups    | Remove group members    | `typex.remove_group_members` (preview → confirm)                          |
| Groups    | List group members      | `typex.list_group_members`                                                |
| Resources | Upload files            | `typex.upload_chat_file`                                                  |
| Resources | List downloadable files | `typex.list_chat_downloadable_files`                                      |
| Resources | Download files          | `typex.download_chat_file`                                                |
| Interact  | Emoji reactions         | `typex.message_reaction`                                                  |
| Bookmarks | Manage bookmarks        | `typex.message_star`                                                      |

## MCP Tool Mapping

### Invocation Rules

1. **Read the tool schema before calling** — do not guess parameter shapes.
2. **Prefer one-step tools** — `contact_name` / `target.name` inline resolve; use `ref` only after ambiguity.
3. **Never expose internal refs** to the user.
4. **Set `response_locale`** (`zh` or `en`) when supported.
5. **Serialize `message_reaction` mutations** on the same `message_ref` — one at a time, wait for `ok:true`.

### Ref Types

| Ref           | Source                                                              | Used by                           |
| ------------- | ------------------------------------------------------------------- | --------------------------------- |
| `opaque_ref`  | `search_contact`                                                    | search, download, upload target   |
| `group_ref`   | `search_contact` (`search_group`) or `remove_group_members` preview | thread, member ops                |
| `message_ref` | `search_chat_records`, `list_mentions`                              | react, remind, star, reply, link  |
| `chat_ref`    | `list_mentions`                                                     | @mention reply target             |
| `contact_ref` | `search_user_to_add` candidate `opaque_ref`                         | `add_contact` only                |
| `member_ref`  | `remove_group_members` preview                                      | removal step 2                    |
| `file_ref`    | `list_chat_downloadable_files`                                      | `download_chat_file`              |
| `folder_ref`  | `list_folder_feeds`                                                 | folder retry after disambiguation |

### Ref Lifecycle

Refs are **session-scoped handles** mapped in TypeX MCP server memory — not permanent IDs.

- **Use only refs returned in the current MCP session** during the active task flow.
- **Do not cache or reuse refs** from earlier conversations, copied chat history, or saved notes.
- **Do not assume refs survive** TypeX restart, MCP disable/re-enable, or long idle gaps.
- If a tool returns ref-not-found or resolution error → **re-run the originating search** (`search_contact`, `search_chat_records`, `list_mentions`, etc.) — never invent or guess a ref string.
- **Same-task reuse is OK** — e.g. `opaque_ref` from `search_contact` → `search_chat_records` → `message_reminder` within one user request.

### Critical Distinctions

| Do NOT use                          | Use instead                                             | Why                                              |
| ----------------------------------- | ------------------------------------------------------- | ------------------------------------------------ |
| `search_user_to_add`                | `search_contact`                                        | Add-friend only vs existing contacts/groups      |
| `search_contact` for removal        | `remove_group_members`                                  | Finds contacts/groups, not in-group member names |
| `resolve_group_members` for removal | `remove_group_members`                                  | Resolves contacts to **invite**, not remove      |
| DM sender after @mention            | `send_message` with `chat_ref` + `reply_to_message_ref` | Reply in source group                            |
| `send_message` for Thread           | `create_thread_reply`                                   | Thread = sub-topic under group message           |

### Tool Catalog

| MCP Tool                              | R/W | When to use                                                                                                      |
| ------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------- |
| `typex.get_me`                        | R   | Identity, "who am I"                                                                                             |
| `typex.search_contact`                | R   | Default lookup: contacts or groups (`search_group`). Returns `opaque_ref`.                                       |
| `typex.search_user_to_add`            | R   | Add-friend directory search only                                                                                 |
| `typex.add_contact`                   | W   | Friend request after confirm; needs `contact_ref`                                                                |
| `typex.list_folder_feeds`             | R   | Chats in a folder + last message time                                                                            |
| `typex.list_mentions`                 | R   | @mention inbox; returns `message_ref` + `chat_ref`                                                               |
| `typex.search_chat_records`           | R   | Read/search messages; returns `message_ref`, `file_download_hint`                                                |
| `typex.send_message`                  | W   | Text/Markdown/rich text/link/image/photo collage; `reply_to_message_ref` for replies                             |
| `typex.create_thread_reply`           | W   | Thread reply: `group_ref` + `message_ref` + `text`                                                               |
| `typex.create_message_link`           | R   | Shareable link via `contact_name` + `query`                                                                      |
| `typex.message_reminder`              | W   | `action=create/list/cancel`; `remind_at` RFC3339                                                                 |
| `typex.message_reaction`              | W   | `action=add/remove/list` + `emoji`                                                                               |
| `typex.message_star`                  | W   | `action=star/unstar/list` bookmarks                                                                              |
| `typex.upload_chat_file`              | W   | Local file to chat; absolute `file_path`                                                                         |
| `typex.list_chat_downloadable_files`  | R   | Real attachments in chat                                                                                         |
| `typex.download_chat_file`            | W   | Requires `opaque_ref` plus `message_ref`+`file_name` or `file_ref`; saves to Desktop when `save_path` is omitted |
| `typex.resolve_group_members`         | R   | Contact names → refs for create/add                                                                              |
| `typex.create_group_chat`             | W   | Create group; encrypted/anonymous supported                                                                      |
| `typex.manage_group_members`          | W   | Normal use: `action=add`; low-level `action=remove` exists but avoid it—use `remove_group_members` for removals  |
| `typex.remove_group_members`          | W   | Preview (`user_confirmed:false`) → confirm → execute                                                             |
| `typex.list_group_members`            | R   | In-group display names                                                                                           |
| `typex.resolve_group_member_in_group` | R   | Low-level; avoid for normal removal                                                                              |

### Common Workflow Chains

```
# Send to contact
send_message(target.name="Alice", message=...) → if ambiguous: search_contact → target.ref

# Send to group (confirm if no exact single match)
send_message(target={name:"...", search_group:true}, message=...)

# Search history
search_chat_records(contact_name="...", search_group=true, query="...", limit=20)

# Reply @mention
list_mentions → send_message(target.ref=chat_ref, reply_to_message_ref=message_ref, message=...)

# Remind / react / star / link
search_contact → search_chat_records(query="...") → message_reminder | message_reaction | message_star | create_message_link

# Thread
search_contact(search_group=true) → search_chat_records → create_thread_reply(group_ref, message_ref, text)

# Download
search_contact → search_chat_records (check file_download_hint) → download_chat_file(opaque_ref, message_ref, file_name)
# alt: search_contact → list_chat_downloadable_files(opaque_ref) → download_chat_file(opaque_ref, file_ref)

# Add friend
search_user_to_add → user confirms not-yet-added candidate → add_contact(contact_ref=...)

# Create group + first message
resolve_group_members → create_group_chat → send_message(target={name: group_name, search_group:true}, ...)

# Remove member
remove_group_members(group_name, member_names, user_confirmed:false) → user confirms → remove_group_members(group_ref, member_refs, user_confirmed:true)

# Add member
search_contact(search_group=true) → resolve_group_members → manage_group_members(action=add, ...)
```

## Operation Workflows

Use **Common Workflow Chains** for tool sequences. Below: message types and scenario notes.

### Message Type Selection (`typex.send_message`)

| User intent                      | How to send                                                                          |
| -------------------------------- | ------------------------------------------------------------------------------------ |
| Plain text                       | `{type:"text", text:"..."}`                                                          |
| Markdown (bold, lists, headings) | `{type:"text", text:"...", is_markdown:true}`                                        |
| Rich HTML                        | `{type:"richtext", html:"<p>...</p>"}`                                               |
| Single image                     | `{type:"image", file_path:"/absolute/path.png"}`                                     |
| Multiple images + caption        | `{type:"photo_collage", images:[{file_path:"..."}], text:"..."}`                     |
| URL / group invite link          | `{type:"link", url:"https://..."}`                                                   |
| Local file (PDF, doc, etc.)      | `typex.upload_chat_file` with absolute `file_path`                                   |
| Group @mention                   | `mention_names:["Alice"]` on text message; use `list_group_members` if names unclear |

**Reply in chat:** `send_message` + `reply_to_message_ref` from `search_chat_records` or `list_mentions`.

**Reply in Thread:** `create_thread_reply` — user explicitly wants a sub-topic under a group message.

### Scenario Notes

| Scenario             | Tool                                 | Notes                                                                             |
| -------------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
| List folder feeds    | `list_folder_feeds`                  | Read-only; `folder_name` → if ambiguous, user picks → `folder_ref`                |
| Find contact/group   | `search_contact`                     | Groups need `search_group=true`                                                   |
| Add friend           | `search_user_to_add` → `add_contact` | Confirm a not-yet-added candidate before sending the request                      |
| Read recent messages | `search_chat_records`                | Omit `query`, set `limit`; summarize if >20                                       |
| Download file        | see chain above                      | App/runtime handles large file transfer; blocked if group has `restrict_download` |
| Remove member        | `remove_group_members`               | Owner/admin only; always preview first                                            |
| Star/bookmark        | `message_star`                       | `list` returns `message_ref` for direct `unstar`                                  |

## Examples

### Send with ambiguity

```
User: Send Zhang San a message that I'll be late

Assistant: I found two contacts named Zhang San:
1. Zhang San, Acme — last contact: yesterday
2. Zhang San, Design Team — last contact: last Friday
Which one?

User: The first one
→ search_contact → send_message → Sent.
```

### @mention reply

```
User: See who @mentioned me
Assistant: [list_mentions summary]

User: Reply to the Product Group one, say 52222
→ send_message(target.ref=chat_ref, reply_to_message_ref=message_ref, message={type:"text", text:"52222"})
```

### Remove member (high-risk)

```
User: Remove Li Lei from the Product Discussion Group
→ remove_group_members(preview) → "Remove Li Lei from Product Discussion Group?"
User: Yes
→ remove_group_members(user_confirmed:true) → Removed.
```

### Create group

```
User: Create a group with Alice, Bob, and Wang Ning named MCP Integration, and send "Let's start integration"
→ resolve_group_members → create_group_chat → send_message(target={name:"MCP Integration", search_group:true}, message=...) → Group created and message sent.
```

### Download blocked (text mention only)

```
User: Download the design draft from the Product Group

→ search_contact(search_group=true) → search_chat_records(query="design draft")
→ hit has file_download_hint=text_mention_only

Assistant: That message only mentions "design draft" in text — there is no downloadable file attachment. I can search for other files in this chat or list downloadable files if you'd like.
```

### Remove member — permission denied

```
User: Remove Wang Ning from the Design Team group

→ remove_group_members(preview) → user confirms → remove_group_members(user_confirmed:true) → fails (not owner/admin)

Assistant: I couldn't remove Wang Ning — only the group owner or an admin can remove members. You can ask the owner to do this, or I can list current members if that helps.
```

### Multiple matching groups

```
User: Send "Meeting moved to 4pm" to the product group

→ send_message(target={name:"Product Group", search_group:true}) → multiple group candidates returned

Assistant: I found two groups named "Product Group":
1. Product Group — Alice, Bob, Wang Ning — last message: today 14:32
2. Product MCP Group — Alice, Li Lei — last message: yesterday
Which one?

User: The first one
→ send_message(target.ref=opaque_ref, message=...) → Sent.
```

## Error Messages

**MCP unavailable:** TypeX MCP is not available right now. Open the TypeX desktop app, enable MCP on the MCP page in Settings, and try again.

**Target not found:** I couldn't find a matching contact or conversation. Provide a name, group name, email, TypeX ID, a recent message snippet, or ask me to add a contact.

**Send failed:** The message didn't send. Try again later, or I can recheck the contact and conversation.

**Too many results:** I found many related results. Narrow down by contact, group name, time range, or keyword.