{
  "markdown": "# Nextcloud MCP Server\n\n**MCP Endpoint:** `https://mcp.techmavie.digital/nextcloud/mcp`\n\n> **Note:** This project is a complete rewrite in TypeScript of the original Python-based [cbcoutinho/nextcloud-mcp-server](https://github.com/cbcoutinho/nextcloud-mcp-server), now with **self-hosted VPS deployment** and **Smithery deployment support**.\n>\n> ### Key Differences from the Original Repository:\n> *   **Language:** This project is written in TypeScript, while the original is in Python.\n> *   **Smithery Support:** Added full support for Smithery deployment and local testing via Smithery playground.\n> *   **Project Structure:** The project structure has been adapted for a Node.js/TypeScript environment with MCP SDK integration.\n> *   **Dependencies:** This project uses npm for package management, whereas the original uses Python's dependency management tools.\n> *   **Deployment:** Now supports both local development and cloud deployment via Smithery.\n\nThe Nextcloud MCP (Model Context Protocol) server allows Large Language Models (LLMs) like OpenAI's GPT, Google's Gemini, or Anthropic's Claude to interact with your Nextcloud instance. This enables automation of various Nextcloud actions across Notes, Calendar, Contacts, Tables, and WebDAV file operations.\n\nThe hosted HTTP integration now supports a safer multi-user flow through the MCP Key Service. Instead of embedding raw Nextcloud credentials in the connector URL, hosted clients can use a user-scoped `usr_...` key and let the server resolve credentials server-side.\n\n## Features\n\nThe server provides integration with multiple Nextcloud apps, enabling LLMs to interact with your Nextcloud data through a comprehensive set of **30 tools** across 5 main categories.\n\n## Supported Nextcloud Apps\n\n| App | Support Status | Description |\n|-----|----------------|-------------|\n| **Notes** | ✅ Full Support | Create, read, update, delete, search, and append to notes. |\n| **Calendar** | ✅ Full Support | Complete calendar integration - manage calendars and events via CalDAV. |\n| **Tables** | ✅ Full Support | Complete table operations - list tables, get schemas, and perform CRUD operations on rows. |\n| **Files (WebDAV)** | ✅ Full Support | Complete file system access - browse directories, read/write files, create/delete resources. |\n| **Contacts** | ✅ Full Support | Create, read, update, and delete contacts and address books via CardDAV. |\n\n## Available Tools (30 Total)\n\n### 📝 Notes Tools (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `nextcloud_notes_create_note` | Create a new note with title, content, and category |\n| `nextcloud_notes_update_note` | Update an existing note by ID with optional title, content, or category |\n| `nextcloud_notes_append_content` | Append content to an existing note with a clear separator |\n| `nextcloud_notes_search_notes` | Search notes by title or content with result filtering |\n| `nextcloud_notes_delete_note` | Delete a note by ID |\n\n### 📅 Calendar Tools (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `nextcloud_calendar_list_calendars` | List all available calendars for the user |\n| `nextcloud_calendar_create_event` | Create a calendar event with summary, description, dates, and location |\n| `nextcloud_calendar_list_events` | List events from a calendar with optional date filtering |\n| `nextcloud_calendar_get_event` | Get detailed information about a specific event |\n| `nextcloud_calendar_update_event` | Update any aspect of an existing event |\n| `nextcloud_calendar_delete_event` | Delete a calendar event |\n\n### 👥 Contacts Tools (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `nextcloud_contacts_list_addressbooks` | List all available addressbooks for the user |\n| `nextcloud_contacts_create_addressbook` | Create a new addressbook with display name and description |\n| `nextcloud_contacts_delete_addressbook` | Delete an addressbook by ID |\n| `nextcloud_contacts_list_contacts` | List all contacts in a specific addressbook |\n| `nextcloud_contacts_create_contact` | Create a new contact with full name, emails, phones, addresses, and organizations |\n| `nextcloud_contacts_delete_contact` | Delete a contact from an addressbook |\n\n### 📊 Tables Tools (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `nextcloud_tables_list_tables` | List all tables available to the user |\n| `nextcloud_tables_get_schema` | Get the schema/structure of a specific table including columns |\n| `nextcloud_tables_read_table` | Read all rows from a table |\n| `nextcloud_tables_insert_row` | Insert a new row into a table with key-value data |\n| `nextcloud_tables_update_row` | Update an existing row in a table |\n| `nextcloud_tables_delete_row` | Delete a row from a table |\n\n### 📁 WebDAV File System Tools (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `nextcloud_webdav_search_files` | **🔍 NEW!** Unified search across filenames, content, and metadata - no need to specify exact paths |\n| `nextcloud_webdav_list_directory` | List files and directories in any Nextcloud path |\n| `nextcloud_webdav_read_file` | Read file content from Nextcloud |\n| `nextcloud_webdav_write_file` | Create or update files in Nextcloud with content |\n| `nextcloud_webdav_create_directory` | Create new directories in Nextcloud |\n| `nextcloud_webdav_delete_resource` | Delete files or directories from Nextcloud |\n\n## 🔍 Revolutionary Unified WebDAV Search Feature\n\nThe crown jewel of this MCP server is the powerful **unified search system** for WebDAV files, inspired by modern search interfaces like on an another MCP that I have created: [mcp-datagovmy](https://github.com/hithereiamaliff/mcp-datagovmy). This completely transforms how you interact with your Nextcloud files by eliminating the need to specify exact file paths.\n\n### ✨ Key Features\n\n- **🎯 Multi-scope Search**: Search across filenames, file content, and metadata simultaneously\n- **🧠 Smart File Type Detection**: Automatically handles text files, code, configuration files, documents, and media\n- **🔧 Advanced Filtering**: Filter by file type, size range, modification date, and directory\n- **📈 Intelligent Ranking**: Results ranked by relevance with bonuses for recent files and exact matches\n- **👀 Content Preview**: Optional content previews for matched text files\n- **⚡ Performance Optimized**: Intelligent caching, timeout protection, and parallel processing\n- **🛡️ Error Recovery**: Fallback strategies prevent timeouts and provide helpful suggestions\n\n### 🚀 Usage Examples\n\n```typescript\n// Basic search - find all files containing \"FAQ Dean List\"\nawait nextcloud_webdav_search_files({\n  query: \"FAQ Dean List\"\n});\n\n// Advanced search - find PDF reports from 2024\nawait nextcloud_webdav_search_files({\n  query: \"report 2024\",\n  fileTypes: [\"pdf\"],\n  searchIn: [\"filename\", \"content\"],\n  limit: 20,\n  includeContent: true,\n  quickSearch: true\n});\n\n// Directory-specific search with date range\nawait nextcloud_webdav_search_files({\n  query: \"meeting notes\",\n  basePath: \"/Documents\",\n  searchIn: [\"filename\", \"content\"],\n  dateRange: {\n    from: \"2024-01-01\",\n    to: \"2024-12-31\"\n  }\n});\n\n// Search by file characteristics\nawait nextcloud_webdav_search_files({\n  query: \"configuration files\",\n  sizeRange: { min: 1024, max: 102400 }, // 1KB - 100KB\n  fileTypes: [\"json\", \"yaml\", \"xml\", \"conf\"]\n});\n\n// Quick search for large directories (optimized)\nawait nextcloud_webdav_search_files({\n  query: \"budget\",\n  basePath: \"/\", // Root directory\n  quickSearch: true, // Enables optimizations\n  limit: 25,\n  maxDepth: 2 // Limit search depth\n});\n```\n\n### 📋 Complete Parameter Reference\n\n| Parameter | Type | Default | Description | Example |\n|-----------|------|---------|-------------|---------|\n| `query` | string | *required* | Search terms - supports multiple words | `\"FAQ Dean List\"` |\n| `searchIn` | array | `[\"filename\", \"content\"]` | Search scope: `filename`, `content`, `metadata` | `[\"filename\", \"content\", \"metadata\"]` |\n| `fileTypes` | array | *all types* | File extensions to include | `[\"pdf\", \"txt\", \"md\", \"docx\"]` |\n| `basePath` | string | `\"/\"` | Directory to search in | `\"/Documents/Reports\"` |\n| `limit` | number | `50` | Maximum results to return | `20` |\n| `includeContent` | boolean | `false` | Include content previews for text files | `true` |\n| `caseSensitive` | boolean | `false` | Case-sensitive matching | `true` |\n| `quickSearch` | boolean | `true` | Use optimized mode for root searches | `false` |\n| `maxDepth` | number | `3` | Maximum directory depth (1-10) | `5` |\n| `sizeRange` | object | *unlimited* | File size filters in bytes | `{min: 1024, max: 1048576}` |\n| `dateRange` | object | *all dates* | Last modified date filters | `{from: \"2024-01-01\", to: \"2024-12-31\"}` |\n\n### 🎯 Performance Tips\n\n- **For root directory searches**: Use `quickSearch: true` and `maxDepth: 2-3` for faster results\n- **For specific directories**: Use `basePath: \"/Documents\"` instead of searching root \"/\"\n- **For large result sets**: Add `fileTypes` filter to narrow scope\n- **For timeout issues**: Enable `quickSearch` and use smaller `limit` values\n\n### 🧪 Test Tool (1 tool)\n\n| Tool | Description |\n|------|-------------|\n| `hello` | Verify server connectivity and list all available tools |\n\n## 🔄 Before vs After: The Search Revolution\n\n### **Before Unified Search**\n```typescript\n// You had to know exact paths\nawait nextcloud_webdav_read_file({\n  path: \"/Documents/Finance/Reports/Q4_Budget_Analysis_2024.pdf\"\n});\n\n// Multiple calls needed to explore\nawait nextcloud_webdav_list_directory({ path: \"/\" });\nawait nextcloud_webdav_list_directory({ path: \"/Documents\" });\nawait nextcloud_webdav_list_directory({ path: \"/Documents/Finance\" });\n// ... and so on\n```\n\n### **After Unified Search** ✨\n```typescript\n// Natural language search across entire Nextcloud!\nawait nextcloud_webdav_search_files({\n  query: \"Q4 budget analysis 2024\",\n  fileTypes: [\"pdf\"]\n});\n\n// Finds files instantly regardless of location!\n```\n\n## 🛠️ Advanced Search Strategies\n\n### Content-Aware Search\nThe system intelligently extracts and searches content from:\n\n- **📝 Text Files**: `.txt`, `.md`, `.csv` - Full content indexing\n- **💻 Code Files**: `.js`, `.ts`, `.py`, `.html`, `.css` - Syntax-aware search\n- **⚙️ Config Files**: `.json`, `.xml`, `.yaml` - Structure-aware indexing\n- **📄 Documents**: `.pdf`, `.docx` - Metadata and properties\n- **🎬 Media Files**: Images, videos - EXIF data and metadata\n\n### Smart Ranking System\nResults are ranked using advanced algorithms:\n\n1. **Exact filename matches** → 100 points\n2. **Word boundaries in filenames** → 80 points\n3. **Partial filename matches** → 60+ points (position bonus)\n4. **Content frequency matches** → 50+ points (term density)\n5. **Recent file bonus** → +10 points (last 30 days)\n6. **File type preference** → +5 points (text/code files)\n7. **Size convenience** → +5 points (files under 100KB)\n\n### Error Handling & Recovery\n- **🕐 20-second timeout protection** - Prevents hanging operations\n- **🔄 Automatic fallback search** - Falls back to directory listing if indexing fails\n- **💡 Intelligent suggestions** - Provides helpful tips for optimization\n- **📊 Performance metrics** - Shows search duration and result counts\n\n## Installation\n\n### Quick Start with npm (Recommended)\n\nInstall directly from npm and run as an MCP server:\n\n```bash\n# Install globally\nnpm install -g mcp-nextcloud\n\n# Or install locally in your project\nnpm install mcp-nextcloud\n```\n\n### Usage as MCP Server\n\nAfter installation, you can run the MCP server directly:\n\n```bash\n# If installed globally\nmcp-nextcloud\n\n# If installed locally\nnpx mcp-nextcloud\n\n# Or using npm script\nnpm exec mcp-nextcloud\n```\n\n**Environment Setup**: Create a `.env` file with your Nextcloud credentials:\n\n```bash\nNEXTCLOUD_HOST=https://your.nextcloud.instance.com\nNEXTCLOUD_USERNAME=your_nextcloud_username\nNEXTCLOUD_PASSWORD=your_nextcloud_app_password\n```\n\n### Integration with LLM Applications\n\nAdd to your MCP client configuration (e.g., Claude Desktop, Continue, etc.):\n\n**For CLI mode (local, single-user):**\n```json\n{\n  \"mcpServers\": {\n    \"nextcloud\": {\n      \"command\": \"mcp-nextcloud\",\n      \"env\": {\n        \"NEXTCLOUD_HOST\": \"https://your.nextcloud.instance.com\",\n        \"NEXTCLOUD_USERNAME\": \"your_username\",\n        \"NEXTCLOUD_PASSWORD\": \"your_app_password\"\n      }\n    }\n  }\n}\n```\n\n**For hosted HTTP mode (via MCP Key Service):**\n```json\n{\n  \"mcpServers\": {\n    \"nextcloud\": {\n      \"transport\": \"streamable-http\",\n      \"url\": \"https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX\"\n    }\n  }\n}\n```\n\n> **Recommended for hosted clients:** Use the path-based URL form (`/mcp/usr_...`) for Claude.ai and similar hosted connectors. Keep the query-param form as a compatibility option for inspectors and clients that preserve query params reliably.\n\n**For self-hosted HTTP mode (your own server):**\n```json\n{\n  \"mcpServers\": {\n    \"nextcloud\": {\n      \"transport\": \"streamable-http\",\n      \"url\": \"https://mcp.techmavie.digital/nextcloud/mcp\",\n      \"headers\": {\n        \"X-API-Key\": \"your-server-api-key\",\n        \"X-Nextcloud-Host\": \"https://your.nextcloud.instance.com\",\n        \"X-Nextcloud-Username\": \"your_username\",\n        \"X-Nextcloud-Password\": \"your_app_password\"\n      }\n    }\n  }\n}\n```\n\n### Prerequisites\n\n*   Node.js 18+\n*   Access to a Nextcloud instance\n*   npm or yarn package manager\n\n### Local Development Setup\n\n1.  Clone the repository:\n    ```bash\n    git clone https://github.com/hithereiamaliff/mcp-nextcloud.git\n    cd mcp-nextcloud\n    ```\n\n2.  Install dependencies:\n    ```bash\n    npm install\n    ```\n\n3.  Configure your Nextcloud credentials (see Configuration section)\n\n4.  Build the project:\n    ```bash\n    npm run build\n    ```\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory based on `.env.sample`:\n\n```dotenv\n# --- CLI/stdio mode only ---\n# These are used when running the server in CLI mode (npm run dev, npm run cli).\n# They are NOT used by the HTTP server.\nNEXTCLOUD_HOST=https://your.nextcloud.instance.com\nNEXTCLOUD_USERNAME=your_nextcloud_username\nNEXTCLOUD_PASSWORD=your_nextcloud_app_password\n\n# --- HTTP server: Self-Hosted mode ---\n# Required for self-hosted /mcp auth, and also used for /analytics access.\nMCP_API_KEY=your-secret-api-key-here\n\n# --- HTTP server: Key Service mode ---\n# Set both to enable user api_key=usr_... resolution via the MCP Key Service.\n# Users obtain and manage those keys at https://mcpkeys.techmavie.digital\n# The MCP server itself talks to the resolver endpoint below.\nKEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve\nKEY_SERVICE_TOKEN=your-key-service-bearer-token\n\n# Optional: Comma-separated list of allowed CORS origins.\nALLOWED_ORIGINS=https://smithery.ai,https://claude.ai\n\n# Optional diagnostics for remote MCP debugging.\n# These are intended for temporary troubleshooting in hosted HTTP mode.\nMCP_TRACE_HTTP=false\nENABLE_MCP_DIAGNOSTICS=false\n\n# Optional dedicated endpoint for Smithery URL publishing.\nENABLE_SMITHERY_ENDPOINT=false\n```\n\n**Important Security Notes:**\n- Use a dedicated Nextcloud App Password instead of your regular login password. Generate one in your Nextcloud Security settings.\n- In HTTP mode, `NEXTCLOUD_*` environment variables are **never used**. Self-hosted clients provide credentials via `X-Nextcloud-*` headers, while key-service clients send only a `usr_...` key.\n- Generate a strong API key: `openssl rand -hex 32`\n\n### Smithery Configuration\n\nWhen deploying via Smithery, you can configure credentials through:\n- Smithery's configuration interface for URL-published servers\n\nFor Smithery, the recommended model is:\n\n- users enter `nextcloudHost`, `nextcloudUsername`, and `nextcloudPassword` directly\n- Smithery forwards those values to the dedicated `/smithery/mcp` endpoint as headers\n- the hosted `usr_...` key-service flow remains separate and continues to use `/mcp/usr_...`\n\n## Deployment & Usage\n\n### Option 1: Hosted Server (Recommended)\n\nThe easiest way to use this MCP server is via the hosted endpoint. **No installation required!**\n\n**Endpoint:** `https://mcp.techmavie.digital/nextcloud/mcp`\n\n#### Authentication\n\nThe hosted server uses the **MCP Key Service** for authentication. You get a personal API key (`usr_XXXXXXXX`) from the MCP Key Service portal:\n\n```text\nhttps://mcpkeys.techmavie.digital\n```\n\nThe server then resolves your Nextcloud credentials automatically through the resolver endpoint behind the scenes.\n\nWhy this is safer than the old query-credential approach:\n\n- raw Nextcloud credentials are not embedded in the connector URL\n- revoking a `usr_...` key is easier than rotating a user's underlying Nextcloud password everywhere\n- server-side auditing and policy are easier to centralize\n- support/debug workflows are safer because users share a scoped key, not their real Nextcloud password\n\n**Claude.ai / hosted connector URL (recommended):**\n\n```\nhttps://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX\n```\n\n**Alternative URL for clients that preserve query params correctly:**\n\n```\nhttps://mcp.techmavie.digital/nextcloud/mcp?api_key=usr_XXXXXXXX\n```\n\n#### Client Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"nextcloud\": {\n      \"transport\": \"streamable-http\",\n      \"url\": \"https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX\"\n    }\n  }\n}\n```\n\n#### Test with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector\n# Select \"Streamable HTTP\"\n# Enter URL: https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX\n```\n\n### Option 2: Self-Hosted (VPS)\n\nIf you prefer to run your own instance, the built-in Docker + Nginx setup is:\n\n```bash\n# Set required environment variables\nexport MCP_API_KEY=your-secret-api-key  # Required for self-hosted /mcp auth and /analytics\nexport KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve  # Optional: enables key service mode\nexport KEY_SERVICE_TOKEN=your-key-service-bearer-token                      # Optional: enables key service mode\n\n# Using Docker\ndocker compose up -d --build\n\n# Or run directly\nnpm run build\nnpm run start:http\n```\n\n#### Recommended VPS setup\n\n1. Clone the repo onto your server:\n   ```bash\n   git clone https://github.com/hithereiamaliff/mcp-nextcloud.git\n   cd mcp-nextcloud\n   ```\n2. Create a `.env` file with your server settings:\n   ```dotenv\n   MCP_API_KEY=your-secret-api-key\n   KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve\n   KEY_SERVICE_TOKEN=your-key-service-bearer-token\n   ALLOWED_ORIGINS=https://smithery.ai,https://claude.ai\n   ENABLE_SMITHERY_ENDPOINT=false\n   ```\n   Notes:\n   - Use `KEY_SERVICE_URL` + `KEY_SERVICE_TOKEN` only if you want hosted-style `usr_...` key resolution.\n   - Users obtain and manage those keys at `https://mcpkeys.techmavie.digital`.\n   - The MCP server itself should keep using the resolver endpoint path, not the portal homepage.\n   - Set `ENABLE_SMITHERY_ENDPOINT=true` only if you want to publish the dedicated Smithery direct-credentials endpoint.\n3. Start the container:\n   ```bash\n   docker compose up -d --build\n   ```\n4. Add the reverse proxy config from [deploy/nginx-mcp.conf](deploy/nginx-mcp.conf) to your nginx server block.\n5. Validate and reload nginx:\n   ```bash\n   sudo nginx -t\n   sudo systemctl reload nginx\n   ```\n6. Verify the server:\n   ```bash\n   curl http://127.0.0.1:8080/health\n   ```\n\n> **Important:** The HTTP server does NOT use `NEXTCLOUD_*` environment variables. In self-hosted mode, each client must provide Nextcloud credentials via request headers. In key-service mode, clients send only `api_key=usr_...`.\n\n> **Remote MCP note:** For hosted connectors such as Claude.ai, prefer the path-based URL form (`/mcp/usr_...`). Keep the query-param form as a compatibility option for inspectors and clients that preserve query params reliably.\n\n> **Debugging note:** If a hosted client shows a generic auth prompt, it does not automatically mean OAuth is required. First verify the auth-free diagnostics route, the key-service resolver response, and the actual `initialize` SSE body.\n\n### Option 3: npm Package (CLI)\n\nInstall and run as a local MCP server:\n\n```bash\nnpm install -g mcp-nextcloud\nmcp-nextcloud\n```\n\n> **Note:** In CLI mode, credentials are read from environment variables (`NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD`). This is safe because CLI mode runs locally for a single user.\n\n### Option 4: Smithery Deployment\n\nFor Smithery's current URL-published model, use a dedicated endpoint that accepts direct Nextcloud credentials via headers:\n\n```bash\n# Enable the Smithery endpoint on your hosted server\nENABLE_SMITHERY_ENDPOINT=true\n```\n\nUse this public MCP URL in Smithery:\n\n```text\nhttps://mcp.techmavie.digital/nextcloud/smithery/mcp\n```\n\nRecommended Smithery config schema for this server:\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"nextcloudHost\": {\n      \"type\": \"string\",\n      \"title\": \"Nextcloud Host\",\n      \"description\": \"Nextcloud server URL (for example https://cloud.example.com)\",\n      \"x-from\": { \"header\": \"X-Nextcloud-Host\" }\n    },\n    \"nextcloudUsername\": {\n      \"type\": \"string\",\n      \"title\": \"Nextcloud Username\",\n      \"x-from\": { \"header\": \"X-Nextcloud-Username\" }\n    },\n    \"nextcloudPassword\": {\n      \"type\": \"string\",\n      \"title\": \"Nextcloud App Password\",\n      \"format\": \"password\",\n      \"x-from\": { \"header\": \"X-Nextcloud-Password\" }\n    }\n  },\n  \"required\": [\"nextcloudHost\", \"nextcloudUsername\", \"nextcloudPassword\"]\n}\n```\n\nWhy this split is recommended:\n\n- Smithery users can connect directly without creating an MCP Key Service key first\n- the hosted `usr_...` connector flow remains unchanged for Claude.ai and other hosted clients\n- the Smithery path is isolated to `/smithery/mcp`, so it does not interfere with `/mcp` or `/mcp/usr_...`\n\n> **Important:** The Smithery endpoint is designed for direct credentials via headers. It does not use the MCP Key Service and does not require the shared `MCP_API_KEY`.\n>\n> To help Smithery discover tools without forcing a live authenticated scan, this server also exposes a static server card at `https://mcp.techmavie.digital/.well-known/mcp/server-card.json`. If your reverse proxy mounts the app under `/nextcloud`, make sure that exact root-level well-known path is proxied to the app.\n\n## Publishing to npm\n\n### For Maintainers\n\nTo publish this package to npm:\n\n1. **Prepare the release:**\n   ```bash\n   npm run build\n   npm version patch|minor|major\n   ```\n\n2. **Publish to npm:**\n   ```bash\n   npm publish\n   ```\n\n3. **Verify the publication:**\n   ```bash\n   npm view mcp-nextcloud\n   ```\n\n### Publishing Checklist\n\n- [ ] All tests pass (Smithery deployment confirmed working)\n- [ ] TypeScript builds without errors (`npm run build`)\n- [ ] Version bumped appropriately (`npm version`)\n- [ ] README updated with changes\n- [ ] `.npmignore` properly excludes development files\n- [ ] CLI executable works (`dist/cli.js`)\n\n### Dual Deployment Strategy\n\nThis project supports both deployment methods simultaneously:\n\n- **Smithery**: For cloud deployment and development testing\n- **npm**: For end-user installation and MCP client integration\n\nThe Smithery configuration (`smithery.yaml`) and npm package configuration coexist without interference.\n\n## Smithery Integration\n\nThis project includes full Smithery support with:\n\n- **`smithery.yaml`**: Specifies TypeScript runtime\n- **Development server**: Local testing with hot reload\n- **One-click deployment**: Deploy to cloud with a single command\n- **Configuration management**: Secure credential handling\n- **Playground integration**: Immediate testing interface\n\n## Security\n\n### HTTP Server Security Model\n\nThe HTTP server (`http-server.ts`) supports two authentication modes:\n\n**Key Service Mode** (hosted/multi-user):\n- User API keys (`usr_...`) are resolved via the MCP Key Service which returns encrypted Nextcloud credentials.\n- No raw credentials are sent by the client - only the user-scoped API key.\n- Credentials are cached for 60 seconds to reduce key service load, then re-validated.\n\n**Self-Hosted Mode** (single-operator):\n- A server-side `MCP_API_KEY` validates access.\n- Each client provides Nextcloud credentials via `X-Nextcloud-*` headers.\n\n**Common security measures:**\n- **Per-Request Credential Isolation**: Each request gets its own isolated set of Nextcloud clients via `AsyncLocalStorage`. No credential state is shared between requests.\n- **No Environment Variable Fallback**: The HTTP server never falls back to `NEXTCLOUD_*` environment variables for credentials. These are only used in CLI mode.\n- **Restricted CORS**: Only origins listed in `ALLOWED_ORIGINS` are permitted (defaults to `smithery.ai` and `claude.ai`).\n- **Protected Analytics**: The `/analytics` endpoint requires `MCP_API_KEY` authentication in both modes. The dashboard page stores the key in session storage, never in the URL. Client IPs are hashed before storage.\n- **Debug Tools Disabled in Production**: Calendar debug tools are automatically disabled when `NODE_ENV=production`.\n\n### Self-Hosting Checklist\n\nIf you deploy your own instance:\n\n1. Choose an auth mode: set `KEY_SERVICE_URL` + `KEY_SERVICE_TOKEN` for key service, or `MCP_API_KEY` for self-hosted\n2. Set `MCP_API_KEY` for analytics access (required in both modes)\n3. Do NOT set `NEXTCLOUD_*` environment variables on the HTTP server\n4. Use HTTPS (TLS) for all connections\n5. Configure `ALLOWED_ORIGINS` to restrict which domains can connect\n6. Use Nextcloud App Passwords (not your main login password)\n\n## Troubleshooting\n\n### Common Issues\n\n1. **404 Errors on WebDAV/Calendar/Contacts**: \n   - Ensure your Nextcloud credentials are correct\n   - Verify the Nextcloud apps (Calendar, Contacts) are installed and enabled\n   - Check that your app password has the necessary permissions\n\n2. **Authentication Failures**:\n   - Use an App Password instead of your regular password\n   - Verify the `NEXTCLOUD_HOST` URL is correct (including https://)\n   - Ensure the Nextcloud instance is accessible\n\n3. **Missing Tools**:\n   - Run the `hello` tool to verify all 30 tools are available\n   - Check the server logs for any initialization errors\n\n4. **Search Timeout Issues**:\n   - Use `quickSearch: true` for root directory searches\n   - Specify a `basePath` like \"/Documents\" instead of searching root \"/\"\n   - Add `fileTypes` filters to narrow the search scope\n   - Reduce `maxDepth` parameter for faster results\n\n### Hosted HTTP / Claude.ai Debugging\n\nIf the hosted connector still fails, use this order:\n\n1. Verify the auth-free diagnostics route first:\n   - enable `ENABLE_MCP_DIAGNOSTICS=true`\n   - test `/mcp-debug/open`\n   - if this works, the issue is likely auth or an upstream dependency, not basic MCP transport\n2. Verify the key-service resolver directly from the deployed MCP host:\n   ```bash\n   curl -i -X POST \"$KEY_SERVICE_URL\" \\\n     -H \"Authorization: Bearer $KEY_SERVICE_TOKEN\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"key\":\"usr_...\"}'\n   ```\n   Expected:\n   - `200 OK`\n   - `Content-Type: application/json`\n   - valid JSON response\n3. Verify the MCP initialize response body, not just the status code:\n   ```bash\n   curl -N --max-time 10 -X POST \"https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX\" \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Accept: application/json, text/event-stream\" \\\n     -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"probe\",\"version\":\"1.0.0\"}}}'\n   ```\n   Expected:\n   - `200 OK`\n   - `Content-Type: text/event-stream`\n   - non-empty SSE initialize response body\n4. If the hosted client keeps retrying the same initialize request every few seconds, suspect an empty or malformed SSE initialize response even if the HTTP status is `200`.\n5. Enable temporary tracing with `MCP_TRACE_HTTP=true` and inspect:\n   - final status code\n   - request `accept`\n   - request `content-type`\n   - `content-type` response header\n   - auth outcome (`resolved`, `invalid_key`, `service_unavailable`, `malformed_response`)\n\n## Development\n\n### Project Structure\n\n```\n├── src/\n│   ├── index.ts          # Main Smithery entry point\n│   ├── http-server.ts    # Streamable HTTP server for VPS deployment\n│   ├── app.ts            # Legacy entry point\n│   ├── client/           # Nextcloud API clients\n│   ├── models/           # TypeScript interfaces\n│   ├── tools/            # Tool implementations\n│   └── utils/            # Utility functions\n├── deploy/\n│   └── nginx-mcp.conf    # Nginx reverse proxy config\n├── .github/\n│   └── workflows/\n│       └── deploy-vps.yml # GitHub Actions auto-deploy\n├── docker-compose.yml    # Docker deployment config\n├── Dockerfile            # Container build config\n├── smithery.yaml         # Smithery configuration\n├── package.json          # Project dependencies and scripts\n└── README.md             # This file\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test with `npm run dev`\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Original Python implementation by [cbcoutinho](https://github.com/cbcoutinho/nextcloud-mcp-server)\n- Built with [Model Context Protocol](https://modelcontextprotocol.io/)\n- Deployable via [Smithery](https://smithery.ai/)\n",
  "bytes": 29426,
  "sha": "e7e94bbba3c5de9cc6e00edbea197249e8c6b2cbc8611d6d3aa94e0738bf58eb",
  "repo_slug": "hithereiamaliff/mcp-nextcloud",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_smithery_hithereiamaliff_mcp_nextclou_7b692a2b/readme"
}