# nc-forms-mcp

**MCP server for the Nextcloud Forms API v3.** Create, update, clone, and validate
forms — without ever leaking an app password into the agent's context.

[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square&logo=python)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-1.28%2B-purple?style=flat-square)](https://github.com/modelcontextprotocol)
[![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)

---

<p align="center">
  <strong>Push Forms API operations into a sealed MCP server.</strong><br>
  <em>Your agent calls tools, not curl. The password never leaves the env.</em>
</p>

---

## 🤨 The Problem

Nextcloud Forms has a REST API at `/ocs/v2.php/apps/forms/api/v3/` that uses
**HTTP Basic Auth with an app password**. When an AI agent calls this API directly:

| Issue | What happens | Consequence |
|-------|-------------|-------------|
| Credential leakage | The password passes through the LLM's context | Stored in logs, prompt caches, conversation history |
| Tool sprawl | Every Forms operation is a raw `curl` invocation | Inconsistent error handling, no validation |
| No isolation | The same credential gets reused for WebDAV, shares, etc. | Scope creep — operations outside Forms API |
| Repetition | Auth headers, error parsing, and retry logic in every call | Wasteful tokens and fragile code |

**Bottom line:** credentials in agent context = risk. Raw API calls in conversation = tech debt.

---

## ✅ The Solution

Wrap the Forms API in an **MCP server** that:

1. Reads credentials from **environment variables only** — the agent never sees them
2. Exposes **16 focused tools** — `forms_get`, `questions_add`, `options_update`, etc.
3. Runs as a **stdio subprocess** managed by the Hermes MCP client
4. Returns structured JSON — no parsing needed
5. Validates form health with a single tool call

```
┌──────────────┐   MCP stdio    ┌──────────────────┐   HTTPS Basic Auth   ┌──────────────────┐
│              │ ──────────────→│                  │ ────────────────────→│                  │
│  Hermes      │ ←──────────────│  nc-forms-mcp    │ ←────────────────────│  Nextcloud Forms  │
│  Agent       │                │  (Python process) │                     │  API v3          │
│              │                │  NC_FORMS_PASSWORD│                     │                  │
└──────────────┘                │  (env only,       │                     └──────────────────┘
                                │   never in chat)  │
                                └──────────────────┘
```

---

## 📦 Installation

### Prerequisites

- Python 3.10+
- Nextcloud instance with **Forms** app (v5+)
- Nextcloud **app password** (Settings → Security → Devices & sessions)

### Install

```bash
git clone https://github.com/erniomaldo/nc-forms-mcp.git ~/Proyectos/nc-forms-mcp
cd ~/Proyectos/nc-forms-mcp

# Hermes uses its own venv — install there:
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python -e .
```

Or use your project's venv:
```bash
uv venv && uv pip install -e .
```

---

## 🔧 Hermes Configuration

Add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  nc-forms:
    command: "uv"
    args:
      - "run"
      - "--directory"
      - "/home/ernesto-personal/Proyectos/nc-forms-mcp"
      - "nc-forms-mcp"
    env:
      NC_FORMS_USER: "erniomaldo"
      NC_FORMS_PASSWORD: "your-app-password-here"
      NC_FORMS_BASE: "https://base.agendasencilla.com"
    timeout: 30
```

**Restart Hermes** after adding. On startup it auto-discovers 16 tools prefixed
`mcp_nc_forms_*`.

---

## 🛠️ Tools

| Tool | What it does | Use case |
|------|-------------|----------|
| `forms_list` | List all owned forms | Dashboard / overview |
| `forms_get` | Get full form with questions, options, shares | Read current state |
| `forms_create` | Create an empty form | Start a new brief/survey |
| `forms_update` | Update title, description, settings | Iterate on form metadata |
| `forms_clone` | Clone a form (no submissions) | V1 → V2 iteration |
| `forms_delete` | Permanently delete a form | Cleanup |
| `questions_list` | List all questions in a form | Overview |
| `questions_get` | Get a single question by ID | Check specific question |
| `questions_add` | Add a question (multiple choice, text, etc.) | Build form content |
| `questions_update` | Update question text, description, isRequired | Refine wording |
| `questions_delete` | Remove a question | Prune sections |
| `questions_reorder` | Reorder questions by ID array | Reorganize sections |
| `options_add` | Add options to a choice question | Populate answer choices |
| `options_update` | Update a single option's text | Fix typos |
| `options_delete` | Remove an option | Cleanup |
| `forms_validate` | Check all questions have valid optionTypes | QA before publishing |

### Tool naming

MCP prefix: `mcp_nc_forms_` + tool name (underscores replace hyphens).

Example: `mcp_nc_forms_forms_get` → get form details.

---

## 🚀 Usage (after Hermes integration)

```python
# List all forms
mcp_nc_forms_forms_list()

# Get form 8 with all questions + options
mcp_nc_forms_forms_get({ "form_id": 8 })

# Add a question to form 8
mcp_nc_forms_questions_add({
    "form_id": 8,
    "type": "multiple_unique",
    "text": "🎨 1.2 ¿Colores definidos?"
})

# Add options
mcp_nc_forms_options_add({
    "form_id": 8,
    "question_id": 74,
    "option_texts": ["✅ De acuerdo", "🟡 Cerca pero ajustes", "❌ No se parece"],
    "option_type": "choice"
})

# Validate before publishing
mcp_nc_forms_forms_validate({ "form_id": 8 })
# → {"healthy": true, "total_questions": 32, "issues": []}
```

---

## 🧪 CLI Testing (without Hermes)

```bash
export NC_FORMS_USER="erniomaldo"
export NC_FORMS_PASSWORD="your-app-password"
export NC_FORMS_BASE="https://base.agendasencilla.com"

nc-forms-mcp forms_list '{}'
nc-forms-mcp forms_get '{"form_id": 8}'
nc-forms-mcp forms_validate '{"form_id": 8}'
```

---

## 🏗️ Project Structure

```
nc-forms-mcp/
├── pyproject.toml          # Project metadata + dependencies
├── README.md               # This file
├── LICENSE
├── nc_forms_mcp/
│   ├── __init__.py         # Package init (re-exports server)
│   ├── server.py           # MCP server: auth, route, tools, entry points
└── tests/                  # Coming soon
```

---

## 🔐 Security

- **Credentials live in `env` config** — the agent never sees `NC_FORMS_PASSWORD`
- The app password is **scoped to Forms API only** — WebDAV, Shares, Calendar,
  Collectives, and other Nextcloud features use their own MCP tools with their
  own auth
- Error messages redact credential-like patterns
- The MCP server process inherits a **filtered environment** (Hermes strips
  secrets from the subprocess env except what you explicitly set in `env`)

### What NOT to do

```yaml
# ❌ WRONG — password leaks into agent context
mcp_servers:
  nc-forms:
    command: "python3"
    args: ["server.py", "--password", "TEZiJ-..."]
```

```yaml
# ✅ CORRECT — password stays in env
mcp_servers:
  nc-forms:
    command: "uv"
    args: ["run", "--directory", "~/Proyectos/nc-forms-mcp", "nc-forms-mcp"]
    env:
      NC_FORMS_PASSWORD: "TEZiJ-..."
```

---

## 💡 Why not just use curl?

| Approach | Secret leaks? | Inconsistent errors? | Token waste? | Reusable? |
|----------|:---:|:---:|:---:|:---:|
| Raw curl in conversation | ✅ Always | ✅ Every call | ✅ Headers + parsing | ❌ No |
| Python script in /tmp | ✅ In code | ✅ Per script | ✅ Duplicated logic | ❌ Per task |
| **MCP server** | ❌ Never | ❌ Unified | ❌ One setup | ✅ All tasks |

---

## 📋 Comparison with alternative approaches

| | nc-forms-mcp | Forms web UI | Direct REST API (curl) | Custom script |
|---|---|---|---|---|
| **Setup** | 5 lines in config.yaml | Zero (browser) | Zero (curl installed) | Python + requests |
| **Speed** | Instant (stdio) | Point-and-click | Fast | Depends on quality |
| **Repeatability** | ✅ Always same tools | ❌ Manual clicks | ❌ Varies per call | ✅ If committed |
| **Validation** | ✅ `forms_validate` built-in | ❌ Manual review | ❌ Never | ❌ Rarely |
| **CI/CD ready** | ✅ Yes | ❌ No | ⚠️ Needs auth wrapper | ✅ If committed |
| **Secret safety** | ✅ In env only | ❌ Browser session | ❌ In command args | ⚠️ In code or env |
| **Token cost** | Low (one discovery) | N/A | High (per call) | Low (per script) |

---

## 🔄 Related Projects

- **[agentcheckpoint](https://github.com/erniomaldo/agentcheckpoint)** — atomic state store for multi-agent coordination (SQLite + MCP)
- **[Hermes Agent](https://hermes-agent.nousresearch.com/)** — the personal AI agent that runs this MCP server

---

## 📄 License

MIT