admin/mcp-nextcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Nextcloud Collectives app support (#621)

Browse Source 
Implement MCP tools for the Collectives wiki/documentation app, enabling
agentic workflows for team knowledge base management.

16 tools covering collectives, pages, tags, search, and trash:
- Read: list collectives, list/get pages (with WebDAV content), search,
  list tags, list trashed pages
- Write: create/update collective, create/move/trash/restore pages,
  set emoji, create/assign/remove tags

Includes Docker hook for app installation, OCS API client with envelope
unwrapping, Pydantic models, unit tests (16), and integration tests (10).

Closes #621

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2026-03-25 07:53:50 +01:00
co-authored by Claude Opus 4.6
parent 7cbe323ef9
commit 32f5a0fe52
11 changed files with 1635 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/client/collectives/__init__.py
View File
tests/client/collectives/test_collectives_api.py
+372
View File
@@ -0,0 +1,372 @@
"""Unit tests for CollectivesClient API methods."""
import httpx
import pytest
from nextcloud_mcp_server.client.collectives import CollectivesClient
from tests.client.conftest import create_mock_response
pytestmark = pytest.mark.unit
# --- OCS mock helpers ---
def _ocs_response(data: dict | list) -> httpx.Response:
"""Wrap data in an OCS envelope and return as mock response."""
return create_mock_response(
status_code=200,
json_data={"ocs": {"meta": {"status": "ok", "statuscode": 200}, "data": data}},
)
def _sample_collective(
collective_id: int = 1, name: str = "Test Wiki", emoji: str | None = None
) -> dict:
return {
"id": collective_id,
"circleId": "circle-abc",
"emoji": emoji,
"name": name,
"level": 9,
"canEdit": True,
"canShare": True,
"pageMode": 0,
}
def _sample_page(
page_id: int = 10,
title: str = "Test Page",
parent_id: int = 0,
collective_path: str = "Collectives/Test Wiki",
) -> dict:
return {
"id": page_id,
"title": title,
"emoji": None,
"fileName": f"{title}.md",
"filePath": f"{title}.md",
"collectivePath": collective_path,
"parentId": parent_id,
"timestamp": 1700000000,
"size": 42,
"lastUserId": "testuser",
"lastUserDisplayName": "Test User",
"subpageOrder": [],
"isFullWidth": False,
}
def _sample_tag(
tag_id: int = 1, name: str = "important", color: str = "FF0000"
) -> dict:
return {
"id": tag_id,
"collectiveId": 1,
"name": name,
"color": color,
}
# --- Collectives ---
async def test_get_collectives(mocker):
"""Test listing collectives unwraps OCS envelope correctly."""
mock_response = _ocs_response(
{
"collectives": [
_sample_collective(1, "Wiki A"),
_sample_collective(2, "Wiki B"),
]
}
)
mocker.patch.object(CollectivesClient, "_make_request", return_value=mock_response)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.get_collectives()
assert isinstance(result, list)
assert len(result) == 2
assert result[0]["id"] == 1
assert result[1]["name"] == "Wiki B"
async def test_create_collective(mocker):
"""Test creating a collective sends name and emoji."""
mock_response = _ocs_response(
{"collective": _sample_collective(5, "New Wiki", "📚")}
)
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.create_collective("New Wiki", emoji="📚")
assert result["id"] == 5
assert result["name"] == "New Wiki"
assert result["emoji"] == "📚"
call_args = mock_request.call_args
assert call_args[0][0] == "POST"
assert call_args[1]["json"]["name"] == "New Wiki"
assert call_args[1]["json"]["emoji"] == "📚"
# --- Pages ---
async def test_get_pages(mocker):
"""Test listing pages in a collective."""
mock_response = _ocs_response(
{"pages": [_sample_page(10, "Page A"), _sample_page(20, "Page B")]}
)
mocker.patch.object(CollectivesClient, "_make_request", return_value=mock_response)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.get_pages(collective_id=1)
assert len(result) == 2
assert result[0]["title"] == "Page A"
assert result[1]["id"] == 20
async def test_get_page(mocker):
"""Test getting a single page metadata."""
mock_response = _ocs_response({"page": _sample_page(10, "My Page")})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.get_page(collective_id=1, page_id=10)
assert result["id"] == 10
assert result["title"] == "My Page"
assert result["collectivePath"] == "Collectives/Test Wiki"
call_args = mock_request.call_args
assert "/collectives/1/pages/10" in call_args[0][1]
async def test_create_page(mocker):
"""Test creating a page under a parent."""
mock_response = _ocs_response({"page": _sample_page(30, "New Page", parent_id=10)})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.create_page(collective_id=1, parent_id=10, title="New Page")
assert result["id"] == 30
assert result["parentId"] == 10
call_args = mock_request.call_args
assert call_args[0][0] == "POST"
assert "/collectives/1/pages/10" in call_args[0][1]
assert call_args[1]["json"]["title"] == "New Page"
async def test_trash_page(mocker):
"""Test trashing a page sends DELETE."""
mock_response = create_mock_response(status_code=200, json_data={})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
await client.trash_page(collective_id=1, page_id=10)
call_args = mock_request.call_args
assert call_args[0][0] == "DELETE"
assert "/collectives/1/pages/10" in call_args[0][1]
async def test_move_page(mocker):
"""Test moving a page sends PUT with correct params."""
mock_response = _ocs_response(
{"page": _sample_page(10, "Moved Page", parent_id=20)}
)
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.move_page(
collective_id=1, page_id=10, parent_id=20, title="Moved Page"
)
assert result["parentId"] == 20
call_args = mock_request.call_args
assert call_args[0][0] == "PUT"
assert call_args[1]["json"]["parentId"] == 20
# --- Search ---
async def test_search_pages(mocker):
"""Test full-text search sends query parameter."""
mock_response = _ocs_response({"pages": [_sample_page(10, "Result Page")]})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.search_pages(collective_id=1, query="test query")
assert len(result) == 1
assert result[0]["title"] == "Result Page"
call_args = mock_request.call_args
assert call_args[1]["params"]["searchString"] == "test query"
# --- Tags ---
async def test_get_tags(mocker):
"""Test listing tags."""
mock_response = _ocs_response(
{"tags": [_sample_tag(1, "important"), _sample_tag(2, "draft", "00FF00")]}
)
mocker.patch.object(CollectivesClient, "_make_request", return_value=mock_response)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.get_tags(collective_id=1)
assert len(result) == 2
assert result[0]["name"] == "important"
assert result[1]["color"] == "00FF00"
async def test_create_tag(mocker):
"""Test creating a tag."""
mock_response = _ocs_response({"tag": _sample_tag(3, "review", "0000FF")})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.create_tag(collective_id=1, name="review", color="0000FF")
assert result["id"] == 3
assert result["name"] == "review"
call_args = mock_request.call_args
assert call_args[0][0] == "POST"
assert call_args[1]["json"]["name"] == "review"
async def test_assign_tag(mocker):
"""Test assigning a tag to a page."""
mock_response = create_mock_response(status_code=200, json_data={})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
await client.assign_tag(collective_id=1, page_id=10, tag_id=3)
call_args = mock_request.call_args
assert call_args[0][0] == "PUT"
assert "/pages/10/tags/3" in call_args[0][1]
async def test_remove_tag(mocker):
"""Test removing a tag from a page."""
mock_response = create_mock_response(status_code=200, json_data={})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
await client.remove_tag(collective_id=1, page_id=10, tag_id=3)
call_args = mock_request.call_args
assert call_args[0][0] == "DELETE"
assert "/pages/10/tags/3" in call_args[0][1]
# --- Trash ---
async def test_get_trashed_pages(mocker):
"""Test listing trashed pages."""
trashed = _sample_page(10, "Trashed Page")
trashed["trashTimestamp"] = 1700000000
mock_response = _ocs_response({"pages": [trashed]})
mocker.patch.object(CollectivesClient, "_make_request", return_value=mock_response)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.get_trashed_pages(collective_id=1)
assert len(result) == 1
assert result[0]["title"] == "Trashed Page"
async def test_restore_page(mocker):
"""Test restoring a page from trash."""
mock_response = _ocs_response({"page": _sample_page(10, "Restored Page")})
mock_request = mocker.patch.object(
CollectivesClient, "_make_request", return_value=mock_response
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
result = await client.restore_page(collective_id=1, page_id=10)
assert result["title"] == "Restored Page"
call_args = mock_request.call_args
assert call_args[0][0] == "PATCH"
assert "/pages/trash/10" in call_args[0][1]
# --- Error Handling ---
async def test_get_collectives_403(mocker):
"""Test 403 response raises HTTPStatusError."""
mock_response = create_mock_response(
status_code=403, json_data={"message": "Forbidden"}
)
mock_response.raise_for_status = lambda: (_ for _ in ()).throw(
httpx.HTTPStatusError(
"Forbidden", request=mock_response.request, response=mock_response
)
)
mocker.patch.object(
CollectivesClient,
"_make_request",
side_effect=httpx.HTTPStatusError(
"Forbidden",
request=httpx.Request("GET", "http://test"),
response=mock_response,
),
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
with pytest.raises(httpx.HTTPStatusError):
await client.get_collectives()
async def test_get_page_404(mocker):
"""Test 404 response raises HTTPStatusError."""
mock_response = create_mock_response(
status_code=404, json_data={"message": "Not found"}
)
mocker.patch.object(
CollectivesClient,
"_make_request",
side_effect=httpx.HTTPStatusError(
"Not Found",
request=httpx.Request("GET", "http://test"),
response=mock_response,
),
)
client = CollectivesClient(mocker.AsyncMock(spec=httpx.AsyncClient), "testuser")
with pytest.raises(httpx.HTTPStatusError):
await client.get_page(collective_id=1, page_id=999)
tests/server/test_collectives_mcp.py
+412
View File
@@ -0,0 +1,412 @@
"""Integration tests for Nextcloud Collectives MCP tools."""
import json
import logging
import uuid
import httpx
import pytest
from mcp import ClientSession
logger = logging.getLogger(__name__)
pytestmark = pytest.mark.integration
# Nextcloud credentials for direct API cleanup (matches docker-compose.yml)
_NC_BASE = "http://localhost:8080"
_NC_AUTH = ("admin", "admin")
_OCS_HEADERS = {
"OCS-APIRequest": "true",
"Accept": "application/json",
}
# --- Fixtures ---
@pytest.fixture(scope="session")
async def temporary_collective(nc_mcp_client: ClientSession):
"""Create a temporary collective for testing. Cleaned up after session."""
unique_suffix = uuid.uuid4().hex[:8]
name = f"MCP Test Collective {unique_suffix}"
result = await nc_mcp_client.call_tool(
"collectives_create_collective",
{"name": name, "emoji": "🧪"},
)
assert result.isError is False, f"Failed to create collective: {result.content}"
data = json.loads(result.content[0].text)
collective_id = data["id"]
logger.info(f"Created temporary collective: {name} (ID: {collective_id})")
# Get the landing page ID (auto-created with each collective)
pages_result = await nc_mcp_client.call_tool(
"collectives_get_pages",
{"collective_id": collective_id},
)
pages_data = json.loads(pages_result.content[0].text)
landing_page_id = pages_data["pages"][0]["id"]
yield {
"id": collective_id,
"name": name,
"landing_page_id": landing_page_id,
}
# Cleanup: trash and permanently delete the collective via direct OCS API
try:
async with httpx.AsyncClient(base_url=_NC_BASE, auth=_NC_AUTH) as client:
api = "/ocs/v2.php/apps/collectives/api/v1.0"
await client.delete(
f"{api}/collectives/{collective_id}",
headers=_OCS_HEADERS,
)
await client.delete(
f"{api}/collectives/trash/{collective_id}",
headers=_OCS_HEADERS,
)
logger.info(f"Cleaned up collective: {collective_id}")
except Exception as e:
logger.warning(f"Cleanup of collective {collective_id} failed: {e}")
# --- Tool Discovery ---
async def test_collectives_tools_available(nc_mcp_client: ClientSession):
"""Verify all Collectives MCP tools are registered."""
tools = await nc_mcp_client.list_tools()
tool_names = [tool.name for tool in tools.tools]
expected_tools = [
"collectives_get_collectives",
"collectives_create_collective",
"collectives_update_collective",
"collectives_get_pages",
"collectives_get_page",
"collectives_create_page",
"collectives_move_page",
"collectives_trash_page",
"collectives_restore_page",
"collectives_set_page_emoji",
"collectives_search_pages",
"collectives_get_tags",
"collectives_create_tag",
"collectives_assign_tag",
"collectives_remove_tag",
"collectives_get_trashed_pages",
]
for expected in expected_tools:
assert expected in tool_names, (
f"Expected tool '{expected}' not found in available tools"
)
logger.info(f"All {len(expected_tools)} Collectives tools registered")
# --- Collective CRUD ---
async def test_collectives_list(
nc_mcp_client: ClientSession, temporary_collective: dict
):
"""Test listing collectives includes the temporary one."""
result = await nc_mcp_client.call_tool("collectives_get_collectives", {})
assert result.isError is False
data = json.loads(result.content[0].text)
assert data["success"] is True
assert data["total"] >= 1
collective_ids = [c["id"] for c in data["collectives"]]
assert temporary_collective["id"] in collective_ids
logger.info(f"Found {data['total']} collectives")
async def test_collectives_update_emoji(
nc_mcp_client: ClientSession, temporary_collective: dict
):
"""Test updating a collective's emoji."""
result = await nc_mcp_client.call_tool(
"collectives_update_collective",
{"collective_id": temporary_collective["id"], "emoji": "📖"},
)
assert result.isError is False
data = json.loads(result.content[0].text)
assert data["success"] is True
assert data["collective_id"] == temporary_collective["id"]
logger.info("Collective emoji updated")
# --- Page CRUD ---
async def test_collectives_page_workflow(
nc_mcp_client: ClientSession, temporary_collective: dict
):
"""Test the full page lifecycle: create, read, set emoji, trash, restore."""
cid = temporary_collective["id"]
landing_id = temporary_collective["landing_page_id"]
# 1. Create a page
unique_title = f"Test Page {uuid.uuid4().hex[:8]}"
create_result = await nc_mcp_client.call_tool(
"collectives_create_page",
{"collective_id": cid, "parent_id": landing_id, "title": unique_title},
)
assert create_result.isError is False
create_data = json.loads(create_result.content[0].text)
page_id = create_data["id"]
assert create_data["collective_id"] == cid
assert create_data["parent_id"] == landing_id
logger.info(f"Created page: {unique_title} (ID: {page_id})")
# 2. List pages — should include the new page
list_result = await nc_mcp_client.call_tool(
"collectives_get_pages",
{"collective_id": cid},
)
assert list_result.isError is False
list_data = json.loads(list_result.content[0].text)
page_ids = [p["id"] for p in list_data["pages"]]
assert page_id in page_ids
logger.info(f"Page found in list ({list_data['total']} pages)")
# 3. Get page with content
get_result = await nc_mcp_client.call_tool(
"collectives_get_page",
{"collective_id": cid, "page_id": page_id},
)
assert get_result.isError is False
get_data = json.loads(get_result.content[0].text)
assert get_data["page"]["id"] == page_id
assert get_data["page"]["title"] == unique_title
# New pages have empty content (empty string or None)
logger.info("Page metadata retrieved")
# 4. Set page emoji
emoji_result = await nc_mcp_client.call_tool(
"collectives_set_page_emoji",
{"collective_id": cid, "page_id": page_id, "emoji": "🚀"},
)
assert emoji_result.isError is False
logger.info("Page emoji set")
# 5. Trash the page
trash_result = await nc_mcp_client.call_tool(
"collectives_trash_page",
{"collective_id": cid, "page_id": page_id},
)
assert trash_result.isError is False
logger.info("Page trashed")
# 6. Verify page is in trash
trashed_result = await nc_mcp_client.call_tool(
"collectives_get_trashed_pages",
{"collective_id": cid},
)
assert trashed_result.isError is False
trashed_data = json.loads(trashed_result.content[0].text)
trashed_ids = [p["id"] for p in trashed_data["pages"]]
assert page_id in trashed_ids
logger.info("Page found in trash")
# 7. Restore from trash
restore_result = await nc_mcp_client.call_tool(
"collectives_restore_page",
{"collective_id": cid, "page_id": page_id},
)
assert restore_result.isError is False
logger.info("Page restored from trash")
# 8. Verify page is back in pages list
list_result2 = await nc_mcp_client.call_tool(
"collectives_get_pages",
{"collective_id": cid},
)
list_data2 = json.loads(list_result2.content[0].text)
page_ids2 = [p["id"] for p in list_data2["pages"]]
assert page_id in page_ids2
logger.info("Page verified restored to pages list")
async def test_collectives_get_landing_page_content(
nc_mcp_client: ClientSession, temporary_collective: dict
):
"""Test that the landing page has auto-generated content readable via WebDAV."""
cid = temporary_collective["id"]
landing_id = temporary_collective["landing_page_id"]
result = await nc_mcp_client.call_tool(
"collectives_get_page",
{"collective_id": cid, "page_id": landing_id},
)
assert result.isError is False
data = json.loads(result.content[0].text)
assert data["page"]["fileName"] == "Readme.md"
assert data["content"] is not None, (
"Landing page should have auto-generated content"
)
assert "Welcome" in data["content"], "Landing page should contain welcome text"
logger.info(f"Landing page content: {len(data['content'])} bytes")
async def test_collectives_move_page(
nc_mcp_client: ClientSession, temporary_collective: dict
):
"""Test moving a page (rename)."""
cid = temporary_collective["id"]
landing_id = temporary_collective["landing_page_id"]
# Create a page to move
create_result = await nc_mcp_client.call_tool(
"collectives_create_page",
{
"collective_id": cid,
"parent_id": landing_id,
"title": f"Movable Page {uuid.uuid4().hex[:8]}",
},
)
assert create_result.isError is False
page_id = json.loads(create_result.content[0].text)["id"]
# Move (rename) the page
new_title = f"Renamed Page {uuid.uuid4().hex[:8]}"
move_result = await nc_mcp_client.call_tool(
"collectives_move_page",
{
"collective_id": cid,
"page_id": page_id,
"title": new_title,
},
)
assert move_result.isError is False
data = json.loads(move_result.content[0].text)
assert data["page_id"] == page_id
assert "moved" in data["message"]
logger.info(f"Page renamed to: {new_title}")
# Cleanup
await nc_mcp_client.call_tool(
"collectives_trash_page",
{"collective_id": cid, "page_id": page_id},
)
# --- Tags ---
async def test_collectives_tag_workflow(
nc_mcp_client: ClientSession, temporary_collective: dict
):
"""Test tag lifecycle: create tag, assign to page, remove from page."""
cid = temporary_collective["id"]
landing_id = temporary_collective["landing_page_id"]
# 1. Create a tag
tag_name = f"test-tag-{uuid.uuid4().hex[:6]}"
create_tag_result = await nc_mcp_client.call_tool(
"collectives_create_tag",
{"collective_id": cid, "name": tag_name, "color": "FF5733"},
)
assert create_tag_result.isError is False
tag_data = json.loads(create_tag_result.content[0].text)
tag_id = tag_data["id"]
assert tag_data["name"] == tag_name
assert tag_data["color"] == "FF5733"
logger.info(f"Created tag: {tag_name} (ID: {tag_id})")
# 2. List tags — should include the new tag
list_tags_result = await nc_mcp_client.call_tool(
"collectives_get_tags",
{"collective_id": cid},
)
assert list_tags_result.isError is False
tags_data = json.loads(list_tags_result.content[0].text)
tag_ids = [t["id"] for t in tags_data["tags"]]
assert tag_id in tag_ids
logger.info(f"Tag found in list ({tags_data['total']} tags)")
# 3. Create a page to tag
page_result = await nc_mcp_client.call_tool(
"collectives_create_page",
{
"collective_id": cid,
"parent_id": landing_id,
"title": f"Tagged Page {uuid.uuid4().hex[:8]}",
},
)
assert page_result.isError is False
page_id = json.loads(page_result.content[0].text)["id"]
# 4. Assign tag to page
assign_result = await nc_mcp_client.call_tool(
"collectives_assign_tag",
{"collective_id": cid, "page_id": page_id, "tag_id": tag_id},
)
assert assign_result.isError is False
logger.info(f"Tag {tag_id} assigned to page {page_id}")
# 5. Remove tag from page
remove_result = await nc_mcp_client.call_tool(
"collectives_remove_tag",
{"collective_id": cid, "page_id": page_id, "tag_id": tag_id},
)
assert remove_result.isError is False
logger.info(f"Tag {tag_id} removed from page {page_id}")
# Cleanup
await nc_mcp_client.call_tool(
"collectives_trash_page",
{"collective_id": cid, "page_id": page_id},
)
# --- Search ---
async def test_collectives_search(
nc_mcp_client: ClientSession, temporary_collective: dict
):
"""Test full-text search within a collective."""
cid = temporary_collective["id"]
# Search for text in the landing page (contains "Welcome")
result = await nc_mcp_client.call_tool(
"collectives_search_pages",
{"collective_id": cid, "query": "Welcome"},
)
assert result.isError is False
data = json.loads(result.content[0].text)
assert data["success"] is True
assert data["query"] == "Welcome"
assert data["collective_id"] == cid
# Search may or may not find results depending on indexing timing
logger.info(f"Search returned {data['total']} results for 'Welcome'")
# --- Error Handling ---
async def test_collectives_get_page_not_found(nc_mcp_client: ClientSession):
"""Test getting a non-existent page returns an error."""
result = await nc_mcp_client.call_tool(
"collectives_get_page",
{"collective_id": 999999, "page_id": 999999},
)
assert result.isError is True
logger.info("Non-existent page correctly returned error")
async def test_collectives_get_pages_not_found(nc_mcp_client: ClientSession):
"""Test listing pages for a non-existent collective returns an error."""
result = await nc_mcp_client.call_tool(
"collectives_get_pages",
{"collective_id": 999999},
)
assert result.isError is True
logger.info("Non-existent collective correctly returned error")