问卷调查API服务

LimeSurvey MCP服务器

模型上下文协议（MCP）服务器，将LimeSurvey Remote API功能公开为MCP工具。该服务器提供了一种标准化的方式，通过MCP客户端与LimeSurvey强大的调查管理功能进行交互。

目录

• 安装
• 配置
• 用法
• API 参考
  • 调查管理
  • 问题管理
  • 响应管理
  • 参与管理
  • 统计管理
• 发展
• 许可证

安装

# Clone the repository
git clone https://github.com/TonisOrmisson/limesurvey-mcp.git
cd limesurvey-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

配置

创建一个 .env 根目录中的文件，包含以下变量：

# LimeSurvey Remote API Settings
LIMESURVEY_API_URL=https://your-limesurvey-instance.com/admin/remotecontrol
LIMESURVEY_USERNAME=your_username
LIMESURVEY_PASSWORD=your_password

# Server settings
PORT=3000
ENABLE_SSE=false

# Optional: run in read‑only mode
# When true, all write tools short‑circuit and return an error message
# instead of calling LimeSurvey.
READONLY_MODE=false

用法

服务器运行后，您可以使用任何MCP客户端连接到它并访问LimeSurvey功能。

默认情况下，服务器以以下方式启动 stdio 只有。集 ENABLE_SSE=true 当您需要HTTP/SSE传输时 /sse 和 /messages例如，当MCP服务器远程运行而不是由客户端在本地生成时。

无头测量施工（addSurvey→ 群组→ 问题）

您可以通过组合编写工具，在没有LimeSurvey管理UI的情况下构建调查：

1. addSurvey --创建一个不活跃的调查；记下返回的调查ID(sid).
2. addGroup --创建一个或多个问题组；每次呼叫返回一个组ID(gid)下一步。
3. importQuestion --对于每个问题，通过 base64编码 .lsq 内容（从UI导出一次原型问题或生成兼容的XML）。使用 importDataType: lsq.
4. setSurveyProperties --欢迎文本、描述、结束URL等。
5. activateSurvey --当结构准备就绪时。

临时重建： 使用 deleteQuestion （每 qid，与 confirmDeletion: true)以及 deleteGroup （每次调查+ gid)在重新导入之前删除一组或单个问题 .lsq 模板。删除组会删除该组的内容；首先在开发调查中确认您的LimeSurvey版本的行为。

参与者链接模式： https://<host>/index.php/<sid> （使用 sid 从 addSurvey 或 listSurveys).令牌化访问使用您现有的参与者工具。

示例MCP客户端代码段（伪YAML）用于列出调查：

tool: listSurveys
args: {}

API 参考

遥控2覆盖范围

下表显示了LimeSurvey RemoteControl2方法如何作为MCP工具公开 在这个服务器上。此处未实现的方法在中也不可用 目标LimeSurvey实例或故意跳过（例如不稳定或 未记录的端点）。

当 READONLY_MODE=true 在环境中设置，所有工具都标记为“写入” 上面的“（防护）”将在不调用LimeSurvey的情况下返回明确的错误消息。

调查管理

列表调查

列出经过身份验证的用户有权访问的所有调查。

参数：无

退货:

• 具有属性的测量对象数组：
  • sid：调查ID
  • surveyls_title：调查标题
  • active：调查是否处于活动状态（“Y”或“N”）
  • expires：到期日期（如果已设置）
  • startdate：开始日期（如果已设置）
  • 以及其他调查元数据

示例响应:

[
  {
    "sid": "123456",
    "surveyls_title": "Customer Satisfaction Survey",
    "active": "Y",
    "expires": null,
    "startdate": "2023-01-01 00:00:00"
  },
  {
    "sid": "789012",
    "surveyls_title": "Employee Feedback",
    "active": "N",
    "expires": "2023-12-31 23:59:59",
    "startdate": "2023-06-01 00:00:00"
  }
]

获取调查属性

获取特定调查的详细属性。

参数:

• surveyId：用于获取房产的调查ID

退货:

• 包含测量属性的对象，包括设置、配置和元数据

激活调查

激活当前处于非活动状态的调查。

参数:

• surveyId：要激活的调查的ID

退货:

• 激活过程的结果

getSurvey语言属性

获取调查的特定语言属性。

参数:

• surveyId：调查的ID
• language：语言代码

退货:

• 包含调查语言特定属性的对象

获取可用语言

获取LimeSurvey安装中的可用语言。

参数：无

退货:

• 可用语言代码及其名称列表

getSurvey语言

获取特定调查的可用语言。

参数:

• surveyId：调查的ID

退货:

• 可用于调查的语言代码数组

getQuotaProperties

获取特定配额的属性。

此工具包装 get_quota_properties 远程控制方法： get_quota_properties($sessionKey, $iQuotaId, $aQuotaSettings = null, $sLanguage = null). 此MCP服务器不支持列出调查的所有配额。

参数:

• quotaId：特定配额ID（必填）
• language （可选）：配额描述语言

退货:

• 给定配额ID的配额信息

添加配额

向调查添加新配额。

参数:

• surveyId：调查的ID
• name：配额名称
• limit：配额的最大响应数

退货:

• LimeSurvey的结果对象，其中包含创建的配额数据

setQuotaProperties

更新现有配额的属性。

参数:

• quotaId：要更新的配额的ID
• properties：具有要更新的配额字段的对象（例如 name, limit, active, action, message, url)

退货:

• 描述更新配额的结果对象

deleteQuota

删除现有配额。

参数:

• quotaId：要删除的配额的ID

退货:

• 结果对象，指示配额是否已成功删除

添加调查语言

在调查中添加新语言。

参数:

• surveyId：调查的ID
• language：要添加的语言代码（例如 "de", "fr")

退货:

• 来自LimeSurvey的语言添加结果对象

deleteSurvey语言

从调查中删除语言。

参数:

• surveyId：调查的ID
• language：要删除的语言代码

退货:

• 结果对象，指示语言是否已删除

setSurvey语言属性

为调查语言设置特定于语言的属性。

参数:

• surveyId：调查的ID
• language （可选）：语言代码；省略以基础语言为目标
• localeData：具有要更新的区域设置字段的对象（例如 surveyls_title, surveyls_description, surveyls_welcometext)

退货:

• 描述更新的语言属性的结果对象

设置调查属性

设置测量的属性。

此工具包装 set_survey_properties 远程控制方法： set_survey_properties($sessionKey, $iSurveyID, $aSurveyData).一些字段 （例如 sid, active, language, additional_languages，和几个 活动调查中的字段）不能更改，LimeSurvey将忽略这些字段。

参数:

• surveyId：调查的ID
• properties：要更新的调查字段对象

退货:

• 描述哪些字段已成功更新的结果对象

问题管理

问题列表

列出特定调查的所有问题。

参数:

• surveyId：调查的ID
• groupId （可选）：仅获取此组的问题
• language （可选）：问题文本的语言

退货:

• 具有ID、文本、类型和其他设置等属性的问题对象数组

list问题组

列出特定调查的所有问题组。

参数:

• surveyId：调查的ID
• language （可选）：小组文本的语言

退货:

• 具有ID、标题、描述和顺序等属性的问题组对象数组

addGroup

创建一个 空的 调查问题小组。包裹远程控制 add_group 并返回新的组ID（成功时为整数），将其传递给 importQuestion 作为 groupId.

参数:

• surveyId：调查ID
• title：组标题
• description （可选）：组描述；默认空字符串

重要问题

从导入问题 base64编码 .lsq 将数据分组。想法与 importSurvey 随着 .lss：准备模板（例如，从LimeSurvey中为每种类型导出一个问题），然后使用不同的有效载荷重复调用此工具。

参数:

• surveyId, groupId：目标调查和小组
• importData：Base64编码 .lsq 内容
• importDataType：必须是 lsq （默认）
• mandatory: Y 或 N （默认值 N)
• newQuestionTitle, newQuestionText, newQuestionHelp （可选）：导入后覆盖匹配RemoteControl可选参数

退货：成功时的新问题ID（整数），或失败时LimeSurvey的错误结构。

deleteGroup

从调查中删除问题组。包裹远程控制 delete_group通常也会删除组内的问题；验证您的实例。

参数:

• surveyId, groupId：要删除的调查和分组
• confirmDeletion：必须是 true （安全防护装置）

删除问题

删除一个问题 qid.包装远程控制 delete_question复杂类型（如排名）可能会在中使用额外的行 listQuestions （子问题）；根据导出/导入周期生成的内容进行删除或重建。

参数:

• questionId：要删除的问题ID
• confirmDeletion：必须是 true

获取问题属性

获取特定问题的属性。

参数:

• questionId：问题的ID
• language （可选）：问题文本的语言
• properties （可选）：要检索的属性名数组

退货:

• 包含问题所请求属性的对象

setQuestion属性

通过遥控器更新问题的可写字段 set_question_properties. 先发现： 呼叫 getQuestionProperties （可选地带有设置名称列表），因此您只发送LimeSurvey接受的密钥。API阻止对结构字段的更改，例如 qid, gid, sid, parent_qid, type，以及 language.

常见编辑

• question：词干文本（通常是HTML）。
• help：茎下的帮助文本。
• 通过 language 当更新非基础调查语言时。

排名问题（R类）
面对排名标签的参与者通常会继续生活 子问题 行(parent_qid 指向父母）。更新每个子问题 question 文本与 setQuestionProperties 在那一排 qid，或调整 .lsq 模板并重新导入。

列表/带注释类型的列表
主要提示仍然是 question / help 在父母身上。答案标签可以是单独的答案记录；如果RemoteControl没有公开您需要的内容，请选择编辑 .lsq 模板和使用 importQuestion （或管理员UI），并使用此工具对API允许的措辞进行调整。

响应管理

getResponseSummary

获取有关调查收集到的答复的摘要信息。

参数:

• surveyId：调查的ID

退货:

• 包含响应计数和状态信息的摘要对象

list响应导出格式

列出全球可用的响应导出格式，包括插件提供的类型。

参数:

• 无

退货:

• 导出格式对象列表，包括：
  • type
  • pluginClass
  • label （可空）
  • tooltip （可空）
  • onclick （可空）
  • isDefault （布尔值）

导出响应

以指定格式导出调查的响应。

参数:

• surveyId：调查的ID
• documentType：导出格式类型（动态/插件感知）。呼叫 listResponseExportFormats 第一个-默认值：“csv”
• language （可选）：用于导出响应的语言
• completionStatus：按完成状态（“完成”、“不完整”、“全部”）筛选-默认值：“全部”
• headingType：标题类型（“代码”、“完整”、“缩写”）-默认值：“代码”
• responseType：响应类型（“短”或“长”）-默认值：“短”
• fields （可选）：要导出的字段名数组

退货:

• 成功总结加上原始出口有效载荷
• 对于具有以下内容的文本格式 decodeOutput: true，还包括解码预览

发现优先导出工作流

1. 呼叫 listResponseExportFormats 发现有效 type 当前LimeSurvey实例暴露的值。
2. 选择一个返回 type （例如 csv, json，或自定义插件格式）。
3. 呼叫 exportResponses 说完这个 documentType.

示例:

tool: listResponseExportFormats
args: {}
---
tool: exportResponses
args:
  surveyId: "123456"
  documentType: "csv"

listResponses

列出特定调查的响应ID。

参数:

• surveyId：调查的ID
• start：启动响应索引-默认值：0
• limit：返回的响应数-默认值：10
• attributes （可选）：要包含的属性名称数组

退货:

• 响应ID和请求属性的数组

参与管理

可寻址

将参与者添加到调查中。

参数:

• surveyId：调查的ID
• email：参与者电子邮件地址
• firstName （可选）：名字
• lastName （可选）：姓氏
• language （可选）：语言代码
• usesLeft：参与者可以访问调查的次数-默认值：1
• validFrom （可选）：生效日期（YYYY-MM-DD HH:MM:ss）
• validUntil （可选）：有效期至日期（YYYY-MM-DD HH:MM:ss）

退货:

• 参与者数据，包括生成的令牌

列表参与者

列出特定调查的参与者。

参数:

• surveyId：调查的ID
• start：起始参与者索引-默认值：0
• limit：要返回的参与者数量-默认值：10
• unused：仅显示未使用的令牌-默认值：false
• attributes （可选）：要包含的属性名称数组

退货:

• 具有请求属性的参与者对象数组

获取参与者属性

获取特定参与者/令牌的属性。

参数:

• surveyId：调查的ID
• tokenId：令牌ID
• attributes （可选）：要包含的属性名称数组

退货:

• 包含指定参与者属性的对象

统计管理

出口统计

以PDF、Excel或HTML格式导出调查统计数据，并附带可选图形。

参数:

• surveyId：用于导出统计数据的调查ID
• documentType：导出格式：pdf、xls或html-默认：pdf
• language （可选）：统计导出语言（默认：调查的默认语言）
• includeGraphs：是否在导出中包含图形（仅适用于PDF）-默认值：false
• groupIds （可选）：要包含在统计数据中的特定问题组ID，可以是单个ID或ID数组

退货:

• Base64编码字符串，包含请求格式的统计文件

示例用法:

exportStatistics:
  surveyId: "123456"
  documentType: "pdf"
  includeGraphs: true

发展

本项目使用以下方式构建：

• Node.js
• @模型上下文协议/sdk -MCP服务器SDK
• TypeScript -用于类型安全和现代JavaScript功能
• Dotenv。 -用于环境变量管理
• 阿西奥斯 -对于LimeSurvey Remote API的HTTP请求

建筑

npm run build

开发模式

npm run dev

许可证

麻省理工学院