nextcloud-mcp-server

brandon/nextcloud-mcp-server

Fork 0

...

Author	SHA1	Message	Date
Chris Coutinho	26099d643d	docs: Update ADR-011 to rejected status with Context Agent validation After comprehensive research, the hybrid OAuth + AppAPI architecture is NOT being implemented due to fundamental architectural incompatibilities. Key updates: - Status: Proposed → Not Planned - Added validation from Nextcloud Context Agent project - Context Agent (official NC ExApp with MCP) faces IDENTICAL limitations - Proves constraints are architectural, not implementation-specific Context Agent findings: - ExApp with MCP server endpoint (~28 tools exposed) - Uses Task Processing API for confirmations (NOT MCP elicitation) - Works around AppAPI proxy limitations by changing protocol - MCP endpoint is secondary feature with documented constraints - Primary use: In-app Assistant integration, not external MCP clients Critical features impossible through AppAPI proxy: - ❌ MCP sampling (eliminates RAG/LLM features) - ❌ MCP elicitation (user prompts) - ❌ Real-time progress updates - ❌ Bidirectional streaming - Validated by Context Agent facing same limitations Decision rationale: - MCP requires multi-turn nested interactions - AppAPI provides stateless request/response proxy only - No implementation effort can bridge this fundamental gap - Would require complete AppAPI redesign (WebSocket, message routing) - Even official Nextcloud projects work around these limitations Alternative considered for future: - Register as Task Processing provider (different product) - Use Nextcloud Assistant UI (not external MCP clients) - Accept different capabilities (no sampling, custom flows) OAuth mode remains sole solution for external MCP client integration. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-11-13 23:30:14 +01:00
Chris Coutinho	ff3123a190	docs: Add ADR-011 for hybrid OAuth + AppAPI deployment architecture This ADR documents the architectural decision to support both OAuth and AppAPI (ExApp) deployment modes in a single codebase with 90%+ code sharing. Key additions: - Comprehensive analysis of AppAPI limitations and challenges - Feature parity matrix comparing OAuth vs AppAPI modes - Resolution of critical open questions via research: * Non-browser client authentication (app passwords/OAuth) * Streaming transport compatibility (buffered, not real-time) * Callbacks/webhooks (MCP notifications not possible in AppAPI) - Detailed implementation plan with 4 phases (10 days) - Mode-aware architecture with abstraction layer Critical findings: - AppAPI mode does NOT support MCP sampling (RAG features) - No real-time progress updates (use Nextcloud notifications) - Buffered streaming only (Streamable HTTP works, WebSocket doesn't) - Requires app password support in AppAPI proxy Deployment mode selection: - OAuth: Multi-tenant, external clients, sampling/RAG, real-time updates - AppAPI: Single-tenant, simplified install, native UI, admin-controlled Related to investigation of ~/Software/app_api/ and ~/Software/nc_py_api/ for AppAPI integration patterns. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-11-13 13:10:21 +01:00
Chris Coutinho	619ba5684d	build: Add ./worktrees to .gitignore	2025-11-12 08:27:33 +01:00

Author

SHA1

Message

Date

Chris Coutinho

26099d643d

docs: Update ADR-011 to rejected status with Context Agent validation

After comprehensive research, the hybrid OAuth + AppAPI architecture is NOT
being implemented due to fundamental architectural incompatibilities.

Key updates:
- Status: Proposed → Not Planned
- Added validation from Nextcloud Context Agent project
- Context Agent (official NC ExApp with MCP) faces IDENTICAL limitations
- Proves constraints are architectural, not implementation-specific

Context Agent findings:
- ExApp with MCP server endpoint (~28 tools exposed)
- Uses Task Processing API for confirmations (NOT MCP elicitation)
- Works around AppAPI proxy limitations by changing protocol
- MCP endpoint is secondary feature with documented constraints
- Primary use: In-app Assistant integration, not external MCP clients

Critical features impossible through AppAPI proxy:
- ❌ MCP sampling (eliminates RAG/LLM features)
- ❌ MCP elicitation (user prompts)
- ❌ Real-time progress updates
- ❌ Bidirectional streaming
- Validated by Context Agent facing same limitations

Decision rationale:
- MCP requires multi-turn nested interactions
- AppAPI provides stateless request/response proxy only
- No implementation effort can bridge this fundamental gap
- Would require complete AppAPI redesign (WebSocket, message routing)
- Even official Nextcloud projects work around these limitations

Alternative considered for future:
- Register as Task Processing provider (different product)
- Use Nextcloud Assistant UI (not external MCP clients)
- Accept different capabilities (no sampling, custom flows)

OAuth mode remains sole solution for external MCP client integration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-13 23:30:14 +01:00

Chris Coutinho

ff3123a190

docs: Add ADR-011 for hybrid OAuth + AppAPI deployment architecture

This ADR documents the architectural decision to support both OAuth and
AppAPI (ExApp) deployment modes in a single codebase with 90%+ code sharing.

Key additions:
- Comprehensive analysis of AppAPI limitations and challenges
- Feature parity matrix comparing OAuth vs AppAPI modes
- Resolution of critical open questions via research:
  * Non-browser client authentication (app passwords/OAuth)
  * Streaming transport compatibility (buffered, not real-time)
  * Callbacks/webhooks (MCP notifications not possible in AppAPI)
- Detailed implementation plan with 4 phases (10 days)
- Mode-aware architecture with abstraction layer

Critical findings:
- AppAPI mode does NOT support MCP sampling (RAG features)
- No real-time progress updates (use Nextcloud notifications)
- Buffered streaming only (Streamable HTTP works, WebSocket doesn't)
- Requires app password support in AppAPI proxy

Deployment mode selection:
- OAuth: Multi-tenant, external clients, sampling/RAG, real-time updates
- AppAPI: Single-tenant, simplified install, native UI, admin-controlled

Related to investigation of ~/Software/app_api/ and ~/Software/nc_py_api/
for AppAPI integration patterns.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-13 13:10:21 +01:00

Chris Coutinho

619ba5684d

build: Add ./worktrees to .gitignore

2025-11-12 08:27:33 +01:00

2 changed files with 1237 additions and 0 deletions

.gitignore

View File

@@ -5,6 +5,9 @@ __pycache__/
 .env.local
 .env.*.local
 # Git
 worktrees/
 docker-compose.override.yml
 # Generated by pytest used to login users

docs/ADR-011-hybrid-oauth-appapi-deployment.md

+1234

View File

File diff suppressed because it is too large Load Diff

Compare commits

3 Commits

v0.32.1 ... feature/app_api

Compare commits

3 Commits v0.32.1 ... feature/app_api

3 Commits

v0.32.1 ... feature/app_api