NaraForm

NaraForm 支援 Model Context Protocol（MCP），讓 AI 工具能直接建立、查詢、管理表單，無需手動操作 Dashboard。

事前準備

登入 Dashboard，進入 設定 → API 金鑰
建立一把 write scope 的金鑰（若只需查詢可用 read）
複製金鑰字串（格式：nf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）

傳輸協定：Streamable HTTP（MCP 最新規格）。以下範例會依照目前文件頁所在網域自動產生 endpoint；請將 YOUR_API_KEY 換成 Dashboard 產生的 API 金鑰。

MCP Server 端點

https://YOUR_NARAFORM_DOMAIN/api/mcp

這個端點會使用目前文件所在的網域自動產生。若你的企業部署在自訂網域，請以該網域開啟文件頁再複製設定。

Claude Desktop 設定

編輯 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：

{
  "mcpServers": {
    "naraform": {
      "url": "https://YOUR_NARAFORM_DOMAIN/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

重啟 Claude Desktop，在對話中輸入「幫我建立一個客戶滿意度問卷」即可開始使用。

Cursor 設定

在專案根目錄建立 `.cursor/mcp.json`，或編輯全域設定 `~/.cursor/mcp.json`：

{
  "mcpServers": {
    "naraform": {
      "url": "https://YOUR_NARAFORM_DOMAIN/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Codex CLI / Codex App 設定

Codex CLI 與 Codex App 共用 `~/.codex/config.toml`。最簡單的方式是先用 CLI 加入 server：

codex mcp add naraform --url https://YOUR_NARAFORM_DOMAIN/api/mcp

接著編輯 `~/.codex/config.toml`，在 `naraform` 設定下加入 Authorization header：

[mcp_servers.naraform]
url = "https://YOUR_NARAFORM_DOMAIN/api/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

重啟 Codex CLI 或完全關閉並重新開啟 Codex App，即可開始使用。

Windsurf 設定

編輯 `~/.codeium/windsurf/mcp_config.json`：

{
  "mcpServers": {
    "naraform": {
      "serverUrl": "https://YOUR_NARAFORM_DOMAIN/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

驗證連線

設定完成後，在 AI 對話框輸入：

列出我的所有表單

若看到表單列表，代表連線成功。

Codex 可用以下指令確認設定已被讀取：

codex mcp list
codex mcp get naraform

可用工具（Tools）

工具	說明	需要 scope
`list_forms`	列出所有表單	read
`get_form`	取得表單詳情含 schema	read
`create_form`	建立新表單	write
`update_form_schema`	更新表單問題結構	write
`publish_form`	發布表單	write
`unpublish_form`	取消發布	write
`get_responses`	查詢回覆資料	read
`get_analytics`	取得分析摘要	read
`delete_form`	刪除表單	write
`update_form_metadata`	更新表單基本設定	write

可用資源（Resources）

URI	說明
`naraform://schema/question-types`	5 種題型的完整規格說明
`naraform://schema/markdown-format`	可被 NaraForm 解析的 Markdown 問卷格式
`naraform://templates`	可用問卷範本列表

可用提示（Prompts）

名稱	說明
`design-survey`	根據目的和受眾引導設計問卷

使用範例

在 AI 對話中，你可以這樣說：

「幫我建立一份員工滿意度問卷，包含 8 個問題」
「列出我 workspace 裡所有已發布的表單」
「取得表單 [ID] 的分析摘要」
「取得表單 [ID] 中來源頁面是 guide 的回覆 metadata」
「將客戶回饋表單新增一個 NPS 題目並重新發布」

get_responses 會回傳每筆 response 的 metadata 欄位，get_responses 與 get_analytics 都可用 metadataFilters 篩選表單中已設定為 hidden 的題目 key，例如：

{
  "formId": "form_123",
  "metadataFilters": {
    "source_page": "guide"
  }
}

常見問題

顯示 `Missing API key`

代表 MCP client 沒有送出 Authorization header，或 API Key 內容不正確。請確認設定中包含：

Authorization: Bearer YOUR_API_KEY

本機開發的 MCP 沒有出現

若 endpoint 是 http://localhost:3000/api/mcp，請先確認本機開發服務已啟動。Docker 開發環境可使用：

npm run dev:infra:up

並確認健康檢查有回應：

curl http://localhost:3000/api/health

開發服務啟動後，重啟你的 MCP client。

MCP 整合設定