add mcp
This commit is contained in:
Сергей Маринкевич
@@ -0,0 +1,172 @@
|
||||
---
|
||||
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 — предложить пользователю, не запускать самому |
|
||||
Reference in New Issue
Block a user