MCP search navigation: TOC, match_id и note_html

tools/list

tools/list вернул:

{
  "name": "search",
  "description": "Search notes by query (hybrid: text + semantic)",
  "inputSchema": {"query": "string"}
}

{
  "name": "note_html",
  "description": "Get HTML content of a note by path",
  "inputSchema": {
    "properties": {
      "path": {"type":"string"}
    },
    "required": ["path"]
  }
}

Вывод:

• в публичном MCP trip2g.com schema для note_html не объявляет toc_path;
• pid тоже не объявлен;
• search возвращает plain text список результатов;
• structured toc/matches[].toc_path наружу не видны.

Попытка вызвать note_html с toc_path

Запрос:

{
  "path": "en/user/default-template.md",
  "toc_path": ["What the default template includes"]
}

Результат:

• HTTP 200;
• вернулся полный HTML заметки;
• размер ответа совпал с обычным note_html(path);
• toc_path фактически проигнорирован.

Запрос:

{
  "pid": 530,
  "toc_path": ["Methods"]
}

Результат:

{"error":{"code":-32602,"message":"path is required"}}

Вывод:

На trip2g.com/_system/mcp `toc_path` сейчас не работает как public tool contract, несмотря на текст в docs.

tools/list

search:

Search notes by query and return note ids, snippets, and match ids. After search, open the best result with note_html(pid=..., match_id=...) when a match id is available.

note_html:

Read a note by pid, note_id, href, or path. If search returned match_id, pass it here to fetch a focused chunk window and save tokens.

Input schema для note_html содержит:

{
  "context_words": "number",
  "href": "string",
  "match_id": "string",
  "note_id": "number",
  "path": "string",
  "pid": "number"
}

Вывод:

На dobireports актуальный механизм — не toc_path, а match_id-focused reads.

search возвращает match_id

Пример результата поиска:

1. 20 - ТЗ для агента - LLM Wiki страница для trip2g.com
   Исследование trip2g/20 - ТЗ для агента - LLM Wiki страница для trip2g.com.md
   https://dobireports.2pub.me/...
   … mcp_method: schema ...
   match_id: p31:c12

Другой результат:

2. 18 - Инструкция для внешнего агента - первый бесплатный инстанс
   Исследование trip2g/18 - Инструкция для внешнего агента - первый бесплатный инстанс.md
   https://dobireports.2pub.me/...
   … mcp_method: schema ...
   match_id: p29:c32

note_html(path, match_id) работает

Полный вызов:

{
  "path": "Исследование trip2g/18 - Инструкция для внешнего агента - первый бесплатный инстанс.md"
}

Вернул полный HTML заметки:

len ≈ 38236 chars

Focused вызов:

{
  "path": "Исследование trip2g/18 - Инструкция для внешнего агента - первый бесплатный инстанс.md",
  "match_id": "p29:c32"
}

Вернул короткое окно вокруг match:

len ≈ 1283 chars

Внутри был именно нужный участок:

### `SCHEMA.md` как MCP method
`SCHEMA.md` действительно хороший кандидат на отдельный `mcp_method`...

Также сработало:

{
  "pid": 29,
  "match_id": "p29:c32"
}

note_html(path, toc_path) на dobireports не сработал как секционная навигация

Запрос:

{
  "path":"Исследование trip2g/18 - Инструкция для внешнего агента - первый бесплатный инстанс.md",
  "toc_path":["MCP properties для `AGENTS.md`, `SCHEMA.md` и дополнительных инструкций"]
}

Результат:

• вернулся полный HTML заметки;
• toc_path был проигнорирован;
• в tools/list toc_path не объявлен.

Docs говорят

search returns toc + matches[].toc_path
note_html accepts toc_path

trip2g.com MCP фактически

search returns plain text list
note_html accepts only path

dobireports MCP фактически

search returns plain text list with match_id
note_html accepts path/pid/note_id/href + match_id
match_id returns focused chunk window

Вариант A — оставить match_id как основной

Плюсы:

• уже работает на dobireports;
• хорошо экономит токены;
• проще для агента: search → match_id → focused read;
• не требует точного совпадения заголовков.

Минусы:

• это chunk-window, а не semantic section;
• для длинной структурной документации иногда нужна вся секция, не только match context.

Вариант B — доделать toc_path

Плюсы:

• лучше для документации;
• позволяет агенту навигировать по структуре;
• хорошо сочетается с LLM Wiki/index-first mode.

Минусы:

• нужно добавить в реальный tools/list schema;
• нужно сделать search structured или хотя бы текстово выводить TOC/toc_path;
• нужно реализовать/починить фильтрацию note_html(..., toc_path=...).

Вариант C — поддерживать оба

Лучший продуктовый вариант:

match_id — for search hit focused windows
toc_path — for deliberate section navigation

Тогда recommended agent workflow:

1. search(query)
2. If result has match_id → note_html(pid/path, match_id)
3. If more context needed → full note_html(pid/path)
4. If TOC is available → navigate by toc_path to nearby sections
5. Answer with citations