mattermost-dl/mattermost-search/SKILL.md

name, description

name

description

mattermost-search

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)

{
  "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 — предложить пользователю, не запускать самому