ai: wrolpi_mcp becomes a thin proxy over /api/ai

Every MCP tool is now one /api/ai call with minimal text rendering;
the formatting, link building, and truncation logic it used to carry
untested lives (tested) in modules/ai.  Tool names are unchanged for
external clients; a source-scan test guards the names and that the
proxy only reaches /api/ai.  New lean blueprint endpoints back the two
tools that had no equivalent: GET archives/{id} (detail + snapshot
history) and GET videos/{id}/comments (paged author lines).  Paged
content is read up to the old 50k-char bound.  get_inventory_items now
takes the inventory slug (inventories are config-only; the old
numeric-id endpoint no longer exists).  This also brings wrolpi_mcp
into version control (venv/ is already gitignored).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Roland 2026-08-25 22:07:49 -06:00
parent 69d78ad95d
commit 9f22b09b0a
No known key found for this signature in database
GPG key ID: 1BA620CE6C9A4680
9 changed files with 692 additions and 0 deletions

View file

@ -126,6 +126,28 @@ async def get_video_captions(request: Request, file_group_id: int):
return json_response(lib.paginate_text(text, _offset(request)))
@ai_bp.get('/videos/<file_group_id:int>/comments')
@openapi.definition(
summary='Get video comments',
description='Read the downloaded comments of a video by its ID. Long comment threads are paged:'
' request again with offset=next_offset to continue reading.',
)
@openapi.operation('get_video_comments')
@openapi.parameter('offset', int, 'query')
@openapi.response(HTTPStatus.OK, schema.AIPagedTextResponse)
@openapi.response(HTTPStatus.NOT_FOUND, JSONErrorResponse)
async def get_video_comments(request: Request, file_group_id: int):
video = videos_lib.get_video(file_group_id)
comments = video.get_comments() or []
lines = []
for comment in comments:
author = comment.get('author') or 'unknown'
text = (comment.get('text') or '').strip()
if text:
lines.append(f'{author}: {text}')
return json_response(lib.paginate_text('\n'.join(lines), _offset(request)))
@ai_bp.post('/archives/search')
@openapi.definition(
summary='Search archived web pages',
@ -150,6 +172,32 @@ async def search_archives(_: Request, body: schema.AIArchiveSearchRequest):
return json_response(lib.format_file_groups(file_groups, total))
@ai_bp.get('/archives/<file_group_id:int>')
@openapi.definition(
summary='Get one archived web page',
description='Get details about one archived web page by its ID from search results: title, source URL,'
' its WROLPi link, a text_link to read it, and earlier snapshots of the same page.',
)
@openapi.operation('get_archive')
@openapi.response(HTTPStatus.NOT_FOUND, JSONErrorResponse)
async def get_archive(request: Request, file_group_id: int):
archive = archive_lib.get_archive_by_file_group_id(request.ctx.session, file_group_id, skip_viewed=True)
result = lib.format_file_group(archive.file_group.__json__(),
description_length=lib.DETAIL_DESCRIPTION_LENGTH)
history = []
for snapshot in archive.history[:10]:
fg = snapshot.file_group.__json__()
history.append({k: v for k, v in dict(
id=fg.get('id'),
title=fg.get('title') or fg.get('name'),
published=fg.get('published_datetime'),
link=lib.wrolpi_link(fg),
).items() if v is not None})
if history:
result['history'] = history
return json_response(result)
@ai_bp.get('/archives/<file_group_id:int>/text')
@openapi.definition(
summary='Read an archived web page',

View file

@ -140,6 +140,47 @@ async def test_ai_get_archive_text(async_client, test_session, archive_factory):
assert response.status_code == HTTPStatus.NOT_FOUND
@pytest.mark.asyncio
async def test_ai_get_archive(async_client, test_session, archive_factory):
"""A single archive can be fetched with its history of snapshots."""
archive_factory(domain='example.com', url='https://example.com/a', title='first', contents='one')
archive = archive_factory(domain='example.com', url='https://example.com/a', title='second', contents='two')
test_session.commit()
request, response = await async_client.get(f'/api/ai/archives/{archive.file_group_id}')
assert response.status_code == HTTPStatus.OK
assert response.json['kind'] == 'archive'
assert response.json['link'] == f'/archives/{archive.file_group_id}'
# History holds the OTHER snapshots of the URL, not the archive itself.
assert [i['title'] for i in response.json['history']] == ['first']
request, response = await async_client.get('/api/ai/archives/123456')
assert response.status_code == HTTPStatus.NOT_FOUND
@pytest.mark.asyncio
async def test_ai_get_video_comments(async_client, test_session, video_factory):
"""Video comments render as paged author lines."""
info_json = dict(duration=5, comments=[
dict(author='alice', text='great video'),
dict(author='bob', text='thanks'),
])
video = video_factory(title='commented', with_info_json=info_json)
test_session.commit()
request, response = await async_client.get(f'/api/ai/videos/{video.file_group_id}/comments')
assert response.status_code == HTTPStatus.OK
assert 'alice: great video' in response.json['content']
assert 'bob: thanks' in response.json['content']
# No comments is an empty page, not an error.
no_comments = video_factory(title='quiet')
test_session.commit()
request, response = await async_client.get(f'/api/ai/videos/{no_comments.file_group_id}/comments')
assert response.status_code == HTTPStatus.OK
assert response.json['content'] == ''
@pytest.mark.asyncio
async def test_ai_search_docs(async_client, test_session, test_directory, example_epub, refresh_files):
"""Docs can be searched and fetched with links."""

View file

@ -0,0 +1,40 @@
"""Guards for the wrolpi_mcp thin proxy.
The MCP server's venv (with the `mcp` package) is separate from the API's, so these are source
scans: external clients depend on the tool names, and the proxy must only reach the tested
/api/ai blueprint (plus the two whole-API reads that predate it)."""
import re
from wrolpi.vars import PROJECT_DIR
MCP_SERVER = PROJECT_DIR / 'wrolpi_mcp/server.py'
# The tool names external clients (Claude etc.) already use. Renaming one breaks them.
EXPECTED_TOOLS = {
'search', 'search_videos', 'search_archives', 'search_docs',
'search_zim', 'search_default_zims',
'get_video', 'get_video_captions', 'get_video_comments',
'get_archive', 'get_archive_text',
'get_doc', 'get_zim_entry',
'list_collections', 'list_zim_files',
'get_statistics', 'get_inventory', 'get_inventory_items', 'get_status',
}
def test_mcp_tool_names_unchanged():
text = MCP_SERVER.read_text()
tools = set(re.findall(r'@mcp\.tool[^\n]*\)\nasync def (\w+)\(', text))
assert tools == EXPECTED_TOOLS
def test_mcp_is_a_thin_proxy():
"""The MCP calls only /api/ai (and the raw statistics read); the formatting layer is gone."""
text = MCP_SERVER.read_text()
endpoints = set(re.findall(r'["\'](/api/[a-z_/{}]+)', text))
allowed_non_ai = {'/api/statistics'}
offenders = {e for e in endpoints if not e.startswith('/api/ai') and e not in allowed_non_ai}
assert not offenders, f'MCP tools must proxy /api/ai, found: {sorted(offenders)}'
# The formatting/truncation layer moved into modules/ai; it must not come back here.
for name in ('_wrolpi_link', '_fmt_file_group', 'html_to_text', 'BeautifulSoup'):
assert name not in text, f'{name} belongs in modules/ai, not the MCP proxy'