mattermost-dl/mattermost-search/SKILL.md

---
name: mattermost-search
description: |
  Search Mattermost export dumps via mattermost-search MCP (mm_search_mcp.py):
  message text, attachment names, attachment text content, filters by user/channel/team/date.
  Use when the user asks to find messages, posts, or files in Mattermost exports,
  mattermost-dl results, or the local sqlite index. Requires MCP server mattermost-search.
  Index bypass (no_index, regex, CLI, grep) needs explicit user permission.
---

# Mattermost Search (MCP)

Search local Mattermost JSON exports produced by `mattermost-dl.py`. **Always use MCP
tools** (`mm_search`, `mm_search_index_status`) as the default path.

## Mandatory rules

**Поиск в обход индекса и MCP — только с явного разрешения пользователя.**

Не делать самостоятельно, пока пользователь явно не попросил:

| Обход | Примеры |
|---|---|
| Индекс | `no_index=true`, `regex=true` (сканирует JSON), прямое чтение/grep по `results/` |
| MCP | запуск `mm_search.py`, `python mm_search.py …`, любой shell вместо MCP tools |

**Разрешено без спроса:** `mm_search` с индексом (`used_index: true`) — обычный
`search_mode="message"`, `file_name`, `file_content`.

**Если индекс недоступен или нужен regex/scan:** остановиться, сообщить пользователю
(нет `db_exists`, нужен `mm_index.py`, или требуется медленный обход JSON) и **дождаться
явного «да»** перед `no_index`, `regex`, CLI или чтением файлов экспорта.

## Prerequisites

- **`mattermost-search`** MCP server connected (`mm_search`, `mm_search_index_status` visible).
- Export JSON under `results/` (or `MM_SEARCH_ROOT`).
- SQLite index `mattermost_index.sqlite` (or `MM_SEARCH_DB`) for fast search and
  **required** for attachment search. Build/update: `python mm_index.py`.

Server env (set in `mcp.json` `cwd` / `env`):

| Variable | Default |
|---|---|
| `MM_SEARCH_ROOT` | `results` |
| `MM_SEARCH_DB` | `mattermost_index.sqlite` |

## Quick start

1. `mm_search_index_status()` — confirm `db_exists`, `root_exists`, `json_files`.
2. Pick **search_mode** (see table below).
3. `mm_search(query=…, …)` with filters; keep `limit` small (10–50) unless the user needs all hits.
4. Read `matches[].post.message`; for attachments also `matches[].attachment`.

## Tools

| Need | Tool |
|---|---|
| Search messages / attachments | `mm_search(query, …)` |
| Check index & export layout | `mm_search_index_status(db?, root?)` |

## Choose search_mode

| Goal | `search_mode` | Notes |
|---|---|---|
| Text in post body | `message` (default) | Uses FTS index; JSON scan only with user permission |
| Attachment filename | `file_name` | Index **required**; no `regex` |
| Text inside attachment | `file_content` | Index **required**; UTF-8 text files only |
| Regex in message | `message` + `regex=true` | **User permission required** — scans JSON, skips index |

## mm_search parameters

| Param | Role |
|---|---|
| `query` | Search string (or regex pattern) |
| `user` | Exact username filter |
| `channel` | Exact `display_name` or `name` |
| `team` | Exact team name |
| `after` / `before` | `YYYY-MM-DD` or ISO datetime |
| `limit` | Max matches (apply early — large exports) |
| `ignore_case` | Default: on for substring, off for regex |
| `no_index` | Force JSON file scan — **user permission required** |
| `output` | `json` (default) or `human` (CLI-style lines) |
| `show_file` | Prefix `file:idx:` in human output |

## Response shape (`output=json`)

```json
{
  "count": 2,
  "used_index": true,
  "search_mode": "message",
  "root": "results",
  "db": "mattermost_index.sqlite",
  "matches": [
    {
      "file": "results/20260605/user/channel.json",
      "channel": "general",
      "team": "myteam",
      "post": {
        "id": "…",
        "idx": 42,
        "created": "2026-01-15T10:00:00Z",
        "username": "alice",
        "message": "…",
        "files": ["path/to/file.pdf"]
      },
      "attachment": {
        "filename": "doc.txt",
        "path": "…",
        "is_text": true
      }
    }
  ]
}
```

`attachment` is present only for `file_name` / `file_content` hits.

## Common workflows

**Find what someone wrote about a topic**

```
mm_search(query="deploy rollback", user="alice", after="2026-01-01", limit=20)
```

**Find posts in a channel**

```
mm_search(query="incident", channel="alerts", limit=30)
```

**Find attachment by name**

```
mm_search(query="report.pdf", search_mode="file_name", limit=10)
```

**Regex over raw JSON (no index)** — только после явного разрешения пользователя

```
mm_search(query="ERROR-\\d+", regex=true, no_index=true, limit=50)
```

**Human-readable listing for the user**

```
mm_search(query="standup", output="human", show_file=true, limit=15)
```

## Pitfalls

- `file_name` / `file_content` + `regex=true` → error.
- Attachment search without index → error; run `mm_index.py` first.
- `channel` / `user` / `team` are **exact** matches, not substring.
- Token budget: prefer `limit`, narrow `after`/`before`, then widen if empty.
- If `count=0` with index: broaden `query`, drop filters, suggest `mm_index.py` — **не**
  переключаться на `no_index` / `regex` / CLI без явного разрешения.

## Related CLI

Использовать **только по явной просьбе пользователя** (обход MCP):

| CLI | MCP equivalent |
|---|---|
| `mm_search.py QUERY` | `mm_search(query=QUERY)` |
| `--file-name` | `search_mode="file_name"` |
| `--file-content` | `search_mode="file_content"` |
| `--regex` | `regex=true` (permission required) |
| `--no-index` | `no_index=true` (permission required) |
| `mm_index.py` | not in MCP — предложить пользователю, не запускать самому |