ATTENTION: LLM-GENERATED CODE

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 启动。当需要在 /sse 和 /messages 上使用 HTTP/SSE 传输时，请设置 ENABLE_SSE=true，例如 MCP 服务远程运行，而不是由客户端在本地启动时。

无界面调查构建（addSurvey → groups → questions）

你可以通过组合写入工具，在不使用 LimeSurvey 管理界面的情况下构建调查：

1. addSurvey — 创建一个未激活的调查；记下返回的调查 ID（sid）。
2. addGroup — 创建一个或多个问题组；每次调用都会返回一个组 ID（gid），供下一步使用。
3. importQuestion — 对于每个问题，传入 经过 base64 编码的 .lsq 内容（从界面导出一次原型问题，或生成兼容的 XML）。使用 importDataType: lsq。
4. setSurveyProperties — 设置欢迎文本、描述、结束 URL 等。
5. activateSurvey — 结构准备就绪后激活调查。

幂等重建： 使用 deleteQuestion（针对每个 qid，并设置 confirmDeletion: true）和 deleteGroup（针对每个调查和 gid），在重新导入 .lsq 模板前删除某个组或单个问题。删除组会移除该组的内容；请先在开发调查中确认你的 LimeSurvey 版本中的行为。

参与者链接格式： https://<host>/index.php/<sid>（使用 addSurvey 或 listSurveys 返回的 sid）。令牌访问使用现有的参与者工具。

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

tool: listSurveys
args: {}

API 参考

RemoteControl2 覆盖范围

下表展示了此服务如何将 LimeSurvey RemoteControl2 方法作为 MCP 工具提供。此处未实现的方法，要么在目标 LimeSurvey 实例中不可用，要么是出于有意而跳过（例如不稳定或未记录的端点）。

领域	RemoteControl2 方法	MCP 工具名称	备注
调查	list_surveys	listSurveys	只读
调查	get_survey_properties	getSurveyProperties	只读
调查	activate_survey	activateSurvey	写入（受 READONLY_MODE 保护）
调查	get_language_properties	getSurveyLanguageProperties	只读
调查	get_site_settings	getAvailableLanguages	读取 availablelanguages 设置
调查	—（派生）	getSurveyLanguages	从调查属性派生
调查	get_fieldmap	getFieldMap	只读
调查生命周期	add_survey	addSurvey	写入（受保护）
调查生命周期	import_survey	importSurvey	写入（受保护）
调查生命周期	copy_survey	copySurvey	写入（受保护）
调查生命周期	delete_survey	deleteSurvey	写入（受保护，需确认）
调查生命周期	activate_tokens	activateTokens	写入（受保护）
调查生命周期	set_survey_properties	setSurveyProperties	写入（受保护）
问题组	list_groups	listQuestionGroups	只读
问题组	get_group_properties	getGroupProperties	只读
问题组	add_group	addGroup	写入（受保护）；返回新的 gid
问题组	delete_group	deleteGroup	写入（受保护，需确认）
问题组	set_group_properties	setGroupProperties	写入（受保护）
问题	list_questions	listQuestions	只读
问题	get_question_properties	getQuestionProperties	只读
问题	import_question	importQuestion	写入（受保护）；base64 .lsq
问题	delete_question	deleteQuestion	写入（受保护，需确认）
问题	set_question_properties	setQuestionProperties	写入（受保护）
回复	get_summary	getResponseSummary	只读
回复	list_response_exports	listResponseExportFormats	只读发现（支持插件）
回复	export_responses	exportResponses	只读导出
回复	add_response	addResponse	写入（受保护）
回复	update_response	updateResponse	写入（受保护）
回复	delete_response	deleteResponse	写入（受保护，需确认）
回复	get_response_ids	getResponseIds	只读
回复	export_responses_by_token	exportResponsesByToken	只读导出
回复	export_timeline	exportTimeline	只读汇总计数
文件	upload_file	uploadFile	写入（受保护）
文件	get_uploaded_files	listUploadedFiles	只读
参与者/令牌	add_participants	addParticipant, addMultipleParticipants	写入（受保护）
参与者/令牌	list_participants	listParticipants, listFilteredParticipants	只读
参与者/令牌	get_participant_properties	getParticipantProperties	只读
参与者/令牌	delete_participants	deleteParticipants	写入（受保护，需确认）
参与者/令牌	invite_participants	inviteParticipants	写入（受保护，邮件/通知）
参与者/令牌	remind_participants	remindParticipants	写入（受保护，邮件/通知）
配额	get_quota_properties	getQuotaProperties	只读；没有列出全部项目的封装
配额	add_quota	addQuota	写入（受保护）
配额	set_quota_properties	setQuotaProperties	写入（受保护）
配额	delete_quota	deleteQuota	写入（受保护，需确认）
语言	add_language	addSurveyLanguage	写入（受保护）
语言	delete_language	deleteSurveyLanguage	写入（受保护，需确认）
语言	set_language_properties	setSurveyLanguageProperties	写入（受保护）
站点设置	get_site_settings	getAvailableLanguages	只读
当环境中设置了 READONLY_MODE=true 时，上文所有标记为“写入（受保护）”的工具都会返回明确的错误消息，而不会调用 LimeSurvey。

调查管理

listSurveys

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

参数：无

返回：

• 调查对象数组，包含以下属性：
  • 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"
  }
]

getSurveyProperties

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

参数：

• surveyId：要获取属性的调查 ID

返回：

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

activateSurvey

启用当前未启用的调查。

参数：

• surveyId：要启用的调查 ID

返回：

• 启用过程的结果

getSurveyLanguageProperties

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

参数：

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

返回：

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

getAvailableLanguages

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

参数：无

返回：

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

getSurveyLanguages

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

参数：

• surveyId：调查 ID

返回：

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

getQuotaProperties

获取特定配额的属性。

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

参数：

• quotaId：特定配额 ID（必需）
• language（可选）：配额说明所用的语言

返回：

• 给定配额 ID 的配额信息

addQuota

向调查添加新配额。

参数：

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

返回：

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

setQuotaProperties

更新现有配额的属性。

参数：

• quotaId：要更新的配额 ID
• properties：包含要更新的配额字段的对象（例如 name、limit、active、action、message、url）

返回：

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

deleteQuota

删除现有配额。

参数：

• quotaId：要删除的配额 ID

返回：

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

addSurveyLanguage

向调查添加新语言。

参数：

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

返回：

• LimeSurvey 返回的语言添加结果对象

deleteSurveyLanguage

从调查中删除一种语言。

参数：

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

返回：

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

setSurveyLanguageProperties

设置调查某种语言的特定语言属性。

参数：

• surveyId：调查 ID
• language（可选）：语言代码；省略则针对基础语言
• localeData：包含要更新的区域设置字段的对象（例如 surveyls_title、surveyls_description、surveyls_welcometext）

返回：

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

setSurveyProperties

设置问卷属性。

此工具封装了 set_survey_properties RemoteControl 方法： set_survey_properties($sessionKey, $iSurveyID, $aSurveyData)。LimeSurvey 无法更改某些字段（例如 sid、active、language、additional_languages，以及处于激活状态的问卷中的若干字段），并会忽略这些字段。

参数：

• surveyId：问卷 ID
• properties：要更新的问卷字段对象

返回：

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

问题管理

listQuestions

列出指定问卷中的所有问题。

参数：

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

返回：

• 问题对象数组，包含 ID、文本、类型及其他设置等属性

listQuestionGroups

列出指定问卷中的所有问题组。

参数：

• surveyId：问卷 ID
• language（可选）：组文本的语言

返回：

• 问题组对象数组，包含 ID、标题、描述和顺序等属性

addGroup

在问卷中创建一个空问题组。封装 RemoteControl add_group，并返回新组 ID（成功时为整数），可将其作为 groupId 传递给 importQuestion。

参数：

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

importQuestion

将 base64 编码的 .lsq 数据导入某个组。其原理与使用 .lss 的 importSurvey 相同：准备模板（例如，在 LimeSurvey 中为每种类型各导出一个问题），然后使用不同的载荷反复调用此工具。

参数：

• surveyId、groupId：目标问卷和组
• importData：base64 编码的 .lsq 内容
• importDataType：必须为 lsq（默认值）
• mandatory：Y 或 N（默认值为 N）
• newQuestionTitle、newQuestionText、newQuestionHelp（可选）：导入后覆盖 RemoteControl 中对应的可选参数

返回：成功时返回新问题 ID（整数）；失败时返回 LimeSurvey 的错误结构。

deleteGroup

从问卷中移除一个问题组。封装 RemoteControl delete_group。通常也会删除组内的问题；请在你的实例中确认。

参数：

• surveyId、groupId：要移除的问卷和组
• confirmDeletion：必须为 true（安全保护）

deleteQuestion

通过 qid 移除一个问题。封装 RemoteControl delete_question。复杂类型（例如排序题）可能会在 listQuestions 中以额外行的形式出现（子问题）；请根据导入/导出流程产生的内容进行删除或重建。

参数：

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

getQuestionProperties

获取指定问题的属性。

参数：

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

返回：

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

setQuestionProperties

通过 RemoteControl set_question_properties 更新问题的可写字段。**先进行发现：**调用 getQuestionProperties（可选地传入设置名称列表），确保只发送 LimeSurvey 接受的键。API 会阻止修改 qid、gid、sid、parent_qid、type 和 language 等结构字段。

常见编辑

• question：题干文本（通常为 HTML）。
• help：题干下方的帮助文本。
• 更新非基础调查语言时，传入 language。

排序题（类型 R）
面向参与者显示的排序标签通常存储在子问题行中（parent_qid 指向父问题）。使用 setQuestionProperties 更新各子问题行 qid 的 question 文本，或调整 .lsq 模板后重新导入。

列表／带注释列表类型
主提示词仍是父问题上的 question／help。答案标签可能是独立的答案记录；如果 RemoteControl 未提供所需内容，建议编辑 .lsq 模板并使用 importQuestion（或管理界面）处理选项列表，并使用此工具调整 API 允许修改的措辞。

响应管理

getResponseSummary

获取调查已收集响应的摘要信息。

参数：

• surveyId：调查的 ID

返回：

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

listResponseExportFormats

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

参数：

• 无

返回：

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

exportResponses

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

参数：

• surveyId：调查的 ID
• documentType：导出格式类型（动态／支持插件）。请先调用 listResponseExportFormats——默认值："csv"
• language（可选）：响应导出的语言
• completionStatus：按完成状态筛选（'complete'、'incomplete'、'all'）——默认值："all"
• headingType：标题类型（'code'、'full'、'abbreviated'）——默认值："code"
• responseType：响应类型（'short' 或 'long'）——默认值："short"
• fields（可选）：要导出的字段名称数组

返回：

• 成功摘要及原始导出数据
• 对于设置了 decodeOutput: true 的文本格式，还会包含解码后的预览

先发现再导出的工作流

1. 调用 listResponseExportFormats，发现当前 LimeSurvey 实例提供的有效 type 值。
2. 选择一个返回的 type（例如 csv、json 或自定义插件格式）。
3. 使用该 documentType 调用 exportResponses。

示例：

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

listResponses

列出特定调查的响应 ID。

参数：

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

返回：

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

参与者管理

addParticipant

向调查添加参与者。

参数：

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

返回：

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

listParticipants

列出特定调查的参与者。

参数：

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

返回：

• 包含所请求属性的参与者对象数组

getParticipantProperties

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

参数：

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

返回：

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

统计数据管理

exportStatistics

以 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
• @modelcontextprotocol/sdk - MCP 服务 SDK
• TypeScript - 用于类型安全和现代 JavaScript 特性
• dotenv - 用于环境变量管理
• Axios - 用于向 LimeSurvey 远程 API 发送 HTTP 请求

构建

npm run build

开发模式

npm run dev

许可证

MIT