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.

---

<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

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:

uv venv && uv pip install -e .

---

🔧 Hermes Configuration

Add to ~/.hermes/config.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)

# 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)

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

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

# ✅ 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 — atomic state store for multi-agent coordination (SQLite + MCP)
• Hermes Agent — the personal AI agent that runs this MCP server

---

📄 License

MIT