Tabular MCP QA Builder

将陌生表格数据集工程化为基于 MCP 的问答服务。基线路径：源表 + 元数据 + 样例问题 → 规划 → 派生数据 → 仓储/查询层 → MCP 工具 →（可选）聊天入口 → 测试与记录。

Skill 说明可用英文书写；但生成的项目文档、规划说明、版本记录、测试摘要、执行提示词默认使用中文，除非用户明确要求其他语言。

输入 / 输出

输入（启动前确认）：

1. 真实表格数据：Excel、CSV、JSON 表导出、库导出或代表性样本
2. 元数据：数据字典或说明各 sheet/字段/单位/业务含义/聚合规则/注意点的文档
3. 样例问题：最终 MCP 应能回答的问题（优先真实用户说法）
4. v1 交付深度：data-only / core-mcp / mcp-and-chat / full-v1
5. 含聊天时的模型提供商：siliconflow / openai-compatible / defer-chat

输出：

• 规划：问题库、按能力分组的动态版本计划、中文目标模式执行提示（如 MCP_BUILD_GOAL_PROMPT.md）
• 派生数据契约：指标字典、维度字典、源列映射、规范化事实表（必要时公式/事件标注）
• 代码：仓储层 + 薄 MCP 工具；返回结构化 JSON，状态为 success / no_data / error / unsupported
• 可选：薄聊天入口（密钥仅走本地环境变量）
• 每版本测试与中文版本记录

Built-In Build Discipline

Apply this minimal-solution discipline throughout:

• Read the real data, metadata, questions, and existing code flow before designing.
• Reuse codebase patterns first, then standard library, then existing dependencies. Add a new dependency only when parsing the real file format requires it.
• Do not build a generic BI platform. Build the smallest general capability that covers the current question group.
• Implement one version at a time. One version should add one concrete MCP tool or one coherent capability layer.
• Fix root causes in shared parsing/query logic rather than patching individual questions.
• Leave one runnable test or self-check for each non-trivial parser, router, formula, or MCP tool.
• Mark deliberate shortcuts in code with a shortcut: comment that names the ceiling and upgrade path.
• Prefer deletion and consolidation over new abstractions. No factory, interface, router, or config exists unless the current version needs it.

Kickoff

Before coding, obtain or confirm the inputs listed above.

If a required file is missing, ask for it directly. If the user insists on proceeding without it, create only a limited planning version and clearly record assumptions. Never invent field meanings as facts.

If the user does not choose v1 depth, default to core-mcp. Add chat only when asked or when the project already clearly expects it.

Workflow

1. Inspect the source files.

   • Identify sheets/tables, header rows, merged or multi-level headers, date columns, metric columns, dimension columns, IDs, units, notes, and total columns.
   • Classify values as number, text, date, time period, ratio, enum, or unsupported.
   • Classify numeric metrics as flow, snapshot, label, ratio, or uncertain.

2. Build the planning version first.

   • Produce a detailed plan before feature coding.
   • Convert sample questions into a question bank.
   • Group questions by required capability: catalog lookup, value query, comparison, derived formula, named period, ranking, range scan, segment comparison, event explanation, or external context.
   • Reflect the chosen v1 depth and model provider in the plan.
   • Let the real data shape and question bank determine the version order.
   • Map each group to an MCP tool and a version.
   • Generate a Markdown execution prompt, such as MCP_BUILD_GOAL_PROMPT.md, in Chinese, so a fresh agent session can run in goal mode without needing continued chat.

3. Create derived data contracts.

   • Generate a metric dictionary, dimension dictionary, source column mapping, and normalized facts table.
   • Add formula and event annotation files only when sample questions require them.
   • Keep derived files deterministic so tests can compare stable outputs.

4. Implement the repository layer.

   • Load derived data.
   • Resolve metric aliases and dimension aliases.
   • Parse dates and named periods.
   • Validate aggregation rules.
   • Implement calculation methods as plain Python functions or methods before exposing them as MCP tools.

5. Expose MCP tools.

   • Wrap repository methods with thin MCP handlers.
   • Keep tool inputs structured and small: metric, date/window, aggregation, dimensions, expression, order, or top_n.
   • Return structured JSON plus clear status values: success, no_data, error, or unsupported.

6. Add a chat entrypoint only when v1 scope includes chat.

   • Keep the first chat layer thin.
   • Use the provider chosen at kickoff.
   • Ask the user to fill API configuration locally through environment variables or local config placeholders.
   • Never ask the user to paste secrets into the model chat, and never store real secrets in generated docs, code, tests, or prompts.

7. Test one version at a time.

   • Add tests for the new parser/build output or MCP tool.
   • Run the smallest relevant test command.
   • Fix until the version passes.
   • Record exact sample questions, calls, results, unsupported cases, and next version.

8. Keep the chat layer honest when present.

   • Let the model route questions and compose prose.
   • Let MCP tools calculate and validate facts.
   • Do not let the chat layer silently invent data, formulas, reasons, or secret configuration values.

Dynamic Version Planning

Do not use a fixed default version order. Derive the version plan from the actual table, metadata, and sample questions.

Use this process:

1. Inspect the real table and metadata.
2. Build the question bank from sample questions.
3. Cluster questions by shared capability and dependency order.
4. Choose the smallest first version that matches the confirmed v1 scope and proves one useful path.
5. Order later versions by dependency, coverage gain, and testability.
6. Keep each version to one MCP tool or one coherent capability layer.
7. Record blocked questions separately when they require missing metadata, external context, or product decisions.

Potential capability layers include catalog lookup, single value query, metric explanation, comparison, formulas, named periods, segmentation, ranking, range scan, event explanation, chat entrypoint, and deployment. These are a menu, not a preset sequence.

Goal Mode

When the user wants an end-to-end autonomous build, generate a Markdown goal-mode prompt before implementation. The prompt should instruct any Agent Skills–compatible agent to:

• Use this skill.
• Read the provided table, metadata, and sample questions.
• Confirm v1 depth and model provider from the user or from existing project decisions.
• Create a dynamic version plan from the real artifacts.
• Create or use a goal for the full MCP build objective.
• Execute all planned versions sequentially without asking the user to continue after each version.
• Write generated planning and record documents in Chinese.
• Include a chat entrypoint only if the confirmed v1 scope includes chat.
• Use the confirmed provider, and if it is SiliconFlow, wire local placeholders such as SILICONFLOW_API_KEY.
• Tell the user to fill secrets locally; do not request they paste keys into chat.
• Stop to ask only when a required file, business meaning, credential, or destructive action blocks progress.
• After each version, run tests and update the version record.
• Finish only when all non-blocked planned capabilities are implemented, verified, and documented.

If the current task is only to prepare the executor prompt, write that prompt to a Markdown file and stop. If the user asks the agent to execute the prompt, run it end to end.

References

Load only the reference needed for the current step:

• Read references/intake-and-planning.md when collecting files, inspecting tables, or turning sample questions into a version plan.
• Read references/data-contract.md when designing derived JSON/JSONL files.
• Read references/implementation-pattern.md when implementing repository methods, query wrappers, MCP server tools, or agent boundaries.
• Read references/version-loop.md when planning, testing, and recording each version.
• Read references/goal-prompt-template.md when generating the Markdown prompt for a fresh goal-mode agent session.