SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstencent-survey

tencent-survey

Office & productivity

View repository

Updated 10-15 17:26

About this skill

SKILL update

Perform an update check once a day before using SKILL, following the steps below:

  1. View the current version version: Read the version field in the frontmatter at the top of this file; the format is MAJOR.MINOR.PATCH
  2. View the latest version latest: Obtain the latest version information via a commandlatest, with input parameter current_version being the current version obtained in the previous step
mcporter call tencent-survey "check_skill_update" --args '{"current_version": "当前版本"}'

JSON format data is returned; example return parameters:

  • has_update: Whether there is an update (true/false)
  • latest: Latest version number, in MAJOR.MINOR.PATCH format
  • current_version: The currently passed version number
  • release_note: Latest version release notes
  • instruction: Update instruction
  1. Update version: If has_update is true (that is, the current versioncurrent_versionis lower than the latest versionlatest), follow the instruction instruction to update, or prompt the user to update
Tencent Surveys MCP User Guide

Tencent Surveys MCP provides survey query, creation, editing, and answer viewing capabilities, allowing AI assistants to directly operate the survey system.

Trigger scenarios

Explicit trigger

This skill should be activated directly in the following cases:

  • The user mentions keywords such as "survey", "questionnaire", "form", "poll", "exam", "assessment", etc.
  • The user provides a wj.qq.com link
  • The user says "help me make a survey", "create a poll", etc.

Ambiguous scenarios

User statement How to determine
"Help me make a poll" Use this skill directly, scene=8
"Make an exam" Use this skill directly, scene=3
"Make an assessment" Use this skill directly, scene=6
"Collect everyone's opinions" Use this skill directly, scene=1 (survey)
"I have a survey link..." Parse the link to extract survey_id and call get_survey
"Modify question X of the survey" First call get_survey to obtain question_id, then update_question
"Look at the survey answers" Call list_answers, and note to paginate to retrieve all data
"How many responses has the survey received" Call list_answers to view the total field

Configuration

Before the first tool call in this session, complete one authentication check (for the full process, see references/auth.md）：

${SKILL_DIR} is the directory path where this skill is located (that is, the directory where SKILL.md is located). It is automatically injected by the AI Agent framework when loading the skill; if the framework does not inject it, replace it with the absolute path of the directory where SKILL.md is located.

Method 1: Pass Token via environment variable

If a Token already exists (environment variable TENCENT_SURVEY_TOKEN), complete the configuration directly without OAuth authorization:

TENCENT_SURVEY_TOKEN=xxx bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth

After the script detects TENCENT_SURVEY_TOKEN , it will automatically write the mcporter configuration and output READY to indicate readiness.

Method 2: OAuth device authorization

When TENCENT_SURVEY_TOKEN is not set, the OAuth authorization flow is entered automatically:

  1. Execute bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth
  2. Output READY → authentication is ready, continue directly
  3. Output AUTH_REQUIRED:<url> → show the authorization link to the user, then execute bash "${SKILL_DIR}/setup.sh" wj_wait_auth to wait for authorization to complete
  4. Output ERROR:* → inform the user of the corresponding error

After authentication passes,subsequent calls within the same session do not need to repeat the check. Only when a tool returns an authentication error such as invalid_token、token expired、missing_token does the above flow need to be executed again.

  • The Token prefix is fixed as wjpt_, length 70 characters
  • Each Token is bound to one team and can only operate surveys under that team

Tool list and calling methods

Tool name Function description Reference documentation
get_survey Get detailed information of a specified survey (title, settings, pages, questions, options + plain text DSL) references/get_survey.md
create_survey Create a survey using plain text (text required, supports specifying scenario/project) references/create_survey.md
update_question Update a certain question in a survey (question_id must be obtained first) references/update_question.md
list_answers Get the response list of a survey (supports cursor pagination) references/list_answers.md
check_skill_update Check whether a new version of the Skill is available for update See the "SKILL Update" section above

Calling priority:

  1. MCP native call: If the current AI Agent is already connected to the tencent-survey service via the MCP protocol (visible in the tool list as get_survey、create_survey、update_question、list_answers), call the tool directly
  2. mcporter CLI call: If the AI Agent does not support MCP native calls, or the tencent-survey tool does not appear in the tool list, execute via the terminal mcporter call tencent-survey.<tool_name> --args '{...}'
  3. Confirm tool availability: Use mcporter list tencent-survey to view the list of registered tools and parameter Schema

The parameter descriptions in the reference documentation should be consistent with the MCP tool Schema. If there is a conflict, the Schema returned by mcporter list tencent-survey shall prevail.

URL parsing rules

The survey distribution link format is https://wj.qq.com/s2/{survey_id}/{hash}

When the user provides a link, take the second path segment as survey_id：

URL format Extraction method Example
wj.qq.com/s2/{id}/{hash} Take the second path segment as survey_id wj.qq.com/s2/292192/abc1 → 292192

After extracting survey_id , call get_survey(survey_id=...) to get survey details.

Data model

问卷（Survey）
├── 基本信息：id, hash, title, scene, state
├── 设置：prefix(欢迎语), suffix(结束语), started_at, end_at ...
├── 项目：project { id, name }
├── 纯文本内容：text（DSL 格式，包含标题和所有题目）
├── 页面列表（Pages[]）
│   └── 题目列表（Questions[]）
│       ├── 基本属性：id, type, sub_type, title, required
│       ├── 选项列表（Options[]）：id, text, exclusive
│       ├── 量表属性：starBeginNum, starNum
│       ├── 矩阵子问题：subTitles[]
│       └── 联动层级：levels[], groups[]
└── 回答列表（Answers[]）← 通过 list_answers 获取
    ├── 基本信息：answer_id, respondent_nickname, started_at, ended_at
    ├── 地理信息：country, province, city
    └── 回答内容（answer[]）
        └── 页面 → 题目回答 { id, type, text, options, blanks, groups }

Core nesting relationships:Survey → Pages[] → Questions[] → Options[] Answer nesting relationships:Answer → answer[] (Pages) → questions[]

Common workflows

View survey details

Reference documentation:references/get_survey.md

  1. Execute the authentication check (see the "Configuration" section above)
  2. Get survey_idfrom the link or ID provided by the user (for link parsing, see "URL parsing rules")
  3. Call get_survey(survey_id=...) to get survey details
  4. Recursively parse the pages → questions → options nested structure
  5. Show the survey title, question list, and other information to the user

Create survey

Reference documentation:references/create_survey.md

  1. Perform an authentication check (see the "Configuration" section above)
  2. Determine based on user needs scene: survey (1, default), exam (3), assessment (6), poll (8)
  3. Organize the content according to the questionnaire text syntax text (see the reference documentation for syntax details)
  4. If the user has specified a project, pass in project_id
  5. Call create_survey to create the questionnaire
  6. From the returned result, take survey_id and hash, concatenate the distribution link wj.qq.com/s2/{survey_id}/{hash} and inform the user
  7. Optional: call get_survey to confirm the questionnaire structure

Update questionnaire questions

Reference documentation:references/update_question.md

  1. Perform an authentication check (see the "Configuration" section above)
  2. Call get_survey(survey_id=...) to get questionnaire details
  3. From the returned pages → questions , find the target question's id(format such as q-1-xxxx）
  4. Refer to the returned text field to understand the current questionnaire's DSL format
  5. Write the new question text according to the DSL syntax (write only this one question, no questionnaire title needed)
  6. Call update_question(survey_id=..., question_id=..., text=...) to update the question
  7. Optional: call get_survey again to confirm the update result

View questionnaire answers

Reference documentation:references/list_answers.md

  1. Perform an authentication check (see the "Configuration" section above)
  2. Call list_answers(survey_id=...) to get the first page of answers
  3. ⚠️ Note pagination: if list.length == per_page, it means there may be a next page, and you need to loop through the pages:
    • Use the returned last_answer_id as the parameter for the next request
    • Continue calling list_answers(survey_id=..., last_answer_id=...) to get the next page
    • Until list.length < per_page indicates the last page has been reached
  4. Parse each answer's answer field (nested structure:页面 → 题目回答）
  5. Display the answer summary or details to the user

Notes

  • Titles may contain HTML tags：get_survey The title field returned by <p>、<br> may contain tags such as
  • text field (DSL format)：get_survey The text field returned by update_question is questionnaire content in plain text DSL format, and can serve as a reference for
  • text parameter format：create_survey The update_question of text and \nis required; in JSON, use 满意 for line breaks; options do not need letter prefixes (write A. 满意）
  • update_question requires first obtaining question_id: you must first call get_survey to get the question list; you cannot construct question_id yourself
  • list_answers requires pagination: the answer list uses cursor-based pagination; if the number of answers exceeds per_page(default 20), you must call it in a loop until all data is retrieved
  • Non-idempotent write operations：create_survey creates a new questionnaire on each call, andupdate_question overwrites the original question on each call

Problem Location Guide

Common error codes

Error code Error type Solution
missing_token Request does not carry Token Check the Authorization header or access_token parameter
invalid_token_prefix Token prefix error Confirm using wjpt_ Token prefixed with
invalid token Token does not exist or has been revoked Recreate the Token
token expired Token expired Reauthorize, see references/auth.md
claim_error Survey does not belong to the current team Confirm the survey ID is correct and belongs to the team bound to the current Token
invalid_text_format Text format error (create_survey / update_question) Check the text DSL syntax
survey_not_editable Survey is not editable (update_question) The survey may be collecting responses and must be paused first

Troubleshooting steps

  1. Check the error message: View the returned error field to determine the error type
  2. Check the request parameters: Confirm survey_id and other parameter values are correct
  3. Read the reference documentation：references/ The directory contains parameter descriptions for all tools
  4. Get the tool list: Use mcporter list tencent-survey to confirm whether the tool is available