nextcloud-agent-development

Nextcloud Agent Development

Use this skill for changes to the nextcloud-agent connector. The package owns Nextcloud API calls, mappings, MCP tools, and connector content; it does not own the connector SDK, Arbora admission, the shared Pages renderer, or Pipelines hooks.

Repository map and runtime boundary

• nextcloud_agent/__init__.py creates the SDK Connector with NextcloudAPI, get_client, and nextcloud_agent.mcp_server as its tool module. Preserve this wiring when changing a client or tool.
• nextcloud_agent/mcp_server.py registers the condensed action-routed tools nextcloud_files, nextcloud_user, nextcloud_sharing, nextcloud_calendar, and nextcloud_contacts. Their action lists and client calls are the runtime contract; the domain clients live under nextcloud_agent/api/ and are composed by nextcloud_agent/api/__init__.py.
• nextcloud_agent/auth.py reads NEXTCLOUD_URL, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD through the SDK setting boundary. The API client resolves the named nextcloud TLS profile through the SDK and configures a verified, same-origin requests session; preserve that transport boundary and its cleanup.
• nextcloud_agent/ontology/, nextcloud_agent/prompts/, and nextcloud_agent/skills/ contain connector content. The package-data table in pyproject.toml declares those trees plus agent_data/** and connectors/**; inspect a built wheel when changing packaged content.
• The current pyproject.toml declares nextcloud-mcp as its console script and nextcloud-mcp as its connector identity. Older README, AGENTS, and deployment examples mention a nextcloud-agent console script and agent_server.py, but those are not declared or present in this source tree. Do not invent that runtime or rewrite it as part of a Pages/skill change.

Rapid delivery: the 5-minute contract

1. Read the owning specs/ row and this repository's AGENTS.md before editing.
2. Inspect the active client/tool path and focused tests before changing API behavior, auth, ontology content, or packaged skills.
3. Prefer the smallest connector-owned change. Preserve action names, parameter schemas, SDK Connector wiring, Nextcloud credentials, TLS verification, same-origin checks, and package-data declarations unless the owning requirement changes them.
4. Run focused tests through the narrow test-slot wrapper, then run the repository pre-commit and pre-push gates without bypasses.
5. For public packaged content, bump the patch version and refresh uv.lock together; inspect the built wheel for the new skill.
6. Treat Pages as a separate proof: after the exact main SHA has a successful Pages run, check /spec-delivery/, its index.html, and snapshot.json over HTTPS and record the revision from the snapshot.